core.validation

core.validation

Decorator engine for runtime validation, domain contracts, and docstring generation.

Two decorator tiers guard the processing functions:

• @requires_attrs(...) — gate: raise if required .attrs are missing.

• @ensures_domain(...) / @computes_in(...) — domain: establish the function’s working domain (time vs. spectral), transforming the input through the standard converters when needed and resolving a dim=None argument. ensures_domain implements the funnel contract (the result is left in the working domain); computes_in implements the domain-preserving contract (the result is transformed back to the input’s representation).

The two domain decorators share one private engine and differ only in whether the coercion is inverted after the wrapped function runs.

Functions¶

computes_in¶

core.validation.computes_in(domain)

Domain-preserving contract: compute in a physical domain, restore the representation.

The domain tier of the validation taxonomy, for operations whose physics is identical seen from either domain (e.g. apodize_exp, zero_fill). Input already in domain is processed directly. Input in the sibling domain takes a round trip: it is transformed in via the standard converters, processed, and transformed back — so the output keeps the input’s representation, with the original coordinates reassigned verbatim whenever the operation preserved the length. Real-valued spectral input is rejected (its inverse transform is undefined), and an explicitly requested dim outside domain passes through untouched.

Parameters¶

See Also¶

ensures_domain : The funnel contract (result is left in the working domain).

ensures_domain¶

core.validation.ensures_domain(domain)

Funnel contract: ensure the input is in a physical domain, leaving the result there.

The domain tier of the validation taxonomy, for operations that are only meaningful in one domain and whose result is consumed there (e.g. autophase, baseline_als). Before the wrapped function runs, its DataArray (first positional argument) is transformed into domain via the standard converters — a no-op if it is already there — and the result is left in that domain (no round-trip restore). A dim argument left as None is resolved to the unique domain dimension present; an explicitly supplied dim is never overridden.

Parameters¶

See Also¶

computes_in : The domain-preserving contract (round trip, representation restored).

requires_attrs¶

core.validation.requires_attrs(*keys)

Decorator to enforce that specific attributes exist in the input’s .attrs.

The gate tier of the validation taxonomy. The wrapped callable’s first positional argument must be the [xarray.DataArray](xref:xarray#xarray.DataArray) (free-function convention). If attributes are missing at runtime, it raises a clear ValueError with instructions on how to fix it using standard xarray methods. At import time, it dynamically appends the required attributes to the function’s docstring.

Parameters¶