Merge branch 'main' of https://github.com/zarr-developers/zarr-python into feat/v2-v3-codecs

Author: d-v-b

.github/workflows/releases.yml

@@ -36,7 +36,7 @@ jobs:
     needs: [build_artifacts]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v5
         with:
           name: releases
           path: dist
@@ -51,7 +51,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v5
         with:
           name: releases
           path: dist

changes/3371.misc.rst

@@ -0,0 +1 @@
+Ensure that tests for executable examples are run in a fresh python environment.

changes/3372.misc.rst

@@ -0,0 +1,2 @@
+Make certain imports in ``zarr.abc.store`` local to method definitions. This minimizes the risk of
+circular imports when adding new classes to ``zarr.abc.store``.

codecov.yml

@@ -3,6 +3,7 @@ coverage:
     patch:
       default:
         target: auto
+        informational: true
     project:
       default:
         target: auto

src/zarr/abc/codec.py

@@ -60,13 +60,13 @@ def _check_codecjson_v2(data: object) -> TypeGuard[CodecJSON_V2[str]]:
     return isinstance(data, Mapping) and "id" in data and isinstance(data["id"], str)
 
 
-CodecConfig_V3 = NamedConfig[str, Mapping[str, object]]
+CodecJSON_V3 = str | NamedConfig[str, Mapping[str, object]]
+"""The JSON representation of a codec for Zarr V3."""
 
-CodecJSON_V3 = str | CodecConfig_V3
-
-# The widest type we will accept for a codec JSON
+# The widest type we will *accept* for a codec JSON
 # This covers v2 and v3
 CodecJSON = str | Mapping[str, object]
+"""The widest type of JSON-like input that could specify a codec."""
 
 
 class BaseCodec(Metadata, Generic[CodecInput, CodecOutput]):

src/zarr/abc/numcodec.py

@@ -6,18 +6,65 @@
 class Numcodec(Protocol):
     """
     A protocol that models the ``numcodecs.abc.Codec`` interface.
+
+    This protocol should be considered experimental. Expect the type annotations for ``buf`` and
+    ``out`` to narrow in the future.
     """
 
     codec_id: str
 
-    def encode(self, buf: Any) -> Any: ...
+    def encode(self, buf: Any) -> Any:
+        """Encode data from ``buf``.
+
+        Parameters
+        ----------
+        buf : Any
+            Data to be encoded.
+
+        Returns
+        -------
+        enc: Any
+            Encoded data.
+        """
+        ...
 
-    def decode(self, buf: Any, out: Any | None = None) -> Any: ...
+    def decode(self, buf: Any, out: Any | None = None) -> Any:
+        """
+        Decode data in ``buf``.
 
-    def get_config(self) -> Any: ...
+        Parameters
+        ----------
+        buf : Any
+            Encoded data.
+        out : Any
+            Writeable buffer to store decoded data. If provided, this buffer must
+            be exactly the right size to store the decoded data.
+
+        Returns
+        -------
+        dec : Any
+            Decoded data.
+        """
+        ...
+
+    def get_config(self) -> Any:
+        """
+        Return a JSON-serializable configuration dictionary for this
+        codec. Must include an ``'id'`` field with the codec identifier.
+        """
+        ...
 
     @classmethod
-    def from_config(cls, config: Any) -> Self: ...
+    def from_config(cls, config: Any) -> Self:
+        """
+        Instantiate a codec from a configuration dictionary.
+
+        Parameters
+        ----------
+        config : Any
+            A configuration dictionary for this codec.
+        """
+        ...
 
 
 def _is_numcodec_cls(obj: object) -> TypeGuard[type[Numcodec]]:

src/zarr/abc/store.py

@@ -435,6 +435,7 @@ async def getsize(self, key: str) -> int:
         # Note to implementers: this default implementation is very inefficient since
         # it requires reading the entire object. Many systems will have ways to get the
         # size of an object without reading it.
+        # avoid circular import
         from zarr.core.buffer.core import default_buffer_prototype
 
         value = await self.get(key, prototype=default_buffer_prototype())
@@ -475,6 +476,8 @@ async def getsize_prefix(self, prefix: str) -> int:
         # on to getting sizes. Ideally we would overlap those two, which should
         # improve tail latency and might reduce memory pressure (since not all keys
         # would be in memory at once).
+
+        # avoid circular import
         from zarr.core.common import concurrent_map
         from zarr.core.config import config
 

src/zarr/core/_info.py

@@ -5,7 +5,8 @@
 from typing import TYPE_CHECKING, Literal
 
 if TYPE_CHECKING:
-    from zarr.abc.codec import ArrayArrayCodec, ArrayBytesCodec, BytesBytesCodec, Numcodec
+    from zarr.abc.codec import ArrayArrayCodec, ArrayBytesCodec, BytesBytesCodec
+    from zarr.abc.numcodec import Numcodec
     from zarr.core.common import ZarrFormat
     from zarr.core.dtype.wrapper import TBaseDType, TBaseScalar, ZDType
 

tests/test_examples.py

@@ -72,7 +72,9 @@ def test_scripts_can_run(script_path: Path, tmp_path: Path) -> None:
     # and then test its behavior.
     # This allows the example to be useful to users who don't have Zarr installed, but also testable.
     resave_script(script_path, dest_path)
-    result = subprocess.run(["uv", "run", str(dest_path)], capture_output=True, text=True)
+    result = subprocess.run(
+        ["uv", "run", "--refresh", str(dest_path)], capture_output=True, text=True
+    )
     assert result.returncode == 0, (
         f"Script at {script_path} failed to run. Output: {result.stdout} Error: {result.stderr}"
     )