lamindb.UPath

class lamindb.UPath(*args, protocol=None, **storage_options)

Bases: PathlibPathShim, Path

Paths: low-level key-value access to files/objects.

Paths are based on keys that offer the typical access patterns of file systems

and object stores.

>>> upath = UPath("s3://my-bucket/my-folder")
>>> upath.exists()
Parameters:

pathlike – A string or Path to a local/cloud file/directory/folder.

Attributes

property anchor
property drive
property fs: AbstractFileSystem

The cached fsspec filesystem instance for the path.

property modified: datetime | None

Return modified time stamp.

property name: str
property parent
property parents
property parts
property path: str

The path that a fsspec filesystem can use.

property protocol: str

The fsspec protocol for the path.

property root
property stem
property storage_options: Mapping[str, Any]

The fsspec storage options for the path.

property suffix
property suffixes

Class methods

classmethod cwd()
Return type:

UPath

classmethod home()
Return type:

UPath

Methods

absolute()
Return type:

Self

as_posix()

Return the string representation of the path with forward (/) slashes.

as_uri()
Return type:

str

chmod(mode, *, follow_symlinks=True)
Return type:

None

download_to(local_path, print_progress=True, **kwargs)

Download from self (a destination in the cloud) to the local path.

exists(*, follow_symlinks=True)

Whether this path exists.

Return type:

bool

expanduser()
Return type:

Self

glob(pattern, *, case_sensitive=None)

Iterate over this subtree and yield all existing files (of any kind, including directories) matching the given relative pattern.

Return type:

Generator[UPath, None, None]

group()
Return type:

str

Return type:

None

is_absolute()
Return type:

bool

is_block_device()
Return type:

bool

is_char_device()
Return type:

bool

is_dir()

Whether this path is a directory.

Return type:

bool

is_fifo()
Return type:

bool

is_file()

Whether this path is a regular file (also True for symlinks pointing to regular files).

Return type:

bool

is_junction()
Return type:

bool

is_mount()
Return type:

bool

is_relative_to(other, /, *_deprecated)
Return type:

bool

is_reserved()
Return type:

bool

is_socket()
Return type:

bool

Return type:

bool

iterdir()

Iterate over the files in this directory. Does not yield any result for the special paths ‘.’ and ‘..’.

Return type:

Generator[UPath, None, None]

joinpath(*pathsegments)
Return type:

Self

joinuri(uri)

Join with urljoin behavior for UPath instances

Return type:

UPath

lchmod(mode)
Return type:

None

Make the target path a hard link pointing to this path.

Note this function does not make this path a hard link to target, despite the implication of the function and argument names. The order of arguments (target, link) is the reverse of Path.symlink_to, but matches that of os.link.

Deprecated since Python 3.10 and scheduled for removal in Python 3.12. Use hardlink_to() instead.

lstat()
Return type:

UPathStatResult

match(path_pattern)

Return True if this path matches the given pattern.

mkdir(mode=511, parents=False, exist_ok=False)
Return type:

None

open(mode='r', *args, **fsspec_kwargs)

Open the file pointed by this path and return a file object, as the built-in open() function does.

Return type:

IO[Any]

owner()
Return type:

str

read_bytes()

Open the file in bytes mode, read it, and close the file.

read_text(encoding=None, errors=None)

Open the file in text mode, read it, and close the file.

Return type:

Self

relative_to(other, /, *_deprecated, walk_up=False)

Return the relative path to another path identified by the passed arguments. If the operation is not possible (because this is not a subpath of the other path), raise ValueError.

Return type:

Self

rename(target, *, recursive=<object object>, maxdepth=<object object>, **kwargs)

Move file, see fsspec.AbstractFileSystem.mv.

>>> upath = Upath("s3://my-bucket/my-file")
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~typing.Self\``
>>> upath.rename(UPath("s3://my-bucket/my-file-renamed"))
>>> upath.rename("my-file-renamed")
>>> upath = Upath("local-folder/my-file")
>>> upath.rename("local-folder/my-file-renamed")
replace(target)
Return type:

UPath

resolve(strict=False)

Make the path absolute, resolving all symlinks on the way and also normalizing it (for example turning slashes into backslashes under Windows).

Return type:

Self

rglob(pattern, *, case_sensitive=None)

Recursively yield all existing files (of any kind, including directories) matching the given relative pattern, anywhere in this subtree.

Return type:

Generator[UPath, None, None]

rmdir(recursive=True)
Return type:

None

samefile(other_path)
Return type:

bool

stat(*, follow_symlinks=True)

Return the result of the stat() system call on this path, like os.stat() does.

Return type:

UPathStatResult

Return type:

None

synchronize(objectpath, error_no_origin=True, print_progress=False, callback=None, timestamp=None)

Sync to a local destination path.

to_url()

Public storage URL.

Generates a public URL for an object in an S3 bucket using fsspec’s UPath, considering the bucket’s region.

Args: - upath: A UPath object representing an S3 path.

Returns: - A string containing the public URL to the S3 object.

touch(mode=438, exist_ok=True)
Return type:

None

Remove this file or link. If the path is a directory, use rmdir() instead.

Return type:

None

upload_from(local_path, create_folder=None, print_progress=True, **kwargs)

Upload from the local path to self (a destination in the cloud).

If the local path is a directory, recursively upload its contents.

Parameters:
  • local_path (lamindb.core.types.UPathStr) – A local path of a file or directory.

  • create_folder (bool | None, default: None) – Only applies if local_path is a directory and then defaults to True. If True, make a new folder in the destination using the directory name of local_path. If False, upload the contents of the directory to to the root-level of the destination.

  • print_progress (bool, default: True) – Print progress.

Return type:

UPath

Returns:

The destination path.

view_tree(*, level=2, only_dirs=False, n_max_files_per_dir_and_type=100, n_max_files=1000, include_paths=None, skip_suffixes=None)

Print a visual tree structure of files & directories.

Parameters:
  • level (int, default: 2) – If 1, only iterate through one level, if 2 iterate through 2 levels, if -1 iterate through entire hierarchy.

  • only_dirs (bool, default: False) – Only iterate through directories.

  • n_max_files (int, default: 1000) – Display limit. Will only show this many files. Doesn’t affect count.

  • include_paths (set[Any] | None, default: None) – Restrict to these paths.

  • skip_suffixes (list[str] | None, default: None) – Skip directories with these suffixes.

Return type:

None

Examples

>>> dir_path = ln.core.datasets.generate_cell_ranger_files(
>>>     "sample_001", ln.settings.storage
>>> )
>>> ln.UPath(dir_path).view_tree()
3 subdirectories, 15 files
sample_001
├── web_summary.html
├── metrics_summary.csv
├── molecule_info.h5
├── filtered_feature_bc_matrix
│   ├── features.tsv.gz
│   ├── barcodes.tsv.gz
│   └── matrix.mtx.gz
├── analysis
│   └── analysis.csv
├── raw_feature_bc_matrix
│   ├── features.tsv.gz
│   ├── barcodes.tsv.gz
│   └── matrix.mtx.gz
├── possorted_genome_bam.bam.bai
├── cloupe.cloupe
├── possorted_genome_bam.bam
├── filtered_feature_bc_matrix.h5
└── raw_feature_bc_matrix.h5
with_name(name)
with_segments(*pathsegments)
Return type:

Self

with_stem(stem)
with_suffix(suffix)
write_bytes(data)

Open the file in bytes mode, write to it, and close the file.

write_text(data, encoding=None, errors=None, newline=None)

Open the file in text mode, write to it, and close the file.