python-statemachine 2.6.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

python_statemachine-3.1.0.dist-info/METADATA

@@ -0,0 +1,421 @@
+Metadata-Version: 2.4
+Name: python-statemachine
+Version: 3.1.0
+Summary: Python Finite State Machines made easy.
+Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
+Author-email: Fernando Macedo <fgmacedo@gmail.com>
+Maintainer-email: Fernando Macedo <fgmacedo@gmail.com>
+License: MIT License
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: diagrams
+Requires-Dist: pydot>=4.0.1; extra == 'diagrams'
+Description-Content-Type: text/markdown
+
+# Python StateMachine
+
+[![pypi](https://img.shields.io/pypi/v/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
+[![downloads total](https://static.pepy.tech/badge/python-statemachine)](https://pepy.tech/project/python-statemachine)
+[![downloads](https://img.shields.io/pypi/dm/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
+[![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/develop/graph/badge.svg)](https://codecov.io/gh/fgmacedo/python-statemachine)
+[![Documentation Status](https://readthedocs.org/projects/python-statemachine/badge/?version=latest)](https://python-statemachine.readthedocs.io/en/latest/?badge=latest)
+[![GitHub commits since last release (main)](https://img.shields.io/github/commits-since/fgmacedo/python-statemachine/main/develop)](https://github.com/fgmacedo/python-statemachine/compare/main...develop)
+
+Expressive [statecharts](https://statecharts.dev/) and [FSMs](https://en.wikipedia.org/wiki/Finite-state_machine) for modern Python.
+
+<div align="center">
+
+![](https://github.com/fgmacedo/python-statemachine/blob/develop/docs/images/python-statemachine.png?raw=true)
+
+</div>
+
+Welcome to python-statemachine, an intuitive and powerful state machine library designed for a
+great developer experience. Define flat state machines or full statecharts with compound states,
+parallel regions, and history — all with a clean, _pythonic_, declarative API that works in both
+sync and async Python codebases.
+
+
+## Quick start
+
+```py
+>>> from statemachine import StateChart, State
+
+>>> class TrafficLightMachine(StateChart):
+...     "A traffic light machine"
+...     green = State(initial=True)
+...     yellow = State()
+...     red = State()
+...
+...     cycle = (
+...         green.to(yellow)
+...         | yellow.to(red)
+...         | red.to(green)
+...     )
+...
+...     def before_cycle(self, event: str, source: State, target: State):
+...         return f"Running {event} from {source.id} to {target.id}"
+...
+...     def on_enter_red(self):
+...         print("Don't move.")
+...
+...     def on_exit_red(self):
+...         print("Go ahead!")
+
+```
+
+Create an instance and send events:
+
+```py
+>>> sm = TrafficLightMachine()
+>>> sm.send("cycle")
+'Running cycle from green to yellow'
+
+>>> sm.send("cycle")
+Don't move.
+'Running cycle from yellow to red'
+
+>>> sm.send("cycle")
+Go ahead!
+'Running cycle from red to green'
+
+```
+
+Check which states are active:
+
+```py
+>>> sm.configuration
+OrderedSet([State('Green', id='green', value='green', initial=True, final=False, parallel=False)])
+
+>>> sm.green.is_active
+True
+
+```
+
+Generate a diagram or get a text representation with f-strings:
+
+```py
+>>> print(f"{sm:md}")
+| State  | Event | Guard | Target |
+| ------ | ----- | ----- | ------ |
+| Green  | Cycle |       | Yellow |
+| Yellow | Cycle |       | Red    |
+| Red    | Cycle |       | Green  |
+<BLANKLINE>
+
+```
+
+```python
+sm._graph().write_png("traffic_light.png")
+```
+
+![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/develop/docs/images/readme_trafficlightmachine.png)
+
+Parameters are injected into callbacks automatically — the library inspects the
+signature and provides only the arguments each callback needs:
+
+```py
+>>> sm.send("cycle")
+'Running cycle from green to yellow'
+
+```
+
+
+## Guards and conditional transitions
+
+Use `cond=` and `unless=` to add guards. When multiple transitions share the same
+event, declaration order determines priority:
+
+```py
+>>> from statemachine import StateChart, State
+
+>>> class ApprovalWorkflow(StateChart):
+...     pending = State(initial=True)
+...     approved = State(final=True)
+...     rejected = State(final=True)
+...
+...     review = (
+...         pending.to(approved, cond="is_valid")
+...         | pending.to(rejected)
+...     )
+...
+...     def is_valid(self, score: int = 0):
+...         return score >= 70
+
+>>> sm = ApprovalWorkflow()
+>>> sm.send("review", score=50)
+>>> sm.rejected.is_active
+True
+
+>>> sm = ApprovalWorkflow()
+>>> sm.send("review", score=85)
+>>> sm.approved.is_active
+True
+
+```
+
+The first transition whose guard passes wins. When `score < 70`, `is_valid` returns
+`False` so the second transition (no guard — always matches) fires instead.
+
+
+## Compound states — hierarchy
+
+Break complex behavior into hierarchical levels with `State.Compound`. Entering a
+compound activates both the parent and its `initial` child. Exiting removes the
+parent and all descendants:
+
+```py
+>>> from statemachine import StateChart, State
+
+>>> class DocumentWorkflow(StateChart):
+...     class editing(State.Compound):
+...         draft = State(initial=True)
+...         review = State()
+...         submit = draft.to(review)
+...         revise = review.to(draft)
+...
+...     published = State(final=True)
+...     approve = editing.to(published)
+
+>>> sm = DocumentWorkflow()
+>>> set(sm.configuration_values) == {"editing", "draft"}
+True
+
+>>> sm.send("submit")
+>>> "review" in sm.configuration_values
+True
+
+>>> sm.send("approve")
+>>> set(sm.configuration_values) == {"published"}
+True
+
+```
+
+
+## Parallel states — concurrency
+
+`State.Parallel` activates all child regions simultaneously. Events in one
+region don't affect others. A `done.state` event fires only when **all**
+regions reach a final state:
+
+```py
+>>> from statemachine import StateChart, State
+
+>>> class DeployPipeline(StateChart):
+...     class deploy(State.Parallel):
+...         class build(State.Compound):
+...             compiling = State(initial=True)
+...             compiled = State(final=True)
+...             finish_build = compiling.to(compiled)
+...         class tests(State.Compound):
+...             running = State(initial=True)
+...             passed = State(final=True)
+...             finish_tests = running.to(passed)
+...     released = State(final=True)
+...     done_state_deploy = deploy.to(released)
+
+>>> sm = DeployPipeline()
+>>> "compiling" in sm.configuration_values and "running" in sm.configuration_values
+True
+
+>>> sm.send("finish_build")
+>>> "compiled" in sm.configuration_values and "running" in sm.configuration_values
+True
+
+>>> sm.send("finish_tests")
+>>> set(sm.configuration_values) == {"released"}
+True
+
+```
+
+
+## History states
+
+`HistoryState()` records which child was active when a compound is exited.
+Re-entering via the history pseudo-state restores the previous child instead
+of starting from the initial one:
+
+```py
+>>> from statemachine import HistoryState, StateChart, State
+
+>>> class EditorWithHistory(StateChart):
+...     class editor(State.Compound):
+...         source = State(initial=True)
+...         visual = State()
+...         h = HistoryState()
+...         toggle = source.to(visual) | visual.to(source)
+...     settings = State()
+...     open_settings = editor.to(settings)
+...     back = settings.to(editor.h)
+
+>>> sm = EditorWithHistory()
+>>> sm.send("toggle")
+>>> "visual" in sm.configuration_values
+True
+
+>>> sm.send("open_settings")
+>>> sm.send("back")
+>>> "visual" in sm.configuration_values
+True
+
+```
+
+Use `HistoryState(type="deep")` for deep history that remembers the exact leaf
+state across nested compounds.
+
+
+## Eventless transitions
+
+Transitions without an event trigger fire automatically. With a guard, they
+fire after any event processing when the condition is met:
+
+```py
+>>> from statemachine import StateChart, State
+
+>>> class AutoCounter(StateChart):
+...     counting = State(initial=True)
+...     done = State(final=True)
+...
+...     counting.to(done, cond="limit_reached")
+...     increment = counting.to.itself(internal=True, on="do_increment")
+...
+...     count = 0
+...
+...     def do_increment(self):
+...         self.count += 1
+...     def limit_reached(self):
+...         return self.count >= 3
+
+>>> sm = AutoCounter()
+>>> sm.send("increment")
+>>> sm.send("increment")
+>>> "counting" in sm.configuration_values
+True
+
+>>> sm.send("increment")
+>>> "done" in sm.configuration_values
+True
+
+```
+
+
+## Error handling
+
+When using `StateChart`, runtime exceptions in callbacks are caught and
+turned into `error.execution` events. Define a transition for that event
+to handle errors within the state machine itself:
+
+```py
+>>> from statemachine import StateChart, State
+
+>>> class ResilientService(StateChart):
+...     running = State(initial=True)
+...     failed = State(final=True)
+...
+...     process = running.to(running, on="do_work")
+...     error_execution = running.to(failed)
+...
+...     def do_work(self):
+...         raise RuntimeError("something broke")
+
+>>> sm = ResilientService()
+>>> sm.send("process")
+>>> sm.failed.is_active
+True
+
+```
+
+
+## Async support
+
+Async callbacks just work — same API, no changes needed. The engine
+detects async callbacks and switches to the async engine automatically:
+
+```py
+>>> import asyncio
+>>> from statemachine import StateChart, State
+
+>>> class AsyncWorkflow(StateChart):
+...     idle = State(initial=True)
+...     done = State(final=True)
+...
+...     finish = idle.to(done)
+...
+...     async def on_finish(self):
+...         return 42
+
+>>> async def run():
+...     sm = AsyncWorkflow()
+...     result = await sm.finish()
+...     print(f"Result: {result}")
+...     print(sm.done.is_active)
+
+>>> asyncio.run(run())
+Result: 42
+True
+
+```
+
+
+## More features
+
+There's a lot more to explore:
+
+- **DoneData** on final states — pass structured data to `done.state` handlers
+- **Delayed events** — schedule events with `sm.send("event", delay=500)`
+- **`In(state)` conditions** — cross-region guards in parallel states
+- **`prepare_event`** callback — inject custom data into all callbacks
+- **Observer pattern** — register external listeners to watch events and state changes
+- **Django integration** — auto-discover state machines in Django apps with `MachineMixin`
+- **Diagram generation** — via f-strings (`f"{sm:mermaid}"`), CLI, Sphinx directive, or Jupyter
+- **Dictionary-based definitions** — create state machines from data structures
+- **Internationalization** — error messages in multiple languages
+
+Full documentation: https://python-statemachine.readthedocs.io
+
+
+## Installing
+
+```
+pip install python-statemachine
+```
+
+To generate diagrams, install with the `diagrams` extra (requires
+[Graphviz](https://graphviz.org/)):
+
+```
+pip install python-statemachine[diagrams]
+```
+
+
+## Contributing
+
+- If you found this project helpful, please consider giving it a star on GitHub.
+
+- **Contribute code**: If you would like to contribute code, please submit a pull
+request. For more information on how to contribute, please see our [contributing.md](contributing.md) file.
+
+- **Report bugs**: If you find any bugs, please report them by opening an issue
+  on our GitHub issue tracker.
+
+- **Suggest features**: If you have an idea for a new feature, or feel something is harder than it should be,
+  please let us know by opening an issue on our GitHub issue tracker.
+
+- **Documentation**: Help improve documentation by submitting pull requests.
+
+- **Promote the project**: Help spread the word by sharing on social media,
+  writing a blog post, or giving a talk about it. Tag me on Twitter
+  [@fgmacedo](https://twitter.com/fgmacedo) so I can share it too!

python_statemachine-3.1.0.dist-info/RECORD

@@ -0,0 +1,58 @@
+statemachine/__init__.py,sha256=ULem4I0OFrhvgXyaka9WLO8OJimg8LtFKKrfG1Zc7Rs,445
+statemachine/callbacks.py,sha256=mY_RAl86240vG2C94ij6AdD7CgsIM8mr0wvpSAMAPv0,14644
+statemachine/configuration.py,sha256=pt3Sq323bZKymnjQzLotqkNVkgqNHh3pmSIXLxk-obA,5453
+statemachine/dispatcher.py,sha256=xvA1Kf1xGQivHTpaGm_HC22vqAmE_tTm9LQwyVLRWLE,7841
+statemachine/event.py,sha256=d_Ky5ph30Os305BceN4x-rftZH-h8G1U5ei34-66lnI,7669
+statemachine/event_data.py,sha256=7_hoE0cp-0uW71Kk3erO3eYM6anTT5X3slGMcehIGIo,3111
+statemachine/events.py,sha256=11GyX8GYpsSwvW0v1b4zHUGhzKRoqNjQYtuDj8NvqOM,1212
+statemachine/exceptions.py,sha256=gXFvDsEtIxKdcGrRG9mwDgXqFQDXfw8v66_VXaQgGr4,1305
+statemachine/factory.py,sha256=HQc2Hn1irg96Rkygn2E21YAxFV5PRYiXYh4tTKVWBbc,14706
+statemachine/graph.py,sha256=r-8L7jXab1_VLtVu-Ig8bpe4Szo-r6WDFTdbfcepyZM,1981
+statemachine/i18n.py,sha256=NLvGseaORmQ0G-V_J8tkjoxh_piWMOm2CI6mBQpLamc,362
+statemachine/invoke.py,sha256=ydYBzP5pi67r9GYmDd6fT169MZkLM4lgpYcbuSyX3Ok,24874
+statemachine/mixins.py,sha256=8qxZZfBwVdFcr3oPFVWHGzgmAubH6VgQus5x3c6VEE0,1706
+statemachine/model.py,sha256=OylI3FjMiHpYyDl9mtK1zEJMeSvemaN4giQDonpc8kI,211
+statemachine/orderedset.py,sha256=PjbegcS7WPJAzC7jQ411_JrFJYEz6mmLRsAZ7aI9BWc,2543
+statemachine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/registry.py,sha256=onT8U5QgYlCSJxgxvi_TY1c1oDetHykOwnyiFk5qoN0,756
+statemachine/signature.py,sha256=N8Vt4X3YOA-NB8oidPAbYZxBgqZm6GYAiuHxBWb1l1s,9922
+statemachine/spec_parser.py,sha256=Io0J5D9s-nu2YdgUlr2cSethGfCS0pSLNmxMCXdwMqQ,8307
+statemachine/state.py,sha256=Sb25t3tAyUfUEP9B8FS7wf_kPaCugVnHeGP0OAOqZWo,15441
+statemachine/statemachine.py,sha256=K2f-MwRkvpnq_9vs7NlqeTkCaeX1eepSZl7XPAUF3V4,19977
+statemachine/states.py,sha256=kWo7y95ikXxNmcf_-J2UoMIwd3NaIdxpHMfoHr3cQ_Y,4934
+statemachine/transition.py,sha256=x9hhxIEyQ7tqsvaXkHg1bVO5hMAjemgHfZhyuypHoOY,6936
+statemachine/transition_list.py,sha256=6NAyOGEgoGOzTYiLfPM21CBVI1tPO63ZIwbaZlqOPI4,4376
+statemachine/transition_mixin.py,sha256=XGGd2J4DnFrqIpeej3QFDOuqI0CAiYwnIb8-_9DpemA,2993
+statemachine/utils.py,sha256=taCgrsRDcQQLweyq607AVZyI0NMukRP-HGpO8TiVNgk,1527
+statemachine/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/contrib/timeout.py,sha256=VXkdLpxNeUKihkbtLv8XTWdG-meQlSFtxJfcxXgV8Uw,2251
+statemachine/contrib/weighted.py,sha256=jcKkm25df6NnzBzuss1-ewDEasZ_CyME03xgJXrwcso,6866
+statemachine/contrib/diagram/__init__.py,sha256=NaVy7LWly8fTJNxjaXoRlWdYQ7cwbuNQPN0BMW6ATrI,7532
+statemachine/contrib/diagram/__main__.py,sha256=iPpiz09xKqtAjrhONS99OYp6R2dQ6Anbhw1qPIN8ELo,80
+statemachine/contrib/diagram/extract.py,sha256=RmjsTpOkbQxwYS_m5BS1VWisef5vHtTRmmwe_Dq3wMk,9891
+statemachine/contrib/diagram/formatter.py,sha256=SeNKdt5jzKIDNUPHD0xZQ0cb_zsQbwrucoZtMVXL0og,4758
+statemachine/contrib/diagram/model.py,sha256=ZspysRy8WbJn4VDYkjoYe0mtao2dT9i6T005ehW5BxA,1498
+statemachine/contrib/diagram/sphinx_ext.py,sha256=HcEXU-aYz8da02XPkZKpF5HDF0XPBGGg9FCz8MtI1C8,10338
+statemachine/contrib/diagram/renderers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/contrib/diagram/renderers/dot.py,sha256=jzKBXJ_m9olnQLXu8SXbFgtdvbFyt5Ukr5uZNjXU0X8,19913
+statemachine/contrib/diagram/renderers/mermaid.py,sha256=jY6cUW9A_P8xLHISrSijx3GlpIl_Gnj3SgayspYq7DI,13526
+statemachine/contrib/diagram/renderers/table.py,sha256=iIdWnVgV7_PY8piSC-WWbEixZSksqXTOujAk6jrO7FQ,3736
+statemachine/engines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/engines/async_.py,sha256=Wtm3GRm2y9gWTevdPkJgnpY7RzZ97HVewWtwgDenoeU,22552
+statemachine/engines/base.py,sha256=bVPYyl_AWWzfjFWiLnDiofdOyb40pojr2qu--C4MHvQ,37993
+statemachine/engines/sync.py,sha256=F_bt4z1KLLcFCP77E9SNWDJMWiMTexE0iOU2XAd_x5A,9153
+statemachine/io/__init__.py,sha256=1J_oVSWrWmx9bLrGU-YoWyO-YYbO6T9Z6vUAnerKe3Q,8739
+statemachine/io/scxml/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/io/scxml/actions.py,sha256=M1fAsuf0gJlnpMWXgoxCwpOk2MQSh8wBvtupp38T9n8,22491
+statemachine/io/scxml/invoke.py,sha256=raRStlMBOfxto6KIkCbi3jJ3UQ3QfuT0ezn4B48A670,8443
+statemachine/io/scxml/parser.py,sha256=zggZwu0rHZNWDaJTHD2XC3MrCy_bi4CNHStfWE9NHgU,16582
+statemachine/io/scxml/processor.py,sha256=_hjW4VTuzbPK2q5a7dp2kYMBcbRBZFbjz-wJKSZLI8I,9467
+statemachine/io/scxml/schema.py,sha256=xNpW_nkS2Z_hye5p1WLr8VhuM85Nic2HqRLCnoFN3ss,3927
+statemachine/locale/en/LC_MESSAGES/statemachine.po,sha256=exLJzm2uGsLWbggRKvgLzqqBstusQWu38HC0IMxEI6g,5338
+statemachine/locale/hi_IN/LC_MESSAGES/statemachine.po,sha256=aAA-ZsZt0SWM5zykZMuaQQli0DWS-yKkMM7lnXHIF10,7948
+statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po,sha256=4Gc2vilchzx1-zTmQqJgweFz_wHzEJBjUG4bgR0xlNI,5814
+statemachine/locale/zh_CN/LC_MESSAGES/statemachine.po,sha256=X51ghMEP9ZNda9HZO0hcYez4HdXuvi-0GXKay2S3ZIQ,5369
+python_statemachine-3.1.0.dist-info/METADATA,sha256=-Hi9lHdURp725XVA52Ew2j6PGKWN1xN2Y1caBTVtCYg,12249
+python_statemachine-3.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_statemachine-3.1.0.dist-info/licenses/LICENSE,sha256=zcP7TsJMqaFxuTvLRZPT7nJl3_ppjxR9Z76BE9pL5zc,1074
+python_statemachine-3.1.0.dist-info/RECORD,,

{python_statemachine-2.6.0.dist-info → python_statemachine-3.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.28.0
+Generator: hatchling 1.29.0
 Root-Is-Purelib: true
 Tag: py3-none-any

statemachine/__init__.py

@@ -1,9 +1,21 @@
 from .event import Event
+from .state import HistoryState
+from .state import HistoryType
 from .state import State
+from .statemachine import StateChart
 from .statemachine import StateMachine
+from .statemachine import TModel
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
-__version__ = "2.6.0"
+__version__ = "3.1.0"
 
-__all__ = ["StateMachine", "State", "Event"]
+__all__ = [
+    "StateChart",
+    "StateMachine",
+    "State",
+    "HistoryState",
+    "HistoryType",
+    "Event",
+    "TModel",
+]