Skip to content

xtr_workflow.decorator

Declaring workflows, their places and transitions, and their listeners where they are written.

Transition here is the marker a workflow class puts on its constants, not :class:xtr_workflow.Transition: import it from this package.

AsWorkflow dataclass

AsWorkflow(*, name: str | None = None, type: WorkflowType = WorkflowType.STATE_MACHINE, supports: type | Sequence[type] = (), support_strategy: str | None = None, initial_marking: str | Enum | Sequence[str | Enum] | None = None, marking_property: str | None = None, marking_store: str | None = None, description: InitVar[str | None] = None, metadata: Mapping[str, object] = dict[str, object](), audit_trail: bool = False, events_to_dispatch: Sequence[str] | None = None, definition_validators: Sequence[type[DefinitionValidatorInterface]] = (), places: type[Enum] | None = None, place_markers: Mapping[Enum, Place] = dict[Enum, Place]())

What @as_workflow declares about the workflow a class defines.

The transitions are the Transition markers on the class's constants; the places are those the transitions use, those of the places enum, and those a Place marker adds.

Attributes:

  • name (str | None) –

    The name of the workflow; without it, the class's name snake-cased, without its Workflow or StateMachine suffix.

  • type (WorkflowType) –

    Whether a subject is in one place at a time (a state machine) or in several (a workflow).

  • supports (type | Sequence[type]) –

    The classes of the subjects the workflow moves; without it nor support_strategy, the workflow is not in the registry and is only reached by injection.

  • support_strategy (str | None) –

    The service telling which subjects the workflow moves.

  • initial_marking (str | Enum | Sequence[str | Enum] | None) –

    The places a subject starts in; without it, the places marked initial, else the first member of places, else the first place the first transition leaves.

  • marking_property (str | None) –

    Where the subjects keep their marking; marking without it.

  • marking_store (str | None) –

    The service keeping the subjects' markings.

  • metadata (Mapping[str, object]) –

    The metadata of the workflow, its description included.

  • audit_trail (bool) –

    Whether every move is logged.

  • events_to_dispatch (Sequence[str] | None) –

    The events dispatched, or, each prefixed with !, those not dispatched; every one without it.

  • definition_validators (Sequence[type[DefinitionValidatorInterface]]) –

    Validators run on the definition, besides the one of its type.

  • places (type[Enum] | None) –

    The string enum listing the places: each member is a place, and each place must be a member.

  • place_markers (Mapping[Enum, Place]) –

    The Place marker of each enum member that needs one, keyed by the member.

NAME_PLACEHOLDER class-attribute

NAME_PLACEHOLDER: str = NAME_PLACEHOLDER

Stands for the workflow's name in the events of its class's listeners, until resolved.

Place dataclass

Place(description: InitVar[str | None] = None, metadata: Mapping[str, object] = dict[str, object](), initial: bool = False)

A place of a workflow declared with @as_workflow, with what it says about it.

Put it on a class constant valued with the place's name, to add a place no transition uses or to describe one: REVIEW: ClassVar[Annotated[str, Place(initial=True)]] = "review". For the members of an enum of places, hand it to @as_workflow through place_markers instead, keyed by the member.

Attributes:

  • metadata (Mapping[str, object]) –

    The metadata of the place, its description included.

  • initial (bool) –

    Whether the place is in the initial marking, unless the workflow declares its initial_marking.

Transition dataclass

Transition(froms: _Places, tos: _Places, description: InitVar[str | None] = None, guard: Callable[[GuardContext], bool | Awaitable[bool]] | None = None, metadata: Mapping[str, object] = dict[str, object]())

A transition of a workflow declared with @as_workflow.

Put it on a class constant valued with the transition's name: PUBLISH: ClassVar[Annotated[str, Transition(froms="draft", tos="published")]] = "publish". Repeat it in the same Annotated to declare several transitions of that name; a transition of a state machine has exactly one place in and one place out.

Attributes:

  • froms (_Places) –

    The places the transition leaves: names, members of a string enum, or :class:~xtr_workflow.Arc to weigh one — on their own or in a sequence.

  • tos (_Places) –

    The places the transition enters, given the same way.

  • guard (Callable[[GuardContext], bool | Awaitable[bool]] | None) –

    Called with the guard context — the subject, the security token and what to check it with; the transition is enabled only when it returns true, or an awaitable resolving to true.

  • metadata (Mapping[str, object]) –

    The metadata of the transition, its description included.

WorkflowListenerDeclaration dataclass

WorkflowListenerDeclaration(declaration: EventListenerDeclaration)

Marks an event listener declaration as made by a workflow listener decorator.

workflow.guard declared by @as_guard_listener() and by @as_event_listener("workflow.guard") read the same, but only the first belongs to the workflow its class declares: @as_workflow narrows the declarations this marks, and leaves a plain listener of every workflow alone.

Attributes: