zarr.buffer.cpu =============== .. py:module:: zarr.buffer.cpu Attributes ---------- .. autoapisummary:: zarr.buffer.cpu.buffer_prototype Classes ------- .. autoapisummary:: zarr.buffer.cpu.Buffer zarr.buffer.cpu.NDBuffer Functions --------- .. autoapisummary:: zarr.buffer.cpu.as_numpy_array_wrapper zarr.buffer.cpu.numpy_buffer_prototype Module Contents --------------- .. py:class:: Buffer(array_like: zarr.core.buffer.core.ArrayLike) Bases: :py:obj:`zarr.core.buffer.core.Buffer` 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] 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: 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: zarr.core.buffer.core.Buffer) -> Self :classmethod: 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: 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:: NDBuffer(array: zarr.core.buffer.core.NDArrayLike) Bases: :py:obj:`zarr.core.buffer.core.NDBuffer` 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 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] 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: 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: 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] .. py:function:: as_numpy_array_wrapper(func: collections.abc.Callable[[numpy.typing.NDArray[Any]], bytes], buf: zarr.core.buffer.core.Buffer, prototype: zarr.core.buffer.core.BufferPrototype) -> zarr.core.buffer.core.Buffer Converts the input of `func` to a numpy array and the output back to `Buffer`. This function is useful when calling a `func` that only support host memory such as `GZip.decode` and `Blosc.decode`. In this case, use this wrapper to convert the input `buf` to a Numpy array and convert the result back into a `Buffer`. :Parameters: **func** The callable that will be called with the converted `buf` as input. `func` must return bytes, which will be converted into a `Buffer` before returned. **buf** The buffer that will be converted to a Numpy array before given as input to `func`. **prototype** The prototype of the output buffer. :Returns: The result of `func` converted to a `Buffer` .. .. !! processed by numpydoc !! .. py:function:: numpy_buffer_prototype() -> zarr.core.buffer.core.BufferPrototype .. py:data:: buffer_prototype