NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #2549 most downloaded on PyPI
A lightweight, object-oriented Python state machine implementation with many extensions.
Last release 1 years ago
02 Jul 2025
Release timing varies
gaps range from 4 weeks to 1.7 years
Nearly every release is documented
notes for 47 of 50 stable releases
Nothing withdrawn
no release was ever pulled
12 years old
50 releases · first in 2014
Release 0.9.3 is a minor release and contains mostly bugfixes and some typing improvements.
Release 0.9.3 is a minor release and contains mostly bugfixes and some typing improvements.
AsyncTimeout did not stop execution (thanks @matt3o)Transition instances can be passed to Machine.__init__ and/or Machine.add_transition(s) (thanks @antonio-antuan)NestedState, FunctionWrapper was not properly initialized (thanks @drpjm)Machine.dispatch should not short-circuit when a model returns False (thanks @Joshuaalbert)transitions.core.(Async)TransitionConfigDict a TypedDict which can be used to spot parameter errors during static analysisMachine.add_transitions and Machine.__init__ expect a Sequence of configurations for transitions nowasyncio extensionFeature: Add Mermaid diagram backend that returns a mermaid diagram as a string. use_pygraphviz is deprecated in favour for graph_engine which may be…
One column per quarter.
Release 0.9.2 is a minor release and contains a new mermaid diagram backend, a new model decoration mode for easier development with types and some more features and bugfixes.
HierarchicalMachine is passed to add_state (thanks @e0lithic)may_<trigger> check all parallel states in processing order (thanks @spearsear)HSM.is_state works with parallel states nowmodel_override to Machine constructor to determine the mode of operation. With model_override=Fale (default), transitions will not override already defined methods on a model just as it did before. For workflows relying on typing, model_override=True will override methods already defined on the model and only those (!). This allows to control which convenience methods shall be assigned to the model and keeps the statically 'assumed' model in sync with its runtime counterpart. Since defining each and every method manually is rather tiresome, transitions.experimental.utils.generate_base_model features a way to convert a machine configuration into a BaseClass with all convenience functions and callbacks.transitions.experimental.utils.{add_transitions, event, with_model_definitions, transition} to define trigger methods in a class model for more convenient type checking. add_transitions can be used as a function decorator and is stackable. event returns a placeholder object for attribute assigment. add_transitions and event have the same signature and support transition definition like machine constructors. The function transition can used for better typing and returns a dictionary that can be passed to the utility functions but also to a machine constructor. add_transitions and event require a machine decorated with with_model_definitions. Decorating a machine with_model_definitions implies model_override=True.may_trigger to models to check whether transitions can be conducted by trigger name.use_pygraphviz is deprecated in favour for graph_engine which may be pygraphviz (default), graphviz or mermaid.Release 0.9.1 is a minor release and contains several bugfixes and some (typing) improvements. This release also introduces on_final callbacks on mach
Release 0.9.1 is a minor release and contains several bugfixes and some (typing) improvements. This release also introduces on_final callbacks on machines (as well as NestedState) and final flags for states.
EventData context in 'may' check (thanks @msclock)Exception is not broad enough and does not catch asyncio.CancelledError or KeyboardInterrupt; use BaseException instead (thanks @e0lithic and @ofacklam)on_final to Machine and NestedState constructor and final to State. Callbacks passed to on_final will be executed when a State with final=True is entered or all children of a parallel state are final.Machine.on_exception in may_<trigger> as well (thanks @match1)GraphMachine and HiearachicalMachine (thanks @drpjm)GraphMachine--strict mypy flag for transitions type checks (not tests though)Release 0.9.0 is a major release and contains improvements to ease development, adds some new features and removes the legacy hierarchical machine:
Release 0.9.0 is a major release and contains improvements to ease development, adds some new features and removes the legacy hierarchical machine:
HierarchicalMachine from the packageGraphMachine (thanks @betaboon)HierachicalMachine (thanks @jankrejci)graphviz when pygraphviz was not installed (thanks @FridjofAmundsen)on_timeout callback resolution when timeout had been initialized with timeout=0 (thanks @Rysbai)GraphSupport was not correctly aligned when show_attributes=True (thanks @spagh-eddie)may transition check to transitions (thanks @artofhuman)MachineError in on_exception callbacks (thanks @kpihus)mypy to test workflowRetry state to supported state stereotypes (thanks @rgov)Machine._identify_callback has been converted to instance method from class methodLockedMachine._get_qualified_state_name has been converted to instance method from static method_super workaround related to dill (see https://github.com/pytransitions/transitions/issues/236)Release 0.8.11 is the last 0.8 release and contains fixes for Python 3.10 compatibility issues:
Release 0.8.11 is the last 0.8 release and contains fixes for Python 3.10 compatibility issues:
Release 0.8.10 is a minor release and contains two bug fixes for the HSM extension and changes how the 'self' literal string is handled.
Release 0.8.10 is a minor release and contains two bug fixes for the HSM extension and changes how the 'self' literal string is handled.
Machine) has been replaced by the class variable Machine.self_literal = 'self'. Machine now performs an identity check (instead of a value check) with mod is self.self_literal to determine whether it should act as a model. While 'self' should still work when passed to the model parameter, we encourage using Machine.self_literal from now on. This was done to enable easier override of Machine.__eq__ in subclasses (thanks @VKSolovev).HierarchicalMachine.prefix_path to resolve global state names since the HSM stack is not reliable when queued=True (thanks @jankrejci).HSM source states were exited even though they are parents of the destination state (thanks @wes-public-apps).Release 0.8.9 is a minor release and contains a bugfix for HSM, a feature for GraphSupport and changes internal cache handling:
Release 0.8.9 is a minor release and contains a bugfix for HSM, a feature for GraphSupport and changes internal cache handling:
NestedEvent now wraps the machine's scope into partials passed to HierarchicalMachine._process. This prevents queued transitions from losing their scope.(A)Graph.draw function (object returned by GraphMachine.get_graph()) can be passed a file/stream object as first parameter or None. The later will result in draw returning a binary string. (thanks @Blindfreddy).LockedMachine, AsyncMachine and GraphMachine. This might influence pickling (thanks @thedrow).Release 0.8.8 is a minor release and contains a bugfix and several new or improved features:
Release 0.8.8 is a minor release and contains a bugfix and several new or improved features:
AsyncMachine does not remove models when remove_models is called (thanks @Plazas87)try/except for finalize callbacks in Machine and HierachicalMachine. Thus, errors occurring in finalize callbacks will be suppressed and only the original error will be raised.MarkupMachine.format_references to tweak reference formatting (thanks @StephenCarboni)Machine.on_exception to handle raised exceptions in callbacks (thanks @thedrow)Machine.get_triggers now supports State and Enum as arguments (thanks @luup2k)NestedState and HierachicalMachine.add_states now accept (lists of) states and enums as initial parameterRelease 0.8.7 is a minor release and contains bugfixes and new features:
Release 0.8.7 is a minor release and contains bugfixes and new features:
HierarchicalMachine can also use states as a keyword to define substates. If children and states are present, only children will be considered.HierarchicalMachine with custom separator now adds is_state partials for nested states (e.g. is_C.s3.a()) to models (thanks @alterscape)model_attribute consistently in AsyncMachine (thanks @thedrow)pygraphviz.Agraph in diagrams_pygraphviz are now copied by transitions since AGraph.copy as of version 1.6 does not close temporary files appropriatelyHierarchicalMachine now checks whether state_cls, event_cls and transition_cls have been subclassed from nested base classes (e.g. NestedState) to prevent hard to debug inheritance errorsRelease 0.8.6 is a minor release and contains bugfixes and new features:
Release 0.8.6 is a minor release and contains bugfixes and new features:
HierarchicalMachine.add_states will raise a ValueError when an Enum name contains the currently used NestedState.separator.NestedState._scope when enter/exit callbacks raise an exception (thanks @m986883511)HierarchicalMachine._get_trigger which is bound to model.trigger raise a MachineError for invalid events and AttributeError for unknown events (thanks @hsharrison)HierarchicalMachine.has_trigger to determine whether an event is valid for an HSMAsyncMachine features an event queue dictionary for individual models when queued='model' (thanks @jekel)Machine.remove_model will now also remove model events from the event queue when queued=TrueMachine.get_transitions and its HSM counterpart now accept Enum and State for source and dest (thanks @thedrow)Release 0.8.5 is a minor release and contains bugfixes:
Release 0.8.5 is a minor release and contains bugfixes:
AsyncMachine.switch_model_context is expected to be async now for easier integration of async code during model switch.GraphSupport threw an exception when initial was set to a nested or parallel state (thanks @nickvazztau)Release 0.8.4 is a minor release and contains bugfixes as well as new features:
Release 0.8.4 is a minor release and contains bugfixes as well as new features:
AsyncMachine.protected_tasks list which can be used to prevent transitions to cancel certain tasks.HierarchicalMachine now accepts substates ('A_1_c') and parallel states (['A', 'B']) as initial parameterRelease 0.8.3 is a minor release and contains several bugfixes mostly related to HierarchicalStateMachine:
Release 0.8.3 is a minor release and contains several bugfixes mostly related to HierarchicalStateMachine:
is_<model_attribute>_<state_name> instead of is_<state_name> when model_attribute != "state" to enable multiple versions of such convenience functions. A warning will be raised when is_<state_name> is used. (thanks @artofhuman)to_<state_name>) will be assigned as to_<model_attribute>_<state_name>. to_<state_name> will work as before but raise a warning until version 0.9.0.allow_substates did not consider enum stateschildren with initial parameterTransitionGraphSupport (thanks @badiku)State.enter/exit debug message emitted when callbacks have been processed.before_state_change/before and after/after_state_change in AsyncMachine (thanks @tzoiker and @vishes-shell)Graph.get_graph() did not consider enum states when show_roi=True (thank @termim)Release 0.8.2 is a minor release and contains several bugfixes and improvements:
Release 0.8.2 is a minor release and contains several bugfixes and improvements:
graphviz package_check_event_result failed when model was in parallel statedest=None in Machine.add_transition (not just falsy) for internal transitions (thanks @Pathfinder216)Model.trigger now considers the machine's and current state's ignore_invalid_triggers attribute and can be called with non-existing events (thanks @potens1)transitions.extensions.asyncio.AsyncTimeout as a state decorator to avoid threads used in transitions.extensions.state.Timeout (thanks @potens1)transitions can now be tested online at mybinder.orgRelease 0.8.1 is a minor release of HSM improvements and bugfixes in the diagram and async extension
Release 0.8.1 is a minor release of HSM improvements and bugfixes in the diagram and async extension
HierarchicalAsync(Graph)MachineHierarchicalMachine (thanks @thedrow)Enum (thanks @kbinpgh)HierarchicalMachine (thanks @xiaohuihui1024)xdist for parallel testing with pytest (thanks @thedrow)Release 0.8.0 is a major release and introduces asyncio support for Python 3.7+, parallel state support and some bugfixes
Release 0.8.0 is a major release and introduces asyncio support for Python 3.7+, parallel state support and some bugfixes
HierarchicalMachine has been rewritten to support parallel states. Please have a look at the ReadMe.md to check what has changed.
transitions.extensions.nesting_legacy for nowAsyncMachine (see discussion #259); note that async HSMs are not yet supportedEnum into strings in MarkupMachine when necessaryMachine.add_ordered_transitions to be called without the initial state (thanks @mkaranki and @facundofc)GraphMachine now attempts to fall back to graphviz when importing pygraphviz failsRelease 0.7.2 is a minor release and contains bugfixes and and a new feature:
Release 0.7.2 is a minor release and contains bugfixes and and a new feature:
Release 0.7.1 is a minor release and contains several documentation improvements and a new feature:
Release 0.7.1 is a minor release and contains several documentation improvements and a new feature:
enum Python 2.7: enum34) support (thanks @artofhuman and @justinttl)nosetests with pytest (thanks @artofhuman)add_ordered_transitions documentation in Readme.mdexamples/Frequently asked questions.ipynblong_description in setup.py (thanks @artofhuman)Release 0.7.0 is a major release with fundamental changes to the diagram extension. It also introduces an intermediate MarkupMachine which can be used
Release 0.7.0 is a major release with fundamental changes to the diagram extension. It also introduces an intermediate MarkupMachine which can be used to transfer and (re-)initialize machine configurations.
MarkupMachine can be used to retrieve a Machine's dictionary representation
GraphMachine uses this representation for Graphs now and does not rely on Machine attributes any longerState.ignore_invalid_triggers changed to None. If it is not explicitly set, the Machine's value is used instead.pygraphviz and graphviz for the creation of diagrams. Currently, GraphMachine will check for pygraphviz first and fall back to graphviz. To use graphviz directly pass use_pygraphiv=False to the constructor of GraphMachineGraphMachine's attributes machine_attributes and style_attributes to adjust it to your needs.get_graph was not assigned to models added during machine runtimeRelease 0.6.9 is a minor release and contains two bugfixes:
Release 0.6.9 is a minor release and contains two bugfixes:
state.Error did not call parent's enter method (thanks @potens1)Release 0.6.8 is a minor release and contains a critical bugfix:
Release 0.6.8 is a minor release and contains a critical bugfix:
Readme.md in setup.py causes a UnicodeDecodeError in non-UTF8-locale environments (thanks @jodal)Release 0.6.7 is identical to 0.6.6. A release had been necessary due to #294 related to PyPI.
Release 0.6.7 is identical to 0.6.6. A release had been necessary due to #294 related to PyPI.
Release 0.6.6 is a minor release and contains several bugfixes and new features:
Release 0.6.6 is a minor release and contains several bugfixes and new features:
HierarchicalMachine now considers the initial state of NestedState instances/names passed to initial.HierarchicalMachine used to ignore children when NestedStates were added to the machine.TimeoutState (thanks @Synss)Machine.resolve_callable(func, event_data) to enable customization of callback definitions (thanks @ollamh and @paulbovbel)dest=None (thanks @maueki)Machine.dispatch to trigger events on all models assigned to MachineRelease 0.6.5 is a minor release and contains a new feature and a bugfix:
Release 0.6.5 is a minor release and contains a new feature and a bugfix:
HierarchicalMachine will now reuse the machine's initial state. Passing initial: False overrides this (thanks @mrjogo).GraphMashine were not picklable in the past due to graph property. Graphs for each model are now stored in GraphMachine.model_graphs (thanks @ansumanm).Release 0.6.4 is a minor release and contains a new feature and two bug fixes related to HierachicalMachine:
Release 0.6.4 is a minor release and contains a new feature and two bug fixes related to HierachicalMachine:
initial has not been passed to super in HierachicalMachine.add_model (thanks to @illes).HierarchicalMachine.add_states now supports keyword parent to be a NestedState or a string.NestedState has not been exited correctly during reflexive triggering (thanks to @hrsmanian).Release 0.6.3 is a minor release and contains a new feature and two bug fixes:
Release 0.6.3 is a minor release and contains a new feature and two bug fixes:
Machine.add_ordered_transitions changed states' order if initial is not the first or last state (thanks to @janekbaraniewski).HierarchicalMachine.to to to_state to prevent warnings when HSM is used as a model.Machine.get_transitions to get a list of transitions for alteration (thanks to @Synss).Release 0.6.2 is a minor release and contains new features and bug fixes but also several internal changes:
Release 0.6.2 is a minor release and contains new features and bug fixes but also several internal changes:
appveyor.yml for Windows testing; However, Windows testing is disabled due to #258prep_ordered_arg is now protected in corelogger instances to _LOGGER to comply with protected module constant naming standardstraverse is now protected in HierarchicalMachineDiagram since it did not add functionality to diagramsadd_state or add_transition to keep the base class parameters instead of *args and **kwargsif len(x) > 0: checks to if x: as suggested by the static code analysis to make use of falsy empty lists/strings.Release 0.6.1 is a minor release and contains new features as well as bug fixes:
Release 0.6.1 is a minor release and contains new features as well as bug fixes:
Transition and StateMachine.remove_transitions converted defaultdict into dict (thanks @Synss)HierarchicalStateMachine's copy procedure used to cause issues with function callbacks and object references (thanks @Grey-Bit)Machine.id to Machine.name to be consistent with the constructor parameter nameMachine.add_transitions for adding multiple transitions at once (thanks @Synss)Release 0.6.0 is a major release and introduces new state features and bug fixes:
Release 0.6.0 is a major release and introduces new state features and bug fixes:
add_state_features convenience decorator supports creation of custom statesTags makes states taggableError checks for error states (not accepted states that cannot be left); subclass of TagsVolatile enables scoped/temporary state objects to handle context parametersadd_self from Machine constructorpygraphviz is now optional; use pip install transitions[diagrams] to install iton_enter_<state> scheme (thanks to @termim)Release 0.5.3 is a minor release and contains several bug fixes:
Release 0.5.3 is a minor release and contains several bug fixes:
LockedMachine as a model prevented correct addition of on_enter/exit_<state> (thanks to @kr2)EventData.transition caused AttributeError in EventData.__repr__ (thanks to @kunalbhagawati)initial parameter of Machine constructor had not been processed properly (thanks @mathiasimmer)Release 0.5.2 is a minor release and contains a bug fix:
Release 0.5.2 is a minor release and contains a bug fix:
LICENSE to be installed to root of installation pathRelease 0.5.1 is a minor release and contains new features and bug fixes:
Release 0.5.1 is a minor release and contains new features and bug fixes:
wildcard_same) and all (wildcard_all) destinations are Machine class variables now which can be altered if necessary.prepare and finalized had not been called for HierarchicalMachines (thanks to @booware)Introduced deprecation warnings for upcoming changes concerning Machine keywords model and add_self
Release 0.5.0 is a major release:
MachineError is now limited to internal error and has been replaced by AttributeError and ValueError where applicable (thanks to @ankostis)add_self; model=None will add NO model starting from next major release; use model='self' instead.Machine keywords model and add_selfMachine.remove_transition (thanks to @PaleNeutron)Machine._create_state for easier subclassing of statesLockedMachine now supports custom context managers for each model (thanks to @paulbovbel)Machine.before/after_state_change can now be altered dynamically (thanks to @peendebak)Machine.add_ordered_transitions now supports prepare, conditons, unless, before and after (thanks to @aforren1)prepare_event and finalize_event keywords to handle transitions globally (thanks to @ankostis)show_auto_transitions keyword for GraphMachine.__init__ (default False); if enabled, show auto transitions in graphshow_roi keyword for GraphMachine._get_graph (default False); if True, show only reachable states in retrieved graphLockedMachine performance by removing recursive lockingtransitions.extensions.nesting.AGraph has been split up into Graph and NestedGraph for easier maintenanceRLock in nestingRelease 0.4.3 is a minor release and contains bug fixes and several new features:
Release 0.4.3 is a minor release and contains bug fixes and several new features:
Machine.add_model (thanks to @paulbovbel)State is passed to Machine.add_transition, it will check if the state (and not just the name) is known to the machineRelease 0.4.2 contains several new features and bugfixes:
Release 0.4.2 contains several new features and bugfixes:
initial keyword for nested states to automatically enter a childMachine.trigger method to trigger events by name (thanks to @IwanLD)Transition.execute and Machine.__init__ have been reassigned to DEBUG log level (thanks to @ankostis)Machine.get_triggers method to return all valid transitions from (a) certain state(s) (thanks to @limdauto and @guilhermecgs)Release 0.4.1 is a minor release containing bug fixes, minor API changes, and community feedback:
Release 0.4.1 is a minor release containing bug fixes, minor API changes, and community feedback:
async is renamed to queued since it describes the mechanism better
HierarchicalStateMachine.is_state now provides allow_substates as an optional argument(thanks to @jonathanunderwood)
Machine can now be used in scenarios where multiple inheritance is required (thanks to @jonathanunderwood)
Adds support for tox (thanks to @medecau and @aisbaa)
Bug fixes:
Minor PEP8 fixes (thanks to @medecau)
Release 0.4 is a major release that includes several new features:
Release 0.4 is a major release that includes several new features:
async Machine keyword allows queueing of transitions (thanks to @khigia)name Machine keyword customizes transitions logger output for easier debugging of multiple running instancesprepare Transition keyword for callbacks before any 'conditions' are checked (thanks to @TheMysteriousX)show_conditions GraphSupport keyword adds condition checks to dot graph edges (thanks to @khigia)Mostly a bug fix release. Changes include:
Mostly a bug fix release. Changes include:
Release 0.3 includes a number of new features (nesting, multithreading, and graphing) as well as bug fixes and minor improvements:
Release 0.3 includes a number of new features (nesting, multithreading, and graphing) as well as bug fixes and minor improvements:
Enabled pickling in Python 3.4 (and in < 3.4 with the dill module)
README improvements, added TOC, and typo fixes
Fixed import bug that prevented dependency installation at setup
Added rudimentary logging for key transition and state change events
Added ability to suppress invalid trigger calls
Automatic detection of predefined state callbacks
Added 'unless' argument to transitions that mirrors 'conditions'
Added automatic to\_{state}() methods
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →