lamindb.UPath

class lamindb.UPath(*args: str | PathLike, **kwargs: Any)

Bases: 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

anchor property

The concatenation of the drive and root, or ‘’.

drive property

The drive prefix (letter or UNC path), if any.

fs AbstractFileSystem

The filesystem_spec filesystem instance

modified datetime | None

Return modified time stamp.

name property

The final path component, if any.

parent PT

The logical parent of the path.

parents _UPathParents

A sequence of this upath’s logical parents.

parts property

An object providing sequence-like access to the components in the filesystem path.

path str

The filesystem_spec path for use with a filesystem instance

Note: for some file systems this can be prefixed by the protocol.

protocol str

The filesystem_spec protocol

For local paths protocol is either ‘file’ if the UPath instance is backed by fsspec or ‘’ if it’s backed by stdlib pathlib. For both fsspec.get_filesystem_class returns LocalFileSystem.

root property

The root of the path, if any.

stem property

The final path component, minus its last suffix.

storage_options dict[str, Any]

The filesystem_spec storage options dictionary

Accessing .storage_options does not instantiate the corresponding fsspec filesystem class.

suffix property

The final component’s last suffix, if any.

This includes the leading period. For example: ‘.txt’

suffixes property

A list of the final component’s suffixes, if any.

These include the leading periods. For example: [‘.tar’, ‘.gz’]

Methods

absolute()
Return type:

TypeVar(PT, bound= UPath)

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

None

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

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

exists()

Whether this path exists.

Return type:

bool

expanduser()
glob(pattern)

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

Return type:

Generator[TypeVar(PT, bound= UPath), None, None]

group()
classmethod home()
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_mount()
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[TypeVar(PT, bound= UPath), None, None]

lchmod(mode)
lstat()
mkdir(mode=511, parents=False, exist_ok=False)

Create a new directory at this given path.

Return type:

None

open(*args, **kwargs)
owner()
relative_to(*other)

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:

TypeVar(PT, bound= UPath)

rename(target, recursive=False, maxdepth=None, **kwargs)

Move file, see fsspec.AbstractFileSystem.mv.

>>> upath = Upath("s3://my-bucket/my-file")
>>> 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)
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:

TypeVar(PT, bound= UPath)

rglob(pattern)

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

Return type:

Generator[TypeVar(PT, bound= UPath), None, None]

rmdir(recursive=True)
Return type:

None

samefile(other_path)
Return type:

bool

stat()

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

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(*args, truncate=True, **kwargs)
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 (str | Path) – 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)

Return a new path with the file name changed.

Return type:

TypeVar(PT, bound= UPath)

with_suffix(suffix)

Return a new path with the file suffix changed. If the path has no suffix, add given suffix. If the given suffix is an empty string, remove the suffix from the path.

Return type:

TypeVar(PT, bound= UPath)