xarray-annotated 0.5.2__tar.gz → 0.7.0__tar.gz

{xarray_annotated-0.5.2 → xarray_annotated-0.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: xarray-annotated
-Version: 0.5.2
-Summary: Run-time validation of xarray DataArray properties (units, dims/coords/dtype) declared via typing.Annotated
+Version: 0.7.0
+Summary: Run-time validation of xarray DataArray structure, units and frequency, declared via typing.Annotated
 Keywords: xarray,pint,units,validation,annotations
 Author: jmarshrossney
 Author-email: jmarshrossney <17361029+jmarshrossney@users.noreply.github.com>
@@ -33,21 +33,19 @@ Description-Content-Type: text/markdown
 [![Docs](https://github.com/jmarshrossney/xarray-annotated/actions/workflows/docs.yml/badge.svg)](https://jmarshrossney.github.io/xarray-annotated)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jmarshrossney/xarray-annotated/blob/main/LICENSE)
 
-`xarray-annotated` enables run-time validation of `xarray.DataArray` properties declared in function signatures via [`typing.Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated).
+`xarray-annotated` checks `xarray.DataArray` arguments and return values against properties declared in the function signature with [`typing.Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated):
 
-The main idea is that annotations serve as a single source of truth for
+- **structure**: dimensions, coordinates and dtype;
+- **physical units**;
+- **time frequency** and phase.
 
-- structural schema (dims, coords, dtype),
-- physical units,
-- frequency (and phase) of a time axis,
+Making signatures the single source of truth has several advantages: the same declaration
 
-from which
+- can be used by automated checks and validation, and hence enforced at run time;
+- appears in generated documentation without needing to be hand-written;
+- provides rich context for AI coding agents.
 
-- static checkers and run-time validation can derive expected properties,
-- documentation can be generated automatically,
-- automated tools (coding agents) receive steering.
-
-For validating and automatically converting physical units we lean on the excellent [pint](https://pint.readthedocs.io/en/stable/) and [pint-xarray](https://pint-xarray.readthedocs.io).
+For physical units we lean on the excellent [pint](https://pint.readthedocs.io/en/stable/) and [pint-xarray](https://pint-xarray.readthedocs.io).
 ([cf-xarray](https://cf-xarray.readthedocs.io) is an optional dependency for CF/UDUNITS unit strings.)
 
 For full user documentation please visit **[https://jmarshrossney.github.io/xarray-annotated/](https://jmarshrossney.github.io/xarray-annotated/)**.
@@ -78,10 +76,12 @@ It assumes a unit (pascals) and says so in the docstring but doesn't check or en
 ```python
 import xarray as xr
 
+
 def altitude(p: xr.DataArray) -> xr.DataArray:
     """Barometric altitude. Assumes p is in Pa."""
     return 44330.0 * (1.0 - (p / 101325.0) ** 0.1903)
 
+
 p = xr.DataArray([1013.0, 1000.0], dims=["time"], attrs={"units": "hPa"})
 altitude(p)
 ```
@@ -96,24 +96,37 @@ Attributes:
 The input units are wrong (hPa vs Pa) but the onus is on the user to check, and in reality we all know that such bugs can go unnoticed for a terrifyingly long time.
 The returned altitude is numerically wrong and carries a completely bogus hPa units in `attrs`.
 
-Here we use `xarray-annotated` to declare expected properties in the signature and enforce them at run-time with minimal boilerplate (just decorators).
+Here we use `xarray-annotated` to declare expected properties in the signature and enforce them at run-time with minimal boilerplate (one decorator).
 
+<!-- docs-test: raises ValueError -->
 ```python
 from typing import Annotated
 import xarray as xr
-from xarray_annotated.schema import declare_schema, Dims
-from xarray_annotated.units import declare_units, Unit
+import xarray_annotated as xra
+from xarray_annotated import Dims, Unit
 
-@declare_units
-@declare_schema
+
+@xra.enforce
 def altitude(
     p: Annotated[xr.DataArray, Dims("time"), Unit("Pa")],
 ) -> Annotated[xr.DataArray, Dims("time"), Unit("m")]:
     """Barometric altitude."""
-    return 44330.0 * (1.0 - (p / 101325.0) ** 0.1903)
+    alt = 44330.0 * (1.0 - (p / 101325.0) ** 0.1903)
+    return alt.assign_attrs(units="m")
+
 
 p = xr.DataArray([1013.0, 1000.0], dims=["time"], attrs={"units": "hPa"})
 altitude(p)
+# ValueError: [altitude] input 'p': unit 'hPa' differs from declared 'Pa'.
+#   Converting would change the values; if that is correct for this quantity,
+#   pass xra.units.convert(da, 'Pa').
+```
+
+The wrong unit is now an error rather than a wrong answer.
+Pressure is safe to convert, so we can do that explicitly:
+
+```python
+altitude(xra.units.convert(p, "Pa"))
 ```
 ```
 <xarray.DataArray (time: 2)> Size: 16B
@@ -123,34 +136,31 @@ Attributes:
     units:    m
 ```
 
-Now the outputs are physical and carry the correct units attribute.
-The `hPa` input was converted to `Pa` before the body ran, and the result was stamped with the unit the signature promised.
+Now the outputs are physical and carry the unit the signature promised.
+The body has to state that unit, because xarray would otherwise leave the `Pa` label on the result, and a label that disagrees with the declaration raises: it could just as easily mean a forgotten conversion.
+Nothing is [converted automatically](https://jmarshrossney.github.io/xarray-annotated/guides/units.html#converting-an-input), because whether a conversion is correct depends on the quantity, and a compatible unit is not always the right one.
 The docstring no longer needs to say "assumes Pa", because the signature does --- and unlike the docstring, it is actually enforced.
 
-If we had handed the function an array whose units were _dimensionally_ wrong, or with an extra dimension, this would have failed gracefully:
+An array whose units were _dimensionally_ wrong would also have raised:
 
+<!-- docs-test: raises DimensionalityError -->
 ```python
 altitude(xr.DataArray([1.0, 2.0], dims=["time"], attrs={"units": "kg"}))
 # DimensionalityError: Cannot convert from 'kilogram' ([mass])
 #   to 'pascal' ([mass] / [length] / [time] ** 2)
-
-altitude(xr.DataArray([[1013.0, 1000.0]], dims=["run", "time"], attrs={"units": "hPa"}))
-# SchemaError: [altitude] 'p' dims mismatch: expected ('time',) in any order, got ('run', 'time')
 ```
 
-## Contributing
+And so would one with an extra dimension:
 
-```sh
-uv sync   # install the package + dev dependencies into .venv
-just      # lint, typecheck, test, build docs
+<!-- docs-test: raises SchemaError -->
+```python
+altitude(
+    xr.DataArray([[101300.0, 100000.0]], dims=["run", "time"], attrs={"units": "Pa"})
+)
+# SchemaError: [altitude] 'p' dims mismatch: expected ('time',) in any order, got ('run', 'time')
 ```
 
-See the `justfile` for individual targets (`just lint`, `just test`, `just test-cov`, ...).
-
-A `.pre-commit-config.yaml` is included to run the same linting (ruff) and type-checking (pyright) steps on every commit. Install the hooks with:
-
-```sh
-uv run pre-commit install
-```
+## Contributing
 
-Contributions are welcome --- open an issue or pull request on GitHub.
+Issues and pull requests are welcome.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the package's scope and how to set up a development environment.

{xarray_annotated-0.5.2 → xarray_annotated-0.7.0}/README.md

@@ -6,21 +6,19 @@
 [![Docs](https://github.com/jmarshrossney/xarray-annotated/actions/workflows/docs.yml/badge.svg)](https://jmarshrossney.github.io/xarray-annotated)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jmarshrossney/xarray-annotated/blob/main/LICENSE)
 
-`xarray-annotated` enables run-time validation of `xarray.DataArray` properties declared in function signatures via [`typing.Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated).
+`xarray-annotated` checks `xarray.DataArray` arguments and return values against properties declared in the function signature with [`typing.Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated):
 
-The main idea is that annotations serve as a single source of truth for
+- **structure**: dimensions, coordinates and dtype;
+- **physical units**;
+- **time frequency** and phase.
 
-- structural schema (dims, coords, dtype),
-- physical units,
-- frequency (and phase) of a time axis,
+Making signatures the single source of truth has several advantages: the same declaration
 
-from which
+- can be used by automated checks and validation, and hence enforced at run time;
+- appears in generated documentation without needing to be hand-written;
+- provides rich context for AI coding agents.
 
-- static checkers and run-time validation can derive expected properties,
-- documentation can be generated automatically,
-- automated tools (coding agents) receive steering.
-
-For validating and automatically converting physical units we lean on the excellent [pint](https://pint.readthedocs.io/en/stable/) and [pint-xarray](https://pint-xarray.readthedocs.io).
+For physical units we lean on the excellent [pint](https://pint.readthedocs.io/en/stable/) and [pint-xarray](https://pint-xarray.readthedocs.io).
 ([cf-xarray](https://cf-xarray.readthedocs.io) is an optional dependency for CF/UDUNITS unit strings.)
 
 For full user documentation please visit **[https://jmarshrossney.github.io/xarray-annotated/](https://jmarshrossney.github.io/xarray-annotated/)**.
@@ -51,10 +49,12 @@ It assumes a unit (pascals) and says so in the docstring but doesn't check or en
 ```python
 import xarray as xr
 
+
 def altitude(p: xr.DataArray) -> xr.DataArray:
     """Barometric altitude. Assumes p is in Pa."""
     return 44330.0 * (1.0 - (p / 101325.0) ** 0.1903)
 
+
 p = xr.DataArray([1013.0, 1000.0], dims=["time"], attrs={"units": "hPa"})
 altitude(p)
 ```
@@ -69,24 +69,37 @@ Attributes:
 The input units are wrong (hPa vs Pa) but the onus is on the user to check, and in reality we all know that such bugs can go unnoticed for a terrifyingly long time.
 The returned altitude is numerically wrong and carries a completely bogus hPa units in `attrs`.
 
-Here we use `xarray-annotated` to declare expected properties in the signature and enforce them at run-time with minimal boilerplate (just decorators).
+Here we use `xarray-annotated` to declare expected properties in the signature and enforce them at run-time with minimal boilerplate (one decorator).
 
+<!-- docs-test: raises ValueError -->
 ```python
 from typing import Annotated
 import xarray as xr
-from xarray_annotated.schema import declare_schema, Dims
-from xarray_annotated.units import declare_units, Unit
+import xarray_annotated as xra
+from xarray_annotated import Dims, Unit
 
-@declare_units
-@declare_schema
+
+@xra.enforce
 def altitude(
     p: Annotated[xr.DataArray, Dims("time"), Unit("Pa")],
 ) -> Annotated[xr.DataArray, Dims("time"), Unit("m")]:
     """Barometric altitude."""
-    return 44330.0 * (1.0 - (p / 101325.0) ** 0.1903)
+    alt = 44330.0 * (1.0 - (p / 101325.0) ** 0.1903)
+    return alt.assign_attrs(units="m")
+
 
 p = xr.DataArray([1013.0, 1000.0], dims=["time"], attrs={"units": "hPa"})
 altitude(p)
+# ValueError: [altitude] input 'p': unit 'hPa' differs from declared 'Pa'.
+#   Converting would change the values; if that is correct for this quantity,
+#   pass xra.units.convert(da, 'Pa').
+```
+
+The wrong unit is now an error rather than a wrong answer.
+Pressure is safe to convert, so we can do that explicitly:
+
+```python
+altitude(xra.units.convert(p, "Pa"))
 ```
 ```
 <xarray.DataArray (time: 2)> Size: 16B
@@ -96,34 +109,31 @@ Attributes:
     units:    m
 ```
 
-Now the outputs are physical and carry the correct units attribute.
-The `hPa` input was converted to `Pa` before the body ran, and the result was stamped with the unit the signature promised.
+Now the outputs are physical and carry the unit the signature promised.
+The body has to state that unit, because xarray would otherwise leave the `Pa` label on the result, and a label that disagrees with the declaration raises: it could just as easily mean a forgotten conversion.
+Nothing is [converted automatically](https://jmarshrossney.github.io/xarray-annotated/guides/units.html#converting-an-input), because whether a conversion is correct depends on the quantity, and a compatible unit is not always the right one.
 The docstring no longer needs to say "assumes Pa", because the signature does --- and unlike the docstring, it is actually enforced.
 
-If we had handed the function an array whose units were _dimensionally_ wrong, or with an extra dimension, this would have failed gracefully:
+An array whose units were _dimensionally_ wrong would also have raised:
 
+<!-- docs-test: raises DimensionalityError -->
 ```python
 altitude(xr.DataArray([1.0, 2.0], dims=["time"], attrs={"units": "kg"}))
 # DimensionalityError: Cannot convert from 'kilogram' ([mass])
 #   to 'pascal' ([mass] / [length] / [time] ** 2)
-
-altitude(xr.DataArray([[1013.0, 1000.0]], dims=["run", "time"], attrs={"units": "hPa"}))
-# SchemaError: [altitude] 'p' dims mismatch: expected ('time',) in any order, got ('run', 'time')
 ```
 
-## Contributing
+And so would one with an extra dimension:
 
-```sh
-uv sync   # install the package + dev dependencies into .venv
-just      # lint, typecheck, test, build docs
+<!-- docs-test: raises SchemaError -->
+```python
+altitude(
+    xr.DataArray([[101300.0, 100000.0]], dims=["run", "time"], attrs={"units": "Pa"})
+)
+# SchemaError: [altitude] 'p' dims mismatch: expected ('time',) in any order, got ('run', 'time')
 ```
 
-See the `justfile` for individual targets (`just lint`, `just test`, `just test-cov`, ...).
-
-A `.pre-commit-config.yaml` is included to run the same linting (ruff) and type-checking (pyright) steps on every commit. Install the hooks with:
-
-```sh
-uv run pre-commit install
-```
+## Contributing
 
-Contributions are welcome --- open an issue or pull request on GitHub.
+Issues and pull requests are welcome.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the package's scope and how to set up a development environment.

{xarray_annotated-0.5.2 → xarray_annotated-0.7.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "uv_build"
 
 [project]
 name = "xarray-annotated"
-version = "0.5.2"
-description = "Run-time validation of xarray DataArray properties (units, dims/coords/dtype) declared via typing.Annotated"
+version = "0.7.0"
+description = "Run-time validation of xarray DataArray structure, units and frequency, declared via typing.Annotated"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -56,6 +56,13 @@ dev = [
     "rust-just>=1.46.0",
     "pre-commit>=4.6.0",
     { include-group = "docs" },
+    { include-group = "integrations" },
+]
+integrations = [
+    "beartype>=0.22.9",
+    "dask>=2026.8.0",
+    "jaxtyping>=0.3.11",
+    "netcdf4>=1.7.5.1.post1",
 ]
 docs = [
     "marimo>=0.23.11",
@@ -80,12 +87,43 @@ line-length = 88
 indent-width = 4
 target-version = "py312"
 
+[tool.ruff.lint]
+select = [
+    "E",
+    "D",
+    "W",
+    "F",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+    "PT",
+    "I",
+]
+
 [tool.ruff.lint.per-file-ignores]
-"examples/notebook.py" = [
-    "F821",
+"tests/**" = [
+    "B008",
+    "D",
+    "E501",
+]
+"examples/**" = [
+    "B018",
+    "D100",
+    "D103",
+    "E501",
     "F722",
+    "F821",
+    "F841",
+    "RUF001",
+    "RUF003",
+    "PLR1711",
+    "PLC0415",
 ]
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
 [tool.uv]
 exclude-newer = "1 week"
 

xarray_annotated-0.7.0/pyproject.toml.orig

@@ -0,0 +1,144 @@
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "xarray-annotated"
+version = "0.7.0"
+description = "Run-time validation of xarray DataArray structure, units and frequency, declared via typing.Annotated"
+authors = [
+    { name = "jmarshrossney", email = "17361029+jmarshrossney@users.noreply.github.com" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "pandas>=2.2",
+    "pint>=0.25.3",
+    "pint-xarray>=0.6.1",
+    "xarray>=2026.2.0",
+]
+keywords = ["xarray", "pint", "units", "validation", "annotations"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering",
+]
+
+[project.optional-dependencies]
+cf = ["cf-xarray>=0.11.3"]
+
+[project.urls]
+Homepage = "https://jmarshrossney.github.io/xarray-annotated"
+Repository = "https://github.com/jmarshrossney/xarray-annotated"
+Documentation = "https://jmarshrossney.github.io/xarray-annotated"
+
+[dependency-groups]
+dev = [
+    "xarray-annotated[cf]",
+    "cftime>=1.6",
+    "coverage>=7.13.5",
+    "pyright>=1.1.409",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.4",
+    "rust-just>=1.46.0",
+    "pre-commit>=4.6.0",
+    {include-group = "docs"},
+    {include-group = "integrations"},
+]
+# Third-party libraries xarray-annotated *composes with* but never imports.  These are
+# test-only: there is nothing for a user to install to "enable" the integration, so this
+# is deliberately a dependency group and not an optional-dependency extra (contrast
+# `cf`, which is an extra because `units._registry` really does import cf_xarray).
+# `tests/test_jaxtyping.py`, `test_dask.py` and `test_netcdf.py` skip themselves when
+# they are absent.
+integrations = [
+    "beartype>=0.22.9",
+    "dask>=2026.8.0",
+    "jaxtyping>=0.3.11",
+    "netcdf4>=1.7.5.1.post1",
+]
+docs = [
+    "marimo>=0.23.11",
+    "marimo-md-export>=0.7.0",
+    "mkdocstrings-python>=2.0.5",
+    "zensical>=0.0.46",
+]
+
+[tool.pytest]
+testpaths = ["tests"]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+include = ["src/", "tests/"]
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py312"
+
+[tool.ruff.lint]
+# Ruff broadened its default rule set in 0.16, so always select explicitly:
+# that way a version bump cannot change which rules apply.
+select = [
+    "E",   # pycodestyle errors
+    "D",   # pydocstyle
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific rules
+    "PT",  # flake8-pytest-style
+    "I",   # isort
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Exempt tests from docstring requirements. B008 (function call in an argument
+# default) is exempted because several tests exist precisely to check that a
+# parameter left at its default is still converted/validated -- the call in the
+# default is the fixture under test, not an oversight.
+"tests/**" = ["B008", "D", "E501"]
+# marimo threads `Annotated` in as a cell argument, so ruff can't resolve it to
+# `typing.Annotated` and misreads the unit strings in the metadata as forward
+# references (F821 "undefined name" / F722 "syntax error in forward annotation").
+# The rest are generic to marimo notebooks, which are generated dataflow
+# descriptions rather than hand-written modules:
+#   B018    a bare trailing expression IS the cell's output mechanism.
+#   E501    long prose/URLs inside mo.md() cannot be rewrapped by ruff format,
+#           and a `# noqa` after the closing quotes flip-flops forever
+#           (marimo strips the two spaces, ruff format restores them).
+#   D100    notebooks are not modules and have no module docstring.
+#   D103    cell functions are machine-generated and undocumented.
+#   F841    exploratory cells leave unused variables around.
+#   RUF001  prose contains en dashes; RUF003 contains Greek letters.
+"examples/**" = [
+    "B018",
+    "D100",
+    "D103",
+    "E501",
+    "F722",
+    "F821",
+    "F841",
+    "RUF001",
+    "RUF003",
+    # Pre-emptive, and only active if "PL" is ever added to select above:
+    #   PLR1711 ruff deletes the bare `return` that ends every cell and
+    #           `marimo check --fix` re-adds it -- an infinite flip-flop.
+    #   PLC0415 notebook imports live inside cells by design.
+    "PLR1711",
+    "PLC0415",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.uv]
+exclude-newer = "1 week"
+exclude-newer-package = { marimo-md-export = false }

xarray_annotated-0.7.0/src/xarray_annotated/__init__.py

@@ -0,0 +1,60 @@
+"""xarray-annotated: validate DataArray properties declared via ``typing.Annotated``.
+
+Annotation is the unifying technology: a declared property is read off an
+``Annotated[DataArray, ...]`` hint and enforced at runtime.  Each kind of
+property is a domain subpackage, imported explicitly:
+
+* ``xarray_annotated.units`` — physical units (pint / CF).
+* ``xarray_annotated.schema`` — structural properties (dims, coords, dtype);
+  validate-only (never mutates).
+* ``xarray_annotated.temporal`` — the frequency (and phase) of a time axis;
+  validate-only.
+
+One decorator, ``enforce``, applies every facet declared on a signature, units first:
+
+    import xarray_annotated as xra
+    from xarray_annotated import Dims, Freq, Unit
+
+    @xra.enforce
+    def f(p: Annotated[xr.DataArray, Unit("Pa"), Dims("time"), Freq("D")]): ...
+
+The top level is deliberately thin — the domains' checker names stay in their
+subpackages.  The exceptions are the markers (``Coords``, ``Dims``, ``Dtype``,
+``Freq``, ``Unit``), which are unique across domains and are combined freely in one
+hint, and the domain-*agnostic*
+names: ``enforce``; the ``enabled`` switch; the shared
+declaration *writer* ``annotate`` and its inverse *readers*
+``declaration_from_hint`` and ``declarations_from_signature`` (which read every facet
+declared on a hint or a signature into one uniform ``Declared`` value).
+"""
+
+from importlib.metadata import version as _version
+
+from . import schema, temporal, units
+from ._config import enabled
+from ._enforce import enforce
+from ._reader import Declared, declaration_from_hint, declarations_from_signature
+from ._writer import annotate
+from .schema import Coords, Dims, Dtype
+from .temporal import Freq
+from .units import Unit
+
+__version__ = _version("xarray-annotated")
+
+__all__ = [
+    "Coords",
+    "Declared",
+    "Dims",
+    "Dtype",
+    "Freq",
+    "Unit",
+    "__version__",
+    "annotate",
+    "declaration_from_hint",
+    "declarations_from_signature",
+    "enabled",
+    "enforce",
+    "schema",
+    "temporal",
+    "units",
+]