prefect.server.orchestration.rules
OrchestrationContext
OrchestrationContext
,
which is subsequently governed by nested orchestration rules implemented using
the BaseOrchestrationRule
ABC.
OrchestrationContext
introduces the concept of a state being None
in the
context of an intended state transition. An initial state can be None
if a run
is is attempting to set a state for the first time. The proposed state might be
None
if a rule governing the transition determines that no state change
should occur at all and nothing is written to the database.
Args:
session
: a SQLAlchemy database sessioninitial_state
: the initial state of a runproposed_state
: the proposed state a run is transitioning intoentry_context
OrchestrationContext
defines a state transition that is managed by
orchestration rules which can fire hooks before a transition has been committed
to the database. These hooks have a consistent interface which can be generated
with this method.
exit_context
OrchestrationContext
defines a state transition that is managed by
orchestration rules which can fire hooks after a transition has been committed
to the database. These hooks have a consistent interface which can be generated
with this method.
flow_run
initial_state_type
self.initial_state
if it exists.
model_validate_list
proposed_state_type
self.proposed_state
if it exists.
reset_fields
_reset_fields
set.
Returns:
run_settings
safe_copy
OrchestrationContext
. However, mutating objects stored on the context
directly can have unintended side-effects. To guard against this,
self.safe_copy
can be used to pass information to orchestration rules
without risking mutation.
Returns:
OrchestrationContext
validated_state_type
self.validated_state
if it exists.
FlowOrchestrationContext
OrchestrationContext
,
which is subsequently governed by nested orchestration rules implemented using
the BaseOrchestrationRule
ABC.
FlowOrchestrationContext
introduces the concept of a state being None
in the
context of an intended state transition. An initial state can be None
if a run
is is attempting to set a state for the first time. The proposed state might be
None
if a rule governing the transition determines that no state change
should occur at all and nothing is written to the database.
Args:
session
: a SQLAlchemy database sessionrun
: the flow run attempting to change stateinitial_state
: the initial state of a runproposed_state
: the proposed state a run is transitioning intoflow_run
run_settings
safe_copy
OrchestrationContext
. However, mutating objects stored on the context
directly can have unintended side-effects. To guard against this,
self.safe_copy
can be used to pass information to orchestration rules
without risking mutation.
Returns:
FlowOrchestrationContext
task_run
validate_proposed_state
FlowOrchestrationContext
is governed by orchestration rules, the
proposed state can be validated: the proposed state is added to the current
SQLAlchemy session and is flushed. self.validated_state
set to the flushed
state. The state on the run is set to the validated state as well.
If the proposed state is None
when this method is called, no state will be
written and self.validated_state
will be set to the run’s current state.
Returns:
TaskOrchestrationContext
OrchestrationContext
,
which is subsequently governed by nested orchestration rules implemented using
the BaseOrchestrationRule
ABC.
TaskOrchestrationContext
introduces the concept of a state being None
in the
context of an intended state transition. An initial state can be None
if a run
is is attempting to set a state for the first time. The proposed state might be
None
if a rule governing the transition determines that no state change
should occur at all and nothing is written to the database.
Args:
session
: a SQLAlchemy database sessionrun
: the task run attempting to change stateinitial_state
: the initial state of a runproposed_state
: the proposed state a run is transitioning intoflow_run
run_settings
safe_copy
OrchestrationContext
. However, mutating objects stored on the context
directly can have unintended side-effects. To guard against this,
self.safe_copy
can be used to pass information to orchestration rules
without risking mutation.
Returns:
TaskOrchestrationContext
task_run
validate_proposed_state
TaskOrchestrationContext
is governed by orchestration rules, the
proposed state can be validated: the proposed state is added to the current
SQLAlchemy session and is flushed. self.validated_state
set to the flushed
state. The state on the run is set to the validated state as well.
If the proposed state is None
when this method is called, no state will be
written and self.validated_state
will be set to the run’s current state.
Returns:
BaseOrchestrationRule
OrchestrationRule
is a stateful context manager that directly governs a state
transition. Complex orchestration is achieved by nesting multiple rules.
Each rule runs against an OrchestrationContext
that contains the transition
details; this context is then passed to subsequent rules. The context can be
modified by hooks that fire before and after a new state is validated and committed
to the database. These hooks will fire as long as the state transition is
considered “valid” and govern a transition by either modifying the proposed state
before it is validated or by producing a side-effect.
A state transition occurs whenever a flow- or task- run changes state, prompting
Prefect REST API to decide whether or not this transition can proceed. The current state of
the run is referred to as the “initial state”, and the state a run is
attempting to transition into is the “proposed state”. Together, the initial state
transitioning into the proposed state is the intended transition that is governed
by these orchestration rules. After using rules to enter a runtime context, the
OrchestrationContext
will contain a proposed state that has been governed by
each rule, and at that point can validate the proposed state and commit it to
the database. The validated state will be set on the context as
context.validated_state
, and rules will call the self.after_transition
hook
upon exiting the managed context.
Examples:
Create a rule:
context
: A FlowOrchestrationContext
or TaskOrchestrationContext
that is
passed between rulesfrom_state_type
: The state type of the initial state of a run, if this
state type is not contained in FROM_STATES
, no hooks will fireto_state_type
: The state type of the proposed state before orchestration, if
this state type is not contained in TO_STATES
, no hooks will fireabort_transition
None
, signaling to the
OrchestrationContext
that no state should be written to the database. A
reason for aborting the transition is also provided. Rules that abort the
transition will not fizzle, despite the proposed state type changing.
Args:
reason
: The reason for aborting the transitionafter_transition
initial_state
: The initial state of a transitionvalidated_state
: The governed state that has been committed to the databasecontext
: A safe copy of the OrchestrationContext
, with the exception of
context.run
, mutating this context will have no effect on the broader
orchestration environment.before_transition
self.reject_transition
,
self.delay_transition
, self.abort_transition
, and self.rename_state
.
Args:
initial_state
: The initial state of a transitionproposed_state
: The proposed state of a transitioncontext
: A safe copy of the OrchestrationContext
, with the exception of
context.run
, mutating this context will have no effect on the broader
orchestration environment.cleanup
self.before_transition
when the transition is found to be invalid on exit.
This allows multiple rules to be gracefully run in sequence, without logic that
keeps track of all other rules that might govern a transition.
Args:
initial_state
: The initial state of a transitionvalidated_state
: The governed state that has been committed to the databasecontext
: A safe copy of the OrchestrationContext
, with the exception of
context.run
, mutating this context will have no effect on the broader
orchestration environment.delay_transition
None
, signaling to the OrchestrationContext
that no state should be
written to the database. The number of seconds a transition should be delayed is
passed to the OrchestrationContext
. A reason for delaying the transition is
also provided. Rules that delay the transition will not fizzle, despite the
proposed state type changing.
Args:
delay_seconds
: The number of seconds the transition should be delayedreason
: The reason for delaying the transitionfizzled
self.before_transition
) but are invalid upon exiting the governed context,
most likely caused by another rule mutating the transition.
Returns:
invalid
self.FROM_STATES
and self.TO_STATES
, or if the context is proposing
a transition that differs from the transition the rule was instantiated with.
Returns:
invalid_transition
OrchestrationContext
is invalid.
If the OrchestrationContext
is attempting to manage a transition with this
rule that differs from the transition the rule was instantiated with, the
transition is considered to be invalid. Depending on the context, a rule with an
invalid transition is either “invalid” or “fizzled”.
Returns:
reject_transition
state
. A reason for rejecting the transition is also passed on
to the OrchestrationContext
. Rules that reject the transition will not fizzle,
despite the proposed state type changing.
Args:
state
: The new proposed state. If None
, the current run state will be
returned in the result instead.reason
: The reason for rejecting the transitionrename_state
update_context_parameters
FlowRunOrchestrationRule
TaskRunOrchestrationRule
GenericOrchestrationRule
BaseUniversalTransform
BaseOrchestrationRule
ABC,
Universal transforms are not stateful, and fire their before- and after- transition
hooks on every state transition unless the proposed state is None
, indicating that
no state should be written to the database. Because there are no guardrails in place
to prevent directly mutating state or other parts of the orchestration context,
universal transforms should only be used with care.
Args:
context
: A FlowOrchestrationContext
or TaskOrchestrationContext
that is
passed between transformsafter_transition
context
: the OrchestrationContext
that contains transition detailsbefore_transition
context
: the OrchestrationContext
that contains transition detailsexception_in_transition
nullified_transition
None
, indicating that
nothing should be written to the database.
Returns:
TaskRunUniversalTransform
FlowRunUniversalTransform
GenericUniversalTransform