document storage classes and some developer apis

src/zarr/core/common.py

@@ -151,3 +151,33 @@ def parse_order(data: Any) -> Literal["C", "F"]:
     if data in ("C", "F"):
         return cast(Literal["C", "F"], data)
     raise ValueError(f"Expected one of ('C', 'F'), got {data} instead.")
+
+
+def _inherit_docstrings(cls: type[Any]) -> type[Any]:
+    """
+    Inherit docstrings from base class
+
+    Iterate over the methods of the class and if a method is missing a docstring,
+    try to inherit one from a base class (ABC).
+
+    Parameters
+    ----------
+    cls : object
+        the class to inherit docstrings from
+
+    Returns
+    -------
+    cls
+        the class with updated docstrings
+    """
+    # Iterate over the methods of the class
+    for name, method in cls.__dict__.items():
+        # Skip if it's not a callable (method or function)
+        if callable(method):
+            # Get the corresponding method from the base class (ABC)
+            for base in cls.__bases__:
+                base_method = getattr(base, name, None)
+                if base_method and not method.__doc__:
+                    method.__doc__ = base_method.__doc__
+                    break
+    return cls

src/zarr/storage/__init__.py

@@ -1,11 +1,13 @@
 from zarr.storage.common import StoreLike, StorePath, make_store_path
 from zarr.storage.local import LocalStore
+from zarr.storage.logging import LoggingStore
 from zarr.storage.memory import MemoryStore
 from zarr.storage.remote import RemoteStore
 from zarr.storage.zip import ZipStore
 
 __all__ = [
     "LocalStore",
+    "LoggingStore",
     "MemoryStore",
     "RemoteStore",
     "StoreLike",

src/zarr/storage/local.py

@@ -9,7 +9,7 @@
 
 from zarr.abc.store import ByteRangeRequest, Store
 from zarr.core.buffer import Buffer
-from zarr.core.common import concurrent_map
+from zarr.core.common import _inherit_docstrings, concurrent_map
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Iterable
@@ -66,6 +66,7 @@ def _put(
             return f.write(view)
 
 
+@_inherit_docstrings
 class LocalStore(Store):
     """
     Local file system store.

src/zarr/storage/logging.py

@@ -9,6 +9,7 @@
 
 from zarr.abc.store import AccessMode, ByteRangeRequest, Store
 from zarr.core.buffer import Buffer
+from zarr.core.common import _inherit_docstrings
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Generator, Iterable
@@ -17,6 +18,7 @@
     from zarr.core.common import AccessModeLiteral
 
 
+@_inherit_docstrings
 class LoggingStore(Store):
     """
     Store wrapper that logs all calls to the wrapped store.

src/zarr/storage/memory.py

@@ -4,7 +4,7 @@
 
 from zarr.abc.store import ByteRangeRequest, Store
 from zarr.core.buffer import Buffer, gpu
-from zarr.core.common import concurrent_map
+from zarr.core.common import _inherit_docstrings, concurrent_map
 from zarr.storage._utils import _normalize_interval_index
 
 if TYPE_CHECKING:
@@ -14,6 +14,7 @@
     from zarr.core.common import AccessModeLiteral
 
 
+@_inherit_docstrings
 class MemoryStore(Store):
     """
     In-memory store for testing purposes.

src/zarr/storage/remote.py

@@ -6,6 +6,7 @@
 
 from zarr.abc.store import ByteRangeRequest, Store
 from zarr.core.buffer import Buffer
+from zarr.core.common import _inherit_docstrings
 from zarr.storage.common import _dereference_path
 
 if TYPE_CHECKING:
@@ -24,6 +25,7 @@
 )
 
 
+@_inherit_docstrings
 class RemoteStore(Store):
     """
     A remote Store based on FSSpec

src/zarr/storage/zip.py

@@ -9,13 +9,15 @@
 
 from zarr.abc.store import ByteRangeRequest, Store
 from zarr.core.buffer import Buffer, BufferPrototype
+from zarr.core.common import _inherit_docstrings
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Iterable
 
 ZipStoreAccessModeLiteral = Literal["r", "w", "a"]
 
 
+@_inherit_docstrings
 class ZipStore(Store):
     """
     Storage class using a ZIP file.