add some docstrings and fix sharding JSON check

Author: d-v-b

src/zarr/codecs/__init__.py

@@ -64,22 +64,31 @@
 
 register_codec("numcodecs.bz2", BZ2, qualname="zarr.codecs.numcodecs.BZ2")
 register_codec("bz2", BZ2, qualname="zarr.codecs.numcodecs.BZ2")
+
 register_codec("numcodecs.crc32", CRC32, qualname="zarr.codecs.numcodecs.CRC32")
 register_codec("crc32", CRC32, qualname="zarr.codecs.numcodecs.CRC32")
+
 register_codec("numcodecs.lz4", LZ4, qualname="zarr.codecs.numcodecs.LZ4")
 register_codec("lz4", LZ4, qualname="zarr.codecs.numcodecs.LZ4")
+
 register_codec("numcodecs.lzma", LZMA, qualname="zarr.codecs.numcodecs.LZMA")
 register_codec("lzma", LZMA, qualname="zarr.codecs.numcodecs.LZMA")
+
 register_codec("numcodecs.zfpy", ZFPY, qualname="zarr.codecs.numcodecs.ZFPY")
 register_codec("zfpy", ZFPY, qualname="zarr.codecs.numcodecs.ZFPY")
+
 register_codec("numcodecs.adler32", Adler32, qualname="zarr.codecs.numcodecs.Adler32")
 register_codec("adler32", Adler32, qualname="zarr.codecs.numcodecs.Adler32")
+
 register_codec("numcodecs.astype", AsType, qualname="zarr.codecs.numcodecs.AsType")
 register_codec("astype", AsType, qualname="zarr.codecs.numcodecs.AsType")
+
 register_codec("numcodecs.bitround", BitRound, qualname="zarr.codecs.numcodecs.BitRound")
 register_codec("bitround", BitRound, qualname="zarr.codecs.numcodecs.BitRound")
+
 register_codec("numcodecs.delta", Delta, qualname="zarr.codecs.numcodecs.Delta")
 register_codec("delta", Delta, qualname="zarr.codecs.numcodecs.Delta")
+
 register_codec(
     "numcodecs.fixedscaleoffset",
     FixedScaleOffset,
@@ -90,20 +99,26 @@
     FixedScaleOffset,
     qualname="zarr.codecs.numcodecs.FixedScaleOffset",
 )
+
 register_codec("numcodecs.fletcher32", Fletcher32, qualname="zarr.codecs.numcodecs.Fletcher32")
 register_codec("fletcher32", Fletcher32, qualname="zarr.codecs.numcodecs.Fletcher32")
+
 register_codec(
     "numcodecs.jenkins_lookup3", JenkinsLookup3, qualname="zarr.codecs.numcodecs.JenkinsLookup3"
 )
 register_codec("jenkins_lookup3", JenkinsLookup3, qualname="zarr.codecs.numcodecs.JenkinsLookup3")
-register_codec("numcodecs.pcodec", PCodec, qualname="zarr.codecs.numcodecs.pcodec")
+
 register_codec("pcodec", PCodec, qualname="zarr.codecs.numcodecs.PCodec")
 register_codec("numcodecs.pcodec", PCodec, qualname="zarr.codecs.numcodecs.PCodec")
+
 register_codec("numcodecs.packbits", PackBits, qualname="zarr.codecs.numcodecs.PackBits")
 register_codec("packbits", PackBits, qualname="zarr.codecs.numcodecs.PackBits")
+
 register_codec("numcodecs.quantize", Quantize, qualname="zarr.codecs.numcodecs.Quantize")
 register_codec("quantize", Quantize, qualname="zarr.codecs.numcodecs.Quantize")
+
 register_codec("numcodecs.shuffle", Shuffle, qualname="zarr.codecs.numcodecs.Shuffle")
 register_codec("shuffle", Shuffle, qualname="zarr.codecs.numcodecs.Shuffle")
+
 register_codec("numcodecs.zlib", Zlib, qualname="zarr.codecs.numcodecs.Zlib")
 register_codec("zlib", Zlib, qualname="zarr.codecs.numcodecs.Zlib")

src/zarr/codecs/numcodecs/_codecs.py

@@ -460,6 +460,12 @@ def compute_encoded_size(self, input_byte_length: int, chunk_spec: ArraySpec) ->
 
 # bytes-to-bytes codecs
 class Blosc(_NumcodecsBytesBytesCodec):
+    """
+    A legacy wrapper used to provide a Zarr V3 API for the numcodecs blosc codec.
+
+    Use `zarr.codecs.blosc.BloscCodec` instead.
+    """
+
     codec_name = "numcodecs.blosc"
     _codec_id = "blosc"
 
@@ -486,6 +492,12 @@ def to_json(self, zarr_format: ZarrFormat) -> LZ4JSON_V2 | LZ4JSON_V3:
 
 
 class Zstd(_NumcodecsBytesBytesCodec):
+    """
+    A legacy wrapper used to provide a Zarr V3 API for the numcodecs zstd codec.
+
+    Use `zarr.codecs.zstd.ZStdCodec` instead.
+    """
+
     codec_name = "numcodecs.zstd"
     _codec_id = "zstd"
     codec_config: ZstdConfig_V3
@@ -513,6 +525,12 @@ def to_json(self, zarr_format: ZarrFormat) -> ZlibJSON_V2 | ZlibJSON_V3:
 
 
 class GZip(_NumcodecsBytesBytesCodec):
+    """
+    A legacy wrapper used to provide a Zarr V3 API for the numcodecs gzip codec.
+
+    Use `zarr.codecs.gzip.GzipCodec` instead.
+    """
+
     codec_name = "numcodecs.gzip"
     _codec_id = "gzip"
     codec_config: GZipConfig

src/zarr/codecs/sharding.py

@@ -132,14 +132,19 @@ def parse_index_location(data: object) -> ShardingCodecIndexLocation:
 
 
 def check_json_v2(data: object) -> TypeGuard[ShardingJSON_V2]:
+    required_keys = {"id", "codecs", "chunk_shape", "index_codecs"}
+    optional_keys = {"index_location"}
     return (
         isinstance(data, Mapping)
-        and set(data.keys()) == {"id", "codecs", "chunk_shape"}
+        and required_keys.issubset(set(data.keys()))
+        and set(data.keys()).issubset(required_keys | optional_keys)
         and data["id"] == "sharding_indexed"
         and isinstance(data["chunk_shape"], Sequence)
         and not isinstance(data["chunk_shape"], str)
         and isinstance(data["codecs"], Sequence)
         and not isinstance(data["codecs"], str)
+        and isinstance(data["index_codecs"], Sequence)
+        and not isinstance(data["index_codecs"], str)
     )
 
 

src/zarr/codecs/transpose.py

@@ -49,7 +49,7 @@ class TransposeJSON_V3(NamedRequiredConfig[Literal["transpose"], TransposeConfig
 def check_json_v2(data: object) -> TypeGuard[TransposeJSON_V2]:
     return (
         isinstance(data, Mapping)
-        and set(data.keys()) == {"id", "configuration"}
+        and set(data.keys()) == {"id", "order"}
         and data["id"] == "transpose"
         and isinstance(data["order"], Sequence)
         and not isinstance(data["order"], str)