zarr.abc.buffer =============== .. py:module:: zarr.abc.buffer Classes ------- .. autoapisummary:: zarr.abc.buffer.ArrayLike zarr.abc.buffer.Buffer zarr.abc.buffer.BufferPrototype zarr.abc.buffer.NDArrayLike zarr.abc.buffer.NDBuffer Module Contents --------------- .. py:class:: ArrayLike Bases: :py:obj:`Protocol` Protocol for the array-like type that underlie Buffer .. !! processed by numpydoc !! .. py:property:: dtype :type: numpy.dtype[Any] .. py:property:: ndim :type: int .. py:property:: size :type: int .. py:class:: Buffer(array_like: ArrayLike) Bases: :py:obj:`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. .. rubric:: Notes This buffer is untyped, so all indexing and sizes are in bytes. .. !! processed by numpydoc !! .. py:method:: as_array_like() -> ArrayLike 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. .. .. !! processed by numpydoc !! .. py:method:: as_buffer_like() -> zarr.core.common.BytesLike Returns the buffer as an object that implements the Python buffer protocol. :Returns: An object that implements the Python buffer protocol .. .. rubric:: Notes Might have to copy data, since the implementation uses `.as_numpy_array()`. .. !! processed by numpydoc !! .. py:method:: as_numpy_array() -> numpy.typing.NDArray[Any] :abstractmethod: Returns the buffer as a NumPy array (host memory). :Returns: NumPy array of this buffer (might be a data copy) .. .. rubric:: Notes Might have to copy data, consider using `.as_array_like()` instead. .. !! processed by numpydoc !! .. py:method:: create_zero_length() -> Self :classmethod: :abstractmethod: Create an empty buffer with length zero :Returns: New empty 0-length buffer .. .. !! processed by numpydoc !! .. py:method:: from_array_like(array_like: ArrayLike) -> Self :classmethod: 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` .. .. !! processed by numpydoc !! .. py:method:: from_buffer(buffer: Buffer) -> Self :classmethod: :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 .. .. rubric:: Notes Subclasses of `Buffer` must override this method to implement more optimal conversions that avoid copies where possible .. !! processed by numpydoc !! .. py:method:: from_bytes(bytes_like: zarr.core.common.BytesLike) -> Self :classmethod: :abstractmethod: Create a new buffer of a bytes-like object (host memory) :Parameters: **bytes_like** bytes-like object :Returns: New buffer representing `bytes_like` .. .. !! processed by numpydoc !! .. py:method:: to_bytes() -> bytes 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. .. !! processed by numpydoc !! .. py:class:: BufferPrototype Bases: :py:obj:`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. .. !! processed by numpydoc !! .. py:attribute:: buffer :type: type[Buffer] .. py:attribute:: nd_buffer :type: type[NDBuffer] .. py:class:: NDArrayLike Bases: :py:obj:`Protocol` Protocol for the nd-array-like type that underlie NDBuffer .. !! processed by numpydoc !! .. py:method:: all() -> bool .. py:method:: astype(dtype: numpy.typing.DTypeLike, order: Literal['K', 'A', 'C', 'F'] = ..., *, copy: bool = ...) -> Self .. py:method:: copy() -> Self .. py:method:: fill(value: Any) -> None .. py:method:: ravel(order: Literal['K', 'A', 'C', 'F'] = ...) -> Self .. py:method:: reshape(shape: zarr.core.common.ChunkCoords | Literal[-1], *, order: Literal['A', 'C', 'F'] = ...) -> Self .. py:method:: transpose(axes: SupportsIndex | collections.abc.Sequence[SupportsIndex] | None) -> Self .. py:method:: view(dtype: numpy.typing.DTypeLike) -> Self .. py:property:: dtype :type: numpy.dtype[Any] .. py:property:: ndim :type: int .. py:property:: shape :type: zarr.core.common.ChunkCoords .. py:property:: size :type: int .. py:class:: NDBuffer(array: NDArrayLike) 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: **array** : ndarray_like ndarray-like object that is convertible to a regular Numpy array. .. rubric:: 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. .. !! processed by numpydoc !! .. py:method:: all_equal(other: Any, equal_nan: bool = True) -> bool Compare to `other` using np.array_equal. .. !! processed by numpydoc !! .. py:method:: as_ndarray_like() -> NDArrayLike 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. .. .. !! processed by numpydoc !! .. py:method:: as_numpy_array() -> numpy.typing.NDArray[Any] :abstractmethod: 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. .. !! processed by numpydoc !! .. py:method:: as_scalar() -> ScalarType Returns the buffer as a scalar value .. !! processed by numpydoc !! .. py:method:: astype(dtype: numpy.typing.DTypeLike, order: Literal['K', 'A', 'C', 'F'] = 'K') -> Self .. py:method:: copy() -> Self .. py:method:: create(*, shape: collections.abc.Iterable[int], dtype: numpy.typing.DTypeLike, order: Literal['C', 'F'] = 'C', fill_value: Any | None = None) -> Self :classmethod: :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 .. .. rubric:: Notes A subclass can overwrite this method to create a ndarray-like object other then the default Numpy array. .. !! processed by numpydoc !! .. py:method:: empty(shape: zarr.core.common.ChunkCoords, dtype: numpy.typing.DTypeLike, order: Literal['C', 'F'] = 'C') -> Self :classmethod: 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. .. seealso:: :obj:`NDBuffer.create` Create a new buffer with some initial fill value. .. !! processed by numpydoc !! .. py:method:: fill(value: Any) -> None .. py:method:: from_ndarray_like(ndarray_like: NDArrayLike) -> Self :classmethod: Create a new buffer of a ndarray-like object :Parameters: **ndarray_like** ndarray-like object :Returns: New buffer representing `ndarray_like` .. .. !! processed by numpydoc !! .. py:method:: from_numpy_array(array_like: numpy.typing.ArrayLike) -> Self :classmethod: :abstractmethod: Create a new buffer of Numpy array-like object :Parameters: **array_like** Object that can be coerced into a Numpy array :Returns: New buffer representing `array_like` .. .. !! processed by numpydoc !! .. py:method:: reshape(newshape: zarr.core.common.ChunkCoords | Literal[-1]) -> Self .. py:method:: squeeze(axis: tuple[int, Ellipsis]) -> Self .. py:method:: transpose(axes: SupportsIndex | collections.abc.Sequence[SupportsIndex] | None) -> Self .. py:property:: byteorder :type: zarr.codecs.bytes.Endian .. py:property:: dtype :type: numpy.dtype[Any] .. py:property:: shape :type: tuple[int, Ellipsis]