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

hardlink_to(target)¶

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

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

link_to(target)¶

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.

readlink()¶

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

symlink_to(target, target_is_directory=False)¶

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

unlink(missing_ok=False)¶

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.