State machine for django models
Project description
Django States
Description
State engine for django models. Define a state graph for a model and remember the state of each object. State transitions can be logged for objects.
Note
This fork provides for changes specifically for Pivotal Energy Solutions
Installation
pip install pivotal-django-states
Usage example
from django_states.fields import StateField from django_states.machine import StateMachine, StateDefinition, StateTransition class PurchaseStateMachine(StateMachine): log_transitions = True # possible states class initiated(StateDefinition): description = _('Purchase initiated') initial = True class paid(StateDefinition): description = _('Purchase paid') def handler(self, instance): code_to_execute_when_arriving_in_this_state() class shipped(StateDefinition): description = _('Purchase shipped') # state transitions class mark_paid(StateTransition): from_state = 'initiated' to_state = 'paid' description = 'Mark this purchase as paid' class ship(StateTransition): from_state = 'paid' to_state = 'shipped' description = 'Ship purchase' def handler(transition, instance, user): code_to_execute_during_this_transition() def has_permission(transition, instance, user): return true_when_user_can_make_this_transition() class Purchase(StateModel): purchase_state = StateField(machine=PurchaseStateMachine, default='initiated') ... (other fields for a purchase)
If log_transitions
is enabled, another model is created. Everything
should be compatible with South_ for migrations.
Note: If you're creating a DataMigration
in
South <http://south.aeracode.org/>
__, remember to use
obj.save(no_state_validation=True)
Usage example:
p = Purchase() # Will automatically create state object for this purchase, in the # initial state. p.save() p.get_purchase_state_info().make_transition('mark_paid', request.user) # User parameter is optional p.state # Will return 'paid' p.get_purchase_state_info().description # Will return 'Purchase paid' # Returns an iterator of possible transitions for this purchase. p.get_purchase_state_info().possible_transitions() # Which can be used like this.. [x.get_name() for x in p.possible_transitions]
For better transition control, override:
has_permission(self, instance, user)
: Check whether this user is allowed to make this transition.handler(self, instance, user)
: Code to run during this transition. When an exception has been raised in here, the transition will not be made.
Get all objects in a certain state::
Purchase.objects.filter(state='initiated')
Validation
You can add a test that needs to pass before a state transition can be
executed. Well, you can add 2: one based on the current user
(has_permission
) and one generic (validate
).
So on a StateTransition
-object you need to specify an extra
validate
function (signature is validate(cls, instance)
). This
should yield TransitionValidationError
, this way you can return
multiple errors on that need to pass before the transition can happen.
The has_permission
function (signature
has_permission(transition, instance, user)
) should check whether the
given user is allowed to make the transition. E.g. a super user can
moderate all comments while other users can only moderate comments on
their blog-posts.
Groups
Sometimes you want to group several states together, since for a certain view (or other content) it doesn't really matter which of the states it is. We support 2 different state groups, inclusive (only these) or exclusive (everything but these):
class is_paid(StateGroup): states = ['paid', 'shipped'] class is_paid(StateGroup): exclude_states = ['initiated']
State graph
You can get a graph of your states by running the graph_states
management command.
python manage.py graph_states myapp.Purchase.state
This requires graphviz and python bindings for
graphviz: pygraphviz
and yapgvb
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pivotal_django_states-1.6.14.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 89d254daf4055f5533251210d5ee1059cbfc26551b9db1d2ba90d56335338e93 |
|
MD5 | 8ea8cd954ea88ef0e37f6378cf8889e2 |
|
BLAKE2-256 | 6f7582c0194d8c42b1db85a13fb72abeaa6aa7f03ea7dc6bef71dcee01fa5e8d |
Hashes for pivotal_django_states-1.6.14-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e026a22450361b039e17868c84577e520b89cbd609eea226275f23bcb8e30a08 |
|
MD5 | a3777cb3ac284b3b9888fbb0c1252482 |
|
BLAKE2-256 | 1278897dc7f64b44fd49043dd343f5d742e4758d151ae05b4dcaba5d2d95de00 |