zarr-cm 0.1.0__tar.gz → 0.2.0__tar.gz

{zarr_cm-0.1.0 → zarr_cm-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zarr-cm
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python implementation of Zarr Conventions Metadata
 Project-URL: Homepage, https://github.com/zarr-conventions/zarr-cm
 Project-URL: Bug Tracker, https://github.com/zarr-conventions/zarr-cm/issues

zarr_cm-0.2.0/docs/api.md

@@ -0,0 +1,42 @@
+# API Reference
+
+## Multi-convention
+
+<!-- prettier-ignore -->
+::: zarr_cm
+    options:
+      members:
+        - CONVENTION_NAMES
+        - ALL_CONVENTION_KEYS
+        - MultiConventionAttrs
+        - create_many
+        - validate_many
+        - validate_all
+        - insert_many
+        - extract_many
+        - extract_all
+
+## Core
+
+<!-- prettier-ignore -->
+::: zarr_cm._core
+
+## geo-proj
+
+::: zarr_cm.geo_proj
+
+## spatial
+
+::: zarr_cm.spatial
+
+## multiscales
+
+::: zarr_cm.multiscales
+
+## license
+
+::: zarr_cm.license
+
+## uom
+
+::: zarr_cm.uom

{zarr_cm-0.1.0 → zarr_cm-0.2.0}/docs/index.md

@@ -73,3 +73,37 @@ print(extracted)
 ```
 
 <!-- blacken-docs:on -->
+
+## Multiple conventions
+
+`create_many`, `insert_many`, `extract_many`, and `validate_many` work with
+several conventions at once, keyed by convention name. `extract_all` and
+`validate_all` are shortcuts that operate on all known conventions.
+
+<!-- blacken-docs:off -->
+<!-- prettier-ignore -->
+```python
+from zarr_cm import create_many, extract_all
+
+# Create attributes with multiple conventions at once
+attrs = create_many(
+    {
+        "geo-proj": {"proj:code": "EPSG:4326"},
+        "spatial": {"spatial:dimensions": ["y", "x"]},
+        "license": {"spdx": "MIT"},
+    }
+)
+print(sorted(attrs.keys()))
+#> ['license', 'proj:code', 'spatial:dimensions', 'zarr_conventions']
+
+# Extract all known conventions
+remaining, extracted = extract_all(attrs)
+print(remaining)
+#> {}
+print(sorted(extracted.keys()))
+#> ['geo-proj', 'license', 'spatial']
+print(extracted["geo-proj"])
+#> {'proj:code': 'EPSG:4326'}
+```
+
+<!-- blacken-docs:on -->

zarr_cm-0.2.0/src/zarr_cm/__init__.py

@@ -0,0 +1,275 @@
+"""
+Copyright (c) 2026 Davis Bennett. All rights reserved.
+
+zarr-cm: Python implementation of Zarr Conventions Metadata
+"""
+
+from __future__ import annotations
+
+import typing
+from typing import Any, Final, Literal, NotRequired, TypedDict
+
+if typing.TYPE_CHECKING:
+    import types
+    from collections.abc import Iterable
+
+from . import geo_proj, multiscales, spatial, uom
+from . import license as license_
+from ._core import (
+    ConventionAttrs,
+    ConventionMetadataObject,
+    validate_convention_metadata_object,
+)
+from ._version import version as __version__
+from .geo_proj import GeoProjAttrs, GeoProjConventionAttrs
+from .license import LicenseAttrs, LicenseConventionAttrs
+from .multiscales import (
+    LayoutObject,
+    MultiscalesAttrs,
+    MultiscalesConventionAttrs,
+    Transform,
+)
+from .spatial import SpatialAttrs, SpatialConventionAttrs
+from .uom import UCUM, UomAttrs, UomConventionAttrs
+
+ConventionName = Literal["geo-proj", "spatial", "multiscales", "license", "uom"]
+
+_REGISTRY: Final[dict[ConventionName, types.ModuleType]] = {
+    "geo-proj": geo_proj,
+    "spatial": spatial,
+    "multiscales": multiscales,
+    "license": license_,
+    "uom": uom,
+}
+
+CONVENTION_NAMES: Final = frozenset(_REGISTRY)
+
+ALL_CONVENTION_KEYS: Final = frozenset(
+    geo_proj.CONVENTION_KEYS
+    | spatial.CONVENTION_KEYS
+    | multiscales.CONVENTION_KEYS
+    | license_.CONVENTION_KEYS
+    | uom.CONVENTION_KEYS
+)
+
+MultiConventionAttrs = TypedDict(
+    "MultiConventionAttrs",
+    {
+        "zarr_conventions": NotRequired[list[ConventionMetadataObject]],
+        # geo-proj
+        "proj:code": NotRequired[str],
+        "proj:wkt2": NotRequired[str],
+        "proj:projjson": NotRequired[dict[str, Any]],
+        # spatial
+        "spatial:dimensions": NotRequired[list[str]],
+        "spatial:bbox": NotRequired[list[float]],
+        "spatial:transform_type": NotRequired[str],
+        "spatial:transform": NotRequired[list[float]],
+        "spatial:shape": NotRequired[list[int]],
+        "spatial:registration": NotRequired[str],
+        # multiscales
+        "multiscales": NotRequired[MultiscalesAttrs],
+        # license
+        "license": NotRequired[LicenseAttrs],
+        # uom
+        "uom": NotRequired[UomAttrs],
+    },
+)
+
+
+def _get_module(name: ConventionName) -> types.ModuleType:
+    """Look up convention module by display name, raise ValueError if unknown."""
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        msg = f"Unknown convention {name!r}. Valid names: {sorted(CONVENTION_NAMES)}"
+        raise ValueError(msg) from None
+
+
+def _detect_conventions(attrs: dict[str, Any]) -> frozenset[ConventionName]:
+    """Identify which conventions are present by matching UUIDs in zarr_conventions."""
+    uuids = {cmo.get("uuid") for cmo in attrs.get("zarr_conventions", [])}
+    return frozenset(name for name, mod in _REGISTRY.items() if mod.UUID in uuids)
+
+
+def create_many(
+    conventions: dict[ConventionName, dict[str, Any]],
+) -> dict[str, Any]:
+    """Create and insert multiple conventions into a single attributes dict.
+
+    Parameters
+    ----------
+    conventions
+        Mapping from convention display name (e.g. ``"geo-proj"``) to
+        already-formed convention data (the ``AttrsT`` value).
+
+    Returns
+    -------
+    dict[str, Any]
+        A new attributes dict containing all convention data and a
+        combined ``zarr_conventions`` array.
+    """
+    result: dict[str, Any] = {}
+    for name, data in conventions.items():
+        mod = _get_module(name)
+        mod.validate(data)
+        result = mod.insert(result, data, overwrite=True)
+    return result
+
+
+def validate_many(
+    attrs: dict[str, Any],
+    conventions: Iterable[ConventionName],
+) -> dict[str, Any]:
+    """Validate multiple conventions within an attributes dict.
+
+    Parameters
+    ----------
+    attrs
+        The attributes dict to validate.
+    conventions
+        Convention names to validate.
+
+    Returns
+    -------
+    dict[str, Any]
+        The input *attrs* (pass-through on success).
+    """
+    for name in conventions:
+        mod = _get_module(name)
+        _, extracted = mod.extract(attrs)
+        mod.validate(dict(extracted))
+    return attrs
+
+
+def insert_many(
+    attrs: dict[str, Any],
+    conventions: dict[ConventionName, dict[str, Any]],
+    *,
+    overwrite: bool = False,
+) -> dict[str, Any]:
+    """Insert multiple conventions into an attributes dict.
+
+    Parameters
+    ----------
+    attrs
+        The existing attributes dict.
+    conventions
+        Mapping from convention display name to already-formed convention data.
+    overwrite
+        If False (default), raise ``ValueError`` when *attrs* already
+        contains keys present in a convention's data.
+
+    Returns
+    -------
+    dict[str, Any]
+        A new attributes dict with all convention data merged in.
+    """
+    result = attrs
+    for name, data in conventions.items():
+        mod = _get_module(name)
+        mod.validate(data)
+        result = mod.insert(result, data, overwrite=overwrite)
+    return result
+
+
+def extract_many(
+    attrs: dict[str, Any],
+    conventions: Iterable[ConventionName],
+) -> tuple[dict[str, Any], dict[ConventionName, dict[str, Any]]]:
+    """Extract multiple conventions from an attributes dict.
+
+    Parameters
+    ----------
+    attrs
+        The attributes dict to extract from.
+    conventions
+        Convention names to extract.
+
+    Returns
+    -------
+    tuple[dict[str, Any], dict[str, dict[str, Any]]]
+        ``(remaining_attrs, extracted)`` where *extracted* maps
+        convention names to their convention data dicts.
+    """
+    remaining = attrs
+    extracted: dict[ConventionName, dict[str, Any]] = {}
+    for name in conventions:
+        mod = _get_module(name)
+        remaining, data = mod.extract(remaining)
+        extracted[name] = dict(data)
+    return remaining, extracted
+
+
+def validate_all(
+    attrs: dict[str, Any],
+) -> dict[str, Any]:
+    """Validate all detected conventions within an attributes dict.
+
+    Detects which conventions are present by matching UUIDs in
+    ``zarr_conventions``, then validates each one.
+
+    Parameters
+    ----------
+    attrs
+        The attributes dict to validate.
+
+    Returns
+    -------
+    dict[str, Any]
+        The input *attrs* (pass-through on success).
+    """
+    return validate_many(attrs, _detect_conventions(attrs))
+
+
+def extract_all(
+    attrs: dict[str, Any],
+) -> tuple[dict[str, Any], dict[ConventionName, dict[str, Any]]]:
+    """Extract all detected conventions from an attributes dict.
+
+    Detects which conventions are present by matching UUIDs in
+    ``zarr_conventions``, then extracts each one.
+
+    Parameters
+    ----------
+    attrs
+        The attributes dict to extract from.
+
+    Returns
+    -------
+    tuple[dict[str, Any], dict[str, dict[str, Any]]]
+        ``(remaining_attrs, extracted)`` where *extracted* maps
+        convention names to their convention data dicts.
+    """
+    return extract_many(attrs, _detect_conventions(attrs))
+
+
+__all__ = [
+    "ALL_CONVENTION_KEYS",
+    "CONVENTION_NAMES",
+    "UCUM",
+    "ConventionAttrs",
+    "ConventionMetadataObject",
+    "ConventionName",
+    "GeoProjAttrs",
+    "GeoProjConventionAttrs",
+    "LayoutObject",
+    "LicenseAttrs",
+    "LicenseConventionAttrs",
+    "MultiConventionAttrs",
+    "MultiscalesAttrs",
+    "MultiscalesConventionAttrs",
+    "SpatialAttrs",
+    "SpatialConventionAttrs",
+    "Transform",
+    "UomAttrs",
+    "UomConventionAttrs",
+    "__version__",
+    "create_many",
+    "extract_all",
+    "extract_many",
+    "insert_many",
+    "validate_all",
+    "validate_convention_metadata_object",
+    "validate_many",
+]

{zarr_cm-0.1.0 → zarr_cm-0.2.0}/src/zarr_cm/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

zarr_cm-0.2.0/tests/test_multi.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from typing import Any, get_args
+
+import pytest
+
+import zarr_cm
+from zarr_cm import (
+    ALL_CONVENTION_KEYS,
+    CONVENTION_NAMES,
+    ConventionName,
+    create_many,
+    extract_all,
+    extract_many,
+    insert_many,
+    validate_all,
+    validate_many,
+)
+
+
+def test_convention_names_constant() -> None:
+    assert (
+        frozenset({"geo-proj", "spatial", "multiscales", "license", "uom"})
+        == CONVENTION_NAMES
+    )
+
+
+def test_all_convention_keys_constant() -> None:
+    assert (
+        frozenset(
+            {
+                "proj:code",
+                "proj:wkt2",
+                "proj:projjson",
+                "spatial:dimensions",
+                "spatial:bbox",
+                "spatial:transform_type",
+                "spatial:transform",
+                "spatial:shape",
+                "spatial:registration",
+                "multiscales",
+                "license",
+                "uom",
+            }
+        )
+        == ALL_CONVENTION_KEYS
+    )
+
+
+def test_create_many_single() -> None:
+    result = create_many({"geo-proj": {"proj:code": "EPSG:4326"}})
+    assert result["proj:code"] == "EPSG:4326"
+    assert len(result["zarr_conventions"]) == 1
+
+
+def test_create_many_mixed() -> None:
+    result = create_many(
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "license": {"spdx": "MIT"},
+        }
+    )
+    assert result["proj:code"] == "EPSG:4326"
+    assert result["license"] == {"spdx": "MIT"}
+    assert len(result["zarr_conventions"]) == 2
+
+
+def test_create_many_all() -> None:
+    result = create_many(
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "spatial": {"spatial:dimensions": ["y", "x"]},
+            "multiscales": {"layout": [{"asset": "0"}]},
+            "license": {"spdx": "MIT"},
+            "uom": {"ucum": {"unit": "kg"}},
+        }
+    )
+    assert len(result["zarr_conventions"]) == 5
+    assert result["proj:code"] == "EPSG:4326"
+    assert result["spatial:dimensions"] == ["y", "x"]
+    assert result["multiscales"]["layout"] == [{"asset": "0"}]
+    assert result["license"] == {"spdx": "MIT"}
+    assert result["uom"]["ucum"]["unit"] == "kg"
+
+
+def test_create_many_invalid_name() -> None:
+    with pytest.raises(ValueError, match="Unknown convention"):
+        create_many({"not-a-convention": {}})  # type: ignore[dict-item]
+
+
+def test_create_many_invalid_data() -> None:
+    with pytest.raises(ValueError, match="Exactly one"):
+        create_many({"geo-proj": {}})
+
+
+def test_validate_many() -> None:
+    attrs = create_many(
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "license": {"spdx": "MIT"},
+        }
+    )
+    result = validate_many(attrs, ["geo-proj", "license"])
+    assert result is attrs
+
+
+def test_validate_many_subset() -> None:
+    attrs = create_many(
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "license": {"spdx": "MIT"},
+        }
+    )
+    result = validate_many(attrs, ["geo-proj"])
+    assert result is attrs
+
+
+def test_validate_many_invalid() -> None:
+    attrs = create_many({"license": {"spdx": "MIT"}})
+    # Corrupt the license data
+    attrs["license"] = {}
+    with pytest.raises(ValueError, match="At least one"):
+        validate_many(attrs, ["license"])
+
+
+def test_validate_all() -> None:
+    attrs = create_many(
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "license": {"spdx": "MIT"},
+            "uom": {"ucum": {"unit": "kg"}},
+        }
+    )
+    result = validate_all(attrs)
+    assert result is attrs
+
+
+def test_insert_many_empty_attrs() -> None:
+    result = insert_many(
+        {},
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "license": {"spdx": "MIT"},
+        },
+    )
+    assert result["proj:code"] == "EPSG:4326"
+    assert result["license"] == {"spdx": "MIT"}
+
+
+def test_insert_many_preserves_attrs() -> None:
+    result = insert_many(
+        {"foo": "bar"},
+        {"geo-proj": {"proj:code": "EPSG:4326"}},
+    )
+    assert result["foo"] == "bar"
+    assert result["proj:code"] == "EPSG:4326"
+
+
+def test_insert_many_collision_raises() -> None:
+    attrs = {"proj:code": "EPSG:3857"}
+    with pytest.raises(ValueError, match="overwritten"):
+        insert_many(attrs, {"geo-proj": {"proj:code": "EPSG:4326"}})
+
+
+def test_insert_many_overwrite() -> None:
+    attrs = {"proj:code": "EPSG:3857"}
+    result = insert_many(
+        attrs,
+        {"geo-proj": {"proj:code": "EPSG:4326"}},
+        overwrite=True,
+    )
+    assert result["proj:code"] == "EPSG:4326"
+
+
+def test_extract_many() -> None:
+    attrs = create_many(
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "license": {"spdx": "MIT"},
+        }
+    )
+    remaining, extracted = extract_many(attrs, ["geo-proj", "license"])
+    assert remaining == {}
+    assert extracted["geo-proj"] == {"proj:code": "EPSG:4326"}
+    assert extracted["license"] == {"spdx": "MIT"}
+
+
+def test_extract_many_subset() -> None:
+    attrs = create_many(
+        {
+            "geo-proj": {"proj:code": "EPSG:4326"},
+            "license": {"spdx": "MIT"},
+        }
+    )
+    remaining, extracted = extract_many(attrs, ["geo-proj"])
+    assert "geo-proj" in extracted
+    assert "license" not in extracted
+    # license data stays in remaining
+    assert remaining["license"] == {"spdx": "MIT"}
+
+
+def test_extract_many_preserves_remaining() -> None:
+    attrs = create_many({"geo-proj": {"proj:code": "EPSG:4326"}})
+    attrs["foo"] = "bar"
+    remaining, extracted = extract_many(attrs, ["geo-proj"])
+    assert remaining == {"foo": "bar"}
+    assert extracted["geo-proj"] == {"proj:code": "EPSG:4326"}
+
+
+def test_extract_all() -> None:
+    conventions: dict[ConventionName, dict[str, Any]] = {
+        "geo-proj": {"proj:code": "EPSG:4326"},
+        "license": {"spdx": "MIT"},
+    }
+    attrs = create_many(conventions)
+    remaining, extracted = extract_all(attrs)
+    assert remaining == {}
+    assert extracted["geo-proj"] == {"proj:code": "EPSG:4326"}
+    assert extracted["license"] == {"spdx": "MIT"}
+
+
+def test_convention_name_literal_matches_registry() -> None:
+    for name in get_args(ConventionName):
+        assert hasattr(zarr_cm, name.replace("-", "_")), (
+            f"{name!r} is not a module in zarr_cm"
+        )
+
+
+def test_roundtrip() -> None:
+    conventions: dict[ConventionName, dict[str, Any]] = {
+        "geo-proj": {"proj:code": "EPSG:4326"},
+        "spatial": {"spatial:dimensions": ["y", "x"]},
+        "license": {"spdx": "MIT"},
+    }
+    attrs = create_many(conventions)
+    remaining, extracted = extract_many(attrs, conventions.keys())
+    assert remaining == {}
+    assert extracted == conventions

zarr_cm-0.1.0/docs/api.md

@@ -1,26 +0,0 @@
-# API Reference
-
-## Core
-
-<!-- prettier-ignore -->
-::: zarr_cm._core
-
-## geo-proj
-
-::: zarr_cm.geo_proj
-
-## spatial
-
-::: zarr_cm.spatial
-
-## multiscales
-
-::: zarr_cm.multiscales
-
-## license
-
-::: zarr_cm.license
-
-## uom
-
-::: zarr_cm.uom

zarr_cm-0.1.0/src/zarr_cm/__init__.py

@@ -1,44 +0,0 @@
-"""
-Copyright (c) 2026 Davis Bennett. All rights reserved.
-
-zarr-cm: Python implementation of Zarr Conventions Metadata
-"""
-
-from __future__ import annotations
-
-from ._core import (
-    ConventionAttrs,
-    ConventionMetadataObject,
-    validate_convention_metadata_object,
-)
-from ._version import version as __version__
-from .geo_proj import GeoProjAttrs, GeoProjConventionAttrs
-from .license import LicenseAttrs, LicenseConventionAttrs
-from .multiscales import (
-    LayoutObject,
-    MultiscalesAttrs,
-    MultiscalesConventionAttrs,
-    Transform,
-)
-from .spatial import SpatialAttrs, SpatialConventionAttrs
-from .uom import UCUM, UomAttrs, UomConventionAttrs
-
-__all__ = [
-    "UCUM",
-    "ConventionAttrs",
-    "ConventionMetadataObject",
-    "GeoProjAttrs",
-    "GeoProjConventionAttrs",
-    "LayoutObject",
-    "LicenseAttrs",
-    "LicenseConventionAttrs",
-    "MultiscalesAttrs",
-    "MultiscalesConventionAttrs",
-    "SpatialAttrs",
-    "SpatialConventionAttrs",
-    "Transform",
-    "UomAttrs",
-    "UomConventionAttrs",
-    "__version__",
-    "validate_convention_metadata_object",
-]