Deus State Machina

Deus State Machina is a state machine for django that makes sure that you're not accidentally shooting yourself in the foot when doing things concurrently.

Deus state machina gives you:

One place to define your state machine transitions
No need for state checking
No more saving your model manually
State transitions define which how the model changes
No more race conditions! (for both database and threading)

Getting started

pip install deus-state-machina

Example:

Given that you have code that works like this:

UNKNOWN = 0
ALIVE = 1
DEAD = 2

class Cat(models.Model):                
    state = IntegerField(choices=[
        (UNKNOWN, 'Unknown'), 
        (ALIVE, 'Alive'), 
        (DEAD, 'Dead'),
    ])
    can_meow = models.Boolean(default=False)
    time_of_death = models.DateTimeField(null=True)

    def survive(self):
        if self.state == UNKNOWN:
            self.state = ALIVE 
            self.can_meow = True
            self.save()

    def rip(self):
        if self.state == UNKNOWN: 
            self.state = DEAD 
            self.time_of_death = now()
            self.save()

You can use deus state machina instead like so:

You define your state machine:

from deus_state_machina import State, StateMachine

class CatStateMachine(StateMachine):
    Unknown = State(0)
    Alive = State(1)
    Dead = State(2)

    def survive(self, instance, transition):
        instance.can_meow = True

    def rip(self, instance, transition):
        instance.time_of_death = now()

    transitions = [
        Unknown | survive | Alive,
        Unknown | rip | Dead,
    ]

Note how you have to wrap each state as State.

You can then use this in your model:

from deus_state_machina import StateMachineField

class Cat(models.Model):
    state = models.IntegerField(choices=...)
    state_machine = StateMachineField(CatStateMachine, 'state')

You can then trigger a state transition like this:

cat = Cat.objects.first()
if random.random() > 0.5:
    cat.state_machine.survive()
else:
    cat.state_machine.rip()

Or alternatively, using the target state in the transition_to call:

cat = Cat.objects.first()
if random.random() > 0.5:
    cat.state_machine.transition_to(ALIVE)
else:
    cat.state_machine.transition_to(DEAD)

You can integrate deus state machine step by step replacing one state transition at a time. Note that it has database locking and thread locking overhead compared to cowboy state machines.

tomtier / deus-state-machina Goto Github PK