pytransitions / transitions Goto Github PK

A lightweight, object-oriented finite state machine implementation in Python with many extensions

License: MIT License

Python 99.99% Shell 0.01%

python state-machine nested-states hierarchical-state-machine state-diagram

transitions's Introduction

transitions

A lightweight, object-oriented state machine implementation in Python with many extensions. Compatible with Python 2.7+ and 3.0+.

Installation

pip install transitions

... or clone the repo from GitHub and then:

python setup.py install

Quickstart
Non-Quickstart

Quickstart

They say a good example is worth 100 pages of API documentation, a million directives, or a thousand words.

Well, "they" probably lie... but here's an example anyway:

from transitions import Machine
import random

class NarcolepticSuperhero(object):

    # Define some states. Most of the time, narcoleptic superheroes are just like
    # everyone else. Except for...
    states = ['asleep', 'hanging out', 'hungry', 'sweaty', 'saving the world']

    def __init__(self, name):

        # No anonymous superheroes on my watch! Every narcoleptic superhero gets
        # a name. Any name at all. SleepyMan. SlumberGirl. You get the idea.
        self.name = name

        # What have we accomplished today?
        self.kittens_rescued = 0

        # Initialize the state machine
        self.machine = Machine(model=self, states=NarcolepticSuperhero.states, initial='asleep')

        # Add some transitions. We could also define these using a static list of
        # dictionaries, as we did with states above, and then pass the list to
        # the Machine initializer as the transitions= argument.

        # At some point, every superhero must rise and shine.
        self.machine.add_transition(trigger='wake_up', source='asleep', dest='hanging out')

        # Superheroes need to keep in shape.
        self.machine.add_transition('work_out', 'hanging out', 'hungry')

        # Those calories won't replenish themselves!
        self.machine.add_transition('eat', 'hungry', 'hanging out')

        # Superheroes are always on call. ALWAYS. But they're not always
        # dressed in work-appropriate clothing.
        self.machine.add_transition('distress_call', '*', 'saving the world',
                         before='change_into_super_secret_costume')

        # When they get off work, they're all sweaty and disgusting. But before
        # they do anything else, they have to meticulously log their latest
        # escapades. Because the legal department says so.
        self.machine.add_transition('complete_mission', 'saving the world', 'sweaty',
                         after='update_journal')

        # Sweat is a disorder that can be remedied with water.
        # Unless you've had a particularly long day, in which case... bed time!
        self.machine.add_transition('clean_up', 'sweaty', 'asleep', conditions=['is_exhausted'])
        self.machine.add_transition('clean_up', 'sweaty', 'hanging out')

        # Our NarcolepticSuperhero can fall asleep at pretty much any time.
        self.machine.add_transition('nap', '*', 'asleep')

    def update_journal(self):
        """ Dear Diary, today I saved Mr. Whiskers. Again. """
        self.kittens_rescued += 1

    @property
    def is_exhausted(self):
        """ Basically a coin toss. """
        return random.random() < 0.5

    def change_into_super_secret_costume(self):
        print("Beauty, eh?")

There, now you've baked a state machine into NarcolepticSuperhero. Let's take him/her/it out for a spin...

>>> batman = NarcolepticSuperhero("Batman")
>>> batman.state
'asleep'

>>> batman.wake_up()
>>> batman.state
'hanging out'

>>> batman.nap()
>>> batman.state
'asleep'

>>> batman.clean_up()
MachineError: "Can't trigger event clean_up from state asleep!"

>>> batman.wake_up()
>>> batman.work_out()
>>> batman.state
'hungry'

# Batman still hasn't done anything useful...
>>> batman.kittens_rescued
0

# We now take you live to the scene of a horrific kitten entreement...
>>> batman.distress_call()
'Beauty, eh?'
>>> batman.state
'saving the world'

# Back to the crib.
>>> batman.complete_mission()
>>> batman.state
'sweaty'

>>> batman.clean_up()
>>> batman.state
'asleep'   # Too tired to shower!

# Another productive day, Alfred.
>>> batman.kittens_rescued
1

While we cannot read the mind of the actual batman, we surely can visualize the current state of our NarcolepticSuperhero.

Have a look at the Diagrams extensions if you want to know how.

The non-quickstart

Basic initialization

Getting a state machine up and running is pretty simple. Let's say you have the object lump (an instance of class Matter), and you want to manage its states:

class Matter(object):
    pass

lump = Matter()

You can initialize a (minimal) working state machine bound to lump like this:

from transitions import Machine
machine = Machine(model=lump, states=['solid', 'liquid', 'gas', 'plasma'], initial='solid')

# Lump now has state!
lump.state
>>> 'solid'

I say "minimal", because while this state machine is technically operational, it doesn't actually do anything. It starts in the 'solid' state, but won't ever move into another state, because no transitions are defined... yet!

Let's try again.

# The states
states=['solid', 'liquid', 'gas', 'plasma']

# And some transitions between states. We're lazy, so we'll leave out
# the inverse phase transitions (freezing, condensation, etc.).
transitions = [
    { 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid' },
    { 'trigger': 'evaporate', 'source': 'liquid', 'dest': 'gas' },
    { 'trigger': 'sublimate', 'source': 'solid', 'dest': 'gas' },
    { 'trigger': 'ionize', 'source': 'gas', 'dest': 'plasma' }
]

# Initialize
machine = Machine(lump, states=states, transitions=transitions, initial='liquid')

# Now lump maintains state...
lump.state
>>> 'liquid'

# And that state can change...
lump.evaporate()
lump.state
>>> 'gas'
lump.trigger('ionize')
lump.state
>>> 'plasma'

Notice the shiny new methods attached to the Matter instance (evaporate(), ionize(), etc.). Each method triggers the corresponding transition. You don't have to explicitly define these methods anywhere; the name of each transition is bound to the model passed to the Machine initializer (in this case, lump). To be more precise, your model should not already contain methods with the same name as event triggers since transitions will only attach convenience methods to your model if the spot is not already taken. If you want to modify that behaviour, have a look at the FAQ. Furthermore, there is a method called trigger now attached to your model (if it hasn't been there before). This method lets you execute transitions by name in case dynamic triggering is required.

States

The soul of any good state machine (and of many bad ones, no doubt) is a set of states. Above, we defined the valid model states by passing a list of strings to the Machine initializer. But internally, states are actually represented as State objects.

You can initialize and modify States in a number of ways. Specifically, you can:

pass a string to the Machine initializer giving the name(s) of the state(s), or
directly initialize each new State object, or
pass a dictionary with initialization arguments

The following snippets illustrate several ways to achieve the same goal:

# import Machine and State class
from transitions import Machine, State

# Create a list of 3 states to pass to the Machine
# initializer. We can mix types; in this case, we
# pass one State, one string, and one dict.
states = [
    State(name='solid'),
    'liquid',
    { 'name': 'gas'}
    ]
machine = Machine(lump, states)

# This alternative example illustrates more explicit
# addition of states and state callbacks, but the net
# result is identical to the above.
machine = Machine(lump)
solid = State('solid')
liquid = State('liquid')
gas = State('gas')
machine.add_states([solid, liquid, gas])

States are initialized once when added to the machine and will persist until they are removed from it. In other words: if you alter the attributes of a state object, this change will NOT be reset the next time you enter that state. Have a look at how to extend state features in case you require some other behaviour.

Callbacks

A State can also be associated with a list of enter and exit callbacks, which are called whenever the state machine enters or leaves that state. You can specify callbacks during initialization by passing them to a State object constructor, in a state property dictionary, or add them later.

For convenience, whenever a new State is added to a Machine, the methods on_enter_«state name» and on_exit_«state name» are dynamically created on the Machine (not on the model!), which allow you to dynamically add new enter and exit callbacks later if you need them.

# Our old Matter class, now with  a couple of new methods we
# can trigger when entering or exit states.
class Matter(object):
    def say_hello(self): print("hello, new state!")
    def say_goodbye(self): print("goodbye, old state!")

lump = Matter()

# Same states as above, but now we give StateA an exit callback
states = [
    State(name='solid', on_exit=['say_goodbye']),
    'liquid',
    { 'name': 'gas', 'on_exit': ['say_goodbye']}
    ]

machine = Machine(lump, states=states)
machine.add_transition('sublimate', 'solid', 'gas')

# Callbacks can also be added after initialization using
# the dynamically added on_enter_ and on_exit_ methods.
# Note that the initial call to add the callback is made
# on the Machine and not on the model.
machine.on_enter_gas('say_hello')

# Test out the callbacks...
machine.set_state('solid')
lump.sublimate()
>>> 'goodbye, old state!'
>>> 'hello, new state!'

Note that on_enter_«state name» callback will not fire when a Machine is first initialized. For example if you have an on_enter_A() callback defined, and initialize the Machine with initial='A', on_enter_A() will not be fired until the next time you enter state A. (If you need to make sure on_enter_A() fires at initialization, you can simply create a dummy initial state and then explicitly call to_A() inside the __init__ method.)

In addition to passing in callbacks when initializing a State, or adding them dynamically, it's also possible to define callbacks in the model class itself, which may increase code clarity. For example:

class Matter(object):
    def say_hello(self): print("hello, new state!")
    def say_goodbye(self): print("goodbye, old state!")
    def on_enter_A(self): print("We've just entered state A!")

lump = Matter()
machine = Machine(lump, states=['A', 'B', 'C'])

Now, any time lump transitions to state A, the on_enter_A() method defined in the Matter class will fire.

Checking state

You can always check the current state of the model by either:

inspecting the .state attribute, or
calling is_«state name»()

And if you want to retrieve the actual State object for the current state, you can do that through the Machine instance's get_state() method.

lump.state
>>> 'solid'
lump.is_gas()
>>> False
lump.is_solid()
>>> True
machine.get_state(lump.state).name
>>> 'solid'

If you'd like you can choose your own state attribute name by passing the model_attribute argument while initializing the Machine. This will also change the name of is_«state name»() to is_«model_attribute»_«state name»() though. Similarly, auto transitions will be named to_«model_attribute»_«state name»() instead of to_«state name»(). This is done to allow multiple machines to work on the same model with individual state attribute names.

lump = Matter()
machine = Machine(lump, states=['solid', 'liquid', 'gas'],  model_attribute='matter_state', initial='solid')
lump.matter_state
>>> 'solid'
# with a custom 'model_attribute', states can also be checked like this:
lump.is_matter_state_solid()
>>> True
lump.to_matter_state_gas()
>>> True

Enumerations

So far we have seen how we can give state names and use these names to work with our state machine. If you favour stricter typing and more IDE code completion (or you just can't type 'sesquipedalophobia' any longer because the word scares you) using Enumerations might be what you are looking for:

import enum  # Python 2.7 users need to have 'enum34' installed
from transitions import Machine

class States(enum.Enum):
    ERROR = 0
    RED = 1
    YELLOW = 2
    GREEN = 3

transitions = [['proceed', States.RED, States.YELLOW],
               ['proceed', States.YELLOW, States.GREEN],
               ['error', '*', States.ERROR]]

m = Machine(states=States, transitions=transitions, initial=States.RED)
assert m.is_RED()
assert m.state is States.RED
state = m.get_state(States.RED)  # get transitions.State object
print(state.name)  # >>> RED
m.proceed()
m.proceed()
assert m.is_GREEN()
m.error()
assert m.state is States.ERROR

You can mix enums and strings if you like (e.g. [States.RED, 'ORANGE', States.YELLOW, States.GREEN]) but note that internally, transitions will still handle states by name (enum.Enum.name). Thus, it is not possible to have the states 'GREEN' and States.GREEN at the same time.

Transitions

Some of the above examples already illustrate the use of transitions in passing, but here we'll explore them in more detail.

As with states, each transition is represented internally as its own object – an instance of class Transition. The quickest way to initialize a set of transitions is to pass a dictionary, or list of dictionaries, to the Machine initializer. We already saw this above:

transitions = [
    { 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid' },
    { 'trigger': 'evaporate', 'source': 'liquid', 'dest': 'gas' },
    { 'trigger': 'sublimate', 'source': 'solid', 'dest': 'gas' },
    { 'trigger': 'ionize', 'source': 'gas', 'dest': 'plasma' }
]
machine = Machine(model=Matter(), states=states, transitions=transitions)

Defining transitions in dictionaries has the benefit of clarity, but can be cumbersome. If you're after brevity, you might choose to define transitions using lists. Just make sure that the elements in each list are in the same order as the positional arguments in the Transition initialization (i.e., trigger, source, destination, etc.).

The following list-of-lists is functionally equivalent to the list-of-dictionaries above:

transitions = [
    ['melt', 'solid', 'liquid'],
    ['evaporate', 'liquid', 'gas'],
    ['sublimate', 'solid', 'gas'],
    ['ionize', 'gas', 'plasma']
]

Alternatively, you can add transitions to a Machine after initialization:

machine = Machine(model=lump, states=states, initial='solid')
machine.add_transition('melt', source='solid', dest='liquid')

The trigger argument defines the name of the new triggering method that gets attached to the base model. When this method is called, it will try to execute the transition:

>>> lump.melt()
>>> lump.state
'liquid'

By default, calling an invalid trigger will raise an exception:

>>> lump.to_gas()
>>> # This won't work because only objects in a solid state can melt
>>> lump.melt()
transitions.core.MachineError: "Can't trigger event melt from state gas!"

This behavior is generally desirable, since it helps alert you to problems in your code. But in some cases, you might want to silently ignore invalid triggers. You can do this by setting ignore_invalid_triggers=True (either on a state-by-state basis, or globally for all states):

>>> # Globally suppress invalid trigger exceptions
>>> m = Machine(lump, states, initial='solid', ignore_invalid_triggers=True)
>>> # ...or suppress for only one group of states
>>> states = ['new_state1', 'new_state2']
>>> m.add_states(states, ignore_invalid_triggers=True)
>>> # ...or even just for a single state. Here, exceptions will only be suppressed when the current state is A.
>>> states = [State('A', ignore_invalid_triggers=True), 'B', 'C']
>>> m = Machine(lump, states)
>>> # ...this can be inverted as well if just one state should raise an exception
>>> # since the machine's global value is not applied to a previously initialized state.
>>> states = ['A', 'B', State('C')] # the default value for 'ignore_invalid_triggers' is False
>>> m = Machine(lump, states, ignore_invalid_triggers=True)

If you need to know which transitions are valid from a certain state, you can use get_triggers:

m.get_triggers('solid')
>>> ['melt', 'sublimate']
m.get_triggers('liquid')
>>> ['evaporate']
m.get_triggers('plasma')
>>> []
# you can also query several states at once
m.get_triggers('solid', 'liquid', 'gas', 'plasma')
>>> ['melt', 'evaporate', 'sublimate', 'ionize']

If you have followed this documentation from the beginning, you will notice that get_triggers actually returns more triggers than the explicitly defined ones shown above, such as to_liquid and so on. These are called auto-transitions and will be introduced in the next section.

Automatic transitions for all states

In addition to any transitions added explicitly, a to_«state»() method is created automatically whenever a state is added to a Machine instance. This method transitions to the target state no matter which state the machine is currently in:

lump.to_liquid()
lump.state
>>> 'liquid'
lump.to_solid()
lump.state
>>> 'solid'

If you desire, you can disable this behavior by setting auto_transitions=False in the Machine initializer.

Transitioning from multiple states

A given trigger can be attached to multiple transitions, some of which can potentially begin or end in the same state. For example:

machine.add_transition('transmogrify', ['solid', 'liquid', 'gas'], 'plasma')
machine.add_transition('transmogrify', 'plasma', 'solid')
# This next transition will never execute
machine.add_transition('transmogrify', 'plasma', 'gas')

In this case, calling transmogrify() will set the model's state to 'solid' if it's currently 'plasma', and set it to 'plasma' otherwise. (Note that only the first matching transition will execute; thus, the transition defined in the last line above won't do anything.)

You can also make a trigger cause a transition from all states to a particular destination by using the '*' wildcard:

machine.add_transition('to_liquid', '*', 'liquid')

Note that wildcard transitions will only apply to states that exist at the time of the add_transition() call. Calling a wildcard-based transition when the model is in a state added after the transition was defined will elicit an invalid transition message, and will not transition to the target state.

Reflexive transitions from multiple states

A reflexive trigger (trigger that has the same state as source and destination) can easily be added specifying = as destination. This is handy if the same reflexive trigger should be added to multiple states. For example:

machine.add_transition('touch', ['liquid', 'gas', 'plasma'], '=', after='change_shape')

This will add reflexive transitions for all three states with touch() as trigger and with change_shape executed after each trigger.

Internal transitions

In contrast to reflexive transitions, internal transitions will never actually leave the state. This means that transition-related callbacks such as before or after will be processed while state-related callbacks exit or enter will not. To define a transition to be internal, set the destination to None.

machine.add_transition('internal', ['liquid', 'gas'], None, after='change_shape')

Ordered transitions

A common desire is for state transitions to follow a strict linear sequence. For instance, given states ['A', 'B', 'C'], you might want valid transitions for A → B, B → C, and C → A (but no other pairs).

To facilitate this behavior, Transitions provides an add_ordered_transitions() method in the Machine class:

states = ['A', 'B', 'C']
 # See the "alternative initialization" section for an explanation of the 1st argument to init
machine = Machine(states=states, initial='A')
machine.add_ordered_transitions()
machine.next_state()
print(machine.state)
>>> 'B'
# We can also define a different order of transitions
machine = Machine(states=states, initial='A')
machine.add_ordered_transitions(['A', 'C', 'B'])
machine.next_state()
print(machine.state)
>>> 'C'
# Conditions can be passed to 'add_ordered_transitions' as well
# If one condition is passed, it will be used for all transitions
machine = Machine(states=states, initial='A')
machine.add_ordered_transitions(conditions='check')
# If a list is passed, it must contain exactly as many elements as the
# machine contains states (A->B, ..., X->A)
machine = Machine(states=states, initial='A')
machine.add_ordered_transitions(conditions=['check_A2B', ..., 'check_X2A'])
# Conditions are always applied starting from the initial state
machine = Machine(states=states, initial='B')
machine.add_ordered_transitions(conditions=['check_B2C', ..., 'check_A2B'])
# With `loop=False`, the transition from the last state to the first state will be omitted (e.g. C->A)
# When you also pass conditions, you need to pass one condition less (len(states)-1)
machine = Machine(states=states, initial='A')
machine.add_ordered_transitions(loop=False)
machine.next_state()
machine.next_state()
machine.next_state() # transitions.core.MachineError: "Can't trigger event next_state from state C!"

Queued transitions

The default behaviour in Transitions is to process events instantly. This means events within an on_enter method will be processed before callbacks bound to after are called.

def go_to_C():
    global machine
    machine.to_C()

def after_advance():
    print("I am in state B now!")

def entering_C():
    print("I am in state C now!")

states = ['A', 'B', 'C']
machine = Machine(states=states, initial='A')

# we want a message when state transition to B has been completed
machine.add_transition('advance', 'A', 'B', after=after_advance)

# call transition from state B to state C
machine.on_enter_B(go_to_C)

# we also want a message when entering state C
machine.on_enter_C(entering_C)
machine.advance()
>>> 'I am in state C now!'
>>> 'I am in state B now!' # what?

The execution order of this example is

prepare -> before -> on_enter_B -> on_enter_C -> after.

If queued processing is enabled, a transition will be finished before the next transition is triggered:

machine = Machine(states=states, queued=True, initial='A')
...
machine.advance()
>>> 'I am in state B now!'
>>> 'I am in state C now!' # That's better!

This results in

prepare -> before -> on_enter_B -> queue(to_C) -> after  -> on_enter_C.

Important note: when processing events in a queue, the trigger call will always return True, since there is no way to determine at queuing time whether a transition involving queued calls will ultimately complete successfully. This is true even when only a single event is processed.

machine.add_transition('jump', 'A', 'C', conditions='will_fail')
...
# queued=False
machine.jump()
>>> False
# queued=True
machine.jump()
>>> True

When a model is removed from the machine, transitions will also remove all related events from the queue.

class Model:
    def on_enter_B(self):
        self.to_C()  # add event to queue ...
        self.machine.remove_model(self)  # aaaand it's gone

Conditional transitions

Sometimes you only want a particular transition to execute if a specific condition occurs. You can do this by passing a method, or list of methods, in the conditions argument:

# Our Matter class, now with a bunch of methods that return booleans.
class Matter(object):
    def is_flammable(self): return False
    def is_really_hot(self): return True

machine.add_transition('heat', 'solid', 'gas', conditions='is_flammable')
machine.add_transition('heat', 'solid', 'liquid', conditions=['is_really_hot'])

In the above example, calling heat() when the model is in state 'solid' will transition to state 'gas' if is_flammable returns True. Otherwise, it will transition to state 'liquid' if is_really_hot returns True.

For convenience, there's also an 'unless' argument that behaves exactly like conditions, but inverted:

machine.add_transition('heat', 'solid', 'gas', unless=['is_flammable', 'is_really_hot'])

In this case, the model would transition from solid to gas whenever heat() fires, provided that both is_flammable() and is_really_hot() return False.

Note that condition-checking methods will passively receive optional arguments and/or data objects passed to triggering methods. For instance, the following call:

lump.heat(temp=74)
# equivalent to lump.trigger('heat', temp=74)

... would pass the temp=74 optional kwarg to the is_flammable() check (possibly wrapped in an EventData instance). For more on this, see the Passing data section below.

Check transitions

If you want to check whether a transition is possible before you execute it ('look before you leap'), you can use may_<trigger_name> convenience functions that have been attached to your model:

# check if the current temperature is hot enough to trigger a transition
if lump.may_heat():
    lump.heat()

This will execute all prepare callbacks and evaluate the conditions assigned to the potential transitions. Transition checks can also be used when a transition's destination is not available (yet):

machine.add_transition('elevate', 'solid', 'spiritual')
assert not lump.may_elevate()  # not ready yet :(

Callbacks

You can attach callbacks to transitions as well as states. Every transition has 'before' and 'after' attributes that contain a list of methods to call before and after the transition executes:

class Matter(object):
    def make_hissing_noises(self): print("HISSSSSSSSSSSSSSSS")
    def disappear(self): print("where'd all the liquid go?")

transitions = [
    { 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid', 'before': 'make_hissing_noises'},
    { 'trigger': 'evaporate', 'source': 'liquid', 'dest': 'gas', 'after': 'disappear' }
]

lump = Matter()
machine = Machine(lump, states, transitions=transitions, initial='solid')
lump.melt()
>>> "HISSSSSSSSSSSSSSSS"
lump.evaporate()
>>> "where'd all the liquid go?"

There is also a 'prepare' callback that is executed as soon as a transition starts, before any 'conditions' are checked or other callbacks are executed.

class Matter(object):
    heat = False
    attempts = 0
    def count_attempts(self): self.attempts += 1
    def heat_up(self): self.heat = random.random() < 0.25
    def stats(self): print('It took you %i attempts to melt the lump!' %self.attempts)

    @property
    def is_really_hot(self):
        return self.heat


states=['solid', 'liquid', 'gas', 'plasma']

transitions = [
    { 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid', 'prepare': ['heat_up', 'count_attempts'], 'conditions': 'is_really_hot', 'after': 'stats'},
]

lump = Matter()
machine = Machine(lump, states, transitions=transitions, initial='solid')
lump.melt()
lump.melt()
lump.melt()
lump.melt()
>>> "It took you 4 attempts to melt the lump!"

Note that prepare will not be called unless the current state is a valid source for the named transition.

Default actions meant to be executed before or after every transition can be passed to Machine during initialization with before_state_change and after_state_change respectively:

class Matter(object):
    def make_hissing_noises(self): print("HISSSSSSSSSSSSSSSS")
    def disappear(self): print("where'd all the liquid go?")

states=['solid', 'liquid', 'gas', 'plasma']

lump = Matter()
m = Machine(lump, states, before_state_change='make_hissing_noises', after_state_change='disappear')
lump.to_gas()
>>> "HISSSSSSSSSSSSSSSS"
>>> "where'd all the liquid go?"

There are also two keywords for callbacks which should be executed independently a) of how many transitions are possible, b) if any transition succeeds and c) even if an error is raised during the execution of some other callback. Callbacks passed to Machine with prepare_event will be executed once before processing possible transitions (and their individual prepare callbacks) takes place. Callbacks of finalize_event will be executed regardless of the success of the processed transitions. Note that if an error occurred it will be attached to event_data as error and can be retrieved with send_event=True.

from transitions import Machine

class Matter(object):
    def raise_error(self, event): raise ValueError("Oh no")
    def prepare(self, event): print("I am ready!")
    def finalize(self, event): print("Result: ", type(event.error), event.error)

states=['solid', 'liquid', 'gas', 'plasma']

lump = Matter()
m = Machine(lump, states, prepare_event='prepare', before_state_change='raise_error',
            finalize_event='finalize', send_event=True)
try:
    lump.to_gas()
except ValueError:
    pass
print(lump.state)

# >>> I am ready!
# >>> Result:  <class 'ValueError'> Oh no
# >>> initial

Sometimes things just don't work out as intended and we need to handle exceptions and clean up the mess to keep things going. We can pass callbacks to on_exception to do this:

from transitions import Machine

class Matter(object):
    def raise_error(self, event): raise ValueError("Oh no")
    def handle_error(self, event):
        print("Fixing things ...")
        del event.error  # it did not happen if we cannot see it ...

states=['solid', 'liquid', 'gas', 'plasma']

lump = Matter()
m = Machine(lump, states, before_state_change='raise_error', on_exception='handle_error', send_event=True)
try:
    lump.to_gas()
except ValueError:
    pass
print(lump.state)

# >>> Fixing things ...
# >>> initial

Callable resolution

As you have probably already realized, the standard way of passing callables to states, conditions and transitions is by name. When processing callbacks and conditions, transitions will use their name to retrieve the related callable from the model. If the method cannot be retrieved and it contains dots, transitions will treat the name as a path to a module function and try to import it. Alternatively, you can pass names of properties or attributes. They will be wrapped into functions but cannot receive event data for obvious reasons. You can also pass callables such as (bound) functions directly. As mentioned earlier, you can also pass lists/tuples of callables names to the callback parameters. Callbacks will be executed in the order they were added.

from transitions import Machine
from mod import imported_func

import random


class Model(object):

    def a_callback(self):
        imported_func()

    @property
    def a_property(self):
        """ Basically a coin toss. """
        return random.random() < 0.5

    an_attribute = False


model = Model()
machine = Machine(model=model, states=['A'], initial='A')
machine.add_transition('by_name', 'A', 'A', conditions='a_property', after='a_callback')
machine.add_transition('by_reference', 'A', 'A', unless=['a_property', 'an_attribute'], after=model.a_callback)
machine.add_transition('imported', 'A', 'A', after='mod.imported_func')

model.by_name()
model.by_reference()
model.imported()

The callable resolution is done in Machine.resolve_callable. This method can be overridden in case more complex callable resolution strategies are required.

Example

class CustomMachine(Machine):
    @staticmethod
    def resolve_callable(func, event_data):
        # manipulate arguments here and return func, or super() if no manipulation is done.
        super(CustomMachine, CustomMachine).resolve_callable(func, event_data)

Callback execution order

In summary, there are currently three ways to trigger events. You can call a model's convenience functions like lump.melt(), execute triggers by name such as lump.trigger("melt") or dispatch events on multiple models with machine.dispatch("melt") (see section about multiple models in alternative initialization patterns). Callbacks on transitions are then executed in the following order:

Callback	Current State	Comments
`'machine.prepare_event'`	`source`	executed once before individual transitions are processed
`'transition.prepare'`	`source`	executed as soon as the transition starts
`'transition.conditions'`	`source`	conditions may fail and halt the transition
`'transition.unless'`	`source`	conditions may fail and halt the transition
`'machine.before_state_change'`	`source`	default callbacks declared on model
`'transition.before'`	`source`
`'state.on_exit'`	`source`	callbacks declared on the source state
`<STATE CHANGE>`
`'state.on_enter'`	`destination`	callbacks declared on the destination state
`'transition.after'`	`destination`
`'machine.after_state_change'`	`destination`	default callbacks declared on model
`'machine.on_exception'`	`source/destination`	callbacks will be executed when an exception has been raised
`'machine.finalize_event'`	`source/destination`	callbacks will be executed even if no transition took place or an exception has been raised

If any callback raises an exception, the processing of callbacks is not continued. This means that when an error occurs before the transition (in state.on_exit or earlier), it is halted. In case there is a raise after the transition has been conducted (in state.on_enter or later), the state change persists and no rollback is happening. Callbacks specified in machine.finalize_event will always be executed unless the exception is raised by a finalizing callback itself. Note that each callback sequence has to be finished before the next stage is executed. Blocking callbacks will halt the execution order and therefore block the trigger or dispatch call itself. If you want callbacks to be executed in parallel, you could have a look at the extensions AsyncMachine for asynchronous processing or LockedMachine for threading.

Passing data

Sometimes you need to pass the callback functions registered at machine initialization some data that reflects the model's current state. Transitions allows you to do this in two different ways.

First (the default), you can pass any positional or keyword arguments directly to the trigger methods (created when you call add_transition()):

class Matter(object):
    def __init__(self): self.set_environment()
    def set_environment(self, temp=0, pressure=101.325):
        self.temp = temp
        self.pressure = pressure
    def print_temperature(self): print("Current temperature is %d degrees celsius." % self.temp)
    def print_pressure(self): print("Current pressure is %.2f kPa." % self.pressure)

lump = Matter()
machine = Machine(lump, ['solid', 'liquid'], initial='solid')
machine.add_transition('melt', 'solid', 'liquid', before='set_environment')

lump.melt(45)  # positional arg;
# equivalent to lump.trigger('melt', 45)
lump.print_temperature()
>>> 'Current temperature is 45 degrees celsius.'

machine.set_state('solid')  # reset state so we can melt again
lump.melt(pressure=300.23)  # keyword args also work
lump.print_pressure()
>>> 'Current pressure is 300.23 kPa.'

You can pass any number of arguments you like to the trigger.

There is one important limitation to this approach: every callback function triggered by the state transition must be able to handle all of the arguments. This may cause problems if the callbacks each expect somewhat different data.

To get around this, Transitions supports an alternate method for sending data. If you set send_event=True at Machine initialization, all arguments to the triggers will be wrapped in an EventData instance and passed on to every callback. (The EventData object also maintains internal references to the source state, model, transition, machine, and trigger associated with the event, in case you need to access these for anything.)

class Matter(object):

    def __init__(self):
        self.temp = 0
        self.pressure = 101.325

    # Note that the sole argument is now the EventData instance.
    # This object stores positional arguments passed to the trigger method in the
    # .args property, and stores keywords arguments in the .kwargs dictionary.
    def set_environment(self, event):
        self.temp = event.kwargs.get('temp', 0)
        self.pressure = event.kwargs.get('pressure', 101.325)

    def print_pressure(self): print("Current pressure is %.2f kPa." % self.pressure)

lump = Matter()
machine = Machine(lump, ['solid', 'liquid'], send_event=True, initial='solid')
machine.add_transition('melt', 'solid', 'liquid', before='set_environment')

lump.melt(temp=45, pressure=1853.68)  # keyword args
lump.print_pressure()
>>> 'Current pressure is 1853.68 kPa.'

Alternative initialization patterns

In all of the examples so far, we've attached a new Machine instance to a separate model (lump, an instance of class Matter). While this separation keeps things tidy (because you don't have to monkey patch a whole bunch of new methods into the Matter class), it can also get annoying, since it requires you to keep track of which methods are called on the state machine, and which ones are called on the model that the state machine is bound to (e.g., lump.on_enter_StateA() vs. machine.add_transition()).

Fortunately, Transitions is flexible, and supports two other initialization patterns.

First, you can create a standalone state machine that doesn't require another model at all. Simply omit the model argument during initialization:

machine = Machine(states=states, transitions=transitions, initial='solid')
machine.melt()
machine.state
>>> 'liquid'

If you initialize the machine this way, you can then attach all triggering events (like evaporate(), sublimate(), etc.) and all callback functions directly to the Machine instance.

This approach has the benefit of consolidating all of the state machine functionality in one place, but can feel a little bit unnatural if you think state logic should be contained within the model itself rather than in a separate controller.

An alternative (potentially better) approach is to have the model inherit from the Machine class. Transitions is designed to support inheritance seamlessly. (just be sure to override class Machine's __init__ method!):

class Matter(Machine):
    def say_hello(self): print("hello, new state!")
    def say_goodbye(self): print("goodbye, old state!")

    def __init__(self):
        states = ['solid', 'liquid', 'gas']
        Machine.__init__(self, states=states, initial='solid')
        self.add_transition('melt', 'solid', 'liquid')

lump = Matter()
lump.state
>>> 'solid'
lump.melt()
lump.state
>>> 'liquid'

Here you get to consolidate all state machine functionality into your existing model, which often feels more natural than sticking all of the functionality we want in a separate standalone Machine instance.

A machine can handle multiple models which can be passed as a list like Machine(model=[model1, model2, ...]). In cases where you want to add models as well as the machine instance itself, you can pass the class variable placeholder (string) Machine.self_literal during initialization like Machine(model=[Machine.self_literal, model1, ...]). You can also create a standalone machine, and register models dynamically via machine.add_model by passing model=None to the constructor. Furthermore, you can use machine.dispatch to trigger events on all currently added models. Remember to call machine.remove_model if machine is long-lasting and your models are temporary and should be garbage collected:

class Matter():
    pass

lump1 = Matter()
lump2 = Matter()

# setting 'model' to None or passing an empty list will initialize the machine without a model
machine = Machine(model=None, states=states, transitions=transitions, initial='solid')

machine.add_model(lump1)
machine.add_model(lump2, initial='liquid')

lump1.state
>>> 'solid'
lump2.state
>>> 'liquid'

# custom events as well as auto transitions can be dispatched to all models
machine.dispatch("to_plasma")

lump1.state
>>> 'plasma'
assert lump1.state == lump2.state

machine.remove_model([lump1, lump2])
del lump1  # lump1 is garbage collected
del lump2  # lump2 is garbage collected

If you don't provide an initial state in the state machine constructor, transitions will create and add a default state called 'initial'. If you do not want a default initial state, you can pass initial=None. However, in this case you need to pass an initial state every time you add a model.

machine = Machine(model=None, states=states, transitions=transitions, initial=None)

machine.add_model(Matter())
>>> "MachineError: No initial state configured for machine, must specify when adding model."
machine.add_model(Matter(), initial='liquid')

Models with multiple states could attach multiple machines using different model_attribute values. As mentioned in Checking state, this will add custom is/to_<model_attribute>_<state_name> functions:

lump = Matter()

matter_machine = Machine(lump, states=['solid', 'liquid', 'gas'], initial='solid')
# add a second machine to the same model but assign a different state attribute
shipment_machine = Machine(lump, states=['delivered', 'shipping'], initial='delivered', model_attribute='shipping_state')

lump.state
>>> 'solid'
lump.is_solid()  # check the default field
>>> True
lump.shipping_state
>>> 'delivered'
lump.is_shipping_state_delivered()  # check the custom field.
>>> True
lump.to_shipping_state_shipping()
>>> True
lump.is_shipping_state_delivered()
>>> False

Logging

Transitions includes very rudimentary logging capabilities. A number of events – namely, state changes, transition triggers, and conditional checks – are logged as INFO-level events using the standard Python logging module. This means you can easily configure logging to standard output in a script:

# Set up logging; The basic log level will be DEBUG
import logging
logging.basicConfig(level=logging.DEBUG)
# Set transitions' log level to INFO; DEBUG messages will be omitted
logging.getLogger('transitions').setLevel(logging.INFO)

# Business as usual
machine = Machine(states=states, transitions=transitions, initial='solid')
...

(Re-)Storing machine instances

Machines are picklable and can be stored and loaded with pickle. For Python 3.3 and earlier dill is required.

import dill as pickle # only required for Python 3.3 and earlier

m = Machine(states=['A', 'B', 'C'], initial='A')
m.to_B()
m.state
>>> B

# store the machine
dump = pickle.dumps(m)

# load the Machine instance again
m2 = pickle.loads(dump)

m2.state
>>> B

m2.states.keys()
>>> ['A', 'B', 'C']

Extensions

Even though the core of transitions is kept lightweight, there are a variety of MixIns to extend its functionality. Currently supported are:

Diagrams to visualize the current state of a machine
Hierarchical State Machines for nesting and reuse
Threadsafe Locks for parallel execution
Async callbacks for asynchronous execution
Custom States for extended state-related behaviour

There are two mechanisms to retrieve a state machine instance with the desired features enabled. The first approach makes use of the convenience factory with the four parameters graph, nested, locked or asyncio set to True if the feature is required:

from transitions.extensions import MachineFactory

# create a machine with mixins
diagram_cls = MachineFactory.get_predefined(graph=True)
nested_locked_cls = MachineFactory.get_predefined(nested=True, locked=True)
async_machine_cls = MachineFactory.get_predefined(asyncio=True)

# create instances from these classes
# instances can be used like simple machines
machine1 = diagram_cls(model, state, transitions)
machine2 = nested_locked_cls(model, state, transitions)

This approach targets experimental use since in this case the underlying classes do not have to be known. However, classes can also be directly imported from transitions.extensions. The naming scheme is as follows:

	Diagrams	Nested	Locked	Asyncio
Machine	✘	✘	✘	✘
GraphMachine	✓	✘	✘	✘
HierarchicalMachine	✘	✓	✘	✘
LockedMachine	✘	✘	✓	✘
HierarchicalGraphMachine	✓	✓	✘	✘
LockedGraphMachine	✓	✘	✓	✘
LockedHierarchicalMachine	✘	✓	✓	✘
LockedHierarchicalGraphMachine	✓	✓	✓	✘
AsyncMachine	✘	✘	✘	✓
AsyncGraphMachine	✓	✘	✘	✓
HierarchicalAsyncMachine	✘	✓	✘	✓
HierarchicalAsyncGraphMachine	✓	✓	✘	✓

To use a feature-rich state machine, one could write:

from transitions.extensions import LockedHierarchicalGraphMachine as LHGMachine

machine = LHGMachine(model, states, transitions)

Diagrams

Additional Keywords:

title (optional): Sets the title of the generated image.
show_conditions (default False): Shows conditions at transition edges
show_auto_transitions (default False): Shows auto transitions in graph
show_state_attributes (default False): Show callbacks (enter, exit), tags and timeouts in graph

Transitions can generate basic state diagrams displaying all valid transitions between states. To use the graphing functionality, you'll need to have graphviz and/or pygraphviz installed:
To generate graphs with the package graphviz, you need to install Graphviz manually or via a package manager.

sudo apt-get install graphviz graphviz-dev  # Ubuntu and Debian
brew install graphviz  # MacOS
conda install graphviz python-graphviz  # (Ana)conda

Now you can install the actual Python packages

pip install graphviz pygraphviz # install graphviz and/or pygraphviz manually...
pip install transitions[diagrams]  # ... or install transitions with 'diagrams' extras which currently depends on pygraphviz

Currently, GraphMachine will use pygraphviz when available and fall back to graphviz when pygraphviz cannot be found. This can be overridden by passing use_pygraphviz=False to the constructor. Note that this default might change in the future and pygraphviz support may be dropped. With Model.get_graph() you can get the current graph or the region of interest (roi) and draw it like this:

# import transitions

from transitions.extensions import GraphMachine
m = Model()
# without further arguments pygraphviz will be used
machine = GraphMachine(model=m, ...)
# when you want to use graphviz explicitly
machine = GraphMachine(model=m, use_pygraphviz=False, ...)
# in cases where auto transitions should be visible
machine = GraphMachine(model=m, show_auto_transitions=True, ...)

# draw the whole graph ...
m.get_graph().draw('my_state_diagram.png', prog='dot')
# ... or just the region of interest
# (previous state, active state and all reachable states)
roi = m.get_graph(show_roi=True).draw('my_state_diagram.png', prog='dot')

This produces something like this:

Independent of the backend you use, the draw function also accepts a file descriptor or a binary stream as the first argument. If you set this parameter to None, the byte stream will be returned:

import io

with open('a_graph.png', 'bw') as f:
    # you need to pass the format when you pass objects instead of filenames.
    m.get_graph().draw(f, format="png", prog='dot')

# you can pass a (binary) stream too
b = io.BytesIO()
m.get_graph().draw(b, format="png", prog='dot')

# or just handle the binary string yourself
result = m.get_graph().draw(None, format="png", prog='dot')
assert result == b.getvalue()

References and partials passed as callbacks will be resolved as good as possible:

from transitions.extensions import GraphMachine
from functools import partial


class Model:

    def clear_state(self, deep=False, force=False):
        print("Clearing state ...")
        return True


model = Model()
machine = GraphMachine(model=model, states=['A', 'B', 'C'],
                       transitions=[
                           {'trigger': 'clear', 'source': 'B', 'dest': 'A', 'conditions': model.clear_state},
                           {'trigger': 'clear', 'source': 'C', 'dest': 'A',
                            'conditions': partial(model.clear_state, False, force=True)},
                       ],
                       initial='A', show_conditions=True)

model.get_graph().draw('my_state_diagram.png', prog='dot')

This should produce something similar to this:

If the format of references does not suit your needs, you can override the static method GraphMachine.format_references. If you want to skip reference entirely, just let GraphMachine.format_references return None. Also, have a look at our example IPython/Jupyter notebooks for a more detailed example about how to use and edit graphs.

Hierarchical State Machine (HSM)

Transitions includes an extension module which allows nesting states. This allows us to create contexts and to model cases where states are related to certain subtasks in the state machine. To create a nested state, either import NestedState from transitions or use a dictionary with the initialization arguments name and children. Optionally, initial can be used to define a sub state to transit to, when the nested state is entered.

from transitions.extensions import HierarchicalMachine

states = ['standing', 'walking', {'name': 'caffeinated', 'children':['dithering', 'running']}]
transitions = [
  ['walk', 'standing', 'walking'],
  ['stop', 'walking', 'standing'],
  ['drink', '*', 'caffeinated'],
  ['walk', ['caffeinated', 'caffeinated_dithering'], 'caffeinated_running'],
  ['relax', 'caffeinated', 'standing']
]

machine = HierarchicalMachine(states=states, transitions=transitions, initial='standing', ignore_invalid_triggers=True)

machine.walk() # Walking now
machine.stop() # let's stop for a moment
machine.drink() # coffee time
machine.state
>>> 'caffeinated'
machine.walk() # we have to go faster
machine.state
>>> 'caffeinated_running'
machine.stop() # can't stop moving!
machine.state
>>> 'caffeinated_running'
machine.relax() # leave nested state
machine.state # phew, what a ride
>>> 'standing'
# machine.on_enter_caffeinated_running('callback_method')

A configuration making use of initial could look like this:

# ...
states = ['standing', 'walking', {'name': 'caffeinated', 'initial': 'dithering', 'children': ['dithering', 'running']}]
transitions = [
  ['walk', 'standing', 'walking'],
  ['stop', 'walking', 'standing'],
  # this transition will end in 'caffeinated_dithering'...
  ['drink', '*', 'caffeinated'],
  # ... that is why we do not need do specify 'caffeinated' here anymore
  ['walk', 'caffeinated_dithering', 'caffeinated_running'],
  ['relax', 'caffeinated', 'standing']
]
# ...

The initial keyword of the HierarchicalMachine constructor accepts nested states (e.g. initial='caffeinated_running') and a list of states which is considered to be a parallel state (e.g. initial=['A', 'B']) or the current state of another model (initial=model.state) which should be effectively one of the previous mentioned options. Note that when passing a string, transition will check the targeted state for initial substates and use this as an entry state. This will be done recursively until a substate does not mention an initial state. Parallel states or a state passed as a list will be used 'as is' and no further initial evaluation will be conducted.

Note that your previously created state object must be a NestedState or a derived class of it. The standard State class used in simple Machine instances lacks features required for nesting.

from transitions.extensions.nesting import HierarchicalMachine, NestedState
from transitions import  State
m = HierarchicalMachine(states=['A'], initial='initial')
m.add_state('B')  # fine
m.add_state({'name': 'C'})  # also fine
m.add_state(NestedState('D'))  # fine as well
m.add_state(State('E'))  # does not work!

Some things that have to be considered when working with nested states: State names are concatenated with NestedState.separator. Currently the separator is set to underscore ('_') and therefore behaves similar to the basic machine. This means a substate bar from state foo will be known by foo_bar. A substate baz of bar will be referred to as foo_bar_baz and so on. When entering a substate, enter will be called for all parent states. The same is true for exiting substates. Third, nested states can overwrite transition behaviour of their parents. If a transition is not known to the current state it will be delegated to its parent.

This means that in the standard configuration, state names in HSMs MUST NOT contain underscores. For transitions it's impossible to tell whether machine.add_state('state_name') should add a state named state_name or add a substate name to the state state. In some cases this is not sufficient however. For instance if state names consist of more than one word and you want/need to use underscore to separate them instead of CamelCase. To deal with this, you can change the character used for separation quite easily. You can even use fancy unicode characters if you use Python 3. Setting the separator to something else than underscore changes some of the behaviour (auto_transition and setting callbacks) though:

from transitions.extensions import HierarchicalMachine
from transitions.extensions.nesting import NestedState
NestedState.separator = '↦'
states = ['A', 'B',
  {'name': 'C', 'children':['1', '2',
    {'name': '3', 'children': ['a', 'b', 'c']}
  ]}
]

transitions = [
    ['reset', 'C', 'A'],
    ['reset', 'C↦2', 'C']  # overwriting parent reset
]

# we rely on auto transitions
machine = HierarchicalMachine(states=states, transitions=transitions, initial='A')
machine.to_B()  # exit state A, enter state B
machine.to_C()  # exit B, enter C
machine.to_C.s3.a()  # enter C↦a; enter C↦3↦a;
machine.state
>>> 'C↦3↦a'
assert machine.is_C.s3.a()
machine.to('C↦2')  # not interactive; exit C↦3↦a, exit C↦3, enter C↦2
machine.reset()  # exit C↦2; reset C has been overwritten by C↦3
machine.state
>>> 'C'
machine.reset()  # exit C, enter A
machine.state
>>> 'A'
# s.on_enter('C↦3↦a', 'callback_method')

Instead of to_C_3_a() auto transition is called as to_C.s3.a(). If your substate starts with a digit, transitions adds a prefix 's' ('3' becomes 's3') to the auto transition FunctionWrapper to comply with the attribute naming scheme of Python. If interactive completion is not required, to('C↦3↦a') can be called directly. Additionally, on_enter/exit_<<state name>> is replaced with on_enter/exit(state_name, callback). State checks can be conducted in a similar fashion. Instead of is_C_3_a(), the FunctionWrapper variant is_C.s3.a() can be used.

To check whether the current state is a substate of a specific state, is_state supports the keyword allow_substates:

machine.state
>>> 'C.2.a'
machine.is_C() # checks for specific states
>>> False
machine.is_C(allow_substates=True)
>>> True
assert machine.is_C.s2() is False
assert machine.is_C.s2(allow_substates=True)  # FunctionWrapper support allow_substate as well

new in 0.8.0
You can use enumerations in HSMs as well but keep in mind that Enum are compared by value. If you have a value more than once in a state tree those states cannot be distinguished.

states = [States.RED, States.YELLOW, {'name': States.GREEN, 'children': ['tick', 'tock']}]
states = ['A', {'name': 'B', 'children': states, 'initial': States.GREEN}, States.GREEN]
machine = HierarchicalMachine(states=states)
machine.to_B()
machine.is_GREEN()  # returns True even though the actual state is B_GREEN

new in 0.8.0
HierarchicalMachine has been rewritten from scratch to support parallel states and better isolation of nested states. This involves some tweaks based on community feedback. To get an idea of processing order and configuration have a look at the following example:

from transitions.extensions.nesting import HierarchicalMachine
import logging
states = ['A', 'B', {'name': 'C', 'parallel': [{'name': '1', 'children': ['a', 'b', 'c'], 'initial': 'a',
                                                'transitions': [['go', 'a', 'b']]},
                                               {'name': '2', 'children': ['x', 'y', 'z'], 'initial': 'z'}],
                      'transitions': [['go', '2_z', '2_x']]}]

transitions = [['reset', 'C_1_b', 'B']]
logging.basicConfig(level=logging.INFO)
machine = HierarchicalMachine(states=states, transitions=transitions, initial='A')
machine.to_C()
# INFO:transitions.extensions.nesting:Exited state A
# INFO:transitions.extensions.nesting:Entered state C
# INFO:transitions.extensions.nesting:Entered state C_1
# INFO:transitions.extensions.nesting:Entered state C_2
# INFO:transitions.extensions.nesting:Entered state C_1_a
# INFO:transitions.extensions.nesting:Entered state C_2_z
machine.go()
# INFO:transitions.extensions.nesting:Exited state C_1_a
# INFO:transitions.extensions.nesting:Entered state C_1_b
# INFO:transitions.extensions.nesting:Exited state C_2_z
# INFO:transitions.extensions.nesting:Entered state C_2_x
machine.reset()
# INFO:transitions.extensions.nesting:Exited state C_1_b
# INFO:transitions.extensions.nesting:Exited state C_2_x
# INFO:transitions.extensions.nesting:Exited state C_1
# INFO:transitions.extensions.nesting:Exited state C_2
# INFO:transitions.extensions.nesting:Exited state C
# INFO:transitions.extensions.nesting:Entered state B

When using parallel instead of children, transitions will enter all states of the passed list at the same time. Which substate to enter is defined by initial which should always point to a direct substate. A novel feature is to define local transitions by passing the transitions keyword in a state definition. The above defined transition ['go', 'a', 'b'] is only valid in C_1. While you can reference substates as done in ['go', '2_z', '2_x'] you cannot reference parent states directly in locally defined transitions. When a parent state is exited, its children will also be exited. In addition to the processing order of transitions known from Machine where transitions are considered in the order they were added, HierarchicalMachine considers hierarchy as well. Transitions defined in substates will be evaluated first (e.g. C_1_a is left before C_2_z) and transitions defined with wildcard * will (for now) only add transitions to root states (in this example A, B, C) Starting with 0.8.0 nested states can be added directly and will issue the creation of parent states on-the-fly:

m = HierarchicalMachine(states=['A'], initial='A')
m.add_state('B_1_a')
m.to_B_1()
assert m.is_B(allow_substates=True)

Reuse of previously created HSMs

Besides semantic order, nested states are very handy if you want to specify state machines for specific tasks and plan to reuse them. Before 0.8.0, a HierarchicalMachine would not integrate the machine instance itself but the states and transitions by creating copies of them. However, since 0.8.0 (Nested)State instances are just referenced which means changes in one machine's collection of states and events will influence the other machine instance. Models and their state will not be shared though. Note that events and transitions are also copied by reference and will be shared by both instances if you do not use the remap keyword. This change was done to be more in line with Machine which also uses passed State instances by reference.

count_states = ['1', '2', '3', 'done']
count_trans = [
    ['increase', '1', '2'],
    ['increase', '2', '3'],
    ['decrease', '3', '2'],
    ['decrease', '2', '1'],
    ['done', '3', 'done'],
    ['reset', '*', '1']
]

counter = HierarchicalMachine(states=count_states, transitions=count_trans, initial='1')

counter.increase() # love my counter
states = ['waiting', 'collecting', {'name': 'counting', 'children': counter}]

transitions = [
    ['collect', '*', 'collecting'],
    ['wait', '*', 'waiting'],
    ['count', 'collecting', 'counting']
]

collector = HierarchicalMachine(states=states, transitions=transitions, initial='waiting')
collector.collect()  # collecting
collector.count()  # let's see what we got; counting_1
collector.increase()  # counting_2
collector.increase()  # counting_3
collector.done()  # collector.state == counting_done
collector.wait()  # collector.state == waiting

If a HierarchicalMachine is passed with the children keyword, the initial state of this machine will be assigned to the new parent state. In the above example we see that entering counting will also enter counting_1. If this is undesired behaviour and the machine should rather halt in the parent state, the user can pass initial as False like {'name': 'counting', 'children': counter, 'initial': False}.

Sometimes you want such an embedded state collection to 'return' which means after it is done it should exit and transit to one of your super states. To achieve this behaviour you can remap state transitions. In the example above we would like the counter to return if the state done was reached. This is done as follows:

states = ['waiting', 'collecting', {'name': 'counting', 'children': counter, 'remap': {'done': 'waiting'}}]

... # same as above

collector.increase() # counting_3
collector.done()
collector.state
>>> 'waiting' # be aware that 'counting_done' will be removed from the state machine

As mentioned above, using remap will copy events and transitions since they could not be valid in the original state machine. If a reused state machine does not have a final state, you can of course add the transitions manually. If 'counter' had no 'done' state, we could just add ['done', 'counter_3', 'waiting'] to achieve the same behaviour.

In cases where you want states and transitions to be copied by value rather than reference (for instance, if you want to keep the pre-0.8 behaviour) you can do so by creating a NestedState and assigning deep copies of the machine's events and states to it.

from transitions.extensions.nesting import NestedState
from copy import deepcopy

# ... configuring and creating counter

counting_state = NestedState(name="counting", initial='1')
counting_state.states = deepcopy(counter.states)
counting_state.events = deepcopy(counter.events)

states = ['waiting', 'collecting', counting_state]

For complex state machines, sharing configurations rather than instantiated machines might be more feasible. Especially since instantiated machines must be derived from HierarchicalMachine. Such configurations can be stored and loaded easily via JSON or YAML (see the FAQ). HierarchicalMachine allows defining substates either with the keyword children or states. If both are present, only children will be considered.

counter_conf = {
    'name': 'counting',
    'states': ['1', '2', '3', 'done'],
    'transitions': [
        ['increase', '1', '2'],
        ['increase', '2', '3'],
        ['decrease', '3', '2'],
        ['decrease', '2', '1'],
        ['done', '3', 'done'],
        ['reset', '*', '1']
    ],
    'initial': '1'
}

collector_conf = {
    'name': 'collector',
    'states': ['waiting', 'collecting', counter_conf],
    'transitions': [
        ['collect', '*', 'collecting'],
        ['wait', '*', 'waiting'],
        ['count', 'collecting', 'counting']
    ],
    'initial': 'waiting'
}

collector = HierarchicalMachine(**collector_conf)
collector.collect()
collector.count()
collector.increase()
assert collector.is_counting_2()

Threadsafe(-ish) State Machine

In cases where event dispatching is done in threads, one can use either LockedMachine or LockedHierarchicalMachine where function access (!sic) is secured with reentrant locks. This does not save you from corrupting your machine by tinkering with member variables of your model or state machine.

from transitions.extensions import LockedMachine
from threading import Thread
import time

states = ['A', 'B', 'C']
machine = LockedMachine(states=states, initial='A')

# let us assume that entering B will take some time
thread = Thread(target=machine.to_B)
thread.start()
time.sleep(0.01) # thread requires some time to start
machine.to_C() # synchronized access; won't execute before thread is done
# accessing attributes directly
thread = Thread(target=machine.to_B)
thread.start()
machine.new_attrib = 42 # not synchronized! will mess with execution order

Any python context manager can be passed in via the machine_context keyword argument:

from transitions.extensions import LockedMachine
from threading import RLock

states = ['A', 'B', 'C']

lock1 = RLock()
lock2 = RLock()

machine = LockedMachine(states=states, initial='A', machine_context=[lock1, lock2])

Any contexts via machine_model will be shared between all models registered with the Machine. Per-model contexts can be added as well:

lock3 = RLock()

machine.add_model(model, model_context=lock3)

It's important that all user-provided context managers are re-entrant since the state machine will call them multiple times, even in the context of a single trigger invocation.

Using async callbacks

If you are using Python 3.7 or later, you can use AsyncMachine to work with asynchronous callbacks. You can mix synchronous and asynchronous callbacks if you like but this may have undesired side effects. Note that events need to be awaited and the event loop must also be handled by you.

from transitions.extensions.asyncio import AsyncMachine
import asyncio
import time


class AsyncModel:

    def prepare_model(self):
        print("I am synchronous.")
        self.start_time = time.time()

    async def before_change(self):
        print("I am asynchronous and will block now for 100 milliseconds.")
        await asyncio.sleep(0.1)
        print("I am done waiting.")

    def sync_before_change(self):
        print("I am synchronous and will block the event loop (what I probably shouldn't)")
        time.sleep(0.1)
        print("I am done waiting synchronously.")

    def after_change(self):
        print(f"I am synchronous again. Execution took {int((time.time() - self.start_time) * 1000)} ms.")


transition = dict(trigger="start", source="Start", dest="Done", prepare="prepare_model",
                  before=["before_change"] * 5 + ["sync_before_change"],
                  after="after_change")  # execute before function in asynchronously 5 times
model = AsyncModel()
machine = AsyncMachine(model, states=["Start", "Done"], transitions=[transition], initial='Start')

asyncio.get_event_loop().run_until_complete(model.start())
# >>> I am synchronous.
#     I am asynchronous and will block now for 100 milliseconds.
#     I am asynchronous and will block now for 100 milliseconds.
#     I am asynchronous and will block now for 100 milliseconds.
#     I am asynchronous and will block now for 100 milliseconds.
#     I am asynchronous and will block now for 100 milliseconds.
#     I am synchronous and will block the event loop (what I probably shouldn't)
#     I am done waiting synchronously.
#     I am done waiting.
#     I am done waiting.
#     I am done waiting.
#     I am done waiting.
#     I am done waiting.
#     I am synchronous again. Execution took 101 ms.
assert model.is_Done()

So, why do you need to use Python 3.7 or later you may ask. Async support has been introduced earlier. AsyncMachine makes use of contextvars to handle running callbacks when new events arrive before a transition has been finished:

async def await_never_return():
    await asyncio.sleep(100)
    raise ValueError("That took too long!")

async def fix():
    await m2.fix()

m1 = AsyncMachine(states=['A', 'B', 'C'], initial='A', name="m1")
m2 = AsyncMachine(states=['A', 'B', 'C'], initial='A', name="m2")
m2.add_transition(trigger='go', source='A', dest='B', before=await_never_return)
m2.add_transition(trigger='fix', source='A', dest='C')
m1.add_transition(trigger='go', source='A', dest='B', after='go')
m1.add_transition(trigger='go', source='B', dest='C', after=fix)
asyncio.get_event_loop().run_until_complete(asyncio.gather(m2.go(), m1.go()))

assert m1.state == m2.state

This example actually illustrates two things: First, that 'go' called in m1's transition from A to be B is not cancelled and second, calling m2.fix() will halt the transition attempt of m2 from A to B by executing 'fix' from A to C. This separation would not be possible without contextvars. Note that prepare and conditions are NOT treated as ongoing transitions. This means that after conditions have been evaluated, a transition is executed even though another event already happened. Tasks will only be cancelled when run as a before callback or later.

AsyncMachine features a model-special queue mode which can be used when queued='model' is passed to the constructor. With a model-specific queue, events will only be queued when they belong to the same model. Furthermore, a raised exception will only clear the event queue of the model that raised that exception. For the sake of simplicity, let's assume that every event in asyncio.gather below is not triggered at the same time but slightly delayed:

asyncio.gather(model1.event1(), model1.event2(), model2.event1())
# execution order with AsyncMachine(queued=True)
# model1.event1 -> model1.event2 -> model2.event1
# execution order with AsyncMachine(queued='model')
# (model1.event1, model2.event1) -> model1.event2

asyncio.gather(model1.event1(), model1.error(), model1.event3(), model2.event1(), model2.event2(), model2.event3())
# execution order with AsyncMachine(queued=True)
# model1.event1 -> model1.error
# execution order with AsyncMachine(queued='model')
# (model1.event1, model2.event1) -> (model1.error, model2.event2) -> model2.event3

Note that queue modes must not be changed after machine construction.

Adding features to states

If your superheroes need some custom behaviour, you can throw in some extra functionality by decorating machine states:

from time import sleep
from transitions import Machine
from transitions.extensions.states import add_state_features, Tags, Timeout


@add_state_features(Tags, Timeout)
class CustomStateMachine(Machine):
    pass


class SocialSuperhero(object):
    def __init__(self):
        self.entourage = 0

    def on_enter_waiting(self):
        self.entourage += 1


states = [{'name': 'preparing', 'tags': ['home', 'busy']},
          {'name': 'waiting', 'timeout': 1, 'on_timeout': 'go'},
          {'name': 'away'}]  # The city needs us!

transitions = [['done', 'preparing', 'waiting'],
               ['join', 'waiting', 'waiting'],  # Entering Waiting again will increase our entourage
               ['go', 'waiting', 'away']]  # Okay, let' move

hero = SocialSuperhero()
machine = CustomStateMachine(model=hero, states=states, transitions=transitions, initial='preparing')
assert hero.state == 'preparing'  # Preparing for the night shift
assert machine.get_state(hero.state).is_busy  # We are at home and busy
hero.done()
assert hero.state == 'waiting'  # Waiting for fellow superheroes to join us
assert hero.entourage == 1  # It's just us so far
sleep(0.7)  # Waiting...
hero.join()  # Weeh, we got company
sleep(0.5)  # Waiting...
hero.join()  # Even more company \o/
sleep(2)  # Waiting...
assert hero.state == 'away'  # Impatient superhero already left the building
assert machine.get_state(hero.state).is_home is False  # Yupp, not at home anymore
assert hero.entourage == 3  # At least he is not alone

Currently, transitions comes equipped with the following state features:

Timeout -- triggers an event after some time has passed
- keyword: timeout (int, optional) -- if passed, an entered state will timeout after timeout seconds
- keyword: on_timeout (string/callable, optional) -- will be called when timeout time has been reached
- will raise an AttributeError when timeout is set but on_timeout is not
- Note: A timeout is triggered in a thread. This implies several limitations (e.g. catching Exceptions raised in timeouts). Consider an event queue for more sophisticated applications.
Tags -- adds tags to states
- keyword: tags (list, optional) -- assigns tags to a state
- State.is_<tag_name> will return True when the state has been tagged with tag_name, else False
Error -- raises a MachineError when a state cannot be left
- inherits from Tags (if you use Error do not use Tags)
- keyword: accepted (bool, optional) -- marks a state as accepted
- alternatively the keyword tags can be passed, containing 'accepted'
- Note: Errors will only be raised if auto_transitions has been set to False. Otherwise every state can be exited with to_<state> methods.
Volatile -- initialises an object every time a state is entered
- keyword: volatile (class, optional) -- every time the state is entered an object of type class will be assigned to the model. The attribute name is defined by hook. If omitted, an empty VolatileObject will be created instead
- keyword: hook (string, default='scope') -- The model's attribute name for the temporal object.

You can write your own State extensions and add them the same way. Just note that add_state_features expects Mixins. This means your extension should always call the overridden methods __init__, enter and exit. Your extension may inherit from State but will also work without it. Using @add_state_features has a drawback which is that decorated machines cannot be pickled (more precisely, the dynamically generated CustomState cannot be pickled). This might be a reason to write a dedicated custom state class instead. Depending on the chosen state machine, your custom state class may need to provide certain state features. For instance, HierarchicalMachine requires your custom state to be an instance of NestedState (State is not sufficient). To inject your states you can either assign them to your Machine's class attribute state_cls or override Machine.create_state in case you need some specific procedures done whenever a state is created:

from transitions import Machine, State

class MyState(State):
    pass

class CustomMachine(Machine):
    # Use MyState as state class
    state_cls = MyState


class VerboseMachine(Machine):

    # `Machine._create_state` is a class method but we can
    # override it to be an instance method
    def _create_state(self, *args, **kwargs):
        print("Creating a new state with machine '{0}'".format(self.name))
        return MyState(*args, **kwargs)

If you want to avoid threads in your AsyncMachine entirely, you can replace the Timeout state feature with AsyncTimeout from the asyncio extension:

import asyncio
from transitions.extensions.states import add_state_features
from transitions.extensions.asyncio import AsyncTimeout, AsyncMachine

@add_state_features(AsyncTimeout)
class TimeoutMachine(AsyncMachine):
    pass

states = ['A', {'name': 'B', 'timeout': 0.2, 'on_timeout': 'to_C'}, 'C']
m = TimeoutMachine(states=states, initial='A', queued=True)  # see remark below
asyncio.run(asyncio.wait([m.to_B(), asyncio.sleep(0.1)]))
assert m.is_B()  # timeout shouldn't be triggered
asyncio.run(asyncio.wait([m.to_B(), asyncio.sleep(0.3)]))
assert m.is_C()   # now timeout should have been processed

You should consider passing queued=True to the TimeoutMachine constructor. This will make sure that events are processed sequentially and avoid asynchronous racing conditions that may appear when timeout and event happen in close proximity.

Using transitions together with Django

You can have a look at the FAQ for some inspiration or checkout django-transitions. It has been developed by Christian Ledermann and is also hosted on Github. The documentation contains some usage examples.

I have a [bug report/issue/question]...

First, congratulations! You reached the end of the documentation! If you want to try out transitions before you install it, you can do that in an interactive Jupyter notebook at mybinder.org. Just click this button 👉 .

For bug reports and other issues, please open an issue on GitHub.

For usage questions, post on Stack Overflow, making sure to tag your question with the pytransitions tag. Do not forget to have a look at the extended examples!

For any other questions, solicitations, or large unrestricted monetary gifts, email Tal Yarkoni (initial author) and/or Alexander Neumann (current maintainer).

transitions's People

Contributors

Stargazers

Watchers

Forkers

nzjrs einarhuseby imp expandocean bvdeenen ashutosh2211 relaxdiego mayowa bossjones vltr robert-b-clarke xuwenbao xdmiodz simudream k-hasan-19 f7f8 barseghyanartur acjc yujinrobot asobrien thisismyrobot carlschoonover rbcollins123 aq2004723 zrgravity minmax incidunt ch00k firefoxbug svdgraaf paulormart lnerit henyhollar stvo1 hstarmans bonnierpolska justin-w avikam coverfox steveamor malinoff daheise themysteriousx khigia alihalabyah dsalisbury linearregression triobox debayan johnkewforks hdubey hmmbug jonnew humblepaper pgularski clementtrebuchet fooker pangyuteng vdthatte joaopauloribeiro aisbaa ozzytao ddecoene dcere lexhung iyefeng cabalist tico2303 desperado1992 lepy steveharrison82 macndesign pilgrim2go bag-of-projects computerdl ak47slayer misaelzapata triplekill easypeasykma colinsongf ankostis paulshannon kaishengyao lbzhao28 ketanbhatt hahnsangkim veritystone ramtinms jasonleepeacock davidbistolas engeenity pruthvigopal allanice001 nospoko tintingli stethd clearpathrobotics jasset75 changming1987117 bekerov

transitions's Issues

Triggering event inside callback

It looks like we can trigger an event from inside a callback (e.g. on_enter_mystate). But this is probably a source of confusion: the callback code start executing while the FSM is in one state, call the event (FSM might change state and trigger other callbacks), and first callback finish executing in a different FSM state (we can see strange nested on_entering, on_exiting log).

I believe a less surprising behaviour would be to queue event execution while a transition is already executing. Would that make sense?

pip install fails with transitions 0.2.6

Hi,
Here's the pip output when trying to install last transistions version (0.2.6):

Downloading/unpacking transitions from https://pypi.python.org/packages/source/t/transitions/transitions-0.2.6.tar.gz#md5=c53bdddd361634a91c8b229c936e7e90 (from -r requirements.txt (line 1))
  Downloading transitions-0.2.6.tar.gz
  Running setup.py (path:/Users/nico/Dev/beerfactory/python/env-mqtt/build/transitions/setup.py) egg_info for package transitions
    Traceback (most recent call last):
      File "<string>", line 17, in <module>
      File "/Users/nico/Dev/beerfactory/python/env-mqtt/build/transitions/setup.py", line 4, in <module>
        from transitions.version import __version__
      File "/Users/nico/Dev/beerfactory/python/env-mqtt/build/transitions/transitions/__init__.py", line 2, in <module>
        from .core import (State, Transition, Event, EventData, Machine, MachineError,
      File "/Users/nico/Dev/beerfactory/python/env-mqtt/build/transitions/transitions/core.py", line 8, in     <module>
        from six import string_types
    ImportError: No module named 'six'
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):

  File "<string>", line 17, in <module>

  File "/Users/nico/Dev/beerfactory/python/env-mqtt/build/transitions/setup.py", line 4, in <module>

    from transitions.version import __version__

  File "/Users/nico/Dev/beerfactory/python/env-mqtt/build/transitions/transitions/__init__.py", line 2, in <module>

    from .core import (State, Transition, Event, EventData, Machine, MachineError,

  File "/Users/nico/Dev/beerfactory/python/env-mqtt/build/transitions/transitions/core.py", line 8, in <module>

    from six import string_types

ImportError: No module named 'six'

RuntimeError: maximum recursion depth exceeded

Hi there!
My state machine loops, if there is no work to do. Now, if I leave it running for a while, then at some point, the whole thing crashes with the following error:

RuntimeError: maximum recursion depth exceeded

The long version:

  File "[...]/operator.py", line 196, in _idling_cb
    self.wake_up()
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 214, in trigger
    if t.execute(event):
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 134, in execute
    machine.get_state(self.dest).enter(event_data)
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 48, in enter
    getattr(event_data.model, oe), event_data)
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 447, in callback
    func(*event_data.args, **event_data.kwargs)
  File "[...]/operator.py", line 207, in _processing_ride_requests_cb
    self.no_ride_requests()
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 214, in trigger
    if t.execute(event):
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 134, in execute
    machine.get_state(self.dest).enter(event_data)
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 48, in enter
    getattr(event_data.model, oe), event_data)
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 447, in callback
    func(*event_data.args, **event_data.kwargs)
  File "[...]/operator.py", line 194, in _idling_cb
    rospy.loginfo(self._node_name + " : new state '" + self.state + "'.")
  File "/usr/lib/python2.7/logging/__init__.py", line 1152, in info
    self._log(INFO, msg, args, **kwargs)
  File "/usr/lib/python2.7/logging/__init__.py", line 1271, in _log
    self.handle(record)
  File "/usr/lib/python2.7/logging/__init__.py", line 1281, in handle
    self.callHandlers(record)
  File "/usr/lib/python2.7/logging/__init__.py", line 1321, in callHandlers
    hdlr.handle(record)
  File "/usr/lib/python2.7/logging/__init__.py", line 749, in handle
    self.emit(record)
  File "/opt/ros/indigo/lib/python2.7/dist-packages/rospy/impl/rosout.py", line 112, in emit
    record.filename, record.lineno, record.funcName)
  File "/opt/ros/indigo/lib/python2.7/dist-packages/rospy/impl/rosout.py", line 98, in _rosout
    logger.error("Unable to report rosout: %s\n%s", e, traceback.format_exc())
  File "/usr/lib/python2.7/logging/__init__.py", line 1178, in error
    self._log(ERROR, msg, args, **kwargs)
  File "/usr/lib/python2.7/logging/__init__.py", line 1271, in _log
    self.handle(record)
  File "/usr/lib/python2.7/logging/__init__.py", line 1281, in handle
    self.callHandlers(record)
  File "/usr/lib/python2.7/logging/__init__.py", line 1321, in callHandlers
    hdlr.handle(record)
  File "/usr/lib/python2.7/logging/__init__.py", line 749, in handle
    self.emit(record)
  File "/usr/lib/python2.7/logging/handlers.py", line 82, in emit
    self.handleError(record)
  File "/usr/lib/python2.7/logging/__init__.py", line 802, in handleError
    None, sys.stderr)
  File "/usr/lib/python2.7/traceback.py", line 125, in print_exception
    print_tb(tb, limit, file)
  File "/usr/lib/python2.7/traceback.py", line 69, in print_tb
    line = linecache.getline(filename, lineno, f.f_globals)
  File "/usr/lib/python2.7/linecache.py", line 14, in getline
    lines = getlines(filename, module_globals)
  File "/usr/lib/python2.7/linecache.py", line 40, in getlines
    return updatecache(filename, module_globals)
RuntimeError: maximum recursion depth exceeded

Any idea what's going wrong or where I should start digging further?

True or False returned upon transition

As requested in #63, why is True returned if this code is executed!? Is this is a bug!?

from transitions import Machine
class Matter(object):
    pass
lump=Matter()
states=['solid', 'liquid']
machine = Machine(model=lump, states=states, initial='solid')
machine.add_transition('melt', source='solid', dest='liquid')
print(lump.melt())  # lump.melt() returns True

callback not working when using alternative initialisation pattern 1

I implemented a simple SM using the first pattern described in the alternative initialization patterns. Unfortunately, I cannot get the callbacks to work (e.g. on_enter_<some_state>). I prepared a working and a not working example.

alternative initialisation pattern 1 (not working)

test.py:

#!/usr/bin/env python

from transitions import Machine, State


def test_callback():
    print 'testing callbacks'

if __name__ == '__main__':

    states = ['StateA',
              State(name='StateB', on_enter=['test_callback'])]
    transitions = [{ 'trigger': 'triggerA', 'source': 'StateA', 'dest': 'StateB' }]
    sm = Machine(states=states, transitions=transitions, initial='StateA')

    print sm.state

    sm.triggerA()

    print sm.state

console output:

$ ./test.py 
StateA
Traceback (most recent call last):
  File "./test.py", line 18, in <module>
    sm.triggerA()
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 214, in trigger
    if t.execute(event):
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 134, in execute
    machine.get_state(self.dest).enter(event_data)
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 48, in enter
    getattr(event_data.model, oe), event_data)
  File "/usr/local/lib/python2.7/dist-packages/transitions/core.py", line 447, in callback
    func(*event_data.args, **event_data.kwargs)
TypeError: 'NoneType' object is not callable

normal/default initialisation (working)

test2.py:

#!/usr/bin/env python

from transitions import Machine, State

class TestModel(object):
    def test_callback(self):
        print 'testing callbacks'

if __name__ == '__main__':

    test_model = TestModel()

    states = ['StateA',
              State(name='StateB', on_enter=['test_callback'])]
    transitions = [{ 'trigger': 'triggerA', 'source': 'StateA', 'dest': 'StateB' }]
    sm = Machine(test_model, states=states, transitions=transitions, initial='StateA')

    print test_model.state

    test_model.triggerA()

    print test_model.state

console output:

$ ./test2.py 
StateA
testing callbacks
StateB

Am I missing something or doing something wrong here?

PS: Alternative initialisation pattern 2 works as well.

Before and after state change

Hi everybody,

I noticed one thing, "condition" callback is triggered before "before" callback. I expected that "before" is called before "condition"? Does my logic make any sense?

on_{state} can not work when state is not defined as string

Can't work

Work

Callables as callbacks

At the moment callbacks are set using strings which reference methods on the model object. This has the advantage that a set of transitions is model agnostic and could be used on multiple state machines, however in some cases it would be useful to pass a callable (like a function) as a callback. I have a use case at the moment where the model class has objects as properties, I want to call methods on them and currently I have to wrap those methods in methods defined on the model class itself. This means I have twice as many functions just to pass the callbacks around. I think it would be relatively straightforward to maintain the current usage and just do a type comparison when the callbacks need to be called, if they are strings look up the attribute on the model, if they are callables call them directly.

trafficlight

Hey everyone,

I really like the transitions package. Before. I always used the Qt StateMachine class and PyQt.
If only a Statemachine is required, transitions is leaner and not such a large dependency.
I have two questions.
I have created a traffic light, which can be turned on and run in the background. To do so the machine is dispatched to a separate thread which keeps calling next. The interpreter is constantly updated on the state of the traffic light via print outs and a user can stop or pause it.
Update: Threads were replaced with coroutines, the interpreter was replaced with a web front end, see example at the end.
The machine serves as a simple illustrations for more complicated machines, handled in the background, e.g. 3D printers.
The two questions are as follows:

Why is False or True returned if the traffic light is paused!? I also get this if I transition a machine from the documentation's code samples.
Update: This is to notify transition is successful, documentation has been updated.
Is this is the right way to do it, could you give a more elaborate example in the chapter Threadsafe(-ish) State Machine, any other comments!?
Update: No threads are expensive, use asyncio.
The code works in Python 3, not 2.7.

'''
Created on Jan 8, 2016
'''

from transitions import LockedHierarchicalMachine as Machine
from time import sleep, time
from threading import Thread, Event

class ThreadClass(Thread):
        def __init__(self,trafficlight):
            super().__init__()
            self.trafficlight=trafficlight
            self.stopevent=Event()  
            self.pauseevent=Event()
        def stop(self):  
            self.stopevent.set()
            self.pauseevent.set()    
        def pause(self):
            self.pauseevent.set()            
        def run(self):
            while(True):
                sleep(self.trafficlight.printstatetimeout()) 
                self.trafficlight.lock.acquire() 
                if self.stopevent.isSet():
                    print("Stop pressed, traffic light stops")
                    self.trafficlight.lock.release()
                    break
                else:
                    if self.pauseevent.isSet() and not self.stopevent.isSet():
                        self.trafficlight.lock.release()
                        print("Pause pressed")
                        self.pauseevent.clear()
                        self.pauseevent.wait()
                        print("Resume or stop pressed")
                        self.pauseevent.clear()
                        self.trafficlight.lock.acquire()
                    else:
                        self.trafficlight.next()
                self.trafficlight.lock.release()          

class Trafficlight(Machine):
    def __init__(self):
        self.timeoutdic = {'run_green': 3, 'run_red': 5, 'run_yellow': 2}
        states=['paused',{'name':'run', 'children':['green','yellow','red']}]
        transitions = [
                       { 'trigger': 'next', 'source': 'run_green', 'dest': 'run_yellow'},
                       { 'trigger': 'next', 'source': 'run_yellow', 'dest': 'run_red'},
                       { 'trigger': 'next', 'source': 'run_red', 'dest': 'run_green'},
                       {'trigger':'pause','source': 'run', 'dest':'paused', 'before':'storestate'},
                       {'trigger':'pause','source':'paused','dest':'run', 'after':'restorestate'},
                       {'trigger':'reset', 'source':'*','dest':'run_green'}
                       ]
        Machine.__init__(self, states=states,transitions=transitions, initial='run_green')
        self.reinstall()
    def reinstall(self):
        self.thread=ThreadClass(self) 
        self.oldtime=None
        self.elapsedtime=None
        self.oldstate=None
    def printstatetimeout(self):
        self.oldtime=time()
        self.oldstate=self.state
        if self.elapsedtime:
            naptime=self.timeoutdic[self.state]-self.elapsedtime
            self.elapsedtime=None
        else:
            naptime=self.timeoutdic[self.state]
        print('Light is '+self.state+' and on for '+str(naptime)+'s')
        return naptime
    def start(self):
        self.thread.start()
    def stop(self):
        print('Traffic light is turned off')
        print('Waiting '+str(self.timeoutdic[self.state])+'s for all processes to finish')
        self.thread.stop()
        sleep(self.timeoutdic[self.state])
        self.reset()
        self.reinstall()
    def storestate(self):
        print('Light is turned off temporarily')
        self.elapsedtime=time()-self.oldtime
        self.thread.pause()
    def restorestate(self):
        self.set_state(self.oldstate)
        self.thread.pause()  

trafficlight = Trafficlight()
trafficlight.start()  
sleep(10)
trafficlight.stop()   
trafficlight.start()  
sleep(11)
trafficlight.pause() 
sleep(5)   # TODO: False returned why!?
# Resumes traffic light, interruption is accounted for see; storestate, restorestate
trafficlight.pause()

Multiple callbacks active at the same time

Currently most of my state logic is contained in on_enter callbacks. Since in some states I have to periodical checks, these callbacks run until the sate finishes.

Now I just noticed that it is possible that the on_enter CB of the following state is activated, while the old callback hasn't finished yet. Is this behaviour desired?

In my case I probably will have to start using mutexes ... 😖

Define transitions on states rather than machine?

Would it be possible to change the way transitions are added (or add an additional method for adding them) so that they are added to the source state rather than to the machine? It seems to me that something like:
machine['solid'].add_transition('sublimate', 'gas')
is more immediately comprehensible than:
machine.add_transition('sublimate', 'solid', 'gas')
as it allows the transitions to be conceptually grouped around the source state. I suspect that the wildcard might cause some implementation difficulties, but are there any other issues with this kind of syntax?

plotting graphs

I tried the following code to verify that I have a correct state machine :

#!/usr/bin/python
# -*- coding: utf-8 -*-

from fileStateMachine import *
states = ['1', '2', '3']
transitions = [
    {
        'trigger': 'advance',
        'source': '1',
        'dest': '2',
        'conditions': 'valid_data'
        },
    {
        'trigger': 'advance',
        'source': '1',
        'dest': '3',
        'unless': 'valid_data'
        }
]

class MF():
    def valid_data():
        return random.randrange(100) < 50

lump = MF( )

# the actual state machine a file posses.
machine = Machine( lump, states=states, initial='1', transitions=transitions, auto_transitions=False )

#print state machine
graph = None
try:
    graph = machine.get_graph()
except :
    printError('pygraphviz is missing.')
    sys.exit(101)
graph.draw('my_state_diagram.png', prog='dot')
print 'TODO'

which result in the following state diagram:

now a bunch of questions arise:

Is there a concept to tell a/multiple State(s) that it is final or has a final property.
Can we pass this state to pygraphviz.
Why is the initial state ignored in the graph, or is it ignored in the machine as well?
Would it be possible to add the condition to the graph, e.g. as an argument to advance -> "advance( valid_data==true )", since IMHO this small state machine is valid.

Many thanks in advance
stvo

How to describe one condition func call but different state change in one transition

hi，I have a question when using your awesome FSM, I want the code works like:

state = STATE_A

if condition_test():
    state = STATE_B
else:
    state = STATE_C

I write code like this, but it does work as expected. Becase the trigger: `mycall' will be called two times.

def condition_test():
    return random.randint(0,1) == 0 

transitions = [
    { 
        'trigger': 'mycall', 
        'source': 'STATE_A', 
        'dest': 'STATE_B' ,
        'conditions': 'condition_test'
    },
    { 
        'trigger': 'mycall', 
        'source': 'STATE_A', 
        'dest': 'STATE_C' ,
        'unless': 'condition_test'
    }
]

fsm = Machine(states=states, initial='STATE_A')

#### other code

So please help me, how to achieve one condition func call but different state change in one transition. Thanks verymuch!

Looping / "Running" a Machine

I might be missing a critical concept; I can't find any examples or snippets that show how to do this:

How would I setup a machine to move to the next state until an end state is reached? All of the examples show manual steps from one state to the next. I'd like to "start" the machine and have it automatically transition from one state to the next using conditional transitions until it reaches the "end" state.

Any suggestions are much appreciated. I'm really interested in using this library; it seems to be very clean and lightweight compared to other python implementations of FSM.

Logger as parameter to use with multiple machines

Use of standard logging is great. However there are use cases where more than one FSM can be instanciated, in which case it is difficult to match log lines with code logic.

I would like to propose an optional logger parameter when instanciating the machine (with default to current global logger). This way user has possibility to pass a logger instance embedding some context and configuration.

Lock fails for conditional transition

I just stumbled upon a bug which occurs if a list of possible transitions is evaluated in core.Event. This problem occurs because locking core.Transition.execute is not sufficient for the test scenario below:

def test_conditional_access(self):
    self.stuff.heavy_checking = heavy_checking # checking takes 1s and returns False
    self.stuff.machine.add_transition('advance', 'A', 'B', conditions='heavy_checking')
    self.stuff.machine.add_transition('advance', 'A', 'C')
    t = Thread(target=self.stuff.advance)
    t.start()
    time.sleep(0.1)
    logger.info('Check if state transition done...')
    # Thread will release lock before Transition is finished
    self.assertTrue(self.stuff.machine.is_state('C'))

Cause:

for t in self.transitions[state_name]:
    event.transition = t
    if t.execute(event): # lock is acquired and released here

Execution order will be TransitionAB.execute (Thread), Machine.is_state (Main), TransitionAC.execute (Thread). Update: Since it is a racing condition who gets the lock after TransitionAB it does not fail all the time.

Proposed solution: Lock core.Event.trigger rather than core.Transition.execute.
~~This requires minor changes to core to be able to subclass Event.~~ Update: It does not. It's is three lines of redundant code though.

If you do not object and/or think this is a bad idea I will fix it in a branch fix-67-threading.

transitions prevents logging module from working

I admit I am new to logging, but even with this simple example, adding the transitions module prevents logging from working:

import transitions
import logging


if __name__ == '__main__':

    # set up a logger
    logging.basicConfig(level=logging.INFO,
                        format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
                        datefmt='%m-%d %H:%M',
                        filename='mylog.log',
                        filemode='w')

    logging.info("test")

if you comment out the import transitions the logging file is created and "test" shows up as expected. When the transitions module is imported, the log file is not created.

Am I making the mistake by incorrectly setting up logging? Or is transitions setting something up for logging that overrides my logging attempts?

Wildcard transitions are not applied on newer states

If one adds a state after a transition with a wildcard source then that transition will not apply on the new state.

In [6]: m=transitions.Machine()

In [7]: m.add_transition('one', '*', 'final')

In [8]: m.add_transition('two', 'initial', 'two')

In [9]: m.states
Out[9]: OrderedDict([('initial', <transitions.core.State object at 0x10c84dcd0>)])

In [10]: m.events
Out[10]:
{'one': <transitions.core.Event at 0x10c84dc90>,
 'to_initial': <transitions.core.Event at 0x10c84dad0>,
 'two': <transitions.core.Event at 0x10c84db10>}

In [11]: m.add_state('two')

In [12]: m.to_two()
[14/Jan/2016 16:39:32] INFO [transitions.core:131] Initiating transition from state initial to state two...
[14/Jan/2016 16:39:32] INFO [transitions.core:58] Exited state initial
[14/Jan/2016 16:39:32] INFO [transitions.core:51] Entered state two
Out[12]: True

In [13]: m.one()
---------------------------------------------------------------------------
MachineError                              Traceback (most recent call last)
<ipython-input-13-81b3745163c6> in <module>()
----> 1 m.one()

/Users/administrator/.virtualenvs/test/lib/python2.7/site-packages/transitions/core.pyc in trigger(self, *args, **kwargs)
    227                 logging.warning(msg)
    228             else:
--> 229                 raise MachineError(msg)
    230         event = EventData(self.machine.current_state, self, self.machine,
    231                           self.machine.model, args=args, kwargs=kwargs)

MachineError: "Can't trigger event one from state two!"

Using Machine(s) as State(s)

Can I use composite states like a state? Like using another state machine as a state?

Documentation states that model has `set_state` method

E.g.: https://github.com/tyarkoni/transitions/blame/f378776dd3c8a5bd0f5861c26bb5022938a7dbef/README.md#L263

In fact that method is not created on the model - it is only available on the machine.

Improve nested extension

Since my first implementation I got some feedback about the way I have done Hierarchical State Machines in transitions. The current implementation has some issues:

underscore separator does not cut it: We have been aware of the fact, that underscore is no perfect solution but it allowed nested states to reuse many of transitions' core functionality (auto transitions and callback addition). However, since underscore can also be used in state naming, there is no way to tell if stateC_alt_state1 is actually a (two times) nested state or not. Even worse could be a situation where the naming of states collide (stateC + alt_state1; stateC_alt + state_1). I haven't even tried what the ambiguity in auto transition would do but to_stateC_alt_state1 would probably do random things.
flatten strategy destroys hierarchical information: After flattening, retrieving hierarchical information, especially related to transitions, is bothersome. You cannot rely on the name. This means you have to retrieve the state in question and have a look at the parent (and its parent and so on) to actually know HOW nested the state was. I still think flattening is not a bad approach but especially in combination with the underscore separator it makes things unnecessarily complicated. The blueprint strategy could compensate this a bit and made copying possible but its one of the things that is hard to comprehend and maintain especially if the 'causer' is not available anymore.

I spent some time thinking about it and came to the conclusion that I have to change some things under the hood but also violate the first law of a library developer which is 'One shall not break the API' by switching from underscore to a dot separator. Why choosing the dot:

It's already implicitly forbidden in naming because it makes the convenience features of transitions useless: 'my.state' -> to_my.state (Nope) -> on_enter_my.state (Nope)
From python's point of view it's suitable to imply nesting: machine.to_stateA.alt.state1 resembles common object.child.property nesting. I have chosen to_stateC.alt rather than to.stateC.alt to stick to the way transition's core work. This is done with a callable FunctionWrapper which contains auto transitions to child states as properties (wrapping happens here).

Setback: The way of returning callbacks with partial is not that easy to extend to allow on_enter_C.alt('callback'). The best I came up with was on_enter_C().alt('callback') without overwriting __attr__ in nested (which I try to avoid). So I have chosen another way which is on_enter/on_exit('C.alt','callback'). Implicit calling of model functions does not work in this case though.

However, the rework brings new features which hopefully make up for it:

hierarchical order is kept: No need for blueprints anymore
Machines can be embedded and not just copied into another Machine: {name:'stateC', children:another_machine} no longer copies the structure but references the states directly. This allows to keep the states of a machine and dynamical add them to another super state machine. This becomes handy if you subclass States to keep certain informations independently of their current status or if creating a state requires much time and/or resources.
Embedding machines allows siblings: {name:'stateC', children:['1',another_machine]}is no longer prohibited. If another_machine also contains a state named 1 a ValueError is raised.
Hierarchical delegation of transitions: Previously, parent state transitions had to be copied to its children. Having a transition from stateC means 3 transitions for 3 children and 12 if these children also contain 3 children. Additionally, it makes the trigger unusable for children or leads to unpredictable behaviour if substates 'accidentally' use the same trigger. In this case addition order decides which transition is executed. Not anymore! After the rework trigger events are delegated from children to parents. This means children can intentionally overwrite their parents behaviour.

Ah yeah, I also merged AAGraph and AGraph since AAGraph was already the default class chosen and I haven't found any occasion where AGraph was explicitly used. Actually this is also the reason why #85 fails the coverage test I guess. AGraph._add_nodes and AGraph._add_edges aren't used during testing.

There is still some work to be done (tweaking, documentation and merging the latest changes for instance), that's why I haven't opened a pull request yet. But it has progressed enough to gather some feedback.

So what are your thoughts about that? Is to_stateC.alt.stateD() and on_enter('stateC.alt.stateC','callback') sufficient? Is it okay to break the API and use dots from now on?

More powerful transiton?

I found it may be difficult to pass data from trigger to transition's condition. For example, trigger=foo,when bar>5, StateA->StateB, I can't use Machine.foo(bar=6) to excute the transition.

By the way, I think a transition including Event Trigger, Condition, Condition Action, Transition Action is necessary for building compicated FSM.
That kind of transition is described in http://mathworks.com/help/stateflow/ug/transitions.html

on_enter_{state} does not excute automatically

I found on_enter_{state} excute only if I set the on_enter=xxx in defination of state. I think the code below is natural, but it can not work. Do you think it should be supported?

First argument passed to the trigger will be vanished

>>from transitions import Machine, State
>>class Model(object):
>>    def on_activate(self, value):
>>        print value
>>model = Model()
>>states = [
>>    'init',
>>    State('active', on_enter='on_activate'),
>>]
>>transitions = [{'trigger': 'activate', 'source': 'init', 'dest': 'active'}]
>>machine = Machine(model=model, states=states, transitions=transitions, initial='init')
>>model.activate('simple argument, not a kwarg')
Traceback (most recent call last):
...
TypeError: on_activate() takes exactly 2 arguments (1 given)

a generic callback

Hi!

Is there a way to specify a generic callback which will be called whenever the machine changes its state?

Support tuple to declare states and transitions

Machine fails to parse Machine(states=('A', 'B')) but insists on a list, same for transitions.

Hierarchical Concurrent State Machine

Hi,

I have not worked with transitions so far but it looks like a really neat and pythonic approach to state machines. So in that matter its exactly what we need for a project :). My question is if transitions also supports nested and concurrent states. I know it is a bit contradicting to search something 'simple' but also requiring such complex features. But maybe I have just missed that in the docs or you may have some recommendations about how to realise hierarchical concurrent state machines with transitions.

Best regards,
Alex

Transitions tramples logging config

With the recently added logging support you added a call to logging.basicConfig. That is the WRONG THING(tm) to to do for a library since it destroys the logging config of programs using the library.

The logging docs describe how a library should configure logging

state diagrams

At some point we should add the ability to generate state diagrams via GraphViz or NetworkX.

Graph Mixin Support

I've added in the graph as a mixin as per @aleneum's suggestion. Please take a look and see if it works for you.

Adds a graph attribute to the machine which will auto-track the changes and apply the style attribute from the MachineGraphSupport instance according to the styles_attribute defined in the base AGraph class. Currently has three styles: default, active, passive

Example notebook here

Feel free to iterate on the dev-graph branch.

Generic condition method

Very good work! I'm curious if I could have a generic condition method where I check the transition source and dest field and return True/False accordingly. I can't seem to find transition's dest from generic condition method. Or may be there's a better way?

Inheritance sample

In the inheritance sample:

class Matter(Machine):
    def say_hello(self): print "hello, new state!"
    def say_goodbye(self): print "goodbye, old state!"

    def __init__(self):
        states = ['solid', 'liquid', 'gas']
        Machine.__init__(self, states, initial='solid')
        self.add_transition('melt', 'solid', 'liquid')

constructor args are wrong (1st param is model name).
It could be like this:

Machine.__init__(self, states=states, initial='solid')

Add info to setup.py info

Adding info in setup.py/pypi.python.org (supported python versions)´whould help to spread the package.

Allow machine pickle/unpickle

Currently, pickling or unpickling objects with Machine instance fails with TypeError:
example from quick start example:

import pickle
print(pickle.dumps(batman))
TypeError: 'NoneType' object is not callable

This could be useful to be able to save and restore a machine state. I can work on that if you agree.

State Callback defined in model class does not run

I've created a model class that inherits Machine which contains several on_enter_ callbacks for several states (methods defined/named on_enter_stateName(self)). None of the callbacks are executed when the state is entered. In core.py (lines 369-374) it looks like this method of adding callbacks only works if the model class is not "self".

Inheritance sample seems to be incorrect

This example does not seem work as intended:

>>> from transitions import Machine
>>> class Matter(Machine):
...     def say_hello(self): print ("hello, new state!")
...     def say_goodbye(self): print ("goodbye, old state!")
...     def __init__(self):
...         states = ['solid', 'liquid', 'gas']
...         Machine.__init__(self, states, initial='solid')
...         self.add_transition('melt', 'solid', 'liquid')
...
>>> lump = Matter()
['solid', 'liquid', 'gas']
None
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 6, in __init__
  File "/Users/adamb/Developer/transitions-bug/env-osx/lib/python3.5/site-packages/transitions/core.py", line 294, in __init__
    self.set_state(self._initial)
  File "/Users/adamb/Developer/transitions-bug/env-osx/lib/python3.5/site-packages/transitions/core.py", line 325, in set_state
    state = self.get_state(state)
  File "/Users/adamb/Developer/transitions-bug/env-osx/lib/python3.5/site-packages/transitions/core.py", line 319, in get_state
    raise ValueError("State '%s' is not a registered state." % state)
ValueError: State 'solid' is not a registered state.

I was going to send a pull, but I'm not sure of the correct behaviour.

The issue is that when invoking Machine.init as a class method, the first parameter from the invocation (self) gets put into the first parameter of Machine.init() (self).

This shifts all the parameters left, so states gets put into model etc.

There are three ways to fix this - either add a second self so that Machine.model is set to self:

...         Machine.__init__(self, self, states, initial='solid')

or, use an explicit keyword for states so that Machine.model is set to None (this version is used in your test suite):

...         Machine.__init__(self, states=states, initial='solid')

This also fixes the example:

...         super(Matter, self).__init__(self, states, initial='solid')

Which one is "correct"? When you are using inheritance, is the model intended to be None, or an instance of itself?

Support initial transition?

I found there is no initial transition supported yet, that means the "on_enter_initial" will not excute when state machine start to run to the initial state at the first time. Do you think it's necessary?
UML state machine supports that.(http://en.wikipedia.org/wiki/UML_state_machine)

Logger does not display state information

When using the logging functionality with transitions, the state information of the state machine is not displayed on_enter and on_exit. For example, on entering a state stdout displays:

2015-09-01 13:13:41,528 - transitions.core: Exited state %s

This issue is probably due to an incorrect string formatting in calls to the logger, see below:

logger.info("Entered state %s", self.name)

# should be changed to:
logger.info("Entered state %s" % self.name)

How to achieve other conditions except default `conditions' or `unless' in one condition

Hi, dear tyarkoni

I have another question whiling using your FSM, I want to achieve like this: start a task to wget a large file, and then to check is the wget task finished or not once in a while, because result may be three status: wget_ing, wget_failure, wget_success. Pseudocode is like bellow:

def start_wget():

    return 0

def check_wget():

    return random('WGET_RUNNING', 'WGET_SUCCESS', 'WGET_FAILURE')

# WGET_EXEC
# WGET_RUNNING
# WGET_SUCCESS
# WGET_FAILURE

state = 'WGET_EXEC'

# here we do not care
start_wget()

result = check_wget()

if result == 1:
    state = 'WGET_RUNNING'
elif result == -1:
    state = 'WGET_FAILURE'
elif result == 0:
    state = 'WGET_SUCCESS'

And I do not know how to achieve in your FSM, please help me!

transitions = [
    { 
        'trigger': 'mycall', 
        'source': 'WGET_EXEC', 
        'dest': 'WGET_RUNNING' ,
        'conditions': 'start_wget'
    },
    { 
        'trigger': 'mycall', 
        'source': 'WGET_RUNNING', 
        'dest': 'WGET_SUCCESS' ,
        'conditions': 'check_wget' 
    },
    { 
        'trigger': 'mycall', 
        'source': 'WGET_RUNNING', 
        'dest': 'WGET_RUNNING' ,
    },
    { 
        'trigger': 'mycall', 
        'source': 'WGET_RUNNING', 
        'dest': 'WGET_FAILURE' ,
    },
   ... 
]

fsm = Machine(states=states, initial='WGET_EXEC')

Trouble getting started

from transitions import Machine

states = [
    "leaderboard",
    "chapter_teaser"
    "chapter_chosen",
    "adding_to_leaderboard"
]

transitions = [
    { 'trigger': 'advance', 'source': 'leaderboard', 'dest': 'chapter_teaser' },
    { 'trigger': 'advance', 'source': 'chapter_teaser', 'dest': 'chapter_chosen' },
    { 'trigger': 'advance', 'source': 'chapter_chosen', 'dest': 'adding_to_leaderboard' },
    { 'trigger': 'advance', 'source': 'adding_to_leaderboard', 'dest': 'leaderboard' }
]

class LeaderBoardDisplay(object):
    pass

leaderboard = LeaderBoardDisplay()

machine = Machine(leaderboard, states=states, transitions=transitions, initial='leaderboard')

I've been trying to use the state machine above, but can't work out the method to go to the next state.

Also, machine.anything_at_all returns None, instead of an exception.

conditions in ordered_transitions

Hi, it's me again 😄

As far as I understand there is no way at the moment to specify a condition for a single transition in a chain? If you don't mind about the feature I could provide a pull request for the feature.

Pickling without Dill for Python 3.4 and higher fails for LockedMachine

======================================================================
ERROR: test_pickle (tests.test_threading.TestTransitions)
----------------------------------------------------------------------
Traceback (most recent call last):
  File ".../transitions/tests/test_threading.py", line 67, in test_pickle
    dump = pickle.dumps(m)
AttributeError: Can't pickle local object 'LockedMachine.__getattribute__.<locals>.locked_method'

Main scheduler

Thanks for the nice design and implementation.

I have a question for the "main" loop. ( I do not know if the "conditional transition" is the answer to my question or not. So please advise )
Let's use your NarcolepticSuperhero example walk-through. You used Python interactive prompt. That's the main loop. It sits there and waits for an event to occur (such as .wake_up()). When that event occurs, the main loop notifies the state machine of that event (batman.wake_up()). That notification makes the state machine transitions to the next state, AND THEN it comes back to the main loop (Python interactive prompt), and waits again for the next event to occur.

I am seeking a way to implement the Main loop functionality which is not Python interactive prompt. The same functionality is needed: Wait for an event, pass to the state machine so that it can transition to a next state, and completing before_transition(), on_exit(), on_enter(), after_transition(), and THEN comes back to a main loop.

In the source of "transitions", I found no while loop.

If this questions does not sound making sense, probably I have mistaken the design of your implementation.

Thanks,
pb.

callback function if conditions is not satisfied

Hi,

Is there some way that i could define callback function if condition is not satisfied, after callbacks are only triggered if condition is satisfied. Something like after_fail would be cool.

For example, i have a state change from new to active:

        {'trigger': 'new_to_active', 'source': States.NEW, 'dest': States.ACTIVE,
         'before': 'write_insert_statement',
         'conditions': 'is_instruction_successfully_sent_to_controller',
         'after': ['save_current_state',
                   'set_related_instructions_to_active_state']},

In the part of the code that calls this trigger i have

                if not machine.new_to_provisioned():
                    machine.new_to_error()

I would like to put as much logic as i can in my state machine, so the handlers that call this events are totally dumb.

Best,
Domagoj

Optional debugging feature

This library is very useful, thanks for the great work!

I think that adding an optional logging feature, which would dump to stdout/err all transitions as they get triggered, along with the states which they originate from/go to, would be a big convenience.

on_enter when initialzing machine

Given:

>>> from transitions import Machine
>>> class Practise(object):
...     def on_enter_A(self): print("We've just entered state A!")
... 
>>> test = Practise()

Is there any reason why:

>>> machine = Machine(model=test, states=['A', 'B', 'C'], initial='A')

Doesn't immediately return:

"We've just entered state A!"

As it does when you enter state A subsequent times:

>>> machine.add_transition('repeat', source='A', dest='A')
>>> test.repeat()
We've just entered state A!
True

Thanks.

Error on passing data to functions in 'before', 'after' and 'conditions'

The first example in "Passing Data" section in README gives this error:

Traceback (most recent call last):
  File "/Users/harshit/PycharmProjects/DialogFlow/test.py", line 17, in <module>
    lump.melt(temp=45, pressure=1853.68)  # keyword args
  File "/usr/local/lib/python3.5/site-packages/transitions/core.py", line 227, in trigger
    if t.execute(event):
  File "/usr/local/lib/python3.5/site-packages/transitions/core.py", line 145, in execute
    machine.callback(getattr(event_data.model, func), event_data)
  File "/usr/local/lib/python3.5/site-packages/transitions/core.py", line 460, in callback
    func(*event_data.args, **event_data.kwargs)
TypeError: print_pressure() got an unexpected keyword argument 'temp'

on adding transitions the following way
machine.add_transition('melt', 'solid', 'liquid', before='set_environment', after='print_pressure')

States that triggered event

Hi,

I have a question. I have a code like this

        {'trigger': 'new_to_pending', 'source': States.NEW, 'dest': States.PENDING,
         'before': 'write_insert_statement',
         'after': ['save_current_state',
                   'set_related_active_instructions_to_pending_state']},

i write_insert_statement i would like to access source and dest states, if i send send_event=True to initializer i get event_data object but his object only contains initial state. Is it possible to retrieve both states source and dest?

Best,
Domagoj

Dynamic on_enter/exit_* methods

The documentation says:

# Callbacks can also be added after initialization using 
# the dynamically added on_enter_ and on_exist_ methods.

I haven't looked into this in detail yet but a quick scan doesn't show a route through the code that creates on_enter/on_exit methods for each state after init has run.

Has this ever worked?

>>> from transitions import State, Machine
>>>
>>> class Matter(object):
...     def say_hello(self): print("hello, new state!")
...     def say_goodbye(self): print("goodbye, old state!")
...
>>> lump = Matter()
>>>
>>> states = [
...     State(name='solid', on_exit=['say_goodbye']),
...     'liquid',
...     { 'name': 'gas' }
...     ]
>>>
>>> machine = Machine(lump, states=states)
>>> machine.add_transition('sublimate', 'solid', 'gas')
>>>
>>> lump.on_exit_solid('say_goodbye')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'Matter' object has no attribute 'on_exit_solid'
>>>
>>> machine.set_state('solid')
>>> lump.sublimate()

PyPI Out of Date despite Version

Hi, the package you have on PyPI is listed as version 0.2.9, which is the latest, but hasn't been updated since 2015-11-10. Turns out those small changes with the inspect module on the add_states are important when it comes to multiple inheritance. Took me a while to figure out the code was just out of date. Thanks!

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.

pytransitions / transitions Goto Github PK

transitions's Introduction

transitions

Installation

Table of Contents

Quickstart

The non-quickstart

Basic initialization

States

Callbacks

Checking state

Enumerations

Transitions

Automatic transitions for all states

Transitioning from multiple states

Reflexive transitions from multiple states

Internal transitions

Ordered transitions

Queued transitions

Conditional transitions

Check transitions

Callbacks

Callable resolution

Callback execution order

Passing data

Alternative initialization patterns

Logging

(Re-)Storing machine instances

Extensions

Diagrams

Hierarchical State Machine (HSM)

Reuse of previously created HSMs

Threadsafe(-ish) State Machine

Using async callbacks

Adding features to states

Using transitions together with Django

I have a [bug report/issue/question]...

transitions's People

Contributors

Stargazers

Watchers

Forkers

transitions's Issues

Recommend Projects

Recommend Topics

Recommend Org