Utility classes and variables

A collection of utility classes and variables that are used throughout the Caterva2 API.

Caterva2 - On demand access to remote Blosc2 data repositories

caterva2.__version__ = '2026.09.03.dev0'

The version in use of the Caterva2 package.

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

Attributes:

blocks

The blockshape of the compressed dataset.

chunks

The chunkshape of the compressed dataset.

client

cookie

device

Hardware device the array data resides on.

dtype

The data type of the dataset.

info

Get information about the Operand.

ndim

The number of dimensions of the dataset.

shape

The shape of the dataset.

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

all([axis, keepdims])	Test whether all array elements along a given axis evaluate to True.
any([axis, keepdims])	Test whether any array element along a given axis evaluates to True.
append(data)	Appends data to the dataset.
argmax([axis, keepdims])	Returns the indices of the maximum values along a specified axis.
argmin([axis, keepdims])	Returns the indices of the minimum values along a specified axis.
copy(dst)	Copies the file to a new location.
cumulative_prod([axis, dtype, include_initial])	Calculates the cumulative product of elements in the input array ndarr.
cumulative_sum([axis, dtype, include_initial])	Calculates the cumulative sum of elements in the input array ndarr.
download([localpath])	Downloads the file to storage.
fill_chunk(nchunk, chunk)	Writes one compressed chunk into a slot of this array; see Client.fill_chunk().
get_download_url()	Retrieves the download URL for the file.
item()	Copy an element of an array to a standard Python scalar and return it.
max([axis, keepdims])	Return the maximum along a given axis.
mean([axis, dtype, keepdims])	Return the arithmetic mean along the specified axis.
min([axis, keepdims])	Return the minimum along a given axis.
move(dst)	Moves the file to a new location.
prod([axis, dtype, keepdims])	Return the product of array elements over a given axis.
publish()	Copies this array out to wherever the server publishes to; see Client.publish().
remove()	Removes the file from the remote repository.
slice(key[, as_blosc2])	Get a slice of a File/Dataset.
std([axis, dtype, ddof, keepdims])	Return the standard deviation along the specified axis.
sum([axis, dtype, keepdims])	Return the sum of array elements over a given axis.
to_device(device)	Copy the array from the device on which it currently resides to the specified device.
unfold()	Unfolds the file in a remote directory.
var([axis, dtype, ddof, keepdims])	Return the variance along the specified axis.
where([value1, value2])	Select value1 or value2 values based on True/False for self.
written_chunks()	Says which chunks of this array hold anything yet; see Client.written_chunks().

append(data)

Appends data to the dataset.

Parameters:

data (blosc2.NDArray, numpy.ndarray, sequence) – The data to append to the dataset.

Returns:

out – A pointer to the (modified) dataset.

Return type:

Caterva2.Array

Examples

>>> import caterva2 as cat2
>>> import numpy as np
>>> # To append data to a dataset you need to be a registered user
>>> client = cat2.Client("https://cat2.cloud/demo", ("joedoe@example.com", "foobar"))
>>> data = client.copy('@public/examples/ds-1d.b2nd', '@personal/ds-1d.b2nd')
>>> dataset = client.get('@personal')['ds-1d.b2nd']
>>> dataset.append([1, 2, 3])
(1003,)

property blocks

The blockshape of the compressed dataset.

property chunks

The chunkshape of the compressed dataset.

property dtype

The data type of the dataset.

fill_chunk(nchunk, chunk)

Writes one compressed chunk into a slot of this array; see Client.fill_chunk().

Examples

>>> import caterva2 as cat2, blosc2, numpy as np
>>> client = cat2.Client('https://cat2.cloud/demo', ("joedoe@example.com", "foobar"))
>>> array = client.lay_out('@personal/run.b2nd', (1000,), np.int32, chunks=(100,))
>>> chunk = blosc2.compress2(np.arange(100, dtype=np.int32), typesize=4)
>>> array.fill_chunk(0, chunk)["written"]
1

property ndim

The number of dimensions of the dataset.

publish()

Copies this array out to wherever the server publishes to; see Client.publish().

property shape

The shape of the dataset.

written_chunks()

Says which chunks of this array hold anything yet; see Client.written_chunks().

class caterva2.BasicAuth(username=None, password=None)

Basic authentication for HTTP requests.

Parameters:

• username (str, optional) – The username for authentication.

• password (str, optional) – The password for authentication.

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

A browsable group (HDF5 jargon): a directory, a TreeStore .b2z, or a virtual group inside one. Children are addressed by (inner) path.

Not instantiated directly; obtained from a Root, e.g. root['dir1'] or root['tree.b2z/level1'].

Attributes:

client

cookie

file_list

Deep list of leaf paths under this group (relative to it).

meta

urlbase

Methods

copy(dst)	Copies the file to a new location.
download([localpath])	Downloads the file to storage.
move(dst)	Moves the file to a new location.
remove()	Removes the file from the remote repository.
unfold()	Unfolds the file in a remote directory.

property client

property cookie

property file_list

Deep list of leaf paths under this group (relative to it).

property meta

property urlbase

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

Represents a CTable (.b2z) dataset.

Attributes:

client

columns

cookie

ncols

nrows

schema

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.
head([n])	Get the first n rows as a list of tuples.
move(dst)	Moves the file to a new location.
remove()	Removes the file from the remote repository.
rows([start, stop])	Get rows [start, stop) as a list of tuples.
slice(key)	Get a row slice as a blosc2.CTable.
unfold()	Unfolds the file in a remote directory.
where(expression)	Return a filtered row view matching a boolean expression as a blosc2.CTable.

property columns

head(n=5)

Get the first n rows as a list of tuples.

property ncols

property nrows

rows(start=0, stop=50)

Get rows [start, stop) as a list of tuples.

The default window is bounded (first 50 rows) to avoid accidentally fetching a whole large table; pass stop=self.nrows for everything.

property schema

slice(key)

Get a row slice as a blosc2.CTable.

where(expression)

Return a filtered row view matching a boolean expression as a blosc2.CTable.