How fgmacedo/python-statemachine works
Project type and purpose
• This is an open‐source Python library (“python-statemachine”) that provides a declarative API for defining and executing finite‐state machines (FSM), with both synchronous and asynchronous support. It also offers a built-in facility to generate graphical representations of machines via pydot/Graphviz, and integration mixins for domain models (e.g., Django).
File structure at a high level
• Top‐level items:
• pyproject.toml / setup files – package metadata and dependencies
• statemachine/ – core Python package, subdivided into modules (callbacks, dispatcher, engines, graph, model, registry, etc.)
• statemachine/engines/ – sync and async event‐dispatch engines
• tests/ – pytest suite with examples and real‐world integration tests (including a Django project)
README for additional insights
• Confirms key responsibilities:
• Defining States, Events, Transitions
• Dispatching events via sync or async engines
• Invoking callbacks, guards, and actions with dependency‐injection
• Mixins for domain‐model integration (e.g., Django)
• Mentions architectural constraints and correctness guarantees enforced at class‐definition time.
Main components and interactions
a. User‐defined StateMachine subclass (API layer)
• Defines State objects, Event/Transition declarations, callback methods
b. Core Library Modules
• Model & Registry: scans class attributes to build an in‐memory state machine graph
• Dispatcher & Engines: route events into either the synchronous or asynchronous execution engine
• State/Transition/Graph: store metadata, enforce correctness rules, produce dot graphs
• Callbacks & Mixins: handle before/after hooks, observer notifications, DI of parameters
c. External Dependencies & Tools
• pydot + Graphviz for rendering
• pytest for automated testing
• Django (optional) for automatic discovery in web apps
Relationships and data flows
• At startup, user subclass invocation triggers Model & Registry → builds State/Transition graph
• When sm.event() or sm.send(event) is called:
• Dispatcher selects appropriate Engine (sync or async)
• Engine validates “current state → transition” and raises errors if not allowed
• Engine invokes guard methods, fires callbacks (before_<event>, on_enter_<state>, on_exit_<state>, after_<event>) with DI
• StateMachine.current_state is updated
• Graph module exports Graphviz dot format
• pydot + Graphviz produce PNG/SVG
Architectural patterns and design principles
• Declarative API: class attributes describe states/transitions
• Observer/Publisher‐Subscriber: external listeners register for lifecycle events
• Dependency Injection: callback parameters are auto‐injected based on signature
• Strategy/Engine Pattern: pluggable dispatch engines (sync vs async)
• Single‐source of truth: Model & Registry enforce correctness at definition time
Technologies, frameworks, and libraries
• Python 3.7+
• pytest, tox for testing
• Django (optional integration)
• Break the library into these components:
• API Layer (StateMachine subclass)
• Model & Registry (graph builder, correctness enforcer)
• Dispatcher & Engine(s) (sync vs async strategy)
• Callback & Observer subsystem (dependency injection)
• Integration mixins (e.g., Django discovery)