zarr.abc.buffer#

Classes#

`ArrayLike`	Protocol for the array-like type that underlie Buffer
`Buffer`	A flat contiguous memory block
`BufferPrototype`	Prototype of the Buffer and NDBuffer class
`NDArrayLike`	Protocol for the nd-array-like type that underlie NDBuffer
`NDBuffer`	An n-dimensional memory block

Module Contents#

class zarr.abc.buffer.ArrayLike[source]#

Bases: Protocol

Protocol for the array-like type that underlie Buffer

property dtype: numpy.dtype[Any]#

property ndim: int#

property size: int#

class zarr.abc.buffer.Buffer(array_like: ArrayLike)[source]#

Bases: abc.ABC

A flat contiguous memory block

We use Buffer throughout Zarr to represent a contiguous block of memory.

A Buffer is backed by a underlying array-like instance that represents the memory. The memory type is unspecified; can be regular host memory, CUDA device memory, or something else. The only requirement is that the array-like instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

array_like: array-like object that must be 1-dim, contiguous, and byte dtype.

Notes

This buffer is untyped, so all indexing and sizes are in bytes.

as_array_like() → ArrayLike[source]#

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

The underlying 1d array such as a NumPy or CuPy array.

as_buffer_like() → zarr.core.common.BytesLike[source]#

Returns the buffer as an object that implements the Python buffer protocol.

Returns:

An object that implements the Python buffer protocol

Notes

Might have to copy data, since the implementation uses .as_numpy_array().

abstract as_numpy_array() → numpy.typing.NDArray[Any][source]#

Returns the buffer as a NumPy array (host memory).

Returns:

NumPy array of this buffer (might be a data copy)

Notes

Might have to copy data, consider using .as_array_like() instead.

classmethod create_zero_length() → Self[source]#

Abstractmethod:

Create an empty buffer with length zero

Returns:

New empty 0-length buffer

classmethod from_array_like(array_like: ArrayLike) → Self[source]#

Create a new buffer of an array-like object

Parameters:

array_like: array-like object that must be 1-dim, contiguous, and byte dtype.

Returns:

New buffer representing array_like

classmethod from_buffer(buffer: Buffer) → Self[source]#

Abstractmethod:

Create a new buffer of an existing Buffer

This is useful if you want to ensure that an existing buffer is of the correct subclass of Buffer. E.g., MemoryStore uses this to return a buffer instance of the subclass specified by its BufferPrototype argument.

Typically, this only copies data if the data has to be moved between memory types, such as from host to device memory.

Parameters:

buffer: buffer object.

Returns:

A new buffer representing the content of the input buffer

Notes

Subclasses of Buffer must override this method to implement more optimal conversions that avoid copies where possible

classmethod from_bytes(bytes_like: zarr.core.common.BytesLike) → Self[source]#

Abstractmethod:

Create a new buffer of a bytes-like object (host memory)

Parameters:

bytes_like: bytes-like object

Returns:

New buffer representing bytes_like

to_bytes() → bytes[source]#

Returns the buffer as bytes (host memory).

Returns:

bytes of this buffer (data copy)

Warning

Will always copy data, only use this method for small buffers such as metadata buffers. If possible, use .as_numpy_array() or .as_array_like() instead.

class zarr.abc.buffer.BufferPrototype[source]#

Bases: NamedTuple

Prototype of the Buffer and NDBuffer class

The protocol must be pickable.

Attributes:

buffer: The Buffer class to use when Zarr needs to create new Buffer.
nd_buffer: The NDBuffer class to use when Zarr needs to create new NDBuffer.

buffer: type[Buffer]#

nd_buffer: type[NDBuffer]#

class zarr.abc.buffer.NDArrayLike[source]#

Bases: Protocol

Protocol for the nd-array-like type that underlie NDBuffer

all() → bool[source]#

astype( dtype: numpy.typing.DTypeLike, order: Literal['K', 'A', 'C', 'F'] = ..., *, copy: bool = ..., ) → Self[source]#

copy() → Self[source]#

fill(value: Any) → None[source]#

ravel(order: Literal['K', 'A', 'C', 'F'] = ...) → Self[source]#

reshape( shape: zarr.core.common.ChunkCoords | Literal[-1], *, order: Literal['A', 'C', 'F'] = ..., ) → Self[source]#

transpose( axes: SupportsIndex | collections.abc.Sequence[SupportsIndex] | None, ) → Self[source]#

view(dtype: numpy.typing.DTypeLike) → Self[source]#

property dtype: numpy.dtype[Any]#

property ndim: int#

property shape: zarr.core.common.ChunkCoords#

property size: int#

class zarr.abc.buffer.NDBuffer(array: NDArrayLike)[source]#

An n-dimensional memory block

We use NDBuffer throughout Zarr to represent a n-dimensional memory block.

A NDBuffer is backed by a underlying ndarray-like instance that represents the memory. The memory type is unspecified; can be regular host memory, CUDA device memory, or something else. The only requirement is that the ndarray-like instance can be copied/converted to a regular Numpy array (host memory).

Parameters:

arrayndarray_like: ndarray-like object that is convertible to a regular Numpy array.

Notes

The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer is a special case of NDBuffer where dim=1, stride=1, and dtype=”B”. However, in order to use Python’s type system to differentiate between the contiguous Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the two classes separate.

all_equal(other: Any, equal_nan: bool = True) → bool[source]#: Compare to other using np.array_equal.

as_ndarray_like() → NDArrayLike[source]#

Returns the underlying array (host or device memory) of this buffer

This will never copy data.

Returns:

The underlying array such as a NumPy or CuPy array.

abstract as_numpy_array() → numpy.typing.NDArray[Any][source]#

Returns the buffer as a NumPy array (host memory).

Returns:

NumPy array of this buffer (might be a data copy)

Warning

Might have to copy data, consider using .as_ndarray_like() instead.

as_scalar() → ScalarType[source]#: Returns the buffer as a scalar value

astype( dtype: numpy.typing.DTypeLike, order: Literal['K', 'A', 'C', 'F'] = 'K', ) → Self[source]#

copy() → Self[source]#

classmethod create( *, shape: collections.abc.Iterable[int], dtype: numpy.typing.DTypeLike, order: Literal['C', 'F'] = 'C', fill_value: Any | None = None, ) → Self[source]#

Abstractmethod:

Create a new buffer and its underlying ndarray-like object

Parameters:

shape: The shape of the buffer and its underlying ndarray-like object
dtype: The datatype of the buffer and its underlying ndarray-like object
order: Whether to store multi-dimensional data in row-major (C-style) or column-major (Fortran-style) order in memory.
fill_value: If not None, fill the new buffer with a scalar value.

Returns:

New buffer representing a new ndarray_like object

Notes

A subclass can overwrite this method to create a ndarray-like object other then the default Numpy array.

classmethod empty( shape: zarr.core.common.ChunkCoords, dtype: numpy.typing.DTypeLike, order: Literal['C', 'F'] = 'C', ) → Self[source]#

Create an empty buffer with the given shape, dtype, and order.

This method can be faster than NDBuffer.create because it doesn’t have to initialize the memory used by the underlying ndarray-like object.

Parameters:

shape: The shape of the buffer and its underlying ndarray-like object
dtype: The datatype of the buffer and its underlying ndarray-like object
order: Whether to store multi-dimensional data in row-major (C-style) or column-major (Fortran-style) order in memory.

Returns:

buffer: New buffer representing a new ndarray_like object with empty data.

zarr.abc.buffer#

Classes#

Module Contents#

This Page