refactor!: remove strict_states, add validate_trap_states and validate_final_reachability (#568)

Replace the `strict_states` class parameter (introduced in v2.2.0) with two
independent class-level attributes that default to `True`:

- `validate_trap_states`: non-final states must have outgoing transitions
- `validate_final_reachability`: when final states exist, all non-final states
  must have a path to at least one final state

This fulfils the v2.2.0 promise that `strict_states=True` would become the
default in the next major release. The warning-based behavior is removed —
violations now always raise `InvalidDefinition`.

BREAKING CHANGE: `strict_states=True/False` no longer accepted. Use
`validate_trap_states = False` / `validate_final_reachability = False` to
opt out, or (recommended) mark terminal states as `final=True`.

Author: fgmacedo

docs/releases/2.2.0.md

@@ -39,21 +39,21 @@ and warn you if any states would result in the statemachine becoming trapped in
 This will currently issue a warning, but can be turned into an exception by setting `strict_states=True` on the class.
 ```
 
-```py
->>> from statemachine import StateMachine, State
+```python
+from statemachine import StateMachine, State
 
->>> class TrafficLightMachine(StateMachine, strict_states=True):
-...     "A workflow machine"
-...     red = State('Red', initial=True, value=1)
-...     green = State('Green', value=2)
-...     orange = State('Orange', value=3)
-...     hazard = State('Hazard', value=4)
-...
-...     cycle = red.to(green) | green.to(orange) | orange.to(red)
-...     fault = red.to(hazard) | green.to(hazard) | orange.to(hazard)
-Traceback (most recent call last):
-...
-InvalidDefinition: All non-final states should have at least one outgoing transition. These states have no outgoing transition: ['hazard']
+class TrafficLightMachine(StateMachine, strict_states=True):
+    "A workflow machine"
+    red = State('Red', initial=True, value=1)
+    green = State('Green', value=2)
+    orange = State('Orange', value=3)
+    hazard = State('Hazard', value=4)
+
+    cycle = red.to(green) | green.to(orange) | orange.to(red)
+    fault = red.to(hazard) | green.to(hazard) | orange.to(hazard)
+
+# InvalidDefinition: All non-final states should have at least one outgoing transition.
+# These states have no outgoing transition: ['hazard']
 ```
 
 ```{warning}

docs/releases/3.0.0.md

@@ -580,3 +580,41 @@ The short-name lookup (by `cls.__name__`) that was deprecated since v0.8 has bee
 
 If you use `get_machine_cls()` (e.g., via `MachineMixin`), make sure you pass the fully-qualified
 dotted path.
+
+
+### `strict_states` parameter removed
+
+The `strict_states` class parameter (introduced in v2.2.0) has been removed and replaced by
+two independent class-level attributes that default to `True`:
+
+- `validate_trap_states`: non-final states must have at least one outgoing transition.
+- `validate_final_reachability`: when final states exist, all non-final states must have
+  a path to at least one final state.
+
+**Migration:**
+
+- Remove `strict_states=True` — this is now the default behavior.
+- **Recommended:** fix your state machine definition so that terminal states are marked
+  `final=True`:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class MySM(StateChart):
+...     s1 = State(initial=True)
+...     s2 = State(final=True)
+...     go = s1.to(s2)
+
+```
+
+- If you intentionally have non-final trap states, replace `strict_states=False` with
+  `validate_trap_states = False` and/or `validate_final_reachability = False`:
+
+```py
+>>> class MySM(StateChart):
+...     validate_trap_states = False
+...     s1 = State(initial=True)
+...     s2 = State()
+...     go = s1.to(s2)
+
+```

docs/releases/upgrade_2x_to_3.md

@@ -19,6 +19,7 @@ defaults. Review this guide to understand what changed and adopt the new APIs at
 7. Review `on` callbacks that query `is_active` or `current_state` during transitions.
 8. If using `States.from_enum`, note that `use_enum_instance` now defaults to `True`.
 9. If using `get_machine_cls()` with short names, switch to fully-qualified names.
+10. Remove `strict_states=True/False` — replace with `validate_trap_states` / `validate_final_reachability`.
 
 ---
 
@@ -369,6 +370,44 @@ from statemachine import Event           # unchanged
 ```
 
 
+## `strict_states` removed — use `validate_trap_states` / `validate_final_reachability`
+
+The `strict_states` class parameter has been removed. The two validations it controlled are now
+always-on by default, each controlled by its own class-level attribute.
+
+**Before (2.x):**
+
+```python
+class MyMachine(StateMachine, strict_states=True):
+    # raises InvalidDefinition for trap states and unreachable final states
+    ...
+
+class MyMachine(StateMachine, strict_states=False):
+    # only warns (default in 2.x)
+    ...
+```
+
+**After (3.0) — recommended: fix the definition by marking terminal states as `final`:**
+
+```python
+class MyMachine(StateMachine):
+    s1 = State(initial=True)
+    s2 = State(final=True)        # was State() — now correctly marked as final
+    go = s1.to(s2)
+```
+
+**After (3.0) — opt out if you intentionally have non-final trap states:**
+
+```python
+class MyMachine(StateMachine):
+    validate_trap_states = False           # allow non-final states without outgoing transitions
+    validate_final_reachability = False    # allow non-final states without path to final
+    ...
+```
+
+The two flags are independent — you can disable one while keeping the other enabled.
+
+
 ## New features overview
 
 For full details on all new features, see the {ref}`3.0.0 release notes <StateMachine 3.0.0>`.

docs/states.md

@@ -44,17 +44,13 @@ Traceback (most recent call last):
 InvalidDefinition: There are unreachable states. The statemachine graph should have a single component. Disconnected states: ['hazard']
 ```
 
-`StateChart` will also check that all non-final states have an outgoing transition, and warn you if any states would result in
-the statemachine becoming trapped in a non-final state with no further transitions possible.
-
-```{note}
-This will currently issue a warning, but can be turned into an exception by setting `strict_states=True` on the class.
-```
+`StateChart` will also check that all non-final states have an outgoing transition.
+If any non-final state has no outgoing transitions, an `InvalidDefinition` exception is raised.
 
 ```py
 >>> from statemachine import StateChart, State
 
->>> class TrafficLightMachine(StateChart, strict_states=True):
+>>> class TrafficLightMachine(StateChart):
 ...     "A workflow machine"
 ...     red = State('Red', initial=True, value=1)
 ...     green = State('Green', value=2)
@@ -68,8 +64,19 @@ Traceback (most recent call last):
 InvalidDefinition: All non-final states should have at least one outgoing transition. These states have no outgoing transition: ['hazard']
 ```
 
-```{warning}
-`strict_states=True` will become the default behaviour in future versions.
+You can disable this check by setting `validate_trap_states = False` on the class:
+
+```py
+>>> class TrafficLightMachine(StateChart):
+...     validate_trap_states = False
+...     red = State('Red', initial=True, value=1)
+...     green = State('Green', value=2)
+...     orange = State('Orange', value=3)
+...     hazard = State('Hazard', value=4)
+...
+...     cycle = red.to(green) | green.to(orange) | orange.to(red)
+...     fault = red.to(hazard) | green.to(hazard) | orange.to(hazard)
+
 ```
 
 
@@ -100,12 +107,8 @@ InvalidDefinition: Cannot declare transitions from final state. Invalid state(s)
 
 If you mark any states as final, `StateChart` will check that all non-final states have a path to reach at least one final state.
 
-```{note}
-This will currently issue a warning, but can be turned into an exception by setting `strict_states=True` on the class.
-```
-
 ```py
->>> class CampaignMachine(StateChart, strict_states=True):
+>>> class CampaignMachine(StateChart):
 ...     "A workflow machine"
 ...     draft = State('Draft', initial=True, value=1)
 ...     producing = State('Being produced', value=2)
@@ -122,9 +125,7 @@ InvalidDefinition: All non-final states should have at least one path to a final
 
 ```
 
-```{warning}
-`strict_states=True` will become the default behaviour in future versions.
-```
+You can disable this check by setting `validate_final_reachability = False` on the class.
 
 You can query a list of all final states from your statemachine.
 

docs/transitions.md

@@ -185,7 +185,7 @@ State machine class level. The name will be converted to an {ref}`Event`:
 
 >>> class SimpleSM(StateChart):
 ...     initial = State(initial=True)
-...     final = State()
+...     final = State(final=True)
 ...
 ...     start = initial.to(final)  # start is a name that will be converted to an `Event`
 
@@ -207,7 +207,7 @@ To declare an explicit event you must also import the {ref}`Event`:
 
 >>> class SimpleSM(StateChart):
 ...     initial = State(initial=True)
-...     final = State()
+...     final = State(final=True)
 ...
 ...     start = Event(
 ...         initial.to(final),

statemachine/factory.py

@@ -1,4 +1,3 @@
-import warnings
 from typing import Any
 from typing import Dict
 from typing import List
@@ -28,12 +27,18 @@ class StateMachineMetaclass(type):
     validate_disconnected_states: bool = True
     """If `True`, the state machine will validate that there are no unreachable states."""
 
+    validate_trap_states: bool = True
+    """If ``True``, non-final states without outgoing transitions raise ``InvalidDefinition``."""
+
+    validate_final_reachability: bool = True
+    """If ``True`` and final states exist, non-final states without a path to any final
+    state raise ``InvalidDefinition``."""
+
     def __init__(
         cls,
         name: str,
         bases: Tuple[type],
         attrs: Dict[str, Any],
-        strict_states: bool = False,
     ) -> None:
         super().__init__(name, bases, attrs)
         registry.register(cls)
@@ -46,7 +51,6 @@ def __init__(
         """Map of ``state.value`` to the corresponding :ref:`state`."""
 
         cls._abstract = True
-        cls._strict_states = strict_states
         cls._events: Dict[Event, None] = {}  # used Dict to preserve order and avoid duplicates
         cls._protected_attrs: set = set()
         cls._events_to_update: Dict[Event, Optional[Event]] = {}
@@ -173,30 +177,30 @@ def _check_final_states(cls):
             )
 
     def _check_trap_states(cls):
+        if not cls.validate_trap_states:
+            return
         trap_states = [s for s in cls.states if not s.final and not s.transitions]
         if trap_states:
-            message = _(
-                "All non-final states should have at least one outgoing transition. "
-                "These states have no outgoing transition: {!r}"
-            ).format([s.id for s in trap_states])
-            if cls._strict_states:
-                raise InvalidDefinition(message)
-            else:
-                warnings.warn(message, UserWarning, stacklevel=4)
+            raise InvalidDefinition(
+                _(
+                    "All non-final states should have at least one outgoing transition. "
+                    "These states have no outgoing transition: {!r}"
+                ).format([s.id for s in trap_states])
+            )
 
     def _check_reachable_final_states(cls):
+        if not cls.validate_final_reachability:
+            return
         if not any(s.final for s in cls.states):
             return  # No need to check final reachability
         disconnected_states = list(states_without_path_to_final_states(cls.states))
         if disconnected_states:
-            message = _(
-                "All non-final states should have at least one path to a final state. "
-                "These states have no path to a final state: {!r}"
-            ).format([s.id for s in disconnected_states])
-            if cls._strict_states:
-                raise InvalidDefinition(message)
-            else:
-                warnings.warn(message, UserWarning, stacklevel=1)
+            raise InvalidDefinition(
+                _(
+                    "All non-final states should have at least one path to a final state. "
+                    "These states have no path to a final state: {!r}"
+                ).format([s.id for s in disconnected_states])
+            )
 
     def _check_disconnected_state(cls):
         if not cls.validate_disconnected_states:

statemachine/io/scxml/processor.py

@@ -105,6 +105,8 @@ def process_definition(self, definition, location: str):
                 "states": states_dict,
                 "prepare_event": self._prepare_event,
                 "validate_disconnected_states": False,
+                "validate_trap_states": False,
+                "validate_final_reachability": False,
                 "start_configuration_values": list(definition.initial_states),
             },
         )

statemachine/statemachine.py

@@ -126,7 +126,6 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
     """List of top-level :ref:`State` objects marked as ``final``."""
 
     _abstract: bool
-    _strict_states: bool
     _events: "Dict[Event, None]"
     _protected_attrs: set
     _specs: CallbackSpecList
@@ -181,10 +180,6 @@ def _processing_loop(self, caller_future: "Any | None" = None) -> Any:
             return result
         return run_async_from_sync(result)
 
-    def __init_subclass__(cls, strict_states: bool = False):
-        cls._strict_states = strict_states
-        super().__init_subclass__()
-
     def __repr__(self):
         configuration_ids = [s.id for s in self.configuration]
         return (

tests/examples/statechart_error_handling_machine.py

@@ -89,7 +89,7 @@ class QuestNoCatch(StateChart):
     error_on_execution = False
 
     safe = State("Safe", initial=True)
-    danger_zone = State("Danger Zone")
+    danger_zone = State("Danger Zone", final=True)
 
     venture = safe.to(danger_zone)
 

tests/test_async.py

@@ -216,7 +216,7 @@ async def test_async_error_on_execution_in_condition():
 
     class SM(StateChart):
         s1 = State(initial=True)
-        s2 = State()
+        s2 = State(final=True)
         error_state = State(final=True)
 
         go = s1.to(s2, cond="bad_cond")
@@ -236,7 +236,7 @@ async def test_async_error_on_execution_in_transition():
 
     class SM(StateChart):
         s1 = State(initial=True)
-        s2 = State()
+        s2 = State(final=True)
         error_state = State(final=True)
 
         go = s1.to(s2, on="bad_action")
@@ -276,7 +276,7 @@ async def test_async_invalid_definition_in_transition_propagates():
 
     class SM(StateChart):
         s1 = State(initial=True)
-        s2 = State()
+        s2 = State(final=True)
 
         go = s1.to(s2, on="bad_action")
 
@@ -338,7 +338,7 @@ async def test_async_engine_invalid_definition_in_condition_propagates():
 
     class SM(StateChart):
         s1 = State(initial=True)
-        s2 = State()
+        s2 = State(final=True)
 
         go = s1.to(s2, cond="bad_cond")
 
@@ -357,7 +357,7 @@ async def test_async_engine_invalid_definition_in_transition_propagates():
 
     class SM(StateChart):
         s1 = State(initial=True)
-        s2 = State()
+        s2 = State(final=True)
 
         go = s1.to(s2, on="bad_action")
 
@@ -494,7 +494,7 @@ async def test_duplicate_event_across_transitions_deduplicated(self):
 
         class MyMachine(StateChart):
             s0 = State(initial=True)
-            s1 = State()
+            s1 = State(final=True)
             s2 = State(final=True)
 
             go = s0.to(s1, cond="cond_a") | s0.to(s2, cond="cond_b")
@@ -514,7 +514,7 @@ async def cond_b(self):
     async def test_mixed_enabled_and_disabled_async(self):
         class MyMachine(StateChart):
             s0 = State(initial=True)
-            s1 = State()
+            s1 = State(final=True)
             s2 = State(final=True)
 
             go = s0.to(s1, cond="cond_true")