Change-Id: Ic791d14b00503c4eaa26f8e83f8197f62a135436
5.2 KiB
Creating/adopting automaton
https://blueprints.launchpad.net/oslo.utils/+spec/adopt-automaton
The goal of this library would be to provide a well documented state machine classes/utilities that start off with the a basic set and can expand into a larger set as time goes on. The state machine pattern (or the implemented variation there-of) is a commonly used pattern and has a multitude of various usages.
Some of the current usages for it (that are being actively pursued):
- Provided state & transition validation for ironic.
- Providing state & transition validation & running/scheduling/analysis of the execution of taskflow engines.
The code for this library was extracted from taskflow and has been
copied into ironic and appears to be a key part of that projects states
work where it is now serving a useful purpose there; so I would consider
the API mostly stable (ironic is not currently using the FSM runner
properties while taskflow would be/is). The code/mini-library was
recently split off into https://github.com/harlowja/automaton
where it has been developed and isolated (the tests extracted for
example, a setup.py
added and pbr integrated...)
and it has travis-ci running
against it for testing integration (this would no longer be needed as
the openstackci serves a similar/equivalent purpose).
Library Name
automaton
Contents
automaton/__init__.py
automaton/exceptions.py
automaton/machines.py
- This is the main file that contains a finite state machine and a hierarchical state machine and associated run classes that can be used to run the state machines until they terminate; this usage of these runners is optional and is not necessary to use the machines for state and transition processing and/or validation.
For those wondering what a hierarchical state machine is the following can be referred to about it (the concepts are similar to what is described in the following slide-set).
Early Adopters
- Taskflow
- Ironic
- Others?
Public API
Currently the machine public API is the following:
FiniteMachine
- runner (read-only property)
- default_start_state (read/write property)
- current_state (read-only property)
- terminated (read-only property)
- add_state(state, terminal=False, on_enter=None, on_exit=None)
- add_reaction(state, event, reaction, *args, **kwargs)
- add_transition(start, end, event)
- process_event(event) -- main function/method!!
- initialize(start_state=None)
- copy(shallow=False, unfreeze=False)
- freeze()
- frozen (read/write property)
- states (read-only property)
- events (read-only property)
- pformat(sort=True, empty='.')
HierarchicalFiniteMachine(FiniteMachine)
- runner (read-only property)
- add_state(state, terminal=False,
on_enter=None, on_exit=None, machine=None)
The runners of each state machine have the following public API:
run(event, initialize=True)
run_iter(event, initialize=True)
Further API documentation (that is likely more readable and better commented) can be found at:
https://github.com/harlowja/automaton
Or from the live taskflow docs (that are using a slightly older version of the machines, minus a couple API adjustments; nothing major changed though):
http://docs.openstack.org/developer/taskflow/types.html#module-taskflow.types.fsm
Implementation
Assignee(s)
Primary assignee:
- Harlowja
Other contributors:
- You?
Primary maintainer
Primary maintainer:
- Harlowja (until further notice).
Other contributors:
- Praneshp (@yahoo)
- You?
Security Contact
Security Contact: harlowja
Milestones
Target Milestone for completion: liberty-1
Work Items
- Create launchpad project
- Change owner of Launchpad project (make it part of the Oslo projectgroup)
- Give openstackci Owner permissions on PyPI
- Create Initial Repository
- Make the library do something
- Update the README.rst
- Publish git repo
- Oslo team review new repository
- Infra project configuration
- Update Gerrit Groups and ACLs
- openstack-infra/devstack-gate adjustments
- openstack/requirements projects.txt adjustments
- Update project list on docs.openstack.org
- Tag a release
- Profit!
Adoption Notes
N/A
Dependencies
Requirements
- python 2.6 --> 3.4 (and beyond!)
- ordereddict (only needed on python 2.6)
- pbr
- prettytable
- six
Note
All of the currently planned dependencies are in the requirements repository.
References
N/A
Note
This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode