Python Event Driven System
Python Event Driven System<nav class="contents local" id="table-of-contents" role="doc-toc">
Table of contents
This package provides a means to efficiently write finite state machines (FSM) by hand. The focus was to make the API as simple as possible since no GUI tools are included to define a FSM.
PyEDS can be installed using the standard Python tool pip with
pip install pyeds
The easiest way to install PyEDS from source is to use setup.py script which uses setuptools. For complete documentation about this script please refer to setuptools manual.
To install from source issue the following command:
python setup.py install
Code documentation is bundled together with the source. The documentation scripts use Sphinx to generate documents.
To generate HTML documentation:
cd doc make html
This will create HTML documents in doc/_build/html directory.
The documentation can be accessed via Python interpreter, too.
>>> import pyeds >>> help(pyeds.fsm)
The basic routine to create a state machine is the following:
Declare a FSM class
Declare all state classes
Instantiate FSM class
FSM class is the entry point of a FSM which is used to receive events (see below) and do the transitions between states. Each FSM must declare it’s own class which is a subclass of StateMachine. The simplest way is to just declare an empty class which inherits the class StateMachine:
from pyeds import fsm class MyFsm(fsm.StateMachine): pass
Each state is represented by different class. Every method in that class may handle one particular event. To declare the state, a class must be decorated with DeclareState decorator which require state machine as an argument. This decorator binds the state class to the specific FSM class. Also, the new state class must be a subclass of State class:
@fsm.DeclareState(MyFsm) class MyState(fsm.State): pass
Declare a new class per state.
To instantiate the FSM class do the following:
my_fsm = MyFsm()
After object initialization the FSM is put into running state.
An event is a notable occurrence at a particular point in time. Events can, but do not necessarily, cause state transitions from one state to another in state machines.
An event can have associated parameters, allowing the event to convey not only the occurrence but also quantitative information about the occurrence.
An event is the only means of communication between state machines. Each event carries name. Based on the event name a handler will be called from current state class which has the same name.
An event in PyEDS is instanced using class Event.
The associated parameters with an event are:
Name of the event: this is a string containing event name.
Owner of event: specifies which state machine has generated this event.
To generate a new event just instantiate Event class with event name as parameter:
new_event = fsm.Event('my_special_event')
Alternative way is to first declare a new event class and instantiate this derived class:
class MySpecialEvent(fsm.Event): pass new_event = MySpecialEvent() # This event is implicitly # called 'my_special_event'
In this case base Event class will implicitly take the name of the class as own name. This can be overridden by calling the super constructor:
# This event has the exact same name as the above one class DerivedEvent(fsm.Event): def __init__(self): super().__init__('my_special_event')
When an event is created and sent to a state machine it’s name is used to decide which method in current state instance should be invoked. The state machine takes the name of the event, it prepends text on_ to the name string and then it looks up to event handler method.
Example: If an event named toggle is created and sent to a state machine, the target state machine will lookup for a method named on_toggle in the current state instance.
Since the event name directly impacts which state instance method will be called the name of events must follow the Python identifier naming rules; please refer to https://docs.python.org/3.3/reference/lexical_analysis.html#identifiers for more details.
ok_event = fsm.Event('some_event_with_long_name') bad_event = fsm.Event('you cannot use spaces, @, $ and % here')
Timers are used to generate time events:
After: Means an event will be generated after elapsed time.
Every: Means an event will be generated every period of time.
To generate the events use After and Every objects:
@fsm.DeclareState(BlinkyFsm) class Initialization(fsm.State): def on_init(self): self.blinking = fsm.Every(1.0, 'blink') return StateOn
This line will generate an event named blink every 1.0 seconds. To stop the timer use:
@fsm.DeclareState(BlinkyFsm) class StateOn(fsm.State): def on_entry(self): print('on') self.blinking.cancel()
Second approach to cancel a running timer is by using event timer attribute. When a timer generates an event it will automatically create event attribute called timer. With this attribute you can also access the originating timer through event. To stop the timer through an event see the example below:
@fsm.DeclareState(BlinkyFsm) class StateOn(fsm.State): def on_blink(self, event): event.timer.cancel() # Stop the originating timer return StateOff
A state is a description of the status of a system that is waiting to execute a transition.
A finite-state machine (FSM) is a mathematical model of computation. It is an abstract machine that can be in exactly one of a finite number of states at any given time. The FSM can change from one state to another in response to some external events; the change from one state to another is called a state transition. An FSM is defined by a list of its states, its initial state, and the conditions for each transition.
Switching from one state to another is called state transition. A transition is a set of actions to be executed when a condition is fulfilled or when an event is received.
Transitions are started by returning target state class in an event handler.
def on_some_event(self, event): do_some_stuff() return SomeOtherState # Note: return a class object, not instance object
Please, refer to Wikipedia article for further explanation:
Source is available at github:
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.