XWorkflows¶
XWorkflows is a library designed to bring a simple approach to workflows in Python.
It provides:
- Simple workflow definition
- Running code when performing transitions
- Hooks for running extra code before/after the transition
- A hook for logging performed transitions
You can also refer to the django_xworkflows project for integration with Django.
Getting started¶
First, install the xworkflows package:
pip install xworkflows
Declaring workflows¶
You can now define a Workflow
:
import xworkflows
class MyWorkflow(xworkflows.Workflow):
states = (
('init', "Initial state"),
('ready', "Ready"),
('active', "Active"),
('done', "Done"),
('cancelled', "Cancelled"),
)
transitions = (
('prepare', 'init', 'ready'),
('activate', 'ready', 'active'),
('complete', 'active', 'done'),
('cancelled', ('ready', 'active'), 'cancelled'),
)
initial_state = 'init'
Applying a workflow¶
In order to apply that workflow to an object, you must:
- Inherit from
xworkflows.WorkflowEnabled
- Define one (or more) class attributes as
Workflow
instances.
Here is an example:
class MyObject(xworkflows.WorkflowEnabled):
state = MyWorkflow()
Using the transitions¶
With the previous definition, some methods have been magically added to your object
definition (have a look at WorkflowEnabledMeta
to see how).
There is now one method per transition defined in the workflow:
>>> obj = MyObject()
>>> obj.state
<StateWrapper: <State: 'init'>>
>>> obj.state.name
'init'
>>> obj.state.title
'Initial state'
>>> obj.prepare()
>>> obj.state
<StateWrapper: <State: 'ready'>>
>>> obj.state.name
'ready'
>>> obj.state.title
'Ready'
As seen in the example above, calling a transition automatically updates the state of the workflow.
Only transitions compatible with the current state may be called:
>>> obj.state
<StateWrapper: <State: 'ready'>>
>>> obj.complete()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
InvalidTransitionError: Transition 'complete' isn't available from state 'ready'.
Custom transition code¶
It is possible to define explicit code for a transition:
class MyObject(xworkflows.WorkflowEnabled):
state = MyWorkflow()
@xworkflows.transition()
def activate(self, user):
self.activated_by = user
print("State is %s" % self.state.name)
obj = MyObject()
When calling the transition, the custom code is called before updating the state:
>>> obj.state
<StateWrapper: <State: 'init'>>
>>> obj.prepare()
>>> obj.state
<StateWrapper: <State: 'ready'>>
>>> obj.activate('blah')
State is ready
>>> obj.state
<StateWrapper: <State: 'active'>>
>>> obj.activated_by
'blah'
Hooks¶
Other functions can be hooked onto transitions, through the before_transition()
,
after_transition()
, transition_check()
,
on_enter_state()
and on_leave_state()
decorators:
class MyObject(xworkflows.WorkflowEnabled):
state = MyWorkflow()
@xworkflows.before_transition('foobar', 'gobaz')
def hook(self, *args, **kwargs):
pass
Contents¶
- Reference
- Internals
- ChangeLog
- 1.1.1 (unreleased)
- 1.1.0 (2021-04-29)
- 1.0.4 (2014-08-11)
- 1.0.3 (2014-01-29)
- 1.0.2 (2013-09-24)
- 1.0.1 (2013-09-24)
- 1.0.0 (2013-04-29)
- 0.4.1 (2012-08-03)
- 0.4.0 (2012-08-02)
- 0.3.2 (2012-06-05)
- 0.3.1 (2012-05-29)
- 0.3.0 (2012-04-30)
- 0.2.4 (23 04 2012)
- 0.2.3 (15 04 2012)
- 0.2.1 (26 03 2012)
- 0.1.0 (08 09 2011)
Resources¶
- Package on PyPI: http://pypi.python.org/pypi/xworkflows
- Repository and issues on GitHub: http://github.com/rbarrois/xworkflows
- Doc on http://readthedocs.org/docs/xworkflows/