GitHub

activity

API reference for activity.

Named steps of a workflow whose results the engine stores (Effect's effect/workflow/Activity)::

charge = activity.make(
    name="charge",
    success=S.String,
    error=S.String,
    execute=payments.charge(order),
)
charge_id = yield from charge

An activity is an effect. Run inside a workflow, it runs once: its exit is stored (encoded by its schemas), and a replay of the workflow gets the stored exit back instead of running it again. An activity interrupted from outside is retried (up to 10 times, exponential from 400 ms, at most 10 s apart; interrupt_retry_policy changes that).

Only completed results are stored: an activity that suspends (waiting on a child workflow or a durable clock) runs again when the workflow replays, so its side effects before the suspension must be idempotent.

Values

AttributeTypeDescription
DEFAULT_INTERRUPT_RETRY_POLICYInterruptRetryPolicy

Exponential from 400 ms, at most 10 s apart, while the activity was interrupted, at most 10 times.

Types

TypeDefinitionDescription
InterruptRetryPolicytype InterruptRetryPolicy = Schedule[Any, Cause[Any], Any, Any]

Classes

Functions

codec_of

codec_of[T](schema) -> Codec[T, Any, Never, Never]

The schema as a Codec (it is one: Exactly only checks it).

ParameterTypeDescription
schemaExactly[T]

Returns Codec[T, Any, Never, Never]

def codec_of[T](schema: Exactly[T]) -> Codec[T, Any, Never, Never]:
    """The schema as a ``Codec`` (it is one: ``Exactly`` only checks it)."""
    return cast("Codec[T, Any, Never, Never]", schema)

make

make(*, name: str, execute: Effect[None, Never, WorkflowEngine | WorkflowInstance | Scope], success: None = None, error: None = None, interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[None, Never, Never]
make[R](*, name: str, execute: Effect[None, Never, R | WorkflowEngine | WorkflowInstance | Scope], success: None = None, error: None = None, interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[None, Never, R]
make[A](*, name: str, execute: Effect[A, Never, WorkflowEngine | WorkflowInstance | Scope], success: Exactly[A], error: None = None, interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[A, Never, Never]
make[A, R](*, name: str, execute: Effect[A, Never, R | WorkflowEngine | WorkflowInstance | Scope], success: Exactly[A], error: None = None, interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[A, Never, R]
make[E](*, name: str, execute: Effect[None, E, WorkflowEngine | WorkflowInstance | Scope], success: None = None, error: Exactly[E], interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[None, E, Never]
make[E, R](*, name: str, execute: Effect[None, E, R | WorkflowEngine | WorkflowInstance | Scope], success: None = None, error: Exactly[E], interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[None, E, R]
make[A, E](*, name: str, execute: Effect[A, E, WorkflowEngine | WorkflowInstance | Scope], success: Exactly[A], error: Exactly[E], interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[A, E, Never]
make[A, E, R](*, name: str, execute: Effect[A, E, R | WorkflowEngine | WorkflowInstance | Scope], success: Exactly[A], error: Exactly[E], interrupt_retry_policy: InterruptRetryPolicy | None = None, annotations: Context[Any] | None = None) -> Activity[A, E, R]

An activity named name (unique within its workflow) running execute. success defaults to None (Effect's Void), error to none; execute is checked against them.

ParameterTypeDescription
name
execute
success= None
error= None
interrupt_retry_policy= None
annotations= None
@overload
def make(
    *,
    name: str,
    execute: Effect[None, Never, WorkflowEngine | WorkflowInstance | Scope],
    success: None = None,
    error: None = None,
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[None, Never, Never]: ...
@overload
def make[R](
    *,
    name: str,
    execute: Effect[None, Never, R | WorkflowEngine | WorkflowInstance | Scope],
    success: None = None,
    error: None = None,
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[None, Never, R]: ...
@overload
def make[A](
    *,
    name: str,
    execute: Effect[A, Never, WorkflowEngine | WorkflowInstance | Scope],
    success: Exactly[A],
    error: None = None,
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[A, Never, Never]: ...
@overload
def make[A, R](
    *,
    name: str,
    execute: Effect[A, Never, R | WorkflowEngine | WorkflowInstance | Scope],
    success: Exactly[A],
    error: None = None,
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[A, Never, R]: ...
@overload
def make[E](
    *,
    name: str,
    execute: Effect[None, E, WorkflowEngine | WorkflowInstance | Scope],
    success: None = None,
    error: Exactly[E],
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[None, E, Never]: ...
@overload
def make[E, R](
    *,
    name: str,
    execute: Effect[None, E, R | WorkflowEngine | WorkflowInstance | Scope],
    success: None = None,
    error: Exactly[E],
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[None, E, R]: ...
@overload
def make[A, E](
    *,
    name: str,
    execute: Effect[A, E, WorkflowEngine | WorkflowInstance | Scope],
    success: Exactly[A],
    error: Exactly[E],
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[A, E, Never]: ...
@overload
def make[A, E, R](
    *,
    name: str,
    execute: Effect[A, E, R | WorkflowEngine | WorkflowInstance | Scope],
    success: Exactly[A],
    error: Exactly[E],
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[A, E, R]: ...
def make[A = None, E = Never, R = Never](
    *,
    name: str,
    execute: Effect[A, E, R | WorkflowEngine | WorkflowInstance | Scope],
    success: Exactly[A] | None = None,
    error: Exactly[E] | None = None,
    interrupt_retry_policy: InterruptRetryPolicy | None = None,
    annotations: Context[Any] | None = None,
) -> Activity[A, E, R]:
    """An activity named ``name`` (unique within its workflow) running
    ``execute``. ``success`` defaults to ``None`` (Effect's ``Void``),
    ``error`` to none; ``execute`` is checked against them."""
    require_effect(execute, "execute")
    return Activity(
        name=name,
        success=cast("Codec[A, Any, Never, Never]", NullSchema)
        if success is None
        else codec_of(success),
        error=cast("Codec[E, Any, Never, Never]", NeverSchema)
        if error is None
        else codec_of(error),
        execute=execute,
        interrupt_retry_policy=(
            DEFAULT_INTERRUPT_RETRY_POLICY
            if interrupt_retry_policy is None
            else interrupt_retry_policy
        ),
        annotations=Context.empty() if annotations is None else annotations,
    )

retry

retry(*, times=None, while_=None, until=None) -> _Retry

Effect.retry (for .pipe) that sets CurrentAttempt for each attempt, so an activity made inside gets a name and an idempotency key per attempt.

ParameterTypeDescription
timesint | None = None
while_Callable[[Any], bool] | None = None
untilCallable[[Any], bool] | None = None

Returns _Retry

def retry(
    *,
    times: int | None = None,
    while_: Callable[[Any], bool] | None = None,
    until: Callable[[Any], bool] | None = None,
) -> _Retry:
    """``Effect.retry`` (for ``.pipe``) that sets ``CurrentAttempt`` for each
    attempt, so an activity made inside gets a name and an idempotency key
    per attempt."""
    options: dict[str, Any] = {}
    if times is not None:
        options["times"] = times
    if while_ is not None:
        options["while_"] = while_
    if until is not None:
        options["until"] = until
    return _Retry(options)

idempotency_key

idempotency_key(name, *, include_attempt=False) -> Effect[str, Never, WorkflowInstance]

A key unique to the current execution and name (and the attempt, with include_attempt), for idempotent calls to other systems.

ParameterTypeDescription
namestr
include_attemptbool = False

Returns Effect[str, Never, WorkflowInstance]

def idempotency_key(
    name: str, *, include_attempt: bool = False
) -> Effect[str, Never, WorkflowInstance]:
    """A key unique to the current execution and ``name`` (and the attempt,
    with ``include_attempt``), for idempotent calls to other systems."""

    def body() -> Generator[Effect[Any, Never, Any], Any, str]:
        instance = yield from WorkflowInstance()
        key = instance.execution_id
        if include_attempt:
            attempt = yield from CurrentAttempt()
            key += f"-{attempt}"
        key += f"-{name}"
        return (yield from make_hash_digest(key))

    return gen(body)

race_all

race_all[A, E, R](name, activities) -> Effect[A, E, R | WorkflowEngine | WorkflowInstance]

Race activities durably: the first to succeed wins (or the last failure), and a replay gets the same winner.

ParameterTypeDescription
namestr
activitiesSequence[Activity[A, E, R]]

Returns Effect[A, E, R | WorkflowEngine | WorkflowInstance]

def race_all[A, E, R](
    name: str, activities: Sequence[Activity[A, E, R]]
) -> Effect[A, E, R | WorkflowEngine | WorkflowInstance]:
    """Race ``activities`` durably: the first to succeed wins (or the last
    failure), and a replay gets the same winner."""
    from pyfect.workflow import durable_deferred

    if not activities:
        raise ValueError("race_all needs at least one activity")
    return durable_deferred.race_all(
        name=f"Activity/{name}",
        success=Union(*(a.success_schema for a in activities)),
        error=Union(*(a.error_schema for a in activities)),
        effects=activities,
    )