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
WorkfloworStateMachinesuffix. -
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;
markingwithout 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
Placemarker of each enum member that needs one, keyed by the member.
NAME_PLACEHOLDER
class-attribute
¶
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.Arcto 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
¶
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:
-
declaration(EventListenerDeclaration) –The event listener declaration the decorator made.