xarray-annotated 0.5.2__py3-none-any.whl

xarray_annotated/schema/_decorator.py

@@ -0,0 +1,124 @@
+"""Signature-driven structural-declaration decorator.
+
+`declare_schema` wires the declaration side (`_annotations`) to the checking side
+(`_check`): it reads a function's `Annotated[DataArray, <markers>]` hints once, at
+decoration time, then on every call validates the declared inputs and outputs.
+
+Like `units.declare_units` this is deliberately the *convenience* layer — a plain
+function decorator over the public primitives (`schema_from_signature`,
+`check_schema`, `assert_valid_schema`) with no subclassing hierarchy.  Unlike it,
+schema validation never mutates: inputs and outputs are *checked* and passed
+through unchanged.
+"""
+
+import dataclasses
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+import xarray as xr
+
+from ._annotations import SchemaMarker, schema_from_signature
+from ._check import assert_valid_schema, check_schema
+from ._config import OnMismatch, _validate_on_mismatch, get_policy
+
+
+def declare_schema(
+    func: Callable[..., Any] | None = None,
+    *,
+    on_mismatch: OnMismatch | None = None,
+) -> Callable[..., Any]:
+    """Apply a function's signature-declared structure at runtime.
+
+    Reads the decorated function's own type annotations once, via
+    `schema_from_signature`: parameters annotated `Annotated[DataArray, <markers>]`
+    declare input structure, and a `TypedDict`/dataclass return (or a bare
+    `Annotated[DataArray, <markers>]` return) declares output structure.
+
+    On each call, under the active `Policy` (`get_policy`), the wrapper validates
+    every declared `DataArray` input via `check_schema`, runs the wrapped function,
+    then validates every declared output the same way.  Nothing is mutated; a
+    mismatch raises/warns/ignores per the effective `on_mismatch` (a marker's own
+    override wins over this decorator's `on_mismatch`, which wins over the policy
+    default).  When the policy is **disabled** the wrapper is a total no-op.
+
+    Usable bare (`@declare_schema`) or called (`@declare_schema(on_mismatch=...)`).
+    Every marker declaration is validated **at decoration time** (`assert_valid_schema`),
+    so a malformed declaration fails fast at import.
+
+    Args:
+        func: The function to decorate (when used bare); `None` when parametrised.
+        on_mismatch: Default severity for this function, overriding the policy
+            default. `None` (default) resolves per call from `get_policy`.
+
+    Returns:
+        A wrapped function that validates declared inputs and outputs.
+    """
+    if on_mismatch is not None:
+        _validate_on_mismatch(on_mismatch)
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        input_markers, output_markers = schema_from_signature(fn)
+        sig = inspect.signature(fn)
+        qualname = getattr(fn, "__qualname__", repr(fn))
+
+        # Fail fast on malformed declarations (independent of policy).
+        for pname, markers in input_markers.items():
+            for marker in markers:
+                assert_valid_schema(marker, f"{qualname} input {pname!r}")
+        _assert_output_declarations(output_markers, qualname)
+
+        def _check_output(result: Any, eff: OnMismatch) -> Any:
+            if isinstance(output_markers, list):
+                if isinstance(result, xr.DataArray):
+                    check_schema(result, output_markers, "return", eff, qualname)
+            elif isinstance(output_markers, dict):
+                for key, markers in output_markers.items():
+                    if isinstance(result, dict):
+                        value = result.get(key)
+                    elif dataclasses.is_dataclass(result):
+                        value = getattr(result, key, None)
+                    else:
+                        continue
+                    if isinstance(value, xr.DataArray):
+                        check_schema(value, markers, key, eff, 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 validation at all).
+                return fn(*args, **kwargs)
+            # Per-call default severity (a marker's own override still wins in check_schema).
+            eff = on_mismatch if on_mismatch is not None else pol.on_mismatch
+            if input_markers:
+                bound = sig.bind_partial(*args, **kwargs)
+                # bind_partial omits parameters left at their default; apply
+                # them so a declared default is validated too.
+                bound.apply_defaults()
+                for pname, val in list(bound.arguments.items()):
+                    markers = input_markers.get(pname)
+                    if markers is not None and isinstance(val, xr.DataArray):
+                        check_schema(val, markers, pname, eff, qualname)
+            return _check_output(fn(*args, **kwargs), eff)
+
+        wrapper.__annotations__ = dict(fn.__annotations__)
+        return wrapper
+
+    return decorate if func is None else decorate(func)
+
+
+def _assert_output_declarations(
+    output_markers: dict[str, list[SchemaMarker]] | list[SchemaMarker] | None,
+    qualname: str,
+) -> None:
+    """Fail-fast-validate declared output markers at decoration time."""
+    if isinstance(output_markers, list):
+        for marker in output_markers:
+            assert_valid_schema(marker, f"{qualname} output")
+    elif isinstance(output_markers, dict):
+        for key, markers in output_markers.items():
+            for marker in markers:
+                assert_valid_schema(marker, f"{qualname} output {key!r}")

xarray_annotated/temporal/__init__.py

@@ -0,0 +1,60 @@
+"""Temporal-frequency domain for xarray-annotated.
+
+Declares and validates the *frequency* of a DataArray's time axis — a property
+derived from the values of its datetime coordinate rather than carried in its
+metadata, which is why it is a domain of its own rather than a fourth structural
+marker.  Like ``xarray_annotated.schema`` (and unlike ``units``) it only *asserts*:
+it never converts, resamples, or stamps anything.
+
+A declaration compares on two things: **spacing** (always) and **phase** (the
+``End``/``Begin`` convention, and the anchor where both sides spell one).  So
+``Freq("7D")`` accepts a weekly axis on any weekday, while ``Freq("W-SUN")`` catches
+the classic resample footgun of a series landing on Wednesdays::
+
+    from typing import Annotated
+    import xarray as xr
+    from xarray_annotated.temporal import declare_freq, Freq
+
+    @declare_freq
+    def weekly_mean(x: Annotated[xr.DataArray, Freq("D")]) -> Annotated[xr.DataArray, Freq("W-SUN")]:
+        return x.resample(time="W-SUN").mean()
+
+``freq_compatible`` is the same comparison with no array in hand, for a build-time
+check of a producer/consumer edge.
+"""
+
+from ._annotations import Freq, annotated_freq, freq_from_signature
+from ._check import (
+    FreqError,
+    FreqWarning,
+    assert_valid_freq,
+    check_freq,
+    freq_compatible,
+)
+from ._config import (
+    OnMismatch,
+    OnUninferable,
+    Policy,
+    get_policy,
+    policy,
+    set_policy,
+)
+from ._decorator import declare_freq
+
+__all__ = [
+    "Freq",
+    "FreqError",
+    "FreqWarning",
+    "OnMismatch",
+    "OnUninferable",
+    "Policy",
+    "annotated_freq",
+    "assert_valid_freq",
+    "check_freq",
+    "declare_freq",
+    "freq_compatible",
+    "freq_from_signature",
+    "get_policy",
+    "policy",
+    "set_policy",
+]

xarray_annotated/temporal/_annotations.py

@@ -0,0 +1,154 @@
+"""The `Freq` marker declaring a DataArray's temporal frequency, and the reader.
+
+The temporal counterpart to ``schema._annotations``: where the schema markers
+declare properties an array *carries* (its dims, coords, dtype), ``Freq`` declares
+a property derived from the *values* of its datetime coordinate — the spacing (and
+phase) of its time axis::
+
+    Annotated[xr.DataArray, "degC", Freq("W-SUN")]
+
+The declared string is kept **verbatim**: pandas silently defaults the anchor a user
+did not spell (``"W"`` normalises to ``"W-SUN"``), so the raw spelling is the only
+place the *anchoredness* of a declaration survives.  See ``_check`` for how it is
+compared.
+
+There is deliberately **no bare-string shorthand** — a string in the metadata is a
+unit or a description, never a frequency.  The markers are immutable (``__slots__``)
+and hashable so an annotation carrying them stays hashable; ``eq``/``repr`` cover all
+fields, so ``eval(repr(m)) == m``.
+"""
+
+from typing import (
+    Annotated,
+    Any,
+    get_args,
+    get_origin,
+)
+
+from .._annotations import _is_dataarray_type, walk_signature
+from ._config import OnMismatch, _validate_on_mismatch
+
+
+class Freq:
+    """Declare the expected temporal frequency of a DataArray's time axis.
+
+    ``Freq("7D")`` declares an array whose datetime coordinate advances in
+    seven-day steps; ``Freq("W-SUN")`` declares the same spacing *and* pins the
+    phase to Sundays.  Two independent comparisons follow from the declaration:
+
+    * **spacing** — always compared (``"7D"`` and ``"W-WED"`` have the same spacing);
+    * **phase** — the ``End``/``Begin`` convention (``"ME"`` vs ``"MS"``), always
+      compared; and the anchor (``"-WED"``, ``"-MAR"``), compared only where the
+      declaration *spells* it.  ``Freq("W")`` therefore means "weekly, any weekday",
+      a deliberate divergence from pandas (which would default it to ``W-SUN``).
+
+    Pass ``anchored=True`` to opt in to pandas' default anchor anyway
+    (``Freq("W", anchored=True)`` means ``W-SUN`` and means it), or ``anchored=False``
+    to suppress the anchor comparison of a spelled-out anchor
+    (``Freq("W-SUN", anchored=False)`` = "weekly, any weekday").
+
+    Pass ``dim`` to name the time coordinate explicitly; by default the array's sole
+    datetime-like coordinate is used, and an array carrying two is ambiguous.
+    """
+
+    _freq: str
+    _dim: str | None
+    _anchored: bool | None
+    _on_mismatch: OnMismatch | None
+    __slots__ = ("_freq", "_dim", "_anchored", "_on_mismatch")
+
+    def __init__(
+        self,
+        freq: str,
+        *,
+        dim: str | None = None,
+        anchored: bool | None = None,
+        on_mismatch: OnMismatch | None = None,
+    ) -> None:
+        self._freq = freq
+        self._dim = dim
+        self._anchored = anchored
+        self._on_mismatch = (
+            None if on_mismatch is None else _validate_on_mismatch(on_mismatch)
+        )
+
+    @property
+    def freq(self) -> str:
+        """The declared frequency string, exactly as spelled."""
+        return self._freq
+
+    @property
+    def dim(self) -> str | None:
+        """The declared time dimension, or `None` to auto-detect it."""
+        return self._dim
+
+    @property
+    def anchored(self) -> bool | None:
+        """Whether the anchor is binding, or `None` to infer it from the spelling."""
+        return self._anchored
+
+    @property
+    def on_mismatch(self) -> OnMismatch | None:
+        """Per-marker severity override, or `None` to use the policy default."""
+        return self._on_mismatch
+
+    def __repr__(self) -> str:
+        parts = [repr(self._freq)]
+        if self._dim is not None:
+            parts.append(f"dim={self._dim!r}")
+        if self._anchored is not None:
+            parts.append(f"anchored={self._anchored!r}")
+        if self._on_mismatch is not None:
+            parts.append(f"on_mismatch={self._on_mismatch!r}")
+        return f"Freq({', '.join(parts)})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Freq):
+            return (self._freq, self._dim, self._anchored, self._on_mismatch) == (
+                other._freq,
+                other._dim,
+                other._anchored,
+                other._on_mismatch,
+            )
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self._freq, self._dim, self._anchored, self._on_mismatch))
+
+
+def annotated_freq(hint: Any) -> Freq | None:
+    """Return the `Freq` marker carried by an `Annotated` hint, or `None`.
+
+    The first `Freq` marker in the metadata, and only when the annotated base type
+    is a `DataArray` (incl. `DataArray | None`).  Non-`Annotated` hints, hints on
+    non-DataArray types, and hints with no `Freq` marker return `None` (so
+    `walk_signature`'s "no declaration" filter drops them).
+
+    Args:
+        hint: A type hint, typically from `get_type_hints(..., include_extras=True)`.
+
+    Returns:
+        The declared `Freq`, or `None`.
+    """
+    if get_origin(hint) is not Annotated:
+        return None
+    args = get_args(hint)
+    if not _is_dataarray_type(args[0]):
+        return None
+    return next((m for m in args[1:] if isinstance(m, Freq)), None)
+
+
+def freq_from_signature(
+    func: object,
+) -> tuple[dict[str, Freq], dict[str, Freq] | Freq | None]:
+    """Extract declared frequencies from a function's type annotations.
+
+    Args:
+        func: A callable whose hints carry `Annotated[DataArray, Freq(...)]`.
+
+    Returns:
+        An `(inputs, output)` pair, where each declaration is that parameter's
+        `Freq`; `output` is a per-field dict for a `TypedDict` or dataclass return,
+        a single `Freq` for one declared `DataArray` return, or `None`.
+    """
+    return walk_signature(func, annotated_freq)

xarray_annotated/temporal/_check.py

@@ -0,0 +1,326 @@
+"""Comparing declared frequencies, and validating a DataArray's time axis.
+
+Two legs, sharing one model of what a frequency *is*:
+
+* `freq_compatible` — marker vs marker, with no array in hand (the counterpart to
+  `schema.dims_compatible`), for a build-time check of a producer/consumer edge.
+* `check_freq` — marker vs DataArray, the runtime leg.
+
+**The model.** A declaration is compared along two independent keys:
+
+* **spacing** — always compared.  Fixed-length offsets (ticks, `D`, and `W`, which is
+  seven fixed days) reduce to a nanosecond count, so `"7D"` and `"W-WED"` have the
+  *same* spacing; calendar offsets reduce to a month count, so `"QE"` and `"3ME"` do
+  too.  The two families never compare equal (`"ME"` is not `"30D"`).  Anything else
+  (business days, custom offsets) is opaque and compares by its exact string.
+* **phase** — the `End`/`Begin` convention (`"ME"` vs `"MS"`), always compared; and the
+  anchor (`"-WED"`, `"-MAR"`), compared only where **both** declarations determine it.
+
+That last clause is the whole point.  pandas silently defaults an anchor the user did
+not spell (`to_offset("W").freqstr == "W-SUN"`), so anchoredness is read off the *raw
+declared string* — a `"-"` in it — never off the normalised offset.  `Freq("W")` thus
+means "weekly, any weekday" (a deliberate divergence from pandas), while `Freq("W-SUN")`
+means Sundays and will not accept a `W-WED` axis.  A marker's `anchored=` keyword
+overrides that inference either way.
+
+Known limitation: `Day` is DST-aware in pandas while `24h` is not, so treating them as
+the same spacing is an approximation for timezone-aware axes.
+"""
+
+import warnings
+
+import numpy as np
+import xarray as xr
+from pandas.tseries.frequencies import to_offset
+from pandas.tseries.offsets import (
+    BaseOffset,
+    Day,
+    MonthBegin,
+    MonthEnd,
+    QuarterBegin,
+    QuarterEnd,
+    Tick,
+    Week,
+    YearBegin,
+    YearEnd,
+)
+
+from ._annotations import Freq
+from ._config import (
+    OnMismatch,
+    OnUninferable,
+    _validate_on_mismatch,
+    _validate_on_uninferable,
+    get_policy,
+)
+
+_NANOS_PER_DAY = 86_400_000_000_000
+
+
+class FreqWarning(UserWarning):
+    """Warning issued for a frequency mismatch or an uninferable time axis."""
+
+
+class FreqError(Exception):
+    """Raised for a frequency mismatch under ``on_mismatch="error"``.
+
+    Deliberately **not** a ``ValueError``: a mismatch (the *data* fails the
+    declaration) is a distinct event from a malformed *declaration* (an unparseable
+    offset string), which raises ``ValueError`` from ``assert_valid_freq``.  Keeping
+    them on separate hierarchies means catching one never silently swallows the other.
+    """
+
+
+def assert_valid_freq(marker: Freq, context: str) -> None:
+    """Validate a `Freq` *declaration* itself, independent of any DataArray.
+
+    Used at decoration time to fail fast on a malformed declaration (an unparseable
+    offset string, an empty dim name) rather than only when the decorated function
+    first runs.  pandas' own message is kept — it is the one that explains that the
+    legacy aliases ``"M"`` and ``"H"`` are now spelled ``"ME"`` and ``"h"``.
+
+    Args:
+        marker: The declared `Freq`.
+        context: A label for the error message (e.g. ``"f input 'x'"``).
+
+    Raises:
+        ValueError: If the declaration is malformed.
+    """
+    if marker.dim is not None and not marker.dim:
+        raise ValueError(f"{context}: Freq dim must be a non-empty string.")
+    try:
+        to_offset(marker.freq)
+    except ValueError as exc:
+        raise ValueError(
+            f"{context}: invalid frequency {marker.freq!r}. {exc}"
+        ) from exc
+
+
+def _spacing(off: BaseOffset) -> tuple[str, object]:
+    """The comparable spacing of an offset: fixed nanoseconds, months, or opaque."""
+    if isinstance(off, (Tick, Day)):  # `Day` is not a `Tick` in pandas 3
+        return ("fixed", off.nanos)
+    if isinstance(off, Week):
+        return ("fixed", off.n * 7 * _NANOS_PER_DAY)  # what makes `7D` ≡ `W-*`
+    if isinstance(off, (MonthEnd, MonthBegin)):
+        return ("months", off.n)
+    if isinstance(off, (QuarterEnd, QuarterBegin)):
+        return ("months", 3 * off.n)
+    if isinstance(off, (YearEnd, YearBegin)):
+        return ("months", 12 * off.n)
+    # Business days, custom offsets: no reduction we can trust, so compare exactly.
+    return ("opaque", off.freqstr)
+
+
+def _convention(off: BaseOffset) -> str | None:
+    """The `"end"` / `"begin"` convention of a calendar offset, else `None`."""
+    if isinstance(off, (MonthEnd, QuarterEnd, YearEnd)):
+        return "end"
+    if isinstance(off, (MonthBegin, QuarterBegin, YearBegin)):
+        return "begin"
+    return None
+
+
+def _anchor(off: BaseOffset) -> int | None:
+    """The anchor pandas assigned to an offset (weekday / month), else `None`.
+
+    Note this is pandas' *normalised* anchor, which it fills in even where the user
+    spelled none — `_phase` decides whether it is binding.  (The `type: ignore`s are
+    because these attributes live on the Cython offset classes but not in the stubs.)
+    """
+    if isinstance(off, Week):
+        return off.weekday  # type: ignore[attr-defined]
+    if isinstance(off, (QuarterEnd, QuarterBegin)):
+        return off.startingMonth  # type: ignore[attr-defined]
+    if isinstance(off, (YearEnd, YearBegin)):
+        return off.month
+    return None
+
+
+def _phase(marker: Freq) -> tuple[str | None, int | None]:
+    """The comparable phase of a declaration: `(convention, anchor-or-None)`.
+
+    The anchor is `None` — meaning *undetermined*, so it is not compared — unless the
+    declaration determines it: either the raw string spells it out (`"W-WED"`) or the
+    marker forces the question with `anchored=`.
+    """
+    off = to_offset(marker.freq)
+    anchored = marker.anchored
+    if anchored is None:
+        anchored = "-" in marker.freq
+    return _convention(off), _anchor(off) if anchored else None
+
+
+def freq_compatible(a: Freq, b: Freq) -> bool:
+    """Return whether two `Freq` declarations can describe the same time axis.
+
+    The marker-vs-marker counterpart to `check_freq` (no array in hand), for a static
+    / build-time check of a producer/consumer edge.  Two declarations are compatible
+    when their **spacing** is the same and their **phase** does not conflict — where
+    "conflict" needs *both* sides to determine the thing being compared, so a
+    declaration that does not spell an anchor never conflicts on one.
+
+    Args:
+        a: A `Freq` marker.
+        b: Another `Freq` marker.
+
+    Returns:
+        `True` unless the two are provably inconsistent.
+
+    Raises:
+        ValueError: If either frequency string is unparseable.
+
+    Examples:
+        >>> from xarray_annotated.temporal import Freq, freq_compatible
+        >>> freq_compatible(Freq("7D"), Freq("W-WED"))  # same spacing, no anchor on 7D
+        True
+        >>> freq_compatible(Freq("W-SUN"), Freq("W-WED"))  # the resample-phase footgun
+        False
+        >>> freq_compatible(Freq("W"), Freq("W-WED"))  # "W" spells no anchor
+        True
+        >>> freq_compatible(Freq("QE"), Freq("3ME"))  # same spacing and convention
+        True
+        >>> freq_compatible(Freq("ME"), Freq("MS"))  # month-end is not month-start
+        False
+    """
+    if _spacing(to_offset(a.freq)) != _spacing(to_offset(b.freq)):
+        return False
+    (conv_a, anchor_a), (conv_b, anchor_b) = _phase(a), _phase(b)
+    if conv_a is not None and conv_b is not None and conv_a != conv_b:
+        return False
+    return not (anchor_a is not None and anchor_b is not None and anchor_a != anchor_b)
+
+
+def _is_datetime_like(da: xr.DataArray, name: str) -> bool:
+    """Whether a coordinate carries timestamps — numpy datetimes or cftime ones."""
+    if np.issubdtype(da.coords[name].dtype, np.datetime64):
+        return True
+    return isinstance(da.indexes.get(name), xr.CFTimeIndex)
+
+
+def _locate_axis(da: xr.DataArray, marker: Freq) -> tuple[str | None, str]:
+    """Find the time coordinate a `Freq` declaration is about.
+
+    Returns `(dim, "")` on success, or `(None, detail)` when the array offers no
+    unambiguous answer — which is itself a mismatch (the declaration says the array
+    has a time axis; it does not, or it has two).
+    """
+    candidates = [str(name) for name in da.coords if _is_datetime_like(da, str(name))]
+    if marker.dim is not None:
+        if marker.dim not in candidates:
+            return None, (
+                f"declared {marker!r} but {marker.dim!r} is not a datetime "
+                f"coordinate; datetime coords: {candidates}"
+            )
+        return marker.dim, ""
+    if not candidates:
+        return None, f"declared {marker!r} but the array has no datetime coordinate"
+    if len(candidates) > 1:
+        return None, (
+            f"declared {marker!r} but the time axis is ambiguous: datetime coords "
+            f"{candidates}; name one with Freq(..., dim=...)"
+        )
+    return candidates[0], ""
+
+
+def _infer(coord: xr.DataArray) -> str | None:
+    """The frequency of a time coordinate, or `None` if it has none.
+
+    `xarray.infer_freq` (not pandas') so a `CFTimeIndex` — a 360-day or noleap
+    calendar — works too.  It *raises* on fewer than three points and *returns* `None`
+    on irregular spacing; both mean the same thing here: uninferable.
+    """
+    try:
+        return xr.infer_freq(coord)
+    except ValueError:
+        return None
+
+
+def _report(ok: bool, severity: OnMismatch | OnUninferable, message: str) -> None:
+    """Act on a check result under the resolved severity."""
+    if ok or severity == "ignore":
+        return
+    if severity == "error":
+        raise FreqError(message)
+    # stacklevel=3 targets the declare_freq call path (user -> wrapper ->
+    # check_freq -> _report); one frame too far for a direct check_freq call.
+    warnings.warn(message, FreqWarning, stacklevel=3)
+
+
+def check_freq(
+    da: xr.DataArray,
+    declared: Freq | list[Freq],
+    name: str,
+    on_mismatch: OnMismatch | None = None,
+    on_uninferable: OnUninferable | None = None,
+    qualname: str | None = None,
+) -> xr.DataArray:
+    """Validate `da`'s time axis against its declared frequency; return it unchanged.
+
+    Locates the declared time coordinate (the array's sole datetime-like coordinate,
+    unless the marker names one), infers its frequency with `xarray.infer_freq`, and
+    compares that with the declaration via `freq_compatible`.  Because pandas always
+    hands back a fully-anchored string (`"W-WED"`, never `"7D"`), the *declaration*
+    alone decides how strict the comparison is — `Freq("7D")` accepts any weekday,
+    `Freq("W-SUN")` accepts only Sundays.
+
+    Two events, two axes.  A frequency that contradicts the declaration is a
+    **mismatch**, as is an array with no (or an ambiguous) time axis.  An axis whose
+    frequency cannot be inferred at all — fewer than three points, or irregular
+    spacing — is **uninferable**: the declaration was not violated, it was never
+    tested, and by default that warns rather than raises.
+
+    Severity resolves per marker as: the marker's own `on_mismatch` override, else the
+    `on_mismatch` argument, else the policy default.  When the master switch is off
+    (`enabled=False`) this is a total no-op.
+
+    Args:
+        da: The DataArray to validate.
+        declared: A single `Freq` or a list of them declared for `da`.
+        name: The parameter/field name, for error messages.
+        on_mismatch: Per-call default severity for a mismatch, overriding the policy
+            default but overridden by a marker's own `on_mismatch`.
+        on_uninferable: Per-call severity for an uninferable axis, overriding the
+            policy default.
+        qualname: Optional qualified function name, prefixed to messages.
+
+    Returns:
+        `da`, unchanged (validation never mutates).
+
+    Raises:
+        FreqError: On a mismatch when the effective severity is ``"error"``.
+    """
+    pol = get_policy()
+    if not pol.enabled:
+        return da
+    if on_mismatch is not None:
+        on_mismatch = _validate_on_mismatch(on_mismatch)
+    if on_uninferable is not None:
+        on_uninferable = _validate_on_uninferable(on_uninferable)
+
+    markers = [declared] if isinstance(declared, Freq) else declared
+    uninferable = on_uninferable or pol.on_uninferable
+    prefix = f"[{qualname}] {name!r}" if qualname else f"{name!r}"
+    for marker in markers:
+        severity = marker.on_mismatch or on_mismatch or pol.on_mismatch
+        dim, detail = _locate_axis(da, marker)
+        if dim is None:
+            _report(False, severity, f"{prefix} {detail}")
+            continue
+        inferred = _infer(da[dim])
+        if inferred is None:
+            _report(
+                False,
+                uninferable,
+                f"{prefix} frequency of {dim!r} is uninferable (fewer than three "
+                f"points, or irregular spacing), so {marker!r} was not checked",
+            )
+            continue
+        ok = freq_compatible(marker, Freq(inferred))
+        _report(
+            ok,
+            severity,
+            f"{prefix} frequency mismatch on {dim!r}: expected {marker.freq!r}, "
+            f"got {inferred!r}",
+        )
+    return da