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
File details
Details for the file pivotal_django_states-1.6.14.tar.gz
.
File metadata
- Download URL: pivotal_django_states-1.6.14.tar.gz
- Upload date:
- Size: 23.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.0.1 requests-toolbelt/0.8.0 tqdm/4.23.0 CPython/2.7.10
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 89d254daf4055f5533251210d5ee1059cbfc26551b9db1d2ba90d56335338e93 |
|
MD5 | 8ea8cd954ea88ef0e37f6378cf8889e2 |
|
BLAKE2b-256 | 6f7582c0194d8c42b1db85a13fb72abeaa6aa7f03ea7dc6bef71dcee01fa5e8d |
File details
Details for the file pivotal_django_states-1.6.14-py2.py3-none-any.whl
.
File metadata
- Download URL: pivotal_django_states-1.6.14-py2.py3-none-any.whl
- Upload date:
- Size: 25.7 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.0.1 requests-toolbelt/0.8.0 tqdm/4.23.0 CPython/2.7.10
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | e026a22450361b039e17868c84577e520b89cbd609eea226275f23bcb8e30a08 |
|
MD5 | a3777cb3ac284b3b9888fbb0c1252482 |
|
BLAKE2b-256 | 1278897dc7f64b44fd49043dd343f5d742e4758d151ae05b4dcaba5d2d95de00 |