API

Actions and Flow Control

flowcontrol.base.FlowDirective

  • FlowDirective.CONTINUE: Run the next action in the sequence.
  • FlowDirective.ENTER: Run the sub-actions of the current action.
  • FlowDirective.LEAVE: Run the parent action again (like continue in a loop)
  • FlowDirective.BREAK: Run the parent action's next sibling (like break in a loop).
  • FlowDirective.ABORT: Stop the flow run.
  • FlowDirective.SUSPEND: Pause the execution of the flow run and continue with the action's next sibling at the time of the run's continue_after field.
  • FlowDirective.SUSPEND_AND_REPEAT: Pause the execution of the flow run and re-run the action at the time of the run's continue_after field.

flowcontrol.base.BaseAction

Inherit from this for your own actions:

get_context()

Get the context for the action. This method can be overridden in subclasses to provide additional context.

Returns:
  • –

    The context dictionary for the flow run.

get_name() classmethod

Get the name of the action, uses the class name by default.

return_from_children(*, run, obj=None, config=None)

This is run when returning from child actions to a parent action.

Parameters:
  • run (FlowRun) –

    The FlowRun instance to execute.

  • obj (Optional[Model], default: None ) –

    The model instance associated with the action.

  • config (Optional[Model], default: None ) –

    The configuration model instance for the action.
Returns:
  • Optional[FlowDirective] –

    Optional[FlowDirective]: The flow directive indicating the next action to take. FlowDirective.CONTINUE is used if None.

run(*, run, obj=None, config=None)

Run the action and return a flow directive This method should be overridden in subclasses.

Parameters:
  • run (FlowRun) –

    The FlowRun instance to execute.

  • obj (Optional[Model], default: None ) –

    The model instance associated with the action.

  • config (Optional[Model], default: None ) –

    The configuration model instance for the action.
Returns:
  • Optional[FlowDirective] –

    Optional[FlowDirective]: The flow directive indicating the next action to take. FlowDirective.CONTINUE is used if None.

flowcontrol.registry.register_action

Decorator to register an action class.

Parameters:
  • action_class (BaseAction) –

    The action class to register.
Returns:
  • BaseAction –

    The registered action class.

Flow Triggers

The function to register a trigger returns a function that can be called to start the associated flows. It's optional to use these functions, you can also call the flowcontrol.engine.trigger_flows directly.

flowcontrol.registry.register_trigger

Register the trigger name

Parameters:
  • name (str) –

    Name of the trigger

  • model (Optional[type], default: None ) –

    The Django model object this trigger provides. Defaults to None.

  • label (str, default: '' ) –

    A human readable label. Defaults to "".

  • description (str, default: '' ) –

    A human readable description. Defaults to "".
Returns:
  • Callable[[Optional[Model], Optional[dict], bool], None] –

    A function that can be used to execute the trigger.

flowcontrol.registry.register_trigger_as_signal_handler

Register a trigger and return a Django signal handler function.

This is a shortcut to register a trigger and returns a function that can be used as a signal handler.

Example:

post_save.connect(register_trigger_as_signal_handler("mymodel_postsave"))
Parameters:
  • name (str) –

    Name of the trigger

  • model (Optional[type], default: None ) –

    The Django model object this trigger provides. Defaults to None.

  • label (str, default: '' ) –

    A human readable label. Defaults to "".

  • description (str, default: '' ) –

    A human readable description. Defaults to "".
Returns:
  • Callable[[Model], None] –

    A Django signal handler function that triggers the associated flows with the sender as the associated object.

flowcontrol.engine.trigger_flows

Triggers flows based on the given trigger name.

Parameters:
  • trigger_name (str) –

    trigger name to look up in the database.

  • obj (Optional[Model], default: None ) –

    object associated with the flow run. Defaults to None.

  • state (Optional[dict], default: None ) –

    Default state of the flow run. Defaults to None.

  • immediate (bool, default: False ) –

    Execute immediately if True. Defaults to False.
Returns:
  • list[FlowRun] –

    A list of FlowRun instances that were created as a result of the trigger.

Flow Control Engine

flowcontrol.engine.create_flowrun

Creates a new flow run from flow when limits allow it.

Parameters:
  • flow (Flow) –

    The Flow instance to start.

  • obj (Optional[Model], default: None ) –

    The object related to the flow run.

  • state (Optional[dict], default: None ) –

    Optional initial state for the flow run.

  • parent_run (Optional[FlowRun], default: None ) –

    Optional parent FlowRun instance if this run is a child of another.

  • trigger (Optional[Trigger], default: None ) –

    The trigger that initiated this flow run.
Returns:
  • Optional[FlowRun] –

    The created FlowRun instance, or None if the run was not created.

flowcontrol.engine.start_flowrun

Creates a flow run (flow limits allowing) and executes it immediately.

Parameters:
  • flow (Flow) –

    The Flow instance to start.

  • obj (Optional[Model], default: None ) –

    The object related to the flow run.

  • state (Optional[dict], default: None ) –

    Optional initial state for the flow run.

  • parent_run (Optional[FlowRun], default: None ) –

    Optional parent FlowRun instance if this run is a child of another.
Returns:
  • Optional[FlowRun] –

    The created FlowRun instance, or None if the run was not created.

flowcontrol.engine.execute_flowrun

Executes the flow run, processing its actions.

Parameters:
  • run (FlowRun) –

    The FlowRun instance to execute.

  • max_hot_loop (int, default: MAX_HOT_LOOPS ) –

    Maximum number of times an action can be executed in a loop before aborting.
Returns:
  • Optional[FlowRun] –

    The updated FlowRun instance or None if the run was not executed due to its status.

flowcontrol.engine.cancel_flowrun

Cancel given flowrun.

Parameters:
  • run (FlowRun) –

    flowrun to cancel.

flowcontrol.engine.continue_flowruns

Execute all flowruns that can be continued.