File class

A file is either a Blosc2 dataset or a regular file on a root repository.

class caterva2.File(root, path, meta=None)

Attributes:

client

cookie

urlbase

vlmeta

Returns a mapping of metalayer names to their respective values.

This is used to access variable-length metalayers (user attributes) associated with the file.

>>> import caterva2 as cat2
>>> client = cat2.Client('https://cat2.cloud/demo')
>>> root = client.get('example')
>>> file = root['ds-sc-attr.b2nd']
>>> file.vlmeta
{'a': 1, 'b': 'foo', 'c': 123.456}

Methods

copy(dst)	Copies the file to a new location.
download([localpath])	Downloads the file to storage.
get_download_url()	Retrieves the download URL for the file.
move(dst)	Moves the file to a new location.
remove()	Removes the file from the remote repository.
slice(key[, as_blosc2])	Get a slice of a File/Dataset.
unfold()	Unfolds the file in a remote directory.

Special Methods:

__init__(root, path[, meta])	Represents a file, which can be a Blosc2 dataset or a regular file on a root repository.
__getitem__(item)	Retrieves a slice of the file's data (only meaningful for datasets).

Constructor

__init__(root, path, meta=None)

Represents a file, which can be a Blosc2 dataset or a regular file on a root repository.

This class is not intended for direct instantiation; it should be accessed through a Root instance.

Parameters:

• root (Root) – The root repository.

• path (str) – The path of the file.

Examples

>>> import caterva2 as cat2
>>> client = cat2.Client('https://cat2.cloud/demo')
>>> root = client.get('example')
>>> file = root['README.md']
>>> file
<File: example/README.md>
>>> file.name
'README.md'
>>> file.urlbase
'https://cat2.cloud/demo'
>>> file.path
PurePosixPath('example/README.md')
>>> file.meta['contiguous']
True

Utility Methods

__getitem__(item)

Retrieves a slice of the file’s data (only meaningful for datasets).

Parameters:

item (int, slice, tuple of ints and slices, or None) – Specifies the slice to fetch.

Returns:

The requested slice of the dataset.

Return type:

numpy.ndarray

get_download_url()

Retrieves the download URL for the file.

Returns:

The file’s download URL.

Return type:

str

Examples

>>> import caterva2 as cat2
>>> client = cat2.Client('https://cat2.cloud/demo')
>>> root = client.get('example')
>>> file = root['ds-1d.b2nd']
>>> file.get_download_url()
'https://cat2.cloud/demo/api/fetch/example/ds-1d.b2nd'

slice(key: int | slice | Sequence[slice], as_blosc2: bool = True) → NDArray | SChunk | ndarray

Get a slice of a File/Dataset.

Parameters:

• key (int, slice, or sequence of slices) – The slice to retrieve. If a single slice is provided, it will be applied to the first dimension. If a sequence of slices is provided, each slice will be applied to the corresponding dimension.

• as_blosc2 (bool) – If True (default), the result will be returned as a Blosc2 object (either a SChunk or NDArray). If False, it will be returned as a NumPy array (equivalent to self[key]).

Returns:

A new Blosc2 object containing the requested slice.

Return type:

NDArray or SChunk or numpy.ndarray

Examples

>>> import caterva2 as cat2
>>> client = cat2.Client('https://cat2.cloud/demo')
>>> root = client.get('example')
>>> ds = root['ds-1d.b2nd']
>>> ds.slice(1)
<blosc2.ndarray.NDArray object at 0x10747efd0>
>>> ds.slice(1)[()]
array(1)
>>> ds.slice(slice(0, 10))[:]
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

property vlmeta

Returns a mapping of metalayer names to their respective values.

This is used to access variable-length metalayers (user attributes) associated with the file.

>>> import caterva2 as cat2
>>> client = cat2.Client('https://cat2.cloud/demo')
>>> root = client.get('example')
>>> file = root['ds-sc-attr.b2nd']
>>> file.vlmeta
{'a': 1, 'b': 'foo', 'c': 123.456}