xarray-annotated 0.5.2__tar.gz

xarray_annotated-0.5.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Marsh Rossney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xarray_annotated-0.5.2/PKG-INFO

@@ -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.

xarray_annotated-0.5.2/README.md

@@ -0,0 +1,129 @@
+# 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.

xarray_annotated-0.5.2/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+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"
+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.authors]]
+name = "jmarshrossney"
+email = "17361029+jmarshrossney@users.noreply.github.com"
+
+[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" },
+]
+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.per-file-ignores]
+"examples/notebook.py" = [
+    "F821",
+    "F722",
+]
+
+[tool.uv]
+exclude-newer = "1 week"
+
+[tool.uv.exclude-newer-package]
+marimo-md-export = false

xarray_annotated-0.5.2/pyproject.toml.orig

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+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"
+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"},
+]
+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.per-file-ignores]
+# 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").
+"examples/notebook.py" = ["F821", "F722"]
+
+[tool.uv]
+exclude-newer = "1 week"
+exclude-newer-package = { marimo-md-export = false }

xarray_annotated-0.5.2/src/xarray_annotated/__init__.py

@@ -0,0 +1,50 @@
+"""xarray-annotated: validate xarray DataArray properties declared via ``typing.Annotated``.
+
+Annotation is the unifying technology: a declared property is read off an
+``Annotated[DataArray, ...]`` hint and validated at runtime.  Each kind of
+property is a domain subpackage, imported explicitly:
+
+* ``xarray_annotated.units`` — physical units (pint / CF), the mature domain.
+* ``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.
+
+The top level is deliberately thin — nothing domain-specific is re-exported
+here, so the domains never collide in a shared namespace::
+
+    from xarray_annotated import schema, temporal, units
+    from xarray_annotated.units import declare_units, check_units
+    from xarray_annotated.schema import declare_schema, Dims, Dtype
+    from xarray_annotated.temporal import declare_freq, Freq
+
+The only names surfaced at the top level are domain-*agnostic* helpers that
+belong to no single domain: the shared declaration *writer* ``annotate`` and its
+inverse *reader* ``declarations_from_signature`` (which reads every facet declared
+on a signature into one uniform ``Declared`` value), plus the ``Annotated``
+introspection kernel (``unwrap_annotated``, ``walk_signature``).
+``walk_signature`` is the shared driver behind every domain's reader, so a
+third-party facet author can use it to build their own ``*_from_signature``
+reader.  No domain-specific name is re-exported here.
+"""
+
+from importlib.metadata import version as _version
+
+from . import schema, temporal, units
+from ._annotations import unwrap_annotated, walk_signature
+from ._reader import Declared, declarations_from_signature
+from ._writer import annotate
+
+__version__ = _version("xarray-annotated")
+
+__all__ = [
+    "Declared",
+    "__version__",
+    "annotate",
+    "declarations_from_signature",
+    "schema",
+    "temporal",
+    "units",
+    "unwrap_annotated",
+    "walk_signature",
+]

xarray_annotated-0.5.2/src/xarray_annotated/_annotations.py

@@ -0,0 +1,119 @@
+"""Shared `typing.Annotated` introspection for xarray-annotated.
+
+Pure `typing` machinery with no dependency on any domain's registry or config —
+the "declaration side" common to every domain. A domain supplies an *extractor*
+that turns one `Annotated[...]` hint into its own declaration payload (a unit
+string, a list of schema markers, …); `walk_signature` drives that extractor over
+a whole function signature, handling the `TypedDict` / dataclass / single-value
+return shapes once, for everyone.
+"""
+
+import dataclasses
+import types
+from collections.abc import Callable
+from typing import (
+    Annotated,
+    Any,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+    is_typeddict,
+)
+
+import xarray as xr
+
+_T = TypeVar("_T")
+
+
+def unwrap_annotated(hint: Any) -> Any:
+    """Return the underlying type of an `Annotated` hint, else the hint itself.
+
+    `Annotated[DataArray, ...]` → `DataArray`; a non-`Annotated` hint is returned
+    unchanged.  Lets type comparisons (e.g. `t is DataArray`) see through the
+    metadata that declarations attach to parameters.
+
+    Args:
+        hint: A type hint, possibly `Annotated`.
+
+    Returns:
+        The base type if `hint` is `Annotated`; otherwise `hint` unchanged.
+    """
+    return get_args(hint)[0] if get_origin(hint) is Annotated else hint
+
+
+def _is_dataarray_type(tp: Any) -> bool:
+    """Return whether `tp` is `DataArray` (possibly wrapped in a Union).
+
+    Accepts a bare `DataArray` as well as `DataArray | None` /
+    `Optional[DataArray]` (and any other union that includes `DataArray`), so an
+    optional DataArray parameter can still carry a declaration.  Anything else
+    (scalars, `str`, `bool`, `Dataset`, …) is not a declaration-bearing type.
+
+    Args:
+        tp: A type annotation to inspect.
+
+    Returns:
+        `True` if `tp` is or contains `DataArray`.
+    """
+    if tp is xr.DataArray:
+        return True
+    if get_origin(tp) in (Union, types.UnionType):
+        return any(_is_dataarray_type(arg) for arg in get_args(tp))
+    return False
+
+
+def walk_signature(
+    func: object,
+    extract: Callable[[Any], _T | None],
+) -> tuple[dict[str, _T], dict[str, _T] | _T | None]:
+    """Extract per-parameter and return declarations from a function's hints.
+
+    Reads `get_type_hints(func, include_extras=True)` and maps each hint through
+    `extract`, which returns a domain's declaration payload for that hint or
+    `None` when the hint carries no declaration.  The `is not None` filter is the
+    single "no declaration" rule shared by every domain.
+
+    Args:
+        func: A callable whose parameters/return may carry `Annotated` metadata.
+        extract: Turns one hint into a declaration payload, or `None`.  For units
+            this is `annotated_unit` (payload `str`); for schema `annotated_schema`
+            (payload `list[marker]`).
+
+    Returns:
+        An `(inputs, output)` pair:
+
+        * `inputs` — `dict[str, T]` mapping each declared parameter to its payload.
+        * `output` — a `dict[str, T]` (per-field) if the return hint is a
+            `TypedDict` or dataclass; a single `T` if the return is one declared
+            `Annotated[DataArray, ...]`; `None` otherwise.
+    """
+    hints = get_type_hints(func, include_extras=True)
+    ret = hints.pop("return", None)
+
+    inputs = {
+        name: payload
+        for name, hint in hints.items()
+        if (payload := extract(hint)) is not None
+    }
+
+    output: dict[str, _T] | _T | None
+    if is_typeddict(ret):
+        ret_hints = get_type_hints(ret, include_extras=True)
+        output = {
+            name: payload
+            for name, hint in ret_hints.items()
+            if (payload := extract(hint)) is not None
+        }
+    elif dataclasses.is_dataclass(ret):
+        ret_hints = get_type_hints(ret, include_extras=True)
+        output = {
+            f.name: payload
+            for f in dataclasses.fields(ret)
+            if (payload := extract(ret_hints.get(f.name))) is not None
+        }
+    else:
+        output = extract(ret)
+
+    return inputs, output