lamindb.UPath#

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

Bases: Path

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

Paths are keys that offer the typical access patterns of file systems and object stores. The key field in the File registry is a relative path in the storage location of the record.

If you don’t care about validating & linking extensive metadata to a file, you can store it as a path.

For instance, if you have a folder with 1M images on S3 and you don’t want to create file records for each of them, create a Dataset object like so:

>>> dataset = Dataset("s3://my-bucket/my-folder", file="s3://my-bucket/meta.parquet")

Passing the file parameter is optional. This way, you can iterate over path objects through

>>> dataset.path
>>> assert dataset.path.is_dir()

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 property#: The filesystem_spec filesystem instance

modified property#: Return modified time stamp.

name property#: The final path component, if any.

parent property#: The logical parent of the path.

parents property#: A sequence of this upath’s logical parents.

parts property#: An object providing sequence-like access to the components in the filesystem path.

path property#

The filesystem_spec path for use with a filesystem instance

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

protocol property#

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 property#

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

chmod(mode*follow_symlinks=True)#

Return type:: None

classmethod cwd()#

download_to(path, print_progress=False, **kwargs)#: Download to a 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()#

hardlink_to(target)#

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

is_symlink()#

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)#

link_to(target)#

lstat()#

mkdir(mode=511, parents=False, exist_ok=False)#

Create a new directory at this given path.

Return type:: None

open(*args, **kwargs)#

owner()#

readlink()#

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.

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.

symlink_to(target, target_is_directory=False)#

synchronize(filepath, **kwargs)#: Sync to a local destination path.

touch(*args, truncate=True, **kwargs)#

Return type:: None

unlink(missing_ok=False)#

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

Return type:: None

upload_from(path, print_progress=False, **kwargs)#: Upload from a local path.

view_tree(*, level=-1, only_dirs=False, limit=1000, include_paths=None)#

Print a visual tree structure of files & directories.

Parameters:

level (int, default: -1) – 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.
limit (int, default: 1000) – Display limit. Will only show this many files. Doesn’t affect count.
include_paths (Optional[Set[Any]], default: None) – Restrict to these paths.

Return type:

None

Examples

>>> dir_path = ln.dev.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)

lamindb.FeatureSet

lamindb.track