# fgmacedo/python-statemachine architecture

> Architecture diagram of the GitHub repository fgmacedo/python-statemachine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fgmacedo/python-statemachine
- Repository: https://github.com/fgmacedo/python-statemachine

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        User["User-defined StateMachine subclass"]:::user
    end

    %% Model & Registry
    subgraph "Model & Registry"
        Model["model.py"]:::core
        Registry["registry.py"]:::core
        SpecParser["spec_parser.py"]:::core
        TransList["transition_list.py"]:::core
    end

    %% Dispatcher & Engines
    subgraph "Dispatcher & Engines"
        Disp["dispatcher.py"]:::core
        BaseEngine["base.py"]:::core
        SyncEngine["sync.py"]:::core
        AsyncEngine["async_.py"]:::core
    end

    %% Metadata (State/Transition/Graph)
    subgraph "Metadata (State/Transition/Graph)"
        StateMod["state.py"]:::core
        StatesMod["states.py"]:::core
        TransitionMod["transition.py"]:::core
        GraphMod["graph.py"]:::core
    end

    %% Callbacks & Observer (Dependency Injection)
    subgraph "Callbacks & Observer"
        Callbacks["callbacks.py"]:::core
        Mixins["mixins.py"]:::core
        TransMixin["transition_mixin.py"]:::core
        Signature["signature.py"]:::core
    end

    %% Events & Data Structures
    subgraph "Events & Data"
        Event["event.py"]:::core
        EventData["event_data.py"]:::core
        Events["events.py"]:::core
    end

    %% Factory
    Factory["factory.py"]:::core

    %% Contrib Diagram Subsystem
    subgraph "Contrib Diagram"
        Diagram["diagram.py"]:::ext
    end

    %% Exceptions & Utilities
    subgraph "Exceptions & Utilities"
        Exceptions["exceptions.py"]:::core
        Utils["utils.py"]:::core
    end

    %% External Tools
    subgraph "External Dependencies"
        Pydot["pydot"]:::external
        Graphviz["Graphviz"]:::external
        Pytest["pytest"]:::external
        Django["Django"]:::external
    end

    %% Legend (colors)
    classDef user fill:#f9f,stroke:#333,stroke-width:2px
    classDef core fill:#bbf,stroke:#333,stroke-width:2px
    classDef ext fill:#bfb,stroke:#333,stroke-width:2px
    classDef external fill:#ffa,stroke:#333,stroke-width:2px

    %% Connections
    User -->|"defines states/transitions"| Model
    Model --> Registry
    Registry --> SpecParser
    SpecParser --> TransList

    User -->|"send()/event()"| Disp
    Disp -->|"select engine"| SyncEngine
    Disp -->|"select engine"| AsyncEngine
    SyncEngine -->|"validate transition"| TransitionMod
    AsyncEngine -->|"validate transition"| TransitionMod
    TransitionMod -->|"invoke guards/callbacks"| Callbacks
    Callbacks --> Signature
    Callbacks --> Mixins
    TransitionMod -->|"update state"| User

    %% Diagram generation flow
    User -->|"_graph()"| GraphMod
    GraphMod -->|"export dot"| Diagram
    Diagram -->|"render"| Pydot
    Pydot -->|"render"| Graphviz

    %% External integrations
    User -->|uses| Django
    Pytest -->|tests| User

    %% Click Events
    click User "https://github.com/fgmacedo/python-statemachine/blob/develop/tests/examples/order_control_machine.py"
    click User "https://github.com/fgmacedo/python-statemachine/blob/develop/tests/django_project/workflow/statemachines.py"
    click Model "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/model.py"
    click Registry "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/registry.py"
    click SpecParser "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/spec_parser.py"
    click TransList "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/transition_list.py"
    click Disp "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/dispatcher.py"
    click BaseEngine "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/engines/base.py"
    click SyncEngine "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/engines/sync.py"
    click AsyncEngine "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/engines/async_.py"
    click StateMod "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/state.py"
    click StatesMod "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/states.py"
    click TransitionMod "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/transition.py"
    click GraphMod "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/graph.py"
    click Callbacks "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/callbacks.py"
    click Mixins "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/mixins.py"
    click TransMixin "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/transition_mixin.py"
    click Signature "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/signature.py"
    click Event "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/event.py"
    click EventData "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/event_data.py"
    click Events "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/events.py"
    click Factory "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/factory.py"
    click Diagram "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/contrib/diagram.py"
    click Exceptions "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/exceptions.py"
    click Utils "https://github.com/fgmacedo/python-statemachine/blob/develop/statemachine/utils.py"
```
