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 |
|
BLAKE2b-256 | 6f7582c0194d8c42b1db85a13fb72abeaa6aa7f03ea7dc6bef71dcee01fa5e8d |
Hashes for pivotal_django_states-1.6.14-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e026a22450361b039e17868c84577e520b89cbd609eea226275f23bcb8e30a08 |
|
MD5 | a3777cb3ac284b3b9888fbb0c1252482 |
|
BLAKE2b-256 | 1278897dc7f64b44fd49043dd343f5d742e4758d151ae05b4dcaba5d2d95de00 |