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: tuple[int, Ellipsis], 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: tuple[int, Ellipsis] | 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

