Changelog

Release history and what changed in each version.

Changelog

All notable changes to XState-StateMachine for Python are documented here.

For the full changelog with commit history, see CHANGELOG.md on GitHub.

[0.5.0] — 2026-03-23 (Current Release)

Added

• Pythonic API — three new styles for defining state machines in pure Python:
  • StateMachine base class with metaclass (class-based declarative API)
  • MachineBuilder fluent builder API
  • build_machine() functional API with State objects
• @action, @guard, @service decorators for marking functions with automatic name mapping (snake_case to camelCase)
• State.to() transition API with | operator for combining transitions
• State.internal() method for internal transitions (no state change)
• State.enter() / State.exit() decorators for entry/exit action registration
• CLI --template flag with 5 code generation templates:
  • pythonic-class — StateMachine subclass
  • pythonic-builder — MachineBuilder chain
  • pythonic-functional — build_machine() call
  • class-json — class-based with JSON at runtime (default)
  • function-json — module functions with JSON at runtime
• Strategy pattern architecture for CLI code generation (easily extensible)
• Rich generated code with type hints, docstrings, error handling (try/except), and logging
• 143 Pythonic API tests across 20 test classes
• Stress test suite with 50 real-world XState machine configs
• Comprehensive documentation overhaul (25 guide pages)

Changed

• _resolve_target() signature updated with context-aware resolution for nested states
• Generated code now uses PEP 8 snake_case function names with auto-mapping to camelCase
• Template selection replaces the old --style flag
• Default async mode is template-dependent: sync for Pythonic templates, async for JSON templates

Fixed

• Nested state target resolution when using dot-path references
• State/event name collision in generated code (event variables now get _event suffix)
• Empty actions list emission in generated transition code
• Conditional service decorator import (only imported when services exist)
• Function complexity compliance (flake8 C901) in generator code
• Windows console encoding errors with emoji characters in CLI output

Deprecated

• --style flag (class / function) — use --template instead. Maps to class-json / function-json. Will be removed in v0.6.0.

[0.4.3] — 2025-02-03

• Python 3.14 support
• Build system migration to uv

[0.4.2] — 2025-08-13

• reenter flag for self-transitions (forces exit/re-entry)

[0.4.1] — 2025-07-27

• Enhanced sync actor spawning in SyncInterpreter
• Hierarchical machine generation in CLI (--json-parent, --json-child)
• CLI subcommand aliases (gt for generate-template)

[0.4.0] — 2025-07-16

• CLI tool introduction (xsm generate-template)
• after transition support in SyncInterpreter

[0.3.x]

• Plugin framework (PluginBase, LoggingInspector)
• Snapshot system (save/restore interpreter state)
• Actor spawning (invoke with machine sources)
• Dual execution engines (Interpreter + SyncInterpreter)

[0.2.x]

• LogicLoader with auto-discovery (snake_case → camelCase mapping)
• logic_providers and logic_modules support in create_machine()
• PyPI packaging and distribution

[0.1.0]

• Initial release
• XState JSON parsing and validation
• Async interpreter with full statechart support
• Hierarchical states, parallel states, final states
• Guards, actions, services
• after (delayed) and always (eventless) transitions