tinyfsm 0.0.1__tar.gz → 0.0.2__tar.gz

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

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: tinyfsm
-Version: 0.0.1
+Version: 0.0.2
 Summary: A tiny and minimal finite state machine for Python.
 License: MIT
+License-File: LICENSE.txt
 Author: Maciej Wiatrzyk
 Author-email: maciej.wiatrzyk@gmail.com
 Requires-Python: >=3.9,<4
@@ -13,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Description-Content-Type: text/markdown
 
 # TinyFSM
@@ -38,57 +40,42 @@ $ pip install tinyfsm
 
 ## Quickstart
 
-Below you'll find a simple text parser that split text into WORD and SPACE
-tokens, where WORD is a consecutive collection of alpha characters, and SPACE
-is consecutive collection of space characters:
+Here's a simple text tokenizer written using **TinyFSM** library that splits
+text composed of alphanumeric characters into groups of words and numbers and
+returns list of ``(token_name, token_data)`` tuples:
 
 ```python
-from tinyfsm.api import Traversal, StateMachineRunner, EventRejectedError
+from tinyfsm.api import Traversal, StateMachineRunner, InputRejectedError
 
-# Declaration of the state machine as list of Traversal objects.
-# Each object contains source state, destination state, and a function that
-# checks if current input (or event) should trigger state traversal.
 definition = [
-    Traversal[str]("initial", "word", lambda event: event.isalpha()),
-    Traversal[str]("initial", "space", lambda event: event == " "),
-    Traversal[str]("word", "word", lambda event: event.isalpha()),
-    Traversal[str]("word", "space", lambda event: event == " "),
-    Traversal[str]("word", "final", lambda event: event == ""),
-    Traversal[str]("space", "space", lambda event: event == " "),
-    Traversal[str]("space", "word", lambda event: event.isalpha()),
-    Traversal[str]("space", "final", lambda event: event == ""),
+    Traversal[str]("initial", "word", str.isalpha),
+    Traversal[str]("initial", "number", str.isdigit),
+    Traversal[str]("initial", "final", lambda input: input == ""),
+    Traversal[str]("word", "word", str.isalpha),
+    Traversal[str]("word", "number", str.isdigit),
+    Traversal[str]("word", "final", lambda input: input == ""),
+    Traversal[str]("number", "number", str.isdigit),
+    Traversal[str]("number", "word", str.isalpha),
+    Traversal[str]("number", "final", lambda input: input == ""),
 ]
 
 class Listener:
-    """Event listener for the state machine.
-
-    It listens for events like state change, or input value dispatching end.
-    Implementations (like this one) can use these methods to buffer inputs and
-    emit tokens.
-    """
-
     def __init__(self, output: list[tuple[str, str]]):
         self._output = output
         self._buffer = ""
 
-    def on_state_change(self, event: str, prev_state: str, current_state: str):
+    def on_state_change(self, input: str, prev_state: str, current_state: str):
         if prev_state != current_state:
             if prev_state == "word":
                 self._output.append(("WORD", self._buffer))
-            if prev_state == "space":
-                self._output.append(("SPACE", self._buffer))
+            if prev_state == "number":
+                self._output.append(("NUMBER", self._buffer))
             self._buffer = ""
 
-    def on_dispatch_done(self, event: str, current_state: str):
-        self._buffer += event
+    def on_dispatch_done(self, input: str, current_state: str):
+        self._buffer += input
 
 def tokenize(text: str) -> list[tuple[str, str]]:
-    """Tokenization function.
-
-    This is just an example, but in general a some sort of function gluing all
-    parts together is recommended. Here the function parses given text and
-    outputs list of tokens parsed from it.
-    """
     out = []
     listener = Listener(out)
     runner = StateMachineRunner(definition, listener)
@@ -99,3 +86,15 @@ def tokenize(text: str) -> list[tuple[str, str]]:
     return out
 ```
 
+And the tokenizer from above will split any text composed of just words and
+numbers into something like this:
+
+```python
+out = tokenize("foo123bar456")
+print(out)  # Would print: [("WORD", "foo"), ("NUMBER", "123"), ("WORD", "bar"), ("NUMBER", "456")]
+```
+
+# License
+
+This project is released under the terms of the MIT license.
+

tinyfsm-0.0.2/README.md

@@ -0,0 +1,80 @@
+# TinyFSM
+
+A tiny and minimal finite state machine for Python.
+
+## About
+
+**TinyFSM** is a fast and minimal finite state machine engine for Python. It
+runs the finite state defined as list of traversals, where each traversal is
+given by current and next state name and a traversal function that is evaluated
+on currently processed event. Once traversal function returns true, the current
+state is changed to the next state according to matched traversal.
+
+This library can be used as a backbone for creating larger scale FSM-based
+tokenizers and parsers.
+
+## Installation
+
+```shell
+$ pip install tinyfsm
+```
+
+## Quickstart
+
+Here's a simple text tokenizer written using **TinyFSM** library that splits
+text composed of alphanumeric characters into groups of words and numbers and
+returns list of ``(token_name, token_data)`` tuples:
+
+```python
+from tinyfsm.api import Traversal, StateMachineRunner, InputRejectedError
+
+definition = [
+    Traversal[str]("initial", "word", str.isalpha),
+    Traversal[str]("initial", "number", str.isdigit),
+    Traversal[str]("initial", "final", lambda input: input == ""),
+    Traversal[str]("word", "word", str.isalpha),
+    Traversal[str]("word", "number", str.isdigit),
+    Traversal[str]("word", "final", lambda input: input == ""),
+    Traversal[str]("number", "number", str.isdigit),
+    Traversal[str]("number", "word", str.isalpha),
+    Traversal[str]("number", "final", lambda input: input == ""),
+]
+
+class Listener:
+    def __init__(self, output: list[tuple[str, str]]):
+        self._output = output
+        self._buffer = ""
+
+    def on_state_change(self, input: str, prev_state: str, current_state: str):
+        if prev_state != current_state:
+            if prev_state == "word":
+                self._output.append(("WORD", self._buffer))
+            if prev_state == "number":
+                self._output.append(("NUMBER", self._buffer))
+            self._buffer = ""
+
+    def on_dispatch_done(self, input: str, current_state: str):
+        self._buffer += input
+
+def tokenize(text: str) -> list[tuple[str, str]]:
+    out = []
+    listener = Listener(out)
+    runner = StateMachineRunner(definition, listener)
+    with runner:
+        for char in text:
+            runner.dispatch(char)
+        runner.dispatch("")
+    return out
+```
+
+And the tokenizer from above will split any text composed of just words and
+numbers into something like this:
+
+```python
+out = tokenize("foo123bar456")
+print(out)  # Would print: [("WORD", "foo"), ("NUMBER", "123"), ("WORD", "bar"), ("NUMBER", "456")]
+```
+
+# License
+
+This project is released under the terms of the MIT license.

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

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

tinyfsm-0.0.2/tinyfsm/__init__.py

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

{tinyfsm-0.0.1 → tinyfsm-0.0.2}/tinyfsm/exc.py

@@ -11,38 +11,38 @@ class TinyFSMError(Exception):
 
 
 @export
-class EventRejectedError(TinyFSMError):
-    """Raised when event was rejected by the state machine.
+class InputRejectedError(TinyFSMError):
+    """Raised when input was rejected by the state machine.
 
-    Event is rejected only if there was no matching traversal found.
+    Input is rejected only if there was no matching traversal found or if all
+    traversal functions returned ``False`` for that input.
     """
 
-    #: The rejected event object.
-    event: Any
+    #: The rejected input object.
+    input: Any
 
     #: The current state name.
     current_state: str
 
-    def __init__(self, event: Any, current_state: str):
+    def __init__(self, input: Any, current_state: str):
         super().__init__()
-        self.event = event
+        self.input = input
         self.current_state = current_state
 
     def __str__(self) -> str:
-        return f"event {self.event!r} was rejected; no traversal found for current state {self.current_state!r}"
+        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 of event is incomplete, or that
-    the state machine definition is malformed and final state is
-    unreachable.
+    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 event.
-    last_event: Any
+    #: The last dispatched input.
+    last_input: Any
 
     #: The name of the final state.
     final_state: str
@@ -50,11 +50,11 @@ class FinalStateNotReached(TinyFSMError):
     #: The name of the current state.
     current_state: str
 
-    def __init__(self, last_event: Any, final_state: str, current_state: str):
+    def __init__(self, last_input: Any, final_state: str, current_state: str):
         super().__init__()
-        self.last_event = last_event
+        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 event was {self.last_event!r}"
+        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}"

{tinyfsm-0.0.1 → tinyfsm-0.0.2}/tinyfsm/interface.py

@@ -21,19 +21,16 @@ class Traversal(Generic[T]):
     state.
     """
 
-    #: Source event name.
-    src: str
+    #: Source state name.
+    source_state: str
 
-    #: Destination event name.
-    dest: str
+    #: Target state name.
+    target_state: str
 
-    #: Condition function.
-    #:
-    #: It will be called with the current event and if the return value is #:
-    #: ``True`` then state traversal from :attr:`src` to :attr:`dest`).is
-    #: performed. If the current state is not the source state, then the
-    #: function will not be called.
-    cond: Callable[[T], bool]
+    #: The function to be called for each input when current state is
+    #: :attr:`source_state`; if the function returns ``True``, current state is
+    #: changed to :attr:`target_state`.
+    traverse_func: Callable[[T], bool]
 
 
 @export
@@ -45,15 +42,15 @@ class StateMachineListener(Protocol, Generic[Tc]):
     use this to add events to internal buffers, queues etc.
     """
 
-    def on_state_change(self, event: Tc, prev_state: str, current_state: str):
-        """Triggered when *event* caused state traversal from *prev_state* to
+    def on_state_change(self, input: Tc, prev_state: str, current_state: str):
+        """Triggered when *input* caused state traversal from *prev_state* to
         *current_state*.
 
-        This will only be called if one of state traversal condition functions
-        returned ``True``.
+        This will only be called if one of traverse functions (see
+        :attr:`Traversal.traverse_func`) returned ``True``.
 
-        :param event:
-            The event that caused traversal.
+        :param input:
+            The input that caused traversal.
 
         :param prev_state:
             The name of a previous state.
@@ -63,14 +60,14 @@ class StateMachineListener(Protocol, Generic[Tc]):
         """
         ...
 
-    def on_dispatch_done(self, event: Tc, current_state: str):
-        """Triggered when event dispatching ends.
+    def on_dispatch_done(self, input: Tc, current_state: str):
+        """Triggered when input dispatching ends.
 
-        This method will be called for every successfully accepted event even
+        This method will be called for every successfully accepted input even
         if there was no state change.
 
-        :param event:
-            The event object.
+        :param input:
+            The input object.
 
         :param current_state:
             The name of the state the state machine was left in once *event*

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

@@ -1,7 +1,7 @@
 from typing import Generic, Optional, Sequence, TypeVar
 
 from . import _export_list
-from .exc import EventRejectedError, FinalStateNotReached
+from .exc import InputRejectedError, FinalStateNotReached
 from .interface import StateMachineListener, Traversal
 
 __all__ = export = _export_list.ExportList()  # type: ignore
@@ -66,11 +66,11 @@ class StateMachineRunner(Generic[T]):
         self.__traversal_map: dict[str, list[Traversal]] = {}
         has_initial = has_final = False
         for traversal in definition:
-            if traversal.src == initial_state:
+            if traversal.source_state == initial_state:
                 has_initial = True
-            if traversal.dest == final_state:
+            if traversal.target_state == final_state:
                 has_final = True
-            self.__traversal_map.setdefault(traversal.src, []).append(traversal)
+            self.__traversal_map.setdefault(traversal.source_state, []).append(traversal)
         if not has_initial:
             raise TypeError(f"no initial state found: {initial_state}")
         if not has_final:
@@ -79,7 +79,7 @@ class StateMachineRunner(Generic[T]):
         self.__initial_state = initial_state
         self.__final_state = final_state
         self.__current_state = self.__initial_state
-        self.__last_event: Optional[T] = None
+        self.__last_input: Optional[T] = None
 
     def __enter__(self) -> "StateMachineRunner":
         return self
@@ -89,42 +89,40 @@ class StateMachineRunner(Generic[T]):
             return None
         return self.close()
 
-    def dispatch(self, event: T):
-        """Dispatch event to the state machine.
+    def dispatch(self, input: T):
+        """Dispatch input to the state machine.
 
-        This should be called for each event, and state machine can either
-        accept the event, and maybe traverse to a different state in response
-        for that event, or reject it by raising :exc:`EventRejectedError`
-        exception.
+        This should be called for each input, and state machine can either
+        accept the input, and maybe traverse to a different state, or reject it
+        by raising :exc:`InputRejectedError` exception.
 
-        :param event:
-            The event object to dispatch.
+        :param input:
+            The current input to dispatch.
         """
-        self.__last_event = event
+        self.__last_input = input
         current_state_traversals = self.__traversal_map.get(self.__current_state)
         if current_state_traversals is None:
-            raise EventRejectedError(event, self.__current_state)
-        print(current_state_traversals)
+            raise InputRejectedError(input, self.__current_state)
         for traversal in current_state_traversals:
-            if traversal.cond(event):
-                next_state = traversal.dest
-                self.__listener.on_state_change(event, self.__current_state, next_state)
+            if traversal.traverse_func(input):
+                next_state = traversal.target_state
+                self.__listener.on_state_change(input, self.__current_state, next_state)
                 self.__current_state = next_state
                 break
         else:
-            raise EventRejectedError(event, self.__current_state)
-        self.__listener.on_dispatch_done(event, self.__current_state)
+            raise InputRejectedError(input, self.__current_state)
+        self.__listener.on_dispatch_done(input, self.__current_state)
 
     def close(self):
         """Close this state machine.
 
-        This method should be called after event dispatching ends. Its role is
-        to check if the final state was reached; if the final state was
-        reached, the method silently returns. Otherwise it raises
+        This method should be called shortly after all inputs are dispatched.
+        Its role is to ensure that the final state was reached; if the final
+        state was reached, the method silently returns. Otherwise it raises
         :exc:`tinyfsm.exc.FinalStateNotReached` error.
         """
         if not self.is_final():
-            raise FinalStateNotReached(self.__last_event, self.__final_state, self.__current_state)
+            raise FinalStateNotReached(self.__last_input, self.__final_state, self.__current_state)
 
     def is_final(self) -> bool:
         """Check if the final state is reached."""

tinyfsm-0.0.1/README.md

@@ -1,83 +0,0 @@
-# TinyFSM
-
-A tiny and minimal finite state machine for Python.
-
-## About
-
-**TinyFSM** is a fast and minimal finite state machine engine for Python. It
-runs the finite state defined as list of traversals, where each traversal is
-given by current and next state name and a traversal function that is evaluated
-on currently processed event. Once traversal function returns true, the current
-state is changed to the next state according to matched traversal.
-
-This library can be used as a backbone for creating larger scale FSM-based
-tokenizers and parsers.
-
-## Installation
-
-```shell
-$ pip install tinyfsm
-```
-
-## Quickstart
-
-Below you'll find a simple text parser that split text into WORD and SPACE
-tokens, where WORD is a consecutive collection of alpha characters, and SPACE
-is consecutive collection of space characters:
-
-```python
-from tinyfsm.api import Traversal, StateMachineRunner, EventRejectedError
-
-# Declaration of the state machine as list of Traversal objects.
-# Each object contains source state, destination state, and a function that
-# checks if current input (or event) should trigger state traversal.
-definition = [
-    Traversal[str]("initial", "word", lambda event: event.isalpha()),
-    Traversal[str]("initial", "space", lambda event: event == " "),
-    Traversal[str]("word", "word", lambda event: event.isalpha()),
-    Traversal[str]("word", "space", lambda event: event == " "),
-    Traversal[str]("word", "final", lambda event: event == ""),
-    Traversal[str]("space", "space", lambda event: event == " "),
-    Traversal[str]("space", "word", lambda event: event.isalpha()),
-    Traversal[str]("space", "final", lambda event: event == ""),
-]
-
-class Listener:
-    """Event listener for the state machine.
-
-    It listens for events like state change, or input value dispatching end.
-    Implementations (like this one) can use these methods to buffer inputs and
-    emit tokens.
-    """
-
-    def __init__(self, output: list[tuple[str, str]]):
-        self._output = output
-        self._buffer = ""
-
-    def on_state_change(self, event: str, prev_state: str, current_state: str):
-        if prev_state != current_state:
-            if prev_state == "word":
-                self._output.append(("WORD", self._buffer))
-            if prev_state == "space":
-                self._output.append(("SPACE", self._buffer))
-            self._buffer = ""
-
-    def on_dispatch_done(self, event: str, current_state: str):
-        self._buffer += event
-
-def tokenize(text: str) -> list[tuple[str, str]]:
-    """Tokenization function.
-
-    This is just an example, but in general a some sort of function gluing all
-    parts together is recommended. Here the function parses given text and
-    outputs list of tokens parsed from it.
-    """
-    out = []
-    listener = Listener(out)
-    runner = StateMachineRunner(definition, listener)
-    with runner:
-        for char in text:
-            runner.dispatch(char)
-        runner.dispatch("")
-    return out
-```

tinyfsm-0.0.1/tinyfsm/__init__.py

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