Merge "Document process_event return and expose return namedtuple type"

automaton/machines.py

@@ -60,16 +60,17 @@ class FiniteMachine(object):
     transition. The other way to use this
     state machine is to skip using  :py:meth:`~automaton.runners.Runner.run`
     or :py:meth:`~automaton.runners.Runner.run_iter`
-    completely and use the :meth:`.process_event` method explicitly and
-    trigger the events via some *external* functionality/triggers...
+    completely and use the :meth:`~.FiniteMachine.process_event` method
+    explicitly and trigger the events via
+    some *external* functionality/triggers...
     """
 
-    # Result of processing an event (cause and effect...)
-    _Effect = collections.namedtuple('_Effect', 'reaction,terminal')
+    #: The result of processing an event (cause and effect...)
+    Effect = collections.namedtuple('Effect', 'reaction,terminal')
 
     @classmethod
     def _effect_builder(cls, new_state, event):
-        return cls._Effect(new_state['reactions'].get(event),
+        return cls.Effect(new_state['reactions'].get(event),
                           new_state["terminal"])
 
     @removals.removed_kwarg('default_start_state',
@@ -225,7 +226,17 @@ class FiniteMachine(object):
         return result
 
     def process_event(self, event):
-        """Trigger a state change in response to the provided event."""
+        """Trigger a state change in response to the provided event.
+
+        :returns: Effect this is either a :py:class:`.FiniteMachine.Effect` or
+                  an ``Effect`` from a subclass of :py:class:`.FiniteMachine`.
+                  See the appropriate named tuple for a description of the
+                  actual items in the tuple. For
+                  example, :py:class:`.FiniteMachine.Effect`'s
+                  first item is ``reaction``: one could invoke this reaction's
+                  callback to react to the new stable state.
+        :rtype: namedtuple
+        """
         self._pre_process_event(event)
         current = self._current
         replacement = self._transitions[current.name][event]
@@ -364,8 +375,8 @@ class FiniteMachine(object):
 class HierarchicalFiniteMachine(FiniteMachine):
     """A fsm that understands how to run in a hierarchical mode."""
 
-    # Result of processing an event (cause and effect...)
-    _Effect = collections.namedtuple('_Effect',
+    #: The result of processing an event (cause and effect...)
+    Effect = collections.namedtuple('Effect',
                                     'reaction,terminal,machine')
 
     def __init__(self, default_start_state=None):
@@ -375,7 +386,7 @@ class HierarchicalFiniteMachine(FiniteMachine):
 
     @classmethod
     def _effect_builder(cls, new_state, event):
-        return cls._Effect(new_state['reactions'].get(event),
+        return cls.Effect(new_state['reactions'].get(event),
                           new_state["terminal"], new_state.get('machine'))
 
     def add_state(self, state,