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 operation ids 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))

Note

raw_function exposes the undecorated function, which avoids applying this machinery twice inside another patch function.

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