Skip to content


Subversion checkout URL

You can clone with
Download ZIP
State machine for django models.
Python Makefile

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Django States (v2)

Author: Jonathan Slenders, City Live nv


    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.

Usage example:

    It's basically these two things:
    - Define a model derived from State, where you define the states and
      transitions in a machine.
    - Create a StateField in the model from which you want to track the state.

    >  class PurchaseState(State):
    >      class Machine(StateMachine):
    >          log_transitions = True
    >          class initiated(StateDefinition):
    >              description = _('Purchase initiated')
    >              initial = True
    >          class paid(StateDefinition):
    >              description = _('Purchase paid')
    >          class shipped(StateDefinition):
    >              description = _('Purchase shipped')
    >          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(models.Model):
    >      state = StateField(machine=PurchaseState)
    >      ... (other fields for a purchase)

    This will create the necessary models. if `log_transitions` is enabled, two more models
    are created. Everything should be compatible with South.

    Usage example:

    p = Purchase()   # Will automatically create state object for this purchase, in the initial state.
    p.state.value  # Will return 'paid'
    p.state.transitions.all() # Will return all the state transitions for this instance.
    p.state.transitions.all()[0].user # The user who triggered this transition
    p.state.transitions.all()[0].state.value # Will return 'complete' or 'failed', depending
                            # on the state of this state transition.

    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__value='initiated') 

    Actions for the Django Admin:

    >   class PurchaseAdmin(admin.ModelAdmin);
    >       actions = Purchase.get_admin_state_actions()
Something went wrong with that request. Please try again.