patch_function

patch_function(
    required_dims: str | collections.abc.Sequence[str, collections.abc.Sequence[str], Callable, None] = None,
    required_coords: str | collections.abc.Sequence[str, collections.abc.Sequence[str], None] = None,
    required_attrs: dict[dict[str, Any], str, collections.abc.Sequence[str], None] = None,
    history: Literal[‘full’, ‘method_name’, None] = full,
    validate_call: bool = False,
    data_type: str | None[str, None] = None,
    version: str = 1.0,
)

Decorator to mark a function as a patch method.

Parameters

Parameter	Description
required_dims	Required dimension name or names. Missing dimensions raise `PatchCoordinateError`.
required_coords	Required coordinate name or names. Missing coordinates raise `PatchCoordinateError`.
required_attrs	Required attribute name or names, or a mapping of names to values. Missing or mismatched attributes raise `PatchAttributeError`.
history	`"full"` records the function and arguments, `"method_name"` records only its name, and None records nothing.
validate_call	Whether Pydantic validates calls. This reduces manual checks but adds overhead. See validate_call.
data_type	Output `data_type`. None preserves it; an empty string clears it.
version	Operation version. Bump it when the same arguments mean a different result, keeping new fingerprints distinct from old ones.

Examples

import dascore as dc

@dc.patch_function(required_dims=("time", "distance"))
def do_something(patch):
    return patch

@dc.patch_function(required_attrs={"data_type": "DAS"})
def do_another_thing(patch):
    return patch

from pydantic import Field
@dc.patch_function(validate_call=True)
def validated(patch, count: int = Field(ge=1, le=10, default=1)):
    return patch

# Array API code supports non-NumPy backends.
from dascore.utils.array_api import array_namespace
@dc.patch_function()
def absolute(patch):
    xp = array_namespace(patch.data)
    return patch.new(data=xp.abs(patch.data))

# ``op`` builds a comparable, serializable PatchOp.
patch = dc.get_example_patch()
op = dc.proc.normalize.op(dim="time")
assert op(patch).equals(patch.normalize(dim="time"))
assert op == dc.proc.normalize.op(dim="time")

Note

raw_function exposes the undecorated function, which avoids applying this machinery twice inside another patch function. op builds a PatchOp with arguments bound to the signature, so positional and keyword spellings share a fingerprint.

When annotations use PatchType or SpoolType from constants, import dascore as dc in that module so their forward references resolve.