feat: Internal transition. Closes #78 (#328)

feat: Internal transitions.

Author: fgmacedo

docs/images/test_state_machine_internal.png

@@ -55,7 +55,7 @@ Example:
 See {ref}`diagrams` for more details.
 ```
 
-### Unified dispatch mecanism for callbacks (actions and guards)
+### Unified dispatch mechanism for callbacks (actions and guards)
 
 Every single callback, being {ref}`actions` or {ref}`guards`, is now handled equally by the library.
 
@@ -81,7 +81,7 @@ See {ref}`dynamic-dispatch` for more details.
 
 ### Add observers to a running StateMachine
 
-Observers are a way do generically add behaviour to a StateMachine without
+Observers are a way do generically add behavior to a StateMachine without
 changing it's internal implementation.
 
 The `StateMachine` itself is registered as an observer, so by using `StateMachine.add_observer()`
@@ -162,7 +162,7 @@ See {ref}`State actions` for more details.
 Statemachine integrity checks are now performed at class declaration (import time) instead of on
 instance creation. This allows early feedback of invalid definitions.
 
-This was the previous behaviour, you only got an error when trying to instantiate a StateMachine:
+This was the previous behavior, you only got an error when trying to instantiate a StateMachine:
 
 ```py
 class CampaignMachine(StateMachine):
@@ -206,7 +206,7 @@ with pytest.raises(exceptions.InvalidDefinition):
   called `TransitionList` that implements de `OR` operator. This turns a valid StateMachine
   traversal much easier: `[transition for state in machine.states for transition in state.transitions]`.
 - `StateMachine.get_transition` is removed. See {ref}`event`.
-- The previous excetions `MultipleStatesFound` and `MultipleTransitionCallbacksFound` are removed.
+- The previous exceptions `MultipleStatesFound` and `MultipleTransitionCallbacksFound` are removed.
   Since now you can have more than one callback defined to the same transition.
 - `on_enter_state` and `on_exit_state` now accepts any combination of parameters following the
   {ref}`dynamic-dispatch` rules. Previously it only accepted the `state` param.

docs/releases/1.0.1.md

@@ -0,0 +1,60 @@
+# StateMachine 2.0.0
+
+*Not released yet*
+
+Welcome to StateMachine 2.0.0!
+
+This version is the first to take advantage of the Python3 improvements. We're on our way
+to implement features following the SCXML specs. We hope that
+you enjoy.
+
+These release notes cover the [](#whats-new-in-20), as well as
+some [backwards incompatible changes](#backwards-incompatible-changes-in-20) you'll
+want to be aware of when upgrading from StateMachine 1.*. We've
+[begun the deprecation process for some features](#deprecated-features-in-20).
+
+
+## Python compatibility in 2.0
+
+StateMachine 2.0 supports Python 3.7, 3.8, 3.9, 3.10, and 3.11.
+
+
+## What's new in 2.0
+
+
+### Internal transitions
+
+An internal transition is like a {ref}`self transition`, but in contrast, no entry or exit actions
+are ever executed as a result of an internal transition.
+
+```py
+>>> from statemachine import StateMachine, State
+
+>>> class TestStateMachine(StateMachine):
+...     initial = State("initial", initial=True)
+...
+...     loop = initial.to.itself(internal=True)
+
+```
+
+```{seealso}
+See {ref}`internal transition` for more details.
+```
+
+
+## Minor features in 2.0
+
+- Modernization of the development stack to use linters.
+
+
+## Backwards incompatible changes in 2.0
+
+- TODO
+
+### Other backwards incompatible changes in 2.0
+
+- TODO
+
+## Deprecated features in 2.0
+
+- TODO

docs/releases/2.0.0.md

@@ -9,9 +9,20 @@ Each release note will tell you what's new in each version, and will also descri
 
 Below are release notes through StateMachine and its patch releases.
 
+###  2.0 release
+
+```{toctree}
+:maxdepth: 1
+
+2.0.0
+
+```
+
 
 ###  1.0 release
 
+This is the last release series to support Python 2.X series.
+
 ```{toctree}
 :maxdepth: 1
 

docs/releases/index.md

@@ -10,39 +10,63 @@
 
 # Transitions and events
 
-A machine moves from state to state through transitions. These transitions are
-caused by events.
+A state machine is typically composed of a set of {ref}`state`, {ref}`transition`, {ref}`event`,
+and {ref}`actions`. A state is a representation of the system's current condition or behavior.
+A transition represents the change in the system's state in response to an event or condition.
+An event is a trigger that causes the system to transition from one state to another, and action
+is any side-effect, which is the way a StateMachine can cause things to happen in the
+outside world.
 
 
-## Event
+Consider this traffic light machine as an example:
 
-An event is an external signal that something has happened.
-They are send to a state machine and allow the state machine to react.
+![TrafficLightMachine](images/traffic_light_machine.png)
 
-An event starts a {ref}`transition`, can be thought of as a "cause" that
-initiates a change in the state of the system.
 
-In python-statemachine, an event is specified as an attribute of the
-statemachine class declaration or directly on the {ref}`event` parameter on
-a {ref}`transition`.
+There're three transitions, one starting from green to yellow, another from
+yellow to red, and another from red back to green. All these transitions
+are triggered by the same {ref}`event` called `cycle`.
 
+This state machine could be expressed in `python-statemachine` as:
+
+```{literalinclude} ../tests/examples/traffic_light_machine.py
+:language: python
+:linenos:
+:emphasize-lines: 18
+```
+
+In line 18, you can say that this code defines three transitions:
+
+* `green.to(yellow)`
+* `yellow.to(red)`
+* `red.to(green)`
+
+And these transitions are assigned to the {ref}`event` `cycle` defined at the class level.
 
 ## Transition
 
-In an executing state machine, a transition is the instantaneous transfer
-from one state to another. In a state machine, a transition tells us what
-happens when an {ref}`event` occurs.
+In an executing state machine, a transition is a transfer from one state to another. In a state machine, a transition tells us what happens when an {ref}`event` occurs.
 
-A self transition is a transition that goes from and to the same state.
 
-A transition can define actions that will be executed whenever that transition
+```{tip}
+A transition can define {ref}`actions` that will be executed whenever that transition
 is executed.
 
+An action associated with an event (before, on, after), will be assigned to all transitions
+bounded that uses the event as trigger.
+```
+
 ```{eval-rst}
 .. autoclass:: statemachine.transition.Transition
     :members:
 ```
 
+```{hint}
+Usually you don't need to import and use a {ref}`transition` class directly in your code,
+one of the most powerful features of this library is now transitions and events can be expressed
+linking directly from/to {ref}`state` instances.
+```
+
 (self-transition)=
 
 ### Self transition
@@ -59,49 +83,104 @@ TransitionList([Transition(State('Draft', ...
 
 ```
 
-### Example
+### Internal transition
 
-Consider this traffic light machine as example:
+It's like a {ref}`self transition`.
 
-![TrafficLightMachine](images/traffic_light_machine.png)
+But in contrast to a self-transition, no entry or exit actions are ever executed as a result of an internal transition.
 
 
-There're three transitions, one starting from green to yellow, another from
-yellow to red, and another from red back to green. All these transitions
-are triggered by the same {ref}`event` called `cycle`.
+Syntax:
 
-This statemachine could be expressed in python-statemachine as:
+```py
+>>> draft = State("Draft")
 
+>>> draft.to.itself(internal=True)
+TransitionList([Transition(State('Draft', ...
 
-```{literalinclude} ../tests/examples/traffic_light_machine.py
-:language: python
-:linenos:
-:emphasize-lines: 18
 ```
 
-At line 18, you can say that this code defines three transitions:
+Example:
 
-* `green.to(yellow)`
-* `yellow.to(red)`
-* `red.to(green)`
+```py
+>>> class TestStateMachine(StateMachine):
+...     initial = State("initial", initial=True)
+...
+...     external_loop = initial.to.itself(on="do_something")
+...     internal_loop = initial.to.itself(internal=True, on="do_something")
+...
+...     def __init__(self):
+...         self.calls = []
+...         super().__init__()
+...
+...     def do_something(self):
+...         self.calls.append("do_something")
+...
+...     def on_exit_initial(self):
+...         self.calls.append("on_exit_initial")
+...
+...     def on_enter_initial(self):
+...         self.calls.append("on_enter_initial")
+
+```
+Usage:
+
+```py
+>>> sm = TestStateMachine()
+
+>>> sm._graph().write_png("docs/images/test_state_machine_internal.png")
+
+>>> sm.calls.clear()
+
+>>> sm.external_loop()
+
+>>> sm.calls
+['on_exit_initial', 'do_something', 'on_enter_initial']
+
+>>> sm.calls.clear()
+
+>>> sm.internal_loop()
 
-And these transitions are assigned to the {ref}`event` `cycle` defined at
-class level.
+>>> sm.calls
+['do_something']
 
-When an {ref}`event` is send to a statemachine:
+```
+
+![TestStateMachine](images/test_state_machine_internal.png)
+
+```{note}
+
+The internal transition is represented like an entry/exit action, where
+the event name is used to describe the transition.
+
+```
+
+
+## Event
+
+An event is an external signal that something has happened.
+They are sent to a state machine and allow the state machine to react.
+
+An event starts a {ref}`transition`, which can be thought of as a "cause" that
+initiates a change in the state of the system.
+
+In `python-statemachine`, an event is specified as an attribute of the state machine class declaration or directly on the {ref}`event` parameter on a {ref}`transition`.
 
-1. Uses the current {ref}`state` to check for available transitions.
-1. For each possible transition, it checks for those that matches the received {ref}`event`.
-1. The target state, if the transition succeeds, is determined by a transition
-   that an event matches and;
-1. All {ref}`validators-and-guards`, including {ref}`actions`
-   attached to the `on_<event>` and `before_<event>` callbacks.
+### Triggering events
 
+Triggering an event on a state machine means invoking or sending a signal, initiating the
+process that may result in executing a transition.
 
-## Triggering events
+This process usually involves checking the current state, evaluating any guard conditions
+associated with the transition, executing any actions associated with the transition and states,
+and finally updating the current state.
+
+```{seealso}
+See {ref}`actions` and {ref}`validators-and-guards`.
+```
 
 
-By direct calling the event:
+You can invoke the event in an imperative syntax:
 
 ```py
 >>> machine = TrafficLightMachine()
@@ -114,7 +193,7 @@ By direct calling the event:
 
 ```
 
-In a running (interpreted) machine, events are `send`:
+Or in an event-oriented style, events are `send`:
 
 ```py
 >>> machine.send("cycle")
@@ -126,8 +205,8 @@ In a running (interpreted) machine, events are `send`:
 ```
 
 You can also pass positional and keyword arguments, that will be propagated
-to the actions. On this example, the :code:`TrafficLightMachine` implements
-an action that `echoes` back the params informed.
+to the actions and guards. In this example, the :code:`TrafficLightMachine` implements
+an action that `echoes` back the parameters informed.
 
 ```{literalinclude} ../tests/examples/traffic_light_machine.py
     :language: python

docs/transitions.md

@@ -22,6 +22,9 @@ def __init__(self, func, suppress_errors=False):
     def __repr__(self):
         return "{}({!r})".format(type(self).__name__, self.func)
 
+    def __str__(self):
+        return getattr(self.func, "__name__", self.func)
+
     def __eq__(self, other):
         return self.func == getattr(other, "func", other)
 
@@ -60,6 +63,10 @@ def __init__(self, func, suppress_errors=False, expected_value=True):
         super().__init__(func, suppress_errors)
         self.expected_value = expected_value
 
+    def __str__(self):
+        name = super().__str__()
+        return name if self.expected_value else "!{}".format(name)
+
     def __call__(self, *args, **kwargs):
         return super().__call__(*args, **kwargs) == self.expected_value
 
@@ -75,6 +82,9 @@ def __repr__(self):
             type(self).__name__, self.items, self.factory
         )
 
+    def __str__(self):
+        return ", ".join(str(c) for c in self)
+
     def setup(self, resolver):
         """Validate configuracions"""
         self._resolver = resolver