docs: add v3 upgrade guide and migrate documentation to StateChart API

Add comprehensive upgrade guide from 2.x to 3.0 covering all breaking
changes with before/after examples. Update all documentation to use
StateChart as the primary API with non-deprecated methods/properties,
replacing StateMachine, current_state, and add_observer references.

Author: fgmacedo

conftest.py

@@ -9,6 +9,7 @@ def add_doctest_context(doctest_namespace):  # noqa: PT004
     from statemachine.utils import run_async_from_sync
 
     from statemachine import State
+    from statemachine import StateChart
     from statemachine import StateMachine
 
     class ContribAsyncio:
@@ -23,6 +24,7 @@ def __init__(self):
             self.run = run_async_from_sync
 
     doctest_namespace["State"] = State
+    doctest_namespace["StateChart"] = StateChart
     doctest_namespace["StateMachine"] = StateMachine
     doctest_namespace["asyncio"] = ContribAsyncio()
 

docs/actions.md

@@ -1,6 +1,6 @@
 # Actions
 
-Action is the way a {ref}`StateMachine` can cause things to happen in the
+Action is the way a {ref}`StateChart` can cause things to happen in the
 outside world, and indeed they are the main reason why they exist at all.
 
 The main point of introducing a state machine is for the
@@ -11,7 +11,7 @@ Actions are most commonly performed on entry or exit of a state, although
 it is possible to add them before/after a transition.
 
 There are several action callbacks that you can define to interact with a
-StateMachine in execution.
+StateChart in execution.
 
 There are callbacks that you can specify that are generic and will be called
 when something changes, and are not bound to a specific state or event:
@@ -31,9 +31,9 @@ when something changes, and are not bound to a specific state or event:
 The following example offers an overview of the "generic" callbacks available:
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...     final = State(final=True)
 ...
@@ -91,7 +91,7 @@ For each defined {ref}`state`, you can declare `enter` and `exit` callbacks.
 
 ### Bind state actions by naming convention
 
-Callbacks by naming convention will be searched on the StateMachine and on the
+Callbacks by naming convention will be searched on the StateChart and on the
 model, using the patterns:
 
 - `on_enter_<state.id>()`
@@ -100,9 +100,9 @@ model, using the patterns:
 
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
@@ -120,9 +120,9 @@ model, using the patterns:
 Use the `enter` or `exit` params available on the `State` constructor.
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True, enter="entering_initial", exit="leaving_initial")
 ...
 ...     loop = initial.to.itself()
@@ -143,9 +143,9 @@ It's also possible to use an event name as action.
 
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
@@ -179,9 +179,9 @@ using the patterns:
 
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
@@ -201,9 +201,9 @@ using the patterns:
 ### Bind transition actions using params
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself(before="just_before", on="its_happening", after="loop_completed")
@@ -229,9 +229,9 @@ The action will be registered for every {ref}`transition` in the list associated
 
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
@@ -263,9 +263,9 @@ The action will be registered for every {ref}`transition` in the list associated
 You can also declare an event while also adding a callback:
 
 ```py
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     @initial.to.itself()
@@ -277,7 +277,7 @@ You can also declare an event while also adding a callback:
 
 Note that with this syntax, the resulting `loop` that is present on the `ExampleStateMachine.loop`
 namespace is not a simple method, but an {ref}`event` trigger. So it only executes if the
-StateMachine is in the right state.
+StateChart is in the right state.
 
 So, you can use the event-oriented approach:
 
@@ -307,7 +307,7 @@ that will be included in `**kwargs` to all other callbacks.
 A not so usefull example:
 
 ```py
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
@@ -399,7 +399,7 @@ Note that `None` will be used if the action callback does not return anything, b
 defined explicitly. The following provides an example:
 
 ```py
->>> class ExampleStateMachine(StateMachine):
+>>> class ExampleStateMachine(StateChart):
 ...     initial = State(initial=True)
 ...
 ...     loop = initial.to.itself()
@@ -421,15 +421,15 @@ defined explicitly. The following provides an example:
 
 ```
 
-For {ref}`RTC model`, only the main event will get its value list, while the chained ones simply get
-`None` returned. For {ref}`Non-RTC model`, results for every event will always be collected and returned.
+Only the main event will get its value list, while the chained ones simply get
+`None` returned.
 
 
 (dynamic-dispatch)=
 (dynamic dispatch)=
 ## Dependency injection
 
-{ref}`statemachine` implements a dependency injection mechanism on all available {ref}`Actions` and
+{ref}`StateChart` implements a dependency injection mechanism on all available {ref}`Actions` and
 {ref}`Conditions` that automatically inspects and matches the expected callback params with those available by the library in conjunction with any values informed when calling an event using `*args` and `**kwargs`.
 
 The library ensures that your method signatures match the expected arguments.

docs/api.md

@@ -114,7 +114,7 @@ that will be merged into `**kwargs` for all subsequent callbacks (guards, action
 entry/exit handlers) during that event's processing:
 
 ```python
-class MyMachine(StateMachine):
+class MyMachine(StateChart):
     initial = State(initial=True)
     loop = initial.to.itself()
 

docs/async.md

@@ -4,7 +4,7 @@
 Support for async code was added!
 ```
 
-The {ref}`StateMachine` fully supports asynchronous code. You can write async {ref}`actions`, {ref}`guards`, and {ref}`events` triggers, while maintaining the same external API for both synchronous and asynchronous codebases.
+The {ref}`StateChart` fully supports asynchronous code. You can write async {ref}`actions`, {ref}`guards`, and {ref}`events` triggers, while maintaining the same external API for both synchronous and asynchronous codebases.
 
 This is achieved through a new concept called **engine**, an internal strategy pattern abstraction that manages transitions and callbacks.
 
@@ -89,7 +89,7 @@ async code with a state machine.
 
 
 ```py
->>> class AsyncStateMachine(StateMachine):
+>>> class AsyncStateMachine(StateChart):
 ...     initial = State('Initial', initial=True)
 ...     final = State('Final', final=True)
 ...
@@ -103,11 +103,11 @@ async code with a state machine.
 ...     sm = AsyncStateMachine()
 ...     result = await sm.advance()
 ...     print(f"Result is {result}")
-...     print(sm.current_state)
+...     print(list(sm.configuration_values))
 
 >>> asyncio.run(run_sm())
 Result is 42
-Final
+['final']
 
 ```
 
@@ -124,8 +124,8 @@ If needed, the state machine will create a loop using `asyncio.new_event_loop()`
 >>> result = sm.advance()
 >>> print(f"Result is {result}")
 Result is 42
->>> print(sm.current_state)
-Final
+>>> print(list(sm.configuration_values))
+['final']
 
 ```
 
@@ -134,26 +134,24 @@ Final
 ## Initial State Activation for Async Code
 
 
-If **on async code** you perform checks against the `current_state`, like a loop `while sm.current_state.is_final:`, then you must manually
-await for the  [activate initial state](statemachine.StateMachine.activate_initial_state) to be able to check the current state.
+If **on async code** you perform checks against the `configuration`, like a loop `while not sm.is_terminated:`, then you must manually
+await for the  [activate initial state](statemachine.StateChart.activate_initial_state) to be able to check the configuration.
 
 ```{hint}
 This manual initial state activation on async is because Python don't allow awaiting at class initalization time and the initial state activation may contain async callbacks that must be awaited.
 ```
 
-If you don't do any check for current state externally, just ignore this as the initial state is activated automatically before the first event trigger is handled.
+If you don't do any check for configuration externally, just ignore this as the initial state is activated automatically before the first event trigger is handled.
 
-You get an error checking the current state before the initial state activation:
+You get an error checking the configuration before the initial state activation:
 
 ```py
 >>> async def initialize_sm():
 ...     sm = AsyncStateMachine()
-...     print(sm.current_state)
+...     print(list(sm.configuration_values))
 
 >>> asyncio.run(initialize_sm())
-Traceback (most recent call last):
-...
-InvalidStateValue: There's no current state set. In async code, did you activate the initial state? (e.g., `await sm.activate_initial_state()`)
+[None]
 
 ```
 
@@ -164,10 +162,10 @@ You can activate the initial state explicitly:
 >>> async def initialize_sm():
 ...     sm = AsyncStateMachine()
 ...     await sm.activate_initial_state()
-...     print(sm.current_state)
+...     print(list(sm.configuration_values))
 
 >>> asyncio.run(initialize_sm())
-Initial
+['initial']
 
 ```
 
@@ -178,10 +176,10 @@ before the event is handled:
 >>> async def initialize_sm():
 ...     sm = AsyncStateMachine()
 ...     await sm.keep()  # first event activates the initial state before the event is handled
-...     print(sm.current_state)
+...     print(list(sm.configuration_values))
 
 >>> asyncio.run(initialize_sm())
-Initial
+['initial']
 
 ```
 
@@ -205,7 +203,7 @@ async def run():
 ### Async-specific limitations
 
 - **Initial state activation**: In async code, you must `await sm.activate_initial_state()`
-  before inspecting `sm.configuration` or `sm.current_state`. In sync code this happens
+  before inspecting `sm.configuration`. In sync code this happens
   automatically at instantiation time.
 - **Delayed events**: Both sync and async engines support `delay=` on `send()`. The async
   engine uses `asyncio.sleep()` internally, so it integrates naturally with event loops.

docs/diagram.md

@@ -1,6 +1,6 @@
 # Diagrams
 
-You can generate diagrams from your {ref}`StateMachine`.
+You can generate diagrams from your {ref}`StateChart`.
 
 ```{note}
 This functionality depends on [pydot](https://github.com/pydot/pydot), it means that you need to
@@ -116,7 +116,7 @@ usage: diagram.py [OPTION] <classpath> <out>
 Generate diagrams for StateMachine classes.
 
 positional arguments:
-  classpath   A fully-qualified dotted path to the StateMachine class.
+  classpath   A fully-qualified dotted path to the StateChart class.
   out         File to generate the image using extension as the output format.
 
 optional arguments:

docs/guards.md

@@ -22,7 +22,7 @@ A conditional transition occurs only if specific conditions or criteria are met.
 
 When a transition is conditional, it includes a condition (also known as a _guard_) that must be satisfied for the transition to take place. If the condition is not met, the transition does not occur, and the state machine remains in its current state or follows an alternative path.
 
-This feature allows for multiple transitions on the same {ref}`event`, with each {ref}`transition` checked in **declaration order** — that is, the order in which the transitions themselves were created using `state.to()`. A condition acts like a predicate (a function that evaluates to true/false) and is checked when a {ref}`statemachine` handles an {ref}`event` with a transition from the current state bound to this event. The first transition that meets the conditions (if any) is executed. If none of the transitions meet the conditions, the state machine either raises an exception or does nothing (see the `allow_event_without_transition` parameter of {ref}`StateMachine`).
+This feature allows for multiple transitions on the same {ref}`event`, with each {ref}`transition` checked in **declaration order** — that is, the order in which the transitions themselves were created using `state.to()`. A condition acts like a predicate (a function that evaluates to true/false) and is checked when a {ref}`statemachine` handles an {ref}`event` with a transition from the current state bound to this event. The first transition that meets the conditions (if any) is executed. If none of the transitions meet the conditions, the state machine either raises an exception or does nothing (see the `allow_event_without_transition` attribute of {ref}`StateChart`).
 
 ````{important}
 **Evaluation order is based on declaration order, not composition order.**
@@ -161,18 +161,18 @@ So, a condition `s1.to(s2, cond=lambda: [])` will evaluate as `False`, as an emp
 
 ### Checking enabled events
 
-The {ref}`StateMachine.allowed_events` property returns events reachable from the current state,
+The {ref}`StateChart.allowed_events` property returns events reachable from the current state,
 but it does **not** evaluate `cond`/`unless` guards. To check which events actually have their
-conditions satisfied, use {ref}`StateMachine.enabled_events`.
+conditions satisfied, use {ref}`StateChart.enabled_events`.
 
 ```{testsetup}
 
->>> from statemachine import StateMachine, State
+>>> from statemachine import StateChart, State
 
 ```
 
 ```py
->>> class ApprovalMachine(StateMachine):
+>>> class ApprovalMachine(StateChart):
 ...     pending = State(initial=True)
 ...     approved = State(final=True)
 ...     rejected = State(final=True)
@@ -202,7 +202,7 @@ arguments. Any `*args`/`**kwargs` passed to `enabled_events()` are forwarded to
 condition callbacks, just like when triggering an event:
 
 ```py
->>> class TaskMachine(StateMachine):
+>>> class TaskMachine(StateChart):
 ...     idle = State(initial=True)
 ...     running = State(final=True)
 ...

docs/integrations.md

@@ -7,17 +7,17 @@ When used in a Django App, this library implements an auto-discovery hook simila
 built-in **admin** [autodiscover](https://docs.djangoproject.com/en/dev/ref/contrib/admin/#django.contrib.admin.autodiscover).
 
 > This library attempts to import an **statemachine** or **statemachines** module in each installed
-> application. Such modules are expected to register `StateMachine` classes to be used with
+> application. Such modules are expected to register `StateChart` classes to be used with
 > the {ref}`MachineMixin`.
 
 
 ```{hint}
 When using `python-statemachine` to control the state of a Django model, we advise keeping the
-{ref}`StateMachine` definitions on their own modules.
+{ref}`StateChart` definitions on their own modules.
 
 So as circular references may occur, and as a way to help you organize your
 code, if you put state machines on modules named as mentioned above inside installed
-Django Apps, these {ref}`StateMachine` classes will be automatically
+Django Apps, these {ref}`StateChart` classes will be automatically
 imported and registered.
 
 This is only an advice, nothing stops you do declare your state machine alongside your models.
@@ -31,12 +31,12 @@ Given this StateMachine:
 ```py
 # campaign/statemachines.py
 
-from statemachine import StateMachine
+from statemachine import StateChart
 from statemachine import State
 from statemachine.mixins import MachineMixin
 
 
-class CampaignMachineWithKeys(StateMachine):
+class CampaignMachineWithKeys(StateChart):
     "A workflow machine"
     draft = State('Draft', initial=True, value=1)
     producing = State('Being produced', value=2)