bring in update codec abc

Author: d-v-b

src/zarr/abc/codec.py

@@ -2,13 +2,20 @@
 
 from abc import abstractmethod
 from collections.abc import Mapping
-from typing import TYPE_CHECKING, Generic, TypeGuard, TypeVar
+from typing import (
+    TYPE_CHECKING,
+    Generic,
+    Literal,
+    TypedDict,
+    TypeVar,
+    overload,
+)
 
-from typing_extensions import ReadOnly, TypedDict
+from typing_extensions import ReadOnly
 
 from zarr.abc.metadata import Metadata
 from zarr.core.buffer import Buffer, NDBuffer
-from zarr.core.common import ChunkCoords, NamedConfig, concurrent_map
+from zarr.core.common import ChunkCoords, NamedConfig, ZarrFormat, concurrent_map
 from zarr.core.config import config
 
 if TYPE_CHECKING:
@@ -41,22 +48,16 @@
 
 
 class CodecJSON_V2(TypedDict, Generic[TName]):
-    """The JSON representation of a codec for Zarr V2"""
-
     id: ReadOnly[TName]
 
 
-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]):
@@ -181,6 +182,34 @@ async def encode(
         """
         return await _batching_helper(self._encode_single, chunks_and_specs)
 
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> CodecJSON_V2[str]: ...
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> NamedConfig[str, Mapping[str, object]]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> CodecJSON_V2[str] | NamedConfig[str, Mapping[str, object]]:
+        raise NotImplementedError
+
+    @classmethod
+    def _from_json_v2(cls, data: CodecJSON) -> Self:
+        raise NotImplementedError
+
+    @classmethod
+    def _from_json_v3(cls, data: CodecJSON) -> Self:
+        raise NotImplementedError
+
+    @classmethod
+    def from_json(cls, data: CodecJSON, zarr_format: ZarrFormat) -> Self:
+        if zarr_format == 2:
+            return cls._from_json_v2(data)
+        elif zarr_format == 3:
+            return cls._from_json_v3(data)
+        raise ValueError(
+            f"Unsupported Zarr format {zarr_format}. Expected 2 or 3."
+        )  # pragma: no cover
+
 
 class ArrayArrayCodec(BaseCodec[NDBuffer, NDBuffer]):
     """Base class for array-to-array codecs."""
@@ -471,3 +500,7 @@ async def wrap(chunk: CodecInput | None, chunk_spec: ArraySpec) -> CodecOutput |
         return await func(chunk, chunk_spec)
 
     return wrap
+
+
+# Raised when a codec JSON data is invalid
+class CodecValidationError(ValueError): ...