Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Simple Finite-State Machines

Project Description


pystatemachine is a versatile, yet easy-to-use finite-state machine library written in python. It provides functions to turn any python object into a finite-state automaton which changes from one State to another when initiated by a triggering event.


A finite-state machine is defined by a list of its states, and the triggering condition for each transition. pystatemachine offers an event decorator for a classes’ bound methods, a State class to define the finite-state machine’s states, and a acts_as_state_machine decorator for turning any python (new- or old-style) class into a finite-state machine. By default, any event-decorated method may raise errors. Optionally, a transition_failure_handler decorator turns any class method into a failure handler which gets invoked when an event-decorated method raises an error.


Following, a turnstile is modeled.

An example of a very simple mechanism that can be modeled by a state machine is a turnstile. A turnstile is a gate with three rotating arms at waist height, one across the entryway. Initially the arms are locked, barring the entry, preventing customers from passing through. Depositing a coin or token in a slot on the turnstile unlocks the arms, allowing a single customer to push through. After the customer passes through, the arms are locked again until another coin is inserted. - from [Wikipedia] (
class Turnstile(object):
    locked = State('locked', initial=True)
    unlocked = State('unlocked')

    @event(from_states=(locked, unlocked), to_state=unlocked)
    def coin(self):
        assert random.random() > .5, 'failing for demonstration purposes, only ..'
        print('*blingbling* .. unlocked!')

    @event(from_states=(locked, unlocked), to_state=locked)
    def push(self):
        print('*push* .. locked!')

    def turnstile_malfunction(self, method, from_state, to_state, error):
        print('state transition from {} to {} failed. Reason: {2}'.format(from_state, to_state, error))

    def before_turnstile_malfunction(self, method, from_state, to_state, error):
        print('before state transition failure handler ..')

import random

turnstile = Turnstile()
for _ in range(10):
    handler = random.choice([turnstile.coin, turnstile.push])



  • exceptions in an event-decorated function are now reraised when no transition failure handler was registered


  • added a decorator for registering a class’ method as exception handler when an ‘event’-decorated method fails. multiple methods may be registered as transition failure handler: they are invoked in the order given by the optional ‘calling_sequence’ keyword


  • first public release


pystatemachine is available under MIT License.


You can download


git clone

Release History

This version
History Node


History Node


History Node


Download Files

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

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(9.8 kB) Copy SHA256 Hash SHA256
Source None Apr 14, 2015

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers