Skip to content

salvus.flow.acta.session.task

salvus.flow.acta.session.task salvus flow acta session task

Register annotated functions as cached tasks.

Parameters must be keyword-only. Annotations determine parameter and artifact handling. Explicit impl values control invalidation; otherwise source fingerprints detect changes.

Functions

add_provenance()

def add_provenance(fields: Any) -> None: ...

Record extra provenance fields from inside a running task body.

Does nothing outside a task body.

Parameters
  • fields Any — Plain, JSON-serializable values to record.
Returns None

task()

def task(
    name: str | Callable[..., object] | None = None,
    impl: int | None = None,
    depends_on: Sequence[Callable[..., object]] = (),
    cache: bool = True,
    retention: str | Retention = Retention.STANDARD,
    normalize: Callable[[dict[str, Any]], Mapping[str, Any]] | None = None,
    tags: tuple[str, ...] = (),
    retries: int = 0,
    timeout_seconds: float | None = None,
    spec: type[BaseModel] | None = None,
) -> Any: ...

Register a function as a task.

Use as @task, @task(), or @task(...).

Parameters
  • name str | Callable[..., object] | None = None — Unique task name; defaults to the function’s qualified name.
  • impl int | None = None — Explicit implementation version. When set, code changes do not invalidate cached results; change this value to invalidate them. When omitted, use a source fingerprint. Fingerprints snapshot captured state at registration; re-register after changing that state. Unsupported captured objects require explicit inputs, deterministic serializers or a pinned version. Effective argument defaults affect keys even when impl is set.
  • depends_on Sequence[Callable[..., object]] = () — Additional callable dependencies to include in fingerprinting.
  • cache bool = True — Whether to memoize results.
  • retention str | Retention = Retention.STANDARD — Result lifetime as a Retention member or its name. Recorded at commit and excluded from cache keys.
  • normalize Callable[[dict[str, Any]], Mapping[str, Any]] | None = None — Callable transforming the argument mapping before hashing. Receives defaults and artifact digests. Affects cache keys and manifests, but not arguments passed to the task body. Compose acta.normalize.ignore_args(["site"]) and acta.normalize.round_to_significant_digits(["x"], digits=6) with | to apply them left to right. Custom mapping callables may appear on either side. Helpers raise KeyError for missing names; rounding supports built-in integer and float scalars.
  • tags tuple[str, ...] = () — Placement metadata, excluded from cache keys.
  • retries int = 0 — Remote execution retries; local execution does not retry.
  • timeout_seconds float | None = None — Remote flow timeout.
  • spec type[BaseModel] | None = None — Optional explicit parameter model.
Returns Any — The wrapped function, or a decorator when called with options. Tuple results are stored as one artifact and restored as tuples on direct calls, including nested containers and serializer-bearing members. Annotate them with tuple[T, U] or tuple[T, ...]. Lists and string-keyed dictionaries also support nested containers and serializable objects, for example dict[str, list[Receiver]], as inputs and results. Flat sequence inputs retain per-member refs.