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

Methods

absolute()
as_uri()
chmod(mode, *, follow_symlinks=True)
classmethod cwd()
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.

expanduser()
glob(pattern, *, case_sensitive=None)

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

group()
classmethod home()
is_block_device()
is_char_device()
is_dir()

Whether this path is a directory.

is_fifo()
is_file()

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

is_junction()
is_mount()
is_relative_to(other, /, *_deprecated)
is_reserved()
is_socket()
iterdir()

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

joinuri(uri)

Join with urljoin behavior for UPath instances

Return type:

UPath

lstat()
mkdir(mode=511, parents=False, exist_ok=False)
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()
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.

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

rglob(pattern, *, case_sensitive=None)

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

rmdir(recursive=True)
samefile(other_path)
stat(*, follow_symlinks=True)

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

Return type:

UPathStatResult

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)

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

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_segments(*pathsegments)