Skip to main content

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pivotal_django_states-1.6.14.tar.gz (23.9 kB view details)

Uploaded Source

Built Distribution

pivotal_django_states-1.6.14-py2.py3-none-any.whl (25.7 kB view details)

Uploaded Python 2 Python 3

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

Hashes for pivotal_django_states-1.6.14.tar.gz
Algorithm Hash digest
SHA256 89d254daf4055f5533251210d5ee1059cbfc26551b9db1d2ba90d56335338e93
MD5 8ea8cd954ea88ef0e37f6378cf8889e2
BLAKE2b-256 6f7582c0194d8c42b1db85a13fb72abeaa6aa7f03ea7dc6bef71dcee01fa5e8d

See more details on using hashes here.

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

Hashes for pivotal_django_states-1.6.14-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 e026a22450361b039e17868c84577e520b89cbd609eea226275f23bcb8e30a08
MD5 a3777cb3ac284b3b9888fbb0c1252482
BLAKE2b-256 1278897dc7f64b44fd49043dd343f5d742e4758d151ae05b4dcaba5d2d95de00

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page