zarr.abc.store
==============

.. py:module:: zarr.abc.store


Classes
-------

.. autoapisummary::

   zarr.abc.store.ByteGetter
   zarr.abc.store.ByteSetter
   zarr.abc.store.Store


Functions
---------

.. autoapisummary::

   zarr.abc.store.set_or_delete


Module Contents
---------------

.. py:class:: ByteGetter

   Bases: :py:obj:`Protocol`


   
   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing).

   For example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto[T](Protocol):
           def meth(self) -> T:
               ...















   ..
       !! processed by numpydoc !!

   .. py:method:: get(prototype: zarr.core.buffer.BufferPrototype, byte_range: ByteRequest | None = None) -> zarr.core.buffer.Buffer | None
      :async:



.. py:class:: ByteSetter

   Bases: :py:obj:`Protocol`


   
   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing).

   For example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto[T](Protocol):
           def meth(self) -> T:
               ...















   ..
       !! processed by numpydoc !!

   .. py:method:: delete() -> None
      :async:



   .. py:method:: get(prototype: zarr.core.buffer.BufferPrototype, byte_range: ByteRequest | None = None) -> zarr.core.buffer.Buffer | None
      :async:



   .. py:method:: set(value: zarr.core.buffer.Buffer, byte_range: ByteRequest | None = None) -> None
      :async:



   .. py:method:: set_if_not_exists(default: zarr.core.buffer.Buffer) -> None
      :async:



.. py:class:: Store(*, read_only: bool = False)

   Bases: :py:obj:`abc.ABC`


   
   Abstract base class for Zarr stores.
















   ..
       !! processed by numpydoc !!

   .. py:method:: clear() -> None
      :async:


      
      Clear the store.

      Remove all keys and values from the store.















      ..
          !! processed by numpydoc !!


   .. py:method:: close() -> None

      
      Close the store.
















      ..
          !! processed by numpydoc !!


   .. py:method:: delete(key: str) -> None
      :abstractmethod:

      :async:


      
      Remove a key from the store


      :Parameters:

          **key** : str
              ..














      ..
          !! processed by numpydoc !!


   .. py:method:: delete_dir(prefix: str) -> None
      :async:


      
      Remove all keys and prefixes in the store that begin with a given prefix.
















      ..
          !! processed by numpydoc !!


   .. py:method:: exists(key: str) -> bool
      :abstractmethod:

      :async:


      
      Check if a key exists in the store.


      :Parameters:

          **key** : str
              ..



      :Returns:

          bool
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: get(key: str, prototype: zarr.core.buffer.BufferPrototype, byte_range: ByteRequest | None = None) -> zarr.core.buffer.Buffer | None
      :abstractmethod:

      :async:


      
      Retrieve the value associated with a given key.


      :Parameters:

          **key** : str
              ..

          **prototype** : BufferPrototype
              The prototype of the output buffer. Stores may support a default buffer prototype.

          **byte_range** : ByteRequest, optional
              ByteRequest may be one of the following. If not provided, all data associated with the key is retrieved.
              - RangeByteRequest(int, int): Request a specific range of bytes in the form (start, end). The end is exclusive. If the given range is zero-length or starts after the end of the object, an error will be returned. Additionally, if the range ends after the end of the object, the entire remainder of the object will be returned. Otherwise, the exact requested range will be returned.
              - OffsetByteRequest(int): Request all bytes starting from a given byte offset. This is equivalent to bytes={int}- as an HTTP header.
              - SuffixByteRequest(int): Request the last int bytes. Note that here, int is the size of the request, not the byte offset. This is equivalent to bytes=-{int} as an HTTP header.



      :Returns:

          Buffer
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: get_partial_values(prototype: zarr.core.buffer.BufferPrototype, key_ranges: collections.abc.Iterable[tuple[str, ByteRequest | None]]) -> list[zarr.core.buffer.Buffer | None]
      :abstractmethod:

      :async:


      
      Retrieve possibly partial values from given key_ranges.


      :Parameters:

          **prototype** : BufferPrototype
              The prototype of the output buffer. Stores may support a default buffer prototype.

          **key_ranges** : Iterable[tuple[str, tuple[int | None, int | None]]]
              Ordered set of key, range pairs, a key may occur multiple times with different ranges



      :Returns:

          list of values, in the order of the key_ranges, may contain null/none for missing keys
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: getsize(key: str) -> int
      :async:


      
      Return the size, in bytes, of a value in a Store.


      :Parameters:

          **key** : str
              ..



      :Returns:

          **nbytes** : int
              The size of the value (in bytes).




      :Raises:

          FileNotFoundError
              When the given key does not exist in the store.







      ..
          !! processed by numpydoc !!


   .. py:method:: getsize_prefix(prefix: str) -> int
      :async:


      
      Return the size, in bytes, of all values under a prefix.


      :Parameters:

          **prefix** : str
              The prefix of the directory to measure.



      :Returns:

          **nbytes** : int
              The sum of the sizes of the values in the directory (in bytes).







      .. seealso::

          
          :obj:`zarr.Array.nbytes_stored`
              ..
          :obj:`Store.getsize`
              ..
          
      .. rubric:: Notes

      ``getsize_prefix`` is just provided as a potentially faster alternative to
      listing all the keys under a prefix calling :meth:`Store.getsize` on each.

      In general, ``prefix`` should be the path of an Array or Group in the Store.
      Implementations may differ on the behavior when some other ``prefix``
      is provided.



      ..
          !! processed by numpydoc !!


   .. py:method:: is_empty(prefix: str) -> bool
      :async:


      
      Check if the directory is empty.


      :Parameters:

          **prefix** : str
              Prefix of keys to check.



      :Returns:

          bool
              True if the store is empty, False otherwise.











      ..
          !! processed by numpydoc !!


   .. py:method:: list() -> collections.abc.AsyncIterator[str]
      :abstractmethod:


      
      Retrieve all keys in the store.





      :Returns:

          AsyncIterator[str]
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: list_dir(prefix: str) -> collections.abc.AsyncIterator[str]
      :abstractmethod:


      
      Retrieve all keys and prefixes with a given prefix and which do not contain the character
      “/” after the given prefix.


      :Parameters:

          **prefix** : str
              ..



      :Returns:

          AsyncIterator[str]
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: list_prefix(prefix: str) -> collections.abc.AsyncIterator[str]
      :abstractmethod:


      
      Retrieve all keys in the store that begin with a given prefix. Keys are returned relative
      to the root of the store.


      :Parameters:

          **prefix** : str
              ..



      :Returns:

          AsyncIterator[str]
              ..











      ..
          !! processed by numpydoc !!


   .. py:method:: open(*args: Any, **kwargs: Any) -> Self
      :classmethod:

      :async:


      
      Create and open the store.


      :Parameters:

          **\*args** : Any
              Positional arguments to pass to the store constructor.

          **\*\*kwargs** : Any
              Keyword arguments to pass to the store constructor.



      :Returns:

          Store
              The opened store instance.











      ..
          !! processed by numpydoc !!


   .. py:method:: set(key: str, value: zarr.core.buffer.Buffer) -> None
      :abstractmethod:

      :async:


      
      Store a (key, value) pair.


      :Parameters:

          **key** : str
              ..

          **value** : Buffer
              ..














      ..
          !! processed by numpydoc !!


   .. py:method:: set_if_not_exists(key: str, value: zarr.core.buffer.Buffer) -> None
      :async:


      
      Store a key to ``value`` if the key is not already present.


      :Parameters:

          **key** : str
              ..

          **value** : Buffer
              ..














      ..
          !! processed by numpydoc !!


   .. py:method:: set_partial_values(key_start_values: collections.abc.Iterable[tuple[str, int, zarr.core.common.BytesLike]]) -> None
      :abstractmethod:

      :async:


      
      Store values at a given key, starting at byte range_start.


      :Parameters:

          **key_start_values** : list[tuple[str, int, BytesLike]]
              set of key, range_start, values triples, a key may occur multiple times with different
              range_starts, range_starts (considering the length of the respective values) must not
              specify overlapping ranges for the same key














      ..
          !! processed by numpydoc !!


   .. py:property:: read_only
      :type: bool


      
      Is the store read-only?
















      ..
          !! processed by numpydoc !!


   .. py:property:: supports_deletes
      :type: bool

      :abstractmethod:


      
      Does the store support deletes?
















      ..
          !! processed by numpydoc !!


   .. py:property:: supports_listing
      :type: bool

      :abstractmethod:


      
      Does the store support listing?
















      ..
          !! processed by numpydoc !!


   .. py:property:: supports_partial_writes
      :type: bool

      :abstractmethod:


      
      Does the store support partial writes?
















      ..
          !! processed by numpydoc !!


   .. py:property:: supports_writes
      :type: bool

      :abstractmethod:


      
      Does the store support writes?
















      ..
          !! processed by numpydoc !!


.. py:function:: set_or_delete(byte_setter: ByteSetter, value: zarr.core.buffer.Buffer | None) -> None
   :async:


   
   Set or delete a value in a byte setter


   :Parameters:

       **byte_setter** : ByteSetter
           ..

       **value** : Buffer | None
           ..











   .. rubric:: Notes

   If value is None, the key will be deleted.



   ..
       !! processed by numpydoc !!

