This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

License

MIT licensed. All credits go to Jake Gordon for the original javascript implementation and to Mansour Behabadi for the python port.

Synopsis

This is basically Mansours’ implementation with unit tests and a build process added. It’s also on PyPi (pip install fysom). Fysom is built and tested on python 2.6 to 3.3 and PyPy.

Installation

From your friendly neighbourhood cheeseshop

pip install fysom

Developer setup

This module uses PyBuilder.

sudo pip install pyb_init
pyb-init github mriehl : fysom

Running the tests

pyb verify

Generating and using a setup.py

pyb
cd target/dist/fysom-$VERSION
./setup.py bdist_rpm #build RPM

Looking at the coverage

pyb
cat target/reports/coverage

USAGE

Basics

from fysom import Fysom

fsm = Fysom({ 'initial': 'green',
              'events': [
                  {'name': 'warn', 'src': 'green', 'dst': 'yellow'},
                  {'name': 'panic', 'src': 'yellow', 'dst': 'red'},
                  {'name': 'calm', 'src': 'red', 'dst': 'yellow'},
                  {'name': 'clear', 'src': 'yellow', 'dst': 'green'} ] })

… will create an object with a method for each event:

  • fsm.warn() - transition from ‘green’ to ‘yellow’
  • fsm.panic() - transition from ‘yellow’ to ‘red’
  • fsm.calm() - transition from ‘red’ to ‘yellow’
  • fsm.clear() - transition from ‘yellow’ to ‘green’

along with the following members:

  • fsm.current - contains the current state
  • fsm.isstate(s) - return True if state s is the current state
  • fsm.can(e) - return True if event e can be fired in the current state
  • fsm.cannot(e) - return True if event s cannot be fired in the current state

Shorter Syntax

It’s possible to define event transitions as 3-tuples (event name, source state, destination state) rather than dictionaries. Fysom constructor accepts also keyword arguments initial, events, callbacks, and final.

This is a shorter version of the previous example:

fsm = Fysom(initial='green',
            events=[('warn',  'green',  'yellow'),
                    ('panic', 'yellow', 'red'),
                    ('calm',  'red',    'yellow'),
                    ('clear', 'yellow', 'green')])

Initialization

How the state machine should initialize can depend on your application requirements, so the library provides a number of simple options.

By default, if you don’t specify any initial state, the state machine will be in the ‘none’ state and you would need to provide an event to take it out of this state:

fsm = Fysom({'events': [
                {'name': 'startup', 'src': 'none',  'dst': 'green'},
                {'name': 'panic', 'src': 'green', 'dst': 'red'},
                {'name': 'calm', 'src': 'red', 'dst': 'green'}]})
print fsm.current # "none"
fsm.startup()
print fsm.current # "green"

If you specify the name of your initial event (as in all the earlier examples), then an implicit ‘startup’ event will be created for you and fired when the state machine is constructed:

fsm = Fysom({'initial': 'green',
             'events': [
                 {'name': 'panic', 'src': 'green', 'dst': 'red'},
                 {'name': 'calm', 'src': 'red', 'dst': 'green'}]})
print fsm.current # "green"

If your object already has a startup method, you can use a different name for the initial event:

fsm = Fysom({'initial': {'state': 'green', 'event': 'init'},
             'events': [
                 {'name': 'panic', 'src': 'green', 'dst': 'red'},
                 {'name': 'calm',  'src': 'red', 'dst': 'green'}]})
print fsm.current # "green"

Finally, if you want to wait to call the initial state transition event until a later date, you can defer it:

fsm = Fysom({'initial': {'state': 'green', 'event': 'init', 'defer': True},
             'events': [
                 {'name': 'panic', 'src': 'green', 'dst': 'red'},
                 {'name': 'calm',  'src': 'red',   'dst': 'green'}]})
print fsm.current # "none"
fsm.init()
print fsm.current # "green"

Of course, we have now come full circle, this last example pretty much functions the same as the first example in this section where you simply define your own startup event.

So you have a number of choices available to you when initializing your state machine.

You can also indicate which state should be considered final. This has no effect on the state machine, but lets you use a shorthand method is_finished() that returns true if the state machine is in this ‘final’ state:

fsm = Fysom({'initial': 'green',
             'final': 'red',
             'events': [
                 {'name': 'panic', 'src': 'green', 'dst': 'red'},
                 {'name': 'calm',  'src': 'red',   'dst': 'green'}]})
print fsm.current # "green"
fsm.is_finished() # False
fsm.panic()
fsm.is_finished() # True

Dynamically generated event names

Sometimes you have to compute the name of an event you want to trigger on the fly. Instead of relying on getattr you can use the trigger method, which takes a string (the event name) as a parameter, followed by any arguments/keyword arguments you want to pass to the event method. This is also arguably better if you’re not sure if the event exists at all (FysomError vs. AttributeError, see below).

from fysom import Fysom

fsm = Fysom({ 'initial': 'green',
              'events': [
                  {'name': 'warn', 'src': 'green', 'dst': 'yellow'},
                  {'name': 'panic', 'src': 'yellow', 'dst': 'red'},
                  {'name': 'calm', 'src': 'red', 'dst': 'yellow'},
                  {'name': 'clear', 'src': 'yellow', 'dst': 'green'} ] })

fsm.trigger('warn', msg="danger")  # equivalent to fsm.warn(msg="danger")
fsm.trigger('unknown')  # FysomError, event does not exist
fsm.unknown()  #  AttributeError, event does not exist

Multiple source and destination states for a single event

fsm = Fysom({'initial': 'hungry',
             'events': [
                 {'name': 'eat', 'src': 'hungry', 'dst': 'satisfied'},
                 {'name': 'eat', 'src': 'satisfied', 'dst': 'full'},
                 {'name': 'eat', 'src': 'full', 'dst': 'sick'},
                 {'name': 'rest', 'src': ['hungry', 'satisfied', 'full', 'sick'], 'dst': 'hungry'}]})

This example will create an object with 2 event methods:

  • fsm.eat()
  • fsm.rest()

The rest event will always transition to the hungry state, while the eat event will transition to a state that is dependent on the current state.

NOTE the rest event in the above example can also be specified as multiple events with the same name if you prefer the verbose approach.

NOTE if an event can be triggered from any state, you can specify it using the ‘*’ wildcard, or even by omitting the src attribute from its definition:

fsm = Fysom({'initial': 'hungry',
             'events': [
                 {'name': 'eat', 'src': 'hungry', 'dst': 'satisfied'},
                 {'name': 'eat', 'src': 'satisfied', 'dst': 'full'},
                 {'name': 'eat', 'src': 'full', 'dst': 'sick'},
                 {'name': 'eat_a_lot', 'src': '*', 'dst': 'sick'},
                 {'name': 'rest', 'dst': 'hungry'}]})

NOTE if an event will not change the current state, you can specify destination using the ‘=’ symbol. It’s useful when using wildcard source or multiply sources:

fsm = Fysom({'initial': 'hungry',
             'events': [
                 {'name': 'eat', 'src': 'hungry', 'dst': 'satisfied'},
                 {'name': 'eat', 'src': 'satisfied', 'dst': 'full'},
                 {'name': 'eat', 'src': 'full', 'dst': 'sick'},
                 {'name': 'eat_a_little', 'src': '*', 'dst': '='},
                 {'name': 'eat_a_little', 'src': ['full', 'satisfied'], 'dst': '='},
                 {'name': 'eat_a_little', 'src': 'hungry', 'dst': '='},
                 {'name': 'rest', 'dst': 'hungry'}]})

Callbacks

5 callbacks are available if your state machine has methods using the following naming conventions:

  • onbefore_event_ - fired before the event
  • onleave_state_ - fired when leaving the old state
  • onenter_state_ - fired when entering the new state
  • onreenter_state_ - fired when reentering the old state (a reflexive transition i.e. src == dst)
  • onafter_event_ - fired after the event

You can affect the event in 2 ways:

  • return False from an onbefore_event_ handler to cancel the event. This will raise a fysom.Canceled exception.
  • return False from an onleave_state_ handler to perform an asynchronous state transition (see next section)

For convenience, the 2 most useful callbacks can be shortened:

  • on_event_ - convenience shorthand for onafter_event_
  • on_state_ - convenience shorthand for onenter_state_

In addition, a generic onchangestate() callback can be used to call a single function for all state changes.

All callbacks will be passed one argument ‘e’ which is an object with following attributes:

  • fsm Fysom object calling the callback
  • event Event name
  • src Source state
  • dst Destination state
  • (any other keyword arguments you passed into the original event method)
  • (any positional argument you passed in the original event method, in the ‘args’ attribute of the event)

Note that when you call an event, only one instance of ‘e’ argument is created and passed to all 4 callbacks. This allows you to preserve data across a state transition by storing it in ‘e’. It also allows you to shoot yourself in the foot if you’re not careful.

Callbacks can be specified when the state machine is first created:

def onpanic(e):
    print 'panic! ' + e.msg
def oncalm(e):
    print 'thanks to ' + e.msg + ' done by ' + e.args[0]
def ongreen(e):
    print 'green'
def onyellow(e):
    print 'yellow'
def onred(e):
    print 'red'
fsm = Fysom({'initial': 'green',
             'events': [
                 {'name': 'warn', 'src': 'green', 'dst': 'yellow'},
                 {'name': 'panic', 'src': 'yellow', 'dst': 'red'},
                 {'name': 'panic', 'src': 'green', 'dst': 'red'},
                 {'name': 'calm', 'src': 'red', 'dst': 'yellow'},
                 {'name': 'clear', 'src': 'yellow', 'dst': 'green'}],
             'callbacks': {
                 'onpanic': onpanic,
                 'oncalm': oncalm,
                 'ongreen': ongreen,
                 'onyellow': onyellow,
                 'onred': onred }})

fsm.panic(msg='killer bees')
fsm.calm('bob', msg='sedatives in the honey pots')

Additionally, they can be added and removed from the state machine at any time:

def printstatechange(e):
    print 'event: %s, src: %s, dst: %s' % (e.event, e.src, e.dst)

del fsm.ongreen
del fsm.onyellow
del fsm.onred
fsm.onchangestate = printstatechange

Asynchronous state transitions

Sometimes, you need to execute some asynchronous code during a state transition and ensure the new state is not entered until you code has completed.

A good example of this is when you run a background thread to download something as result of an event. You only want to transition into the new state after the download is complete.

You can return False from your onleave_state_ handler and the state machine will be put on hold until you are ready to trigger the transition using the transition() method.

Release History

Release History

2.1.2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

2.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.1.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.19

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.18

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.17

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.15

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.14

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.13

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.12

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.11

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.10

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.9

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.8

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.7

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.6

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
fysom-2.1.2.tar.gz (13.3 kB) Copy SHA256 Checksum SHA256 Source Aug 16, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting