xarray-annotated 0.5.2__py3-none-any.whl

xarray_annotated/units/_config.py

@@ -0,0 +1,237 @@
+"""Process-wide validation policy: four orthogonal axes.
+
+`check_units` handles three distinct events, and the policy exposes one independent
+control per event, plus one axis governing how declared *outputs* are treated:
+
+- `enabled` — master switch; when `False` no validation happens at all (a true
+  no-op, at every layer).  This is the **package-wide** switch shared with every
+  other domain; it lives in `xarray_annotated._config` and is merely surfaced on
+  this domain's `Policy`.
+- `on_missing` — what to do when a `DataArray` has no parseable unit to check
+  against (an absent or unparseable `units` attribute): `"error"` / `"warn"` /
+  `"ignore"`.
+- `on_inexact` — what to do when the declared and actual units are dimensionally
+  compatible but *value-changing* (e.g. `"hPa"` where `"Pa"` is declared):
+  `"convert"` / `"warn"` / `"error"`.
+- `on_output` — whether a declared return value's own `units` attribute is
+  verified before being overwritten: `"stamp"` / `"strict"`.  See
+  `apply_output_units` for why the default cannot be otherwise.
+
+A fourth case — a *dimensional* mismatch (e.g. a mass where a pressure is declared)
+— is deliberately not configurable **on inputs**: it always raises, because the
+values cannot be converted and continuing would corrupt results silently.
+
+Each axis resolves independently: environment variable, then a process override set
+via `set_policy` / the `policy` context manager, then the module default. The
+shared `_resolve` helper encodes that precedence.
+"""
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Literal
+
+from .._config import (
+    DEFAULT_ENABLED,
+    ENABLED_ENV_VAR,
+    _resolve,
+    _Unset,
+    _UNSET,
+    get_enabled_override,
+    resolve_enabled,
+    set_enabled_override,
+)
+
+# `ENABLED_ENV_VAR` / `DEFAULT_ENABLED` are re-exported (the master switch is
+# shared but callers still reach it as `units._config.ENABLED_ENV_VAR`).
+__all__ = ["ENABLED_ENV_VAR", "Policy", "get_policy", "policy", "set_policy"]
+
+OnMissing = Literal["error", "warn", "ignore"]
+OnInexact = Literal["convert", "warn", "error"]
+OnOutput = Literal["stamp", "strict"]
+
+_VALID_ON_MISSING: frozenset[str] = frozenset({"error", "warn", "ignore"})
+_VALID_ON_INEXACT: frozenset[str] = frozenset({"convert", "warn", "error"})
+_VALID_ON_OUTPUT: frozenset[str] = frozenset({"stamp", "strict"})
+
+#: When a `DataArray` carries no parseable unit, `warn` flags it without
+#: failing — non-breaking for inputs that lack unit metadata, and dev-friendly.
+DEFAULT_ON_MISSING: OnMissing = "warn"
+
+#: A dimensionally compatible but value-changing unit is silently converted by
+#: default; `warn` also converts but says so, `error` refuses.
+DEFAULT_ON_INEXACT: OnInexact = "convert"
+
+#: Outputs are stamped, not verified, by default: a body that does its own unit
+#: arithmetic leaves `attrs` stale, and re-converting would corrupt the values.
+DEFAULT_ON_OUTPUT: OnOutput = "stamp"
+
+ON_MISSING_ENV_VAR = "XARRAY_ANNOTATED_UNITS_ON_MISSING"
+ON_INEXACT_ENV_VAR = "XARRAY_ANNOTATED_UNITS_ON_INEXACT"
+ON_OUTPUT_ENV_VAR = "XARRAY_ANNOTATED_UNITS_ON_OUTPUT"
+
+_process_on_missing: OnMissing | None = None
+_process_on_inexact: OnInexact | None = None
+_process_on_output: OnOutput | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Policy:
+    """The resolved validation policy — the four axes as a single value.
+
+    Returned by `get_policy`.  Build overrides via `set_policy` or the `policy`
+    context manager rather than constructing this directly.
+
+    Attributes:
+        enabled: Master switch; `False` makes all validation a no-op.
+        on_missing: Behaviour when a `DataArray` has no parseable unit
+            (`"error"`, `"warn"`, or `"ignore"`).
+        on_inexact: Behaviour for a value-changing conversion
+            (`"convert"`, `"warn"`, or `"error"`).
+        on_output: How much to trust a declared return value (`"stamp"` or
+            `"strict"`).
+    """
+
+    enabled: bool = DEFAULT_ENABLED
+    on_missing: OnMissing = DEFAULT_ON_MISSING
+    on_inexact: OnInexact = DEFAULT_ON_INEXACT
+    on_output: OnOutput = DEFAULT_ON_OUTPUT
+
+
+def _validate_on_missing(value: str) -> OnMissing:
+    if value not in _VALID_ON_MISSING:
+        raise ValueError(
+            f"Invalid on_missing {value!r}. Choose one of {sorted(_VALID_ON_MISSING)}."
+        )
+    return value  # type: ignore[return-value]
+
+
+def _validate_on_inexact(value: str) -> OnInexact:
+    if value not in _VALID_ON_INEXACT:
+        raise ValueError(
+            f"Invalid on_inexact {value!r}. Choose one of {sorted(_VALID_ON_INEXACT)}."
+        )
+    return value  # type: ignore[return-value]
+
+
+def _validate_on_output(value: str) -> OnOutput:
+    if value not in _VALID_ON_OUTPUT:
+        raise ValueError(
+            f"Invalid on_output {value!r}. Choose one of {sorted(_VALID_ON_OUTPUT)}."
+        )
+    return value  # type: ignore[return-value]
+
+
+def get_policy() -> Policy:
+    """Resolve the active validation policy (env → process → default, per axis).
+
+    Returns:
+        The resolved `Policy`.
+    """
+    return Policy(
+        enabled=resolve_enabled(),
+        on_missing=_resolve(
+            ON_MISSING_ENV_VAR,
+            _process_on_missing,
+            DEFAULT_ON_MISSING,
+            lambda v: _validate_on_missing(v.lower()),
+        ),
+        on_inexact=_resolve(
+            ON_INEXACT_ENV_VAR,
+            _process_on_inexact,
+            DEFAULT_ON_INEXACT,
+            lambda v: _validate_on_inexact(v.lower()),
+        ),
+        on_output=_resolve(
+            ON_OUTPUT_ENV_VAR,
+            _process_on_output,
+            DEFAULT_ON_OUTPUT,
+            lambda v: _validate_on_output(v.lower()),
+        ),
+    )
+
+
+def set_policy(
+    *,
+    enabled: bool | None | _Unset = _UNSET,
+    on_missing: OnMissing | None | _Unset = _UNSET,
+    on_inexact: OnInexact | None | _Unset = _UNSET,
+    on_output: OnOutput | None | _Unset = _UNSET,
+) -> None:
+    """Set process-wide policy overrides for one or more axes.
+
+    Only the axes you pass are changed.  Pass a value to set it, `None` to
+    *clear* that axis's override (so its env var / default applies again), or
+    omit it to leave it untouched.
+
+    Args:
+        enabled: Override the (package-wide) master switch, or `None` to clear.
+        on_missing: Override the on-missing axis, or `None` to clear.
+        on_inexact: Override the on-inexact axis, or `None` to clear.
+        on_output: Override the on-output axis, or `None` to clear.
+    """
+    global _process_on_missing, _process_on_inexact, _process_on_output
+    if not isinstance(enabled, _Unset):
+        set_enabled_override(enabled)
+    if not isinstance(on_missing, _Unset):
+        _process_on_missing = (
+            None if on_missing is None else _validate_on_missing(on_missing)
+        )
+    if not isinstance(on_inexact, _Unset):
+        _process_on_inexact = (
+            None if on_inexact is None else _validate_on_inexact(on_inexact)
+        )
+    if not isinstance(on_output, _Unset):
+        _process_on_output = (
+            None if on_output is None else _validate_on_output(on_output)
+        )
+
+
+@contextmanager
+def policy(
+    *,
+    enabled: bool | None | _Unset = _UNSET,
+    on_missing: OnMissing | None | _Unset = _UNSET,
+    on_inexact: OnInexact | None | _Unset = _UNSET,
+    on_output: OnOutput | None | _Unset = _UNSET,
+):
+    """Temporarily override policy axes, restoring all of them on exit.
+
+    Sets every axis you pass in one go, and restores the previous process
+    overrides afterwards even if an exception is raised.
+
+    Args:
+        enabled: Override the (package-wide) master switch, or `None` to clear.
+        on_missing: Override the on-missing axis, or `None` to clear.
+        on_inexact: Override the on-inexact axis, or `None` to clear.
+        on_output: Override the on-output axis, or `None` to clear.
+
+    Examples:
+        >>> from xarray_annotated.units import policy
+        >>> import xarray as xr
+        >>> da = xr.DataArray([1.0], attrs={"units": "Pa"})
+        >>> with policy(on_missing="error"):
+        ...     pass  # policy restored after block
+    """
+    global _process_on_missing, _process_on_inexact, _process_on_output
+    saved = (
+        get_enabled_override(),
+        _process_on_missing,
+        _process_on_inexact,
+        _process_on_output,
+    )
+    set_policy(
+        enabled=enabled,
+        on_missing=on_missing,
+        on_inexact=on_inexact,
+        on_output=on_output,
+    )
+    try:
+        yield
+    finally:
+        (
+            enabled_saved,
+            _process_on_missing,
+            _process_on_inexact,
+            _process_on_output,
+        ) = saved
+        set_enabled_override(enabled_saved)

xarray_annotated/units/_decorator.py

@@ -0,0 +1,203 @@
+"""Signature-driven unit declaration decorator.
+
+`declare_units` wires the declaration side (`_annotations`) to the checking side
+(`_check`): it reads a function's `Annotated[DataArray, Unit(...)]` hints once, at
+decoration time, then on every call validates/converts the declared inputs and
+stamps the declared outputs.
+
+This is deliberately the *convenience* layer, and deliberately a plain function
+decorator with no subclassing hierarchy. A tool that needs different behaviour
+(build-time/static checks, custom value types, alternative policies) should build
+its own consumer from the same public primitives — `units_from_signature`,
+`check_units`, `assert_valid_unit` — which is exactly, and all, that this decorator
+does. The two knobs most callers want are exposed as keyword arguments below.
+"""
+
+import dataclasses
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+import xarray as xr
+
+from ._annotations import units_from_signature
+from ._check import apply_output_units, assert_valid_unit, check_units
+from ._config import (
+    OnInexact,
+    OnMissing,
+    OnOutput,
+    _validate_on_inexact,
+    _validate_on_missing,
+    _validate_on_output,
+    get_policy,
+)
+
+
+def _set_field(result: Any, name: str, value: xr.DataArray, qualname: str) -> None:
+    """Write a converted output back onto a dataclass return value.
+
+    Only reached when applying the declared unit produced a *new* array, which
+    for a dataclass means a pint-quantified field that needed converting — a
+    plain field is stamped in place and never comes through here.
+
+    A frozen dataclass cannot take the write. `setattr` raises
+    `FrozenInstanceError` (an `AttributeError`, despite reading like a type
+    error), which on its own says nothing about units; re-raise it with the
+    cause and the way out.
+
+    Args:
+        result: The returned dataclass instance.
+        name: The field to write.
+        value: The converted array.
+        qualname: The decorated function, for the error message.
+
+    Raises:
+        dataclasses.FrozenInstanceError: If `result` is frozen.
+    """
+    try:
+        setattr(result, name, value)
+    except dataclasses.FrozenInstanceError as exc:
+        raise dataclasses.FrozenInstanceError(
+            f"[{qualname}] output {name!r} is pint-quantified and needs converting "
+            f"to its declared unit, but the returned dataclass is frozen so the "
+            f"converted array cannot be written back. Dequantify the field in the "
+            f"function body (`.pint.dequantify()`), or drop `frozen=True`."
+        ) from exc
+
+
+def declare_units(
+    func: Callable[..., Any] | None = None,
+    *,
+    on_missing: OnMissing | None = None,
+    on_inexact: OnInexact | None = None,
+    on_output: OnOutput | None = None,
+) -> Callable[..., Any]:
+    """Apply a function's signature-declared units at runtime.
+
+    Reads the decorated function's own type annotations once, via
+    `units_from_signature`: parameters annotated `Annotated[DataArray, Unit(...)]`
+    (or the bare-string shorthand) declare input units, and a `TypedDict` return
+    (or a bare `Annotated[DataArray, Unit(...)]` return) declares output units.
+    Those annotations are the single source of truth, so a unit is never written
+    twice.
+
+    On each call, under the active `Policy` (`get_policy`), the wrapper:
+
+    1. validates/converts every declared `DataArray` input to its unit via
+       `check_units`;
+    2. runs the wrapped function;
+    3. applies each declared output unit to the returned `DataArray` (a `dict`
+       return is handled per key; a single `DataArray` return takes the bare
+       declared unit).
+
+    Note the asymmetry in step 3: an output is **stamped**, not converted.  A
+    body that does its own unit arithmetic (`return p * 100.0`) leaves `attrs`
+    holding the *input's* unit, so converting on the strength of that label would
+    scale correct values a second time.  The `on_output` axis can require the
+    label to match instead (`"strict"`), which suits only bodies that maintain
+    their own units; see `apply_output_units` for the trade-off.
+
+    Only `DataArray` values are touched; other arguments and returns pass
+    through unchanged.  When the policy is **disabled** (`enabled=False`) the
+    wrapper is a total no-op: inputs are not converted and outputs are not
+    stamped.
+
+    Usable bare (`@declare_units`) or called
+    (`@declare_units(on_missing="error")`).
+
+    Every declared unit string is checked against the registry **at decoration
+    time**, so a malformed or undefined unit fails fast at import — regardless
+    of policy — rather than only when the function first runs.
+
+    Args:
+        func: The function to decorate (when used bare).  `None` when called
+            with keyword arguments, in which case a parametrised decorator is
+            returned.
+        on_missing: Override the on-missing axis for the decorated function.
+            When `None` (default) resolved per call from `get_policy`.
+        on_inexact: Override the on-inexact axis for the decorated function.
+            When `None` (default) resolved per call from `get_policy`.
+        on_output: Override the on-output axis for the decorated function.
+            When `None` (default) resolved per call from `get_policy`.
+
+    Returns:
+        A wrapped function that validates inputs and stamps outputs according
+        to the active policy.
+    """
+    if on_missing is not None:
+        _validate_on_missing(on_missing)
+    if on_inexact is not None:
+        _validate_on_inexact(on_inexact)
+    if on_output is not None:
+        _validate_on_output(on_output)
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        input_units, output_units = units_from_signature(fn)
+        sig = inspect.signature(fn)
+        qualname = getattr(fn, "__qualname__", repr(fn))
+
+        # Fail fast on unparseable declarations (independent of policy).
+        for name, unit in input_units.items():
+            assert_valid_unit(unit, f"{qualname} input {name!r}")
+        if isinstance(output_units, str):
+            assert_valid_unit(output_units, f"{qualname} output")
+        elif isinstance(output_units, dict):
+            for name, unit in output_units.items():
+                assert_valid_unit(unit, f"{qualname} output {name!r}")
+
+        def _stamp(result: Any, eff_output: OnOutput | None) -> Any:
+            def apply(value: xr.DataArray, declared: str, name: str) -> xr.DataArray:
+                # Returns `value` itself for the attrs path (stamped in place),
+                # but a *converted* array for a quantified one -- so the result
+                # must always be written back, never discarded.
+                return apply_output_units(value, declared, name, eff_output, qualname)
+
+            if isinstance(output_units, str):
+                if isinstance(result, xr.DataArray):
+                    return apply(result, output_units, "return")
+            elif isinstance(output_units, dict):
+                if isinstance(result, dict):
+                    for name, value in result.items():
+                        declared = output_units.get(name)
+                        if declared is not None and isinstance(value, xr.DataArray):
+                            result[name] = apply(value, declared, name)
+                elif dataclasses.is_dataclass(result):
+                    for name, declared in output_units.items():
+                        value = getattr(result, name, None)
+                        if isinstance(value, xr.DataArray):
+                            applied = apply(value, declared, name)
+                            if applied is not value:
+                                _set_field(result, name, applied, qualname)
+            return result
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            pol = get_policy()
+            if not pol.enabled:
+                # Master switch off: a total no-op (no conversion, no stamping).
+                return fn(*args, **kwargs)
+            if input_units:
+                eff_missing = on_missing if on_missing is not None else pol.on_missing
+                eff_inexact = on_inexact if on_inexact is not None else pol.on_inexact
+                bound = sig.bind_partial(*args, **kwargs)
+                # bind_partial omits parameters left at their default; apply
+                # them so a declared default is converted too (the converted
+                # value is then passed explicitly via bound.args/bound.kwargs).
+                bound.apply_defaults()
+                for name, val in list(bound.arguments.items()):
+                    declared = input_units.get(name)
+                    if declared is not None and isinstance(val, xr.DataArray):
+                        bound.arguments[name] = check_units(
+                            val, declared, name, eff_missing, eff_inexact, qualname
+                        )
+                args, kwargs = bound.args, bound.kwargs
+            eff_output = on_output if on_output is not None else pol.on_output
+            return _stamp(fn(*args, **kwargs), eff_output)
+
+        wrapper.__annotations__ = dict(fn.__annotations__)
+        return wrapper
+
+    # @declare_units  →  func is the decorated function;
+    # @declare_units(on_missing=...)  →  func is None, return the parametrised decorator.
+    return decorate if func is None else decorate(func)

xarray_annotated/units/_registry.py

@@ -0,0 +1,94 @@
+r"""Pluggable pint registry selection.
+
+The active pint registry is **process-global**. By default nothing special
+happens at import time: `get_registry` falls back to
+`pint.get_application_registry()`, so plain pint unit strings work out of the
+box. CF-convention strings such as `"umol m-2 s-1"` or `"g m-2 d-1"` require
+cf-xarray's UDUNITS-aware registry, activated once via `use_cf_units`.
+"""
+
+import importlib.util
+
+import pint
+import pint_xarray
+
+_UREG: pint.UnitRegistry | pint.registry.ApplicationRegistry | None = None
+_using_cf: bool = False
+
+
+def get_registry() -> pint.UnitRegistry | pint.registry.ApplicationRegistry:
+    """Return the active pint `UnitRegistry`.
+
+    Defaults to `pint.get_application_registry()` (plain pint) until
+    `set_registry` or `use_cf_units` is called.
+
+    Returns:
+        The process-global pint `UnitRegistry`.
+    """
+    if _UREG is not None:
+        return _UREG
+    return pint.get_application_registry()
+
+
+def set_registry(ureg: pint.UnitRegistry | pint.registry.ApplicationRegistry) -> None:
+    """Set the process-wide pint registry used by this module and pint-xarray.
+
+    Also calls `pint_xarray.setup_registry(ureg)` so the `.pint` accessor and
+    this module's parse/compat helpers never drift apart, and
+    `pint.set_application_registry(ureg)` so pint's global application registry
+    (which pint-xarray follows for `.pint.quantify()`) stays in sync with this
+    module's choice. Without the latter, switching back to plain pint after
+    `use_cf_units` would leave the application registry pointing at the CF one.
+
+    pint has a single process-global application registry, so this is a
+    one-time, startup choice, not a per-array setting: quantities created under
+    two different registries cannot be mixed (pint raises).
+
+    Args:
+        ureg: The `UnitRegistry` to install as the process-global registry.
+    """
+    global _UREG, _using_cf
+    _UREG = ureg
+    _using_cf = False
+    pint_xarray.setup_registry(ureg)
+    pint.set_application_registry(ureg)
+
+
+def use_cf_units() -> None:
+    """Activate cf-xarray's UDUNITS-aware registry.
+
+    Lazily imports `cf_xarray.units` (from the `[cf]` extra) and installs its
+    registry via `set_registry`, so CF-convention unit strings such as
+    `"umol m-2 s-1"` and `"g m-2 d-1"` parse.
+
+    Raises:
+        ImportError: If `cf-xarray` is not installed.
+    """
+    global _using_cf
+    try:
+        import cf_xarray.units
+    except ImportError as exc:
+        raise ImportError(
+            "use_cf_units() requires cf-xarray. Install it with "
+            "`pip install xarray-annotated[cf]`."
+        ) from exc
+    set_registry(cf_xarray.units.units)
+    _using_cf = True
+
+
+def _cf_hint(unit: str) -> str:
+    """Suggest `use_cf_units` when a unit likely needs the CF registry.
+
+    Returns a parenthetical hint only when cf-xarray is installed but not yet
+    active, i.e. exactly the case where switching registries would fix a parse
+    failure. Empty string otherwise.
+
+    Args:
+        unit: The unit string that failed to parse.
+
+    Returns:
+        A hint string, or `""` when the hint is not applicable.
+    """
+    if _using_cf or importlib.util.find_spec("cf_xarray") is None:
+        return ""
+    return f" (call use_cf_units() to enable CF/UDUNITS units like {unit!r})"

xarray_annotated-0.5.2.dist-info/METADATA

@@ -0,0 +1,156 @@
+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
+Keywords: xarray,pint,units,validation,annotations
+Author: jmarshrossney
+Author-email: jmarshrossney <17361029+jmarshrossney@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: pandas>=2.2
+Requires-Dist: pint>=0.25.3
+Requires-Dist: pint-xarray>=0.6.1
+Requires-Dist: xarray>=2026.2.0
+Requires-Dist: cf-xarray>=0.11.3 ; extra == 'cf'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://jmarshrossney.github.io/xarray-annotated
+Project-URL: Repository, https://github.com/jmarshrossney/xarray-annotated
+Project-URL: Documentation, https://jmarshrossney.github.io/xarray-annotated
+Provides-Extra: cf
+Description-Content-Type: text/markdown
+
+# xarray-annotated
+
+[![PyPI version](https://img.shields.io/pypi/v/xarray-annotated)](https://pypi.org/project/xarray-annotated/)
+[![Python versions](https://img.shields.io/pypi/pyversions/xarray-annotated)](https://pypi.org/project/xarray-annotated/)
+[![CI](https://github.com/jmarshrossney/xarray-annotated/actions/workflows/ci.yml/badge.svg)](https://github.com/jmarshrossney/xarray-annotated/actions/workflows/ci.yml)
+[![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).
+
+The main idea is that annotations serve as a single source of truth for
+
+- structural schema (dims, coords, dtype),
+- physical units,
+- frequency (and phase) of a time axis,
+
+from which
+
+- 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).
+([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/)**.
+
+## Installation
+
+Either using `uv` (recommended) or `pip`:
+
+```sh
+uv add xarray-annotated
+# or
+pip install xarray-annotated
+```
+
+CF-convention / UDUNITS unit strings (e.g. `"umol m-2 s-1"`) need the optional `cf` extra, which pulls in [cf-xarray](https://cf-xarray.readthedocs.io).
+
+```sh
+uv add "xarray-annotated[cf]"
+# or
+pip install "xarray-annotated[cf]"
+```
+
+## A short example
+
+Here is a function that converts barometric pressure to altitude.
+It assumes a unit (pascals) and says so in the docstring but doesn't check or enforce it.
+
+```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)
+```
+```
+<xarray.DataArray (time: 2)> Size: 16B
+array([25876.55998663, 25921.86206292])
+Dimensions without coordinates: time
+Attributes:
+    units:    hPa
+```
+
+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).
+
+```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
+
+@declare_units
+@declare_schema
+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)
+
+p = xr.DataArray([1013.0, 1000.0], dims=["time"], attrs={"units": "hPa"})
+altitude(p)
+```
+```
+<xarray.DataArray (time: 2)> Size: 16B
+array([  2.08162886, 110.90398059])
+Dimensions without coordinates: time
+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.
+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:
+
+```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
+
+```sh
+uv sync   # install the package + dev dependencies into .venv
+just      # lint, typecheck, test, build docs
+```
+
+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
+```
+
+Contributions are welcome --- open an issue or pull request on GitHub.