allow must_understand: true, and add canonical nan strings

Author: d-v-b

packages/zarr-metadata/src/zarr_metadata/v3/array.py

@@ -13,12 +13,19 @@ class ExtensionFieldV3(TypedDict, extra_items=object):  # type: ignore[call-arg]
     Required shape of any extension field on a v3 metadata document.
 
     The Zarr v3 spec permits extra keys on array and group metadata
-    documents, provided each value is an object with `must_understand`
-    set to `False`. This TypedDict captures that constraint and is used
-    as the `extra_items=` parameter on `ArrayMetadataV3` and `GroupMetadataV3`.
+    documents, provided each value is an object with a `must_understand`
+    boolean key. This TypedDict captures that constraint and is used as
+    the `extra_items=` parameter on `ArrayMetadataV3` and `GroupMetadataV3`.
+
+    `must_understand` is typed as `bool` rather than `Literal[False]` so
+    that applications which understand a particular extension can produce
+    or consume it with `must_understand: true` (signalling that readers
+    that don't recognize the extension MUST refuse to open the document).
+    The common case is still `false`, signalling that unknown readers may
+    safely ignore the field.
 
     Spec interpretation: this type follows the original Zarr v3.0 reading
-    of the spec, under which any object with `must_understand: false` is a
+    of the spec, under which any object with a `must_understand` key is a
     valid extension field. The v3.1 spec rewrite added language requiring
     extension fields to also include a `name: str` key (the "Extension
     definition" form). Under the strict v3.1 reading, real-world extension
@@ -30,7 +37,7 @@ class ExtensionFieldV3(TypedDict, extra_items=object):  # type: ignore[call-arg]
     ongoing discussion.
     """
 
-    must_understand: Literal[False]
+    must_understand: bool
 
 
 class ArrayMetadataV3(TypedDict, extra_items=ExtensionFieldV3):  # type: ignore[call-arg]

packages/zarr-metadata/src/zarr_metadata/v3/data_type/float16.py

@@ -42,8 +42,26 @@ def hex_float16(value: str) -> HexFloat16:
 the unsigned-integer representation of the IEEE 754 value).
 """
 
+CANONICAL_NAN_HEX_FLOAT16: Final = "0x7e00"
+"""Canonical hex form of the float16 NaN sentinel `"NaN"`.
+
+Per spec the named `"NaN"` sentinel denotes the float with sign=0, the
+most significant mantissa bit set, and all other mantissa bits zero
+(the IEEE 754 default quiet NaN). Other NaN bit patterns must be
+encoded with the explicit hex-string form.
+"""
+
+CANONICAL_POSITIVE_INFINITY_HEX_FLOAT16: Final = "0x7c00"
+"""Canonical hex form of the float16 `"Infinity"` sentinel."""
+
+CANONICAL_NEGATIVE_INFINITY_HEX_FLOAT16: Final = "0xfc00"
+"""Canonical hex form of the float16 `"-Infinity"` sentinel."""
+
 
 __all__ = [
+    "CANONICAL_NAN_HEX_FLOAT16",
+    "CANONICAL_NEGATIVE_INFINITY_HEX_FLOAT16",
+    "CANONICAL_POSITIVE_INFINITY_HEX_FLOAT16",
     "FLOAT16_DATA_TYPE_NAME",
     "Float16DataTypeName",
     "Float16FillValue",

packages/zarr-metadata/src/zarr_metadata/v3/data_type/float32.py

@@ -42,8 +42,26 @@ def hex_float32(value: str) -> HexFloat32:
 encoding the unsigned-integer representation of the IEEE 754 value).
 """
 
+CANONICAL_NAN_HEX_FLOAT32: Final = "0x7fc00000"
+"""Canonical hex form of the float32 NaN sentinel `"NaN"`.
+
+Per spec the named `"NaN"` sentinel denotes the float with sign=0, the
+most significant mantissa bit set, and all other mantissa bits zero
+(the IEEE 754 default quiet NaN). Other NaN bit patterns must be
+encoded with the explicit hex-string form.
+"""
+
+CANONICAL_POSITIVE_INFINITY_HEX_FLOAT32: Final = "0x7f800000"
+"""Canonical hex form of the float32 `"Infinity"` sentinel."""
+
+CANONICAL_NEGATIVE_INFINITY_HEX_FLOAT32: Final = "0xff800000"
+"""Canonical hex form of the float32 `"-Infinity"` sentinel."""
+
 
 __all__ = [
+    "CANONICAL_NAN_HEX_FLOAT32",
+    "CANONICAL_NEGATIVE_INFINITY_HEX_FLOAT32",
+    "CANONICAL_POSITIVE_INFINITY_HEX_FLOAT32",
     "FLOAT32_DATA_TYPE_NAME",
     "Float32DataTypeName",
     "Float32FillValue",

packages/zarr-metadata/src/zarr_metadata/v3/data_type/float64.py

@@ -43,8 +43,26 @@ def hex_float64(value: str) -> HexFloat64:
 value).
 """
 
+CANONICAL_NAN_HEX_FLOAT64: Final = "0x7ff8000000000000"
+"""Canonical hex form of the float64 NaN sentinel `"NaN"`.
+
+Per spec the named `"NaN"` sentinel denotes the float with sign=0, the
+most significant mantissa bit set, and all other mantissa bits zero
+(the IEEE 754 default quiet NaN). Other NaN bit patterns must be
+encoded with the explicit hex-string form.
+"""
+
+CANONICAL_POSITIVE_INFINITY_HEX_FLOAT64: Final = "0x7ff0000000000000"
+"""Canonical hex form of the float64 `"Infinity"` sentinel."""
+
+CANONICAL_NEGATIVE_INFINITY_HEX_FLOAT64: Final = "0xfff0000000000000"
+"""Canonical hex form of the float64 `"-Infinity"` sentinel."""
+
 
 __all__ = [
+    "CANONICAL_NAN_HEX_FLOAT64",
+    "CANONICAL_NEGATIVE_INFINITY_HEX_FLOAT64",
+    "CANONICAL_POSITIVE_INFINITY_HEX_FLOAT64",
     "FLOAT64_DATA_TYPE_NAME",
     "Float64DataTypeName",
     "Float64FillValue",