Skip to content

Tensor

A read from an Array returns a Tensor. This applies to retrieve_array_subset, retrieve_chunk, and [...]. A Tensor is one of four concrete result types, and the decoded byte layout of the data type selects which one. Use isinstance to narrow to a concrete type before you call a method that belongs to one layout.

zarrista.Tensor module-attribute 

Tensor: TypeAlias = (
    FixedLengthTensor
    | VariableLengthTensor
    | OptionalFixedLengthTensor
    | OptionalVariableLengthTensor
)

The result of a read: one of the four decoded array layouts.

The layout depends on the byte layout of the data type. A data type is either fixed-width or variable-length, and it either carries a validity mask or does not. Use isinstance to narrow to a concrete type before you use a method that belongs to one layout.

zarrista.FixedLengthTensor

Fixed-width, dense decoded array data.

FixedLengthTensor implements the buffer protocol directly as an N-dimensional, typed, read-only view. Therefore it works with memoryview(tensor) and np.asarray(tensor) for any type that the buffer protocol supports.

Use to_numpy to get a NumPy array view over the Rust memory. This is zero-copy whenever possible.

dtype property 

dtype: DataType

The Zarr data type.

shape property 

shape: list[int]

The shape of the decoded region.

__array__ 

__array__(
    dtype: DTypeLike | None = None, copy: bool | None = None
) -> NDArray[Any]

Return a NumPy array, for np.asarray and np.array.

Parameters:

  • dtype (DTypeLike | None, default: None ) –

    The data type of the result. Give None to keep the tensor's own data type.

  • copy (bool | None, default: None ) –

    Whether to copy the data. Give None to let NumPy decide.

Returns:

  • NDArray[Any] –

    A NumPy array with the same shape as this tensor.

__buffer__ 

__buffer__(flags: int) -> memoryview

Export an N-dimensional, typed, read-only PEP 3118 buffer view.

Parameters:

  • flags (int) –

    The buffer request flags, as in inspect.BufferFlags.

Returns:

  • memoryview –

    A read-only memoryview over the decoded bytes.

Raises:

  • BufferError –

    If flags request a writable buffer, or if the data type has no standard format code.

__dlpack__ 

__dlpack__(
    *,
    stream: int | None = None,
    max_version: tuple[int, int] | None = None,
    dl_device: tuple[int, int] | None = None,
    copy: bool | None = None
) -> CapsuleType

Export the data as a DLPack capsule (e.g. for np.from_dlpack).

Keyword Arguments:

  • stream (int | None) –

    The stream to synchronize with. The data is always on the CPU, so this argument has no effect.

  • max_version (tuple[int, int] | None) –

    The highest DLPack version that the caller supports.

  • dl_device (tuple[int, int] | None) –

    The device that the caller wants the data on.

  • copy (bool | None) –

    Whether to copy the data.

Returns:

  • CapsuleType –

    A capsule that holds the DLPack tensor.

__dlpack_device__ 

__dlpack_device__() -> tuple[int, int]

Return the DLPack device (device_type, device_id). Always CPU.

Returns:

  • tuple[int, int] –

    The pair (1, 0), which is DLPack's identifier for the CPU.

buffer 

buffer() -> Buffer

Return the raw decoded bytes as a zero-copy buffer-protocol object.

Returns:

  • Buffer –

    A read-only view over the decoded bytes.

to_numpy 

to_numpy() -> NDArray[Any]

Return a NumPy array view over Rust memory.

This is a zero-copy view through np.frombuffer. Unlike the buffer protocol, this path covers the full NumPy dtype set (e.g. complex).

Returns:

  • NDArray[Any] –

    A read-only NumPy array with the same shape and dtype as this tensor.

zarrista.VariableLengthTensor

Variable-length decoded data (e.g. strings or bytes).

The class exposes the Arrow PyCapsule interface: you can access the contained data in any Python library that speaks Arrow without a copy.

Use to_numpy (or np.asarray) to get a NumPy array.

dtype property 

dtype: DataType

The Zarr data type.

shape property 

shape: list[int]

The shape of the decoded region.

__array__ 

__array__(
    dtype: DTypeLike | None = None, copy: bool | None = None
) -> NDArray[Any]

Return a NumPy array, for np.asarray and np.array.

Parameters:

  • dtype (DTypeLike | None, default: None ) –

    The data type of the result.

  • copy (bool | None, default: None ) –

    Whether to copy the data. This method always copies, so False is an error.

Returns:

  • NDArray[Any] –

    A NumPy array with the same shape as this tensor.

Raises:

  • UnicodeDecodeError –

    If the decoded bytes are not valid UTF-8. This applies to the string data type only.

  • ValueError –

    If copy is False. This method cannot avoid a copy.

__arrow_c_array__ 

__arrow_c_array__(
    requested_schema: object | None = None,
) -> tuple[CapsuleType, CapsuleType]

Export as an Arrow array: a (schema_capsule, array_capsule) pair.

Parameters:

  • requested_schema (object | None, default: None ) –

    A capsule that holds the ArrowSchema that the caller wants. Give None to accept this array's own schema.

Returns:

Raises:

  • TypeError –

    If requested_schema is neither None nor a capsule.

__arrow_c_schema__ 

__arrow_c_schema__() -> CapsuleType

Export the Arrow schema as a PyCapsule (Arrow C Data Interface).

Returns:

  • CapsuleType –

    A capsule that holds the ArrowSchema.

to_numpy 

to_numpy() -> NDArray[Any]

Copy Zarr data to a NumPy array.

Currently all variable-length data types must be copied into NumPy buffers. No zero-copy data sharing is possible.

The string data type gives numpy.dtypes.StringDType. The bytes dtype gives an object dtype array, containing Python bytes objects.

Returns:

  • NDArray[Any] –

    A NumPy array with the same shape as this tensor.

Raises:

  • UnicodeDecodeError –

    If the decoded bytes are not valid UTF-8. This applies to the string data type only.

Examples:

>>> array[:].to_numpy()
array(['a', 'bb', 'ccc'], dtype=StringDType())

zarrista.OptionalFixedLengthTensor

Fixed-width decoded data with a validity mask.

Use to_numpy (or np.asarray/np.array) to get a numpy.ma.MaskedArray view over the underlying Rust memory.

data property 

data: FixedLengthTensor

The values, without the mask applied.

dtype property 

dtype: DataType

The Zarr data type.

mask property 

mask: FixedLengthTensor

The validity mask (bool, True = valid/present).

shape property 

shape: list[int]

The shape of the decoded region.

__array__ 

__array__(
    dtype: DTypeLike | None = None, copy: bool | None = None
) -> MaskedArray

Return a masked array, for np.asarray and np.array.

Parameters:

  • dtype (DTypeLike | None, default: None ) –

    The data type of the result. Give None to keep the tensor's own data type.

  • copy (bool | None, default: None ) –

    Whether to copy the data. Give None to let NumPy decide.

Returns:

  • MaskedArray –

    A masked array with the same shape as this tensor.

to_numpy 

to_numpy() -> MaskedArray

Return a numpy.ma.MaskedArray view over Rust memory.

NumPy's masked-array convention is the inverse of ours: True marks a masked (missing) element. Therefore this method negates the validity mask.

Returns:

  • MaskedArray –

    A masked array with the same shape and dtype as this tensor.

zarrista.OptionalVariableLengthTensor

Variable-length decoded data with a validity mask.

Not yet exposed to NumPy.

dtype property 

dtype: DataType

The Zarr data type.

shape property 

shape: list[int]

The shape of the decoded region.