Skip to content

xtr_workflow.bundle

The xtr-dependency-injection bundle for xtr-workflow, and its configuration.

WORKFLOW_CHANNEL module-attribute

WORKFLOW_CHANNEL: Final = 'workflow'

The logging channel the audit trail writes to.

WORKFLOW_TAG module-attribute

WORKFLOW_TAG: Final = 'workflow'

The tag every workflow carries, with what it was registered from.

ArcConfig dataclass

ArcConfig(place: str | Enum, weight: int = 1)

How many tokens a configured transition moves through one place.

TransitionConfig("merge", froms=(ArcConfig("done", 2), "extra"), tos="archived")

Attributes:

  • place (str) –

    The name of the place; a member of a string enum given here is read as its value.

  • weight (int) –

    The number of tokens; at least 1.

Name the place, and weigh it.

AuditTrailConfig dataclass

AuditTrailConfig(enabled: bool = False)

Whether every move of a workflow's subjects is logged.

Attributes:

  • enabled (bool) –

    Log, on the workflow channel, each place a subject leaves and enters and each transition it takes; off unless enabled.

MarkingStoreConfig dataclass

MarkingStoreConfig(type: Literal['method'] | None = None, property: str | None = None, service: str | None = None)

Where a workflow keeps the marking of each subject.

A type or a property makes the workflow keep the marking on the subject itself, through a :class:~xtr_workflow.marking_store.MethodMarkingStore reading and writing property — marking without one — holding one place for a state machine and several for a workflow. Without either, service names the store; with nothing set at all, the workflow keeps the default store of its type.

Attributes:

  • type (Literal['method'] | None) –

    "method", the only store the workflow builds itself.

  • property (str | None) –

    The name of the subject's attribute, or of its get_<property> / set_<property> methods.

  • service (str | None) –

    The qualifier of the MarkingStoreInterface service to use instead.

PlaceConfig dataclass

PlaceConfig(name: str = '', metadata: Mapping[str, object] = dict[str, object]())

A place of a configured workflow, and what it says about it.

A workflow lists a place to add one no transition uses, to fix the order of its places, or to give it metadata; a place a transition uses needs no configuration of its own.

Attributes:

  • name (str) –

    The name of the place. A place keyed by its name in :attr:WorkflowDefinitionConfig.places may leave it empty, to be named by its key.

  • metadata (Mapping[str, object]) –

    The metadata of the place, its description included.

TransitionConfig dataclass

TransitionConfig(name: str = '', froms: _Arcs = (), tos: _Arcs = (), *, guard: Callable[[GuardContext], bool | Awaitable[bool]] | None = None, weight: int = 1, metadata: Mapping[str, object] = _NO_METADATA)

A transition of a configured workflow.

The places it leaves and enters are given as arcs, each written the shortest way that says it: a place's name, a member of a string enum, an :class:~xtr_workflow.Arc or an :class:ArcConfig to weigh it — on its own or in a sequence::

TransitionConfig("publish", froms="draft", tos=Status.PUBLISHED)
TransitionConfig("merge", froms=(ArcConfig("done", 2), "extra"), tos="archived")

Attributes:

  • name (str) –

    The name of the transition. A transition keyed by its name in :attr:WorkflowDefinitionConfig.transitions may leave it empty, to be named by its key.

  • froms (tuple[ArcConfig, ...]) –

    The arcs from the places the transition leaves.

  • tos (tuple[ArcConfig, ...]) –

    The arcs to the places the transition enters.

  • 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.

  • weight (int) –

    Checked to be at least 1, and read by nothing: only the weights of the arcs count. It is kept so a configuration setting it still reads.

  • metadata (Mapping[str, object]) –

    The metadata of the transition, its description included.

Name the transition and the places it moves tokens between.

WorkflowBundle

WorkflowBundle()

Bases: Bundle[WorkflowConfig]

Registers the configured and declared workflows, the registry, and their listeners.

Register into a build with no peer, until :meth:build says which are active.

prepend_extension

prepend_extension(builder: ContainerBuilder) -> None

Map each workflow event class to its name, and add the workflow logging channel.

build

build(builder: ContainerBuilder) -> None

Register the workflows the scan finds declared; trace every workflow in debug mode.

load_extension

load_extension(config: WorkflowConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Register the registry, every configured workflow, and the dump command with a console.

process

process(builder: ContainerBuilder) -> None

Wire the profiler panel when it is registered; build the dump command with a console.

The panel is handed every workflow defined, and every traced workflow the panel, once the scan has added the declared ones and the debug pass has wrapped them all.

The console registers the command as its class, whose constructor takes the workflows behind the service provider contract, and a dispatcher only when there is one; it is built instead by a factory taking the workflows' locator, and the dispatcher their listeners are on only when the event dispatcher bundle is active.

WorkflowConfig dataclass

WorkflowConfig(workflows: Mapping[str, WorkflowDefinitionConfig] = dict[str, WorkflowDefinitionConfig]())

The workflows and state machines the bundle registers, keyed by name.

Buildable with no arguments: activating the bundle with no workflow configured registers only those declared with @as_workflow.

WorkflowConfig(
    workflows={
        "blog_publishing": WorkflowDefinitionConfig(
            supports=Article,
            marking_store=MarkingStoreConfig(property="status"),
            transitions={
                "publish": TransitionConfig(froms="draft", tos="published"),
            },
        ),
    },
)

Attributes:

WorkflowDebugPass

Wraps every service tagged workflow in a :class:TraceableWorkflow.

The workflows the bundle registers, and any the application registers and tags itself: whatever asks for one — by its name, through a locator, through the registry — gets the traced one, and the record of its calls is cleared between units of work.

The bundle adds the pass in debug mode only.

process

process(builder: ContainerBuilder) -> None

Decorate each workflow with a traceable one, reset between units of work.

WorkflowDefinitionConfig dataclass

WorkflowDefinitionConfig(*, audit_trail: AuditTrailConfig = _AUDIT_TRAIL_DISABLED, type: WorkflowType = WorkflowType.STATE_MACHINE, marking_store: MarkingStoreConfig | None = None, supports: type | Sequence[type] = (), definition_validators: Sequence[type[DefinitionValidatorInterface]] = (), support_strategy: str | None = None, initial_marking: str | Enum | Sequence[str | Enum] = (), events_to_dispatch: Sequence[str] | None = None, places: _Places = (), transitions: _Transitions, metadata: Mapping[str, object] = _NO_METADATA)

A workflow or a state machine, configured.

Lists may be written the shortest way that says them, and are read into one shape: one supported class or initial place on its own; places as names, members of a string enum or :class:PlaceConfig — or keyed by name, a :class:PlaceConfig or None for each; transitions keyed by name. A place given by an enum member is named by its value::

WorkflowDefinitionConfig(
    supports=Article,
    initial_marking=Status.DRAFT,
    places=tuple(Status),
    transitions={
        "publish": TransitionConfig(froms=Status.DRAFT, tos=Status.PUBLISHED),
    },
)

Attributes:

  • audit_trail (AuditTrailConfig) –

    Whether every move of a subject is logged.

  • type (WorkflowType) –

    Whether a subject is in one place at a time or in several.

  • marking_store (MarkingStoreConfig | None) –

    Where the subjects' markings are kept; the default store of the workflow's type without it.

  • supports (tuple[type, ...]) –

    The classes of the subjects the workflow moves. Without them nor a support_strategy, the workflow is not in the registry, and is reached by injection only.

  • definition_validators (tuple[type[DefinitionValidatorInterface], ...]) –

    Validators run on the definition, besides the one of its type; each implements :class:~xtr_workflow.validator.DefinitionValidatorInterface and builds with no arguments.

  • support_strategy (str | None) –

    The qualifier of the WorkflowSupportStrategyInterface service telling which subjects the workflow moves.

  • initial_marking (tuple[str, ...]) –

    The places a subject starts in; the first place without them.

  • events_to_dispatch (tuple[str, ...] | None) –

    The events dispatched besides the guard, which always is: every one when None, none when empty, those listed, or — every entry prefixed with ! — every one but those.

  • places (tuple[PlaceConfig, ...]) –

    The places, in order; those the transitions use are added after them.

  • transitions (tuple[TransitionConfig, ...]) –

    The transitions; at least one.

  • metadata (Mapping[str, object]) –

    The metadata of the workflow, its description included.

Configure a workflow from its transitions, and what else it sets.

WorkflowServiceRegistrar

WorkflowServiceRegistrar(active_bundles: frozenset[str] = _NO_BUNDLE)

Registers the services of a workflow: its definition, the workflow, its listeners.

Shared by the workflows of the configuration and those declared with @as_workflow, so both are registered alike, and a name is taken by one of them only. The definition is built here, as the objects it is made of, and checked by its validators before anything is registered: a definition no workflow could run fails the build.

Each workflow is registered as WorkflowInterface under its name, the way to inject it; its definition and metadata store are under its name too.

Register workflows into a build where active_bundles are active.

register

register(services: ServiceConfigurator, name: str, config: WorkflowDefinitionConfig, source_class: type | None = None) -> None

Register the workflow name configured by config.

Parameters:

  • services (ServiceConfigurator) –

    Where the services are registered.

  • name (str) –

    The name of the workflow.

  • config (WorkflowDefinitionConfig) –

    Its configuration.

  • source_class (type | None, default: None ) –

    The class declaring it, for one declared with @as_workflow.

Raises:

  • LogicError –

    If the name is taken, or the workflow needs a bundle that is not active: the event dispatcher and logging for an audit trail, security for guards.

  • InvalidDefinitionError –

    If a validator refuses the definition.

registry_factory

registry_factory() -> Callable[..., Coroutine[None, None, Registry]]

Return the factory of the registry, holding every workflow that says what it moves.

The workflows are read when the registry is built, so those declared with @as_workflow, registered after it, are in it too.