tinyfsm 0.0.2__tar.gz → 0.1.0__tar.gz

{tinyfsm-0.0.2 → tinyfsm-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyfsm
-Version: 0.0.2
+Version: 0.1.0
 Summary: A tiny and minimal finite state machine for Python.
 License: MIT
 License-File: LICENSE.txt

{tinyfsm-0.0.2 → tinyfsm-0.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tinyfsm"
-version = "0.0.2"
+version = "0.1.0"
 description = "A tiny and minimal finite state machine for Python."
 authors = [
     {name = "Maciej Wiatrzyk",email = "maciej.wiatrzyk@gmail.com"}

tinyfsm-0.1.0/tinyfsm/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tinyfsm-0.1.0/tinyfsm/exc.py

@@ -0,0 +1,107 @@
+from typing import Any, Sequence
+
+from . import _export_list
+
+__all__ = export = _export_list.ExportList()  # type: ignore
+
+
+@export
+class TinyFSMError(Exception):
+    """Common base class for all exception this library may raise."""
+
+
+@export
+class InconsistentDefinitionError(TinyFSMError):
+    """Raised when state machine definition is found to be inconsistent.
+
+    This means that no traversal was defined for the current state, i.e. there
+    is no next state to move to, no matter what the input will be.
+    """
+
+    #: The rejected input object.
+    input: Any
+
+    #: The current state name.
+    current_state: str
+
+    def __init__(self, input: Any, current_state: str):
+        super().__init__()
+        self.input = input
+        self.current_state = current_state
+
+    def __str__(self) -> str:
+        return f"input {self.input!r} was rejected; no next state defined for the current state {self.current_state!r}"
+
+
+@export
+class InputRejectedError(TinyFSMError):
+    """Raised when input was rejected by the state machine.
+
+    Input is rejected when it is not possible to deterministically choose the
+    next state for the current input.
+    """
+
+    #: The rejected input object.
+    input: Any
+
+    #: The current state name.
+    current_state: str
+
+    #: The candidate state names.
+    #:
+    #: These are names of the states that are accessible from the current state
+    #: given via :attr:`current_state`.
+    next_state_candidates: Sequence[str]
+
+    def __init__(self, input: Any, current_state: str, next_state_candidates: Sequence[str]):
+        super().__init__()
+        self.input = input
+        self.current_state = current_state
+        self.next_state_candidates = next_state_candidates
+
+    def __str__(self) -> str:
+        return (
+            f"input {self.input!r} was rejected; "
+            f"cannot traverse from {self.current_state!r} to any of: "
+            f"{', '.join(repr(x) for x in self.next_state_candidates)}"
+        )
+
+
+@export
+class FinalStateNotReached(TinyFSMError):
+    """Raised when closing state machine if final state was not reached.
+
+    This usually means that either the input sequence is incomplete and more
+    data is required to reach the final state. For example, a final state
+    requires text to end with a period, but a period is missing and no more
+    characters are fed into the state machine.
+    """
+
+    #: The last dispatched input.
+    last_input: Any
+
+    #: The name of the final state.
+    final_state: str
+
+    #: The name of the current state.
+    current_state: str
+
+    #: The candidate state names.
+    #:
+    #: These are names of the states that are accessible from the current state
+    #: given via :attr:`current_state`.
+    next_state_candidates: Sequence[str]
+
+    def __init__(self, last_input: Any, final_state: str, current_state: str, next_state_candidates: Sequence[str]):
+        super().__init__()
+        self.last_input = last_input
+        self.final_state = final_state
+        self.current_state = current_state
+        self.next_state_candidates = next_state_candidates
+
+    def __str__(self) -> str:
+        return (
+            f"final state {self.final_state!r} was not reached for last input {self.last_input!r}; "
+            f"more input data is expected to traverse from {self.current_state!r} "
+            f"to any of: {', '.join(repr(x) for x in self.next_state_candidates)}"
+        )

{tinyfsm-0.0.2 → tinyfsm-0.1.0}/tinyfsm/runner.py

@@ -1,7 +1,7 @@
 from typing import Generic, Optional, Sequence, TypeVar
 
 from . import _export_list
-from .exc import InputRejectedError, FinalStateNotReached
+from .exc import InconsistentDefinitionError, InputRejectedError, FinalStateNotReached
 from .interface import StateMachineListener, Traversal
 
 __all__ = export = _export_list.ExportList()  # type: ignore
@@ -102,7 +102,7 @@ class StateMachineRunner(Generic[T]):
         self.__last_input = input
         current_state_traversals = self.__traversal_map.get(self.__current_state)
         if current_state_traversals is None:
-            raise InputRejectedError(input, self.__current_state)
+            raise InconsistentDefinitionError(input, self.__current_state)
         for traversal in current_state_traversals:
             if traversal.traverse_func(input):
                 next_state = traversal.target_state
@@ -110,7 +110,8 @@ class StateMachineRunner(Generic[T]):
                 self.__current_state = next_state
                 break
         else:
-            raise InputRejectedError(input, self.__current_state)
+            next_state_candidates = tuple(x.target_state for x in current_state_traversals)
+            raise InputRejectedError(input, self.__current_state, next_state_candidates)
         self.__listener.on_dispatch_done(input, self.__current_state)
 
     def close(self):
@@ -122,7 +123,11 @@ class StateMachineRunner(Generic[T]):
         :exc:`tinyfsm.exc.FinalStateNotReached` error.
         """
         if not self.is_final():
-            raise FinalStateNotReached(self.__last_input, self.__final_state, self.__current_state)
+            current_state_traversals = self.__traversal_map.get(self.__current_state)
+            next_state_candidates = tuple(x.target_state for x in (current_state_traversals or []))
+            raise FinalStateNotReached(
+                self.__last_input, self.__final_state, self.__current_state, next_state_candidates
+            )
 
     def is_final(self) -> bool:
         """Check if the final state is reached."""

tinyfsm-0.0.2/tinyfsm/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.0.2"

tinyfsm-0.0.2/tinyfsm/exc.py

@@ -1,60 +0,0 @@
-from typing import Any
-
-from . import _export_list
-
-__all__ = export = _export_list.ExportList()  # type: ignore
-
-
-@export
-class TinyFSMError(Exception):
-    """Common base class for all exception this library may raise."""
-
-
-@export
-class InputRejectedError(TinyFSMError):
-    """Raised when input was rejected by the state machine.
-
-    Input is rejected only if there was no matching traversal found or if all
-    traversal functions returned ``False`` for that input.
-    """
-
-    #: The rejected input object.
-    input: Any
-
-    #: The current state name.
-    current_state: str
-
-    def __init__(self, input: Any, current_state: str):
-        super().__init__()
-        self.input = input
-        self.current_state = current_state
-
-    def __str__(self) -> str:
-        return f"input {self.input!r} was rejected; no traversal found for current state {self.current_state!r}"
-
-
-@export
-class FinalStateNotReached(TinyFSMError):
-    """Raised when closing state machine if final state was not reached.
-
-    This means that either the input sequence is incomplete, or that the state
-    machine definition is malformed and final state is unreachable.
-    """
-
-    #: The last dispatched input.
-    last_input: Any
-
-    #: The name of the final state.
-    final_state: str
-
-    #: The name of the current state.
-    current_state: str
-
-    def __init__(self, last_input: Any, final_state: str, current_state: str):
-        super().__init__()
-        self.last_input = last_input
-        self.final_state = final_state
-        self.current_state = current_state
-
-    def __str__(self) -> str:
-        return f"final state {self.final_state!r} was not reached; current state is {self.current_state!r}, last input was {self.last_input!r}"