tinyfsm 0.0.1__tar.gz

tinyfsm-0.0.1/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright 2026 Maciej Wiatrzyk <maciej.wiatrzyk@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tinyfsm-0.0.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.3
+Name: tinyfsm
+Version: 0.0.1
+Summary: A tiny and minimal finite state machine for Python.
+License: MIT
+Author: Maciej Wiatrzyk
+Author-email: maciej.wiatrzyk@gmail.com
+Requires-Python: >=3.9,<4
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+
+# 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/README.md

@@ -0,0 +1,83 @@
+# 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/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "tinyfsm"
+version = "0.0.1"
+description = "A tiny and minimal finite state machine for Python."
+authors = [
+    {name = "Maciej Wiatrzyk",email = "maciej.wiatrzyk@gmail.com"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.9,<4"
+dependencies = [
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "8.4.2"
+pytest-cov = "^7.1.0"
+mockify = "^0.14.0"
+invoke = "^3.0.3"
+ruff = "^0.15.14"
+bumpify = "^0.5.1"
+

tinyfsm-0.0.1/tinyfsm/__init__.py

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

tinyfsm-0.0.1/tinyfsm/_export_list.py

@@ -0,0 +1,10 @@
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+class ExportList(list):
+    def __call__(self, func_or_cls: T) -> T:
+        name = getattr(func_or_cls, "__name__")
+        self.append(name)
+        return func_or_cls

tinyfsm-0.0.1/tinyfsm/api.py

@@ -0,0 +1,13 @@
+from .runner import __all__ as _runner_all
+from .exc import __all__ as _exc_all
+from .interface import __all__ as _interface_all
+
+from .runner import *
+from .exc import *
+from .interface import *
+
+__all__ = (
+    *_runner_all,
+    *_exc_all,
+    *_interface_all,
+)  # type: ignore

tinyfsm-0.0.1/tinyfsm/exc.py

@@ -0,0 +1,60 @@
+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 EventRejectedError(TinyFSMError):
+    """Raised when event was rejected by the state machine.
+
+    Event is rejected only if there was no matching traversal found.
+    """
+
+    #: The rejected event object.
+    event: Any
+
+    #: The current state name.
+    current_state: str
+
+    def __init__(self, event: Any, current_state: str):
+        super().__init__()
+        self.event = event
+        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}"
+
+
+@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.
+    """
+
+    #: The last dispatched event.
+    last_event: Any
+
+    #: The name of the final state.
+    final_state: str
+
+    #: The name of the current state.
+    current_state: str
+
+    def __init__(self, last_event: Any, final_state: str, current_state: str):
+        super().__init__()
+        self.last_event = last_event
+        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}"

tinyfsm-0.0.1/tinyfsm/interface.py

@@ -0,0 +1,79 @@
+import dataclasses
+from typing import Callable, Generic, Protocol, TypeVar
+
+from . import _export_list
+
+__all__ = export = _export_list.ExportList()  # type: ignore
+
+T = TypeVar("T")
+
+Tc = TypeVar("Tc", contravariant=True)
+
+
+@export
+@dataclasses.dataclass
+class Traversal(Generic[T]):
+    """Object for creating state traversal definitions.
+
+    This is the basic building block for creating state machines. It is used to
+    declare source and destination states, and a traversal function that is
+    used to check if current event should cause traversal to the destination
+    state.
+    """
+
+    #: Source event name.
+    src: str
+
+    #: Destination event name.
+    dest: 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]
+
+
+@export
+class StateMachineListener(Protocol, Generic[Tc]):
+    """State machine listener protocol.
+
+    Defines interface to be used by custom state machine listeners receiving
+    notifications about event objects and state traversals. Implementations may
+    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
+        *current_state*.
+
+        This will only be called if one of state traversal condition functions
+        returned ``True``.
+
+        :param event:
+            The event that caused traversal.
+
+        :param prev_state:
+            The name of a previous state.
+
+        :param current_state:
+            The name of a current state.
+        """
+        ...
+
+    def on_dispatch_done(self, event: Tc, current_state: str):
+        """Triggered when event dispatching ends.
+
+        This method will be called for every successfully accepted event even
+        if there was no state change.
+
+        :param event:
+            The event object.
+
+        :param current_state:
+            The name of the state the state machine was left in once *event*
+            was processed.
+        """
+        ...

tinyfsm-0.0.1/tinyfsm/runner.py

@@ -0,0 +1,131 @@
+from typing import Generic, Optional, Sequence, TypeVar
+
+from . import _export_list
+from .exc import EventRejectedError, FinalStateNotReached
+from .interface import StateMachineListener, Traversal
+
+__all__ = export = _export_list.ExportList()  # type: ignore
+
+T = TypeVar("T")
+
+
+@export
+class StateMachineRunner(Generic[T]):
+    """State machine runner.
+
+    Each instance of this class can only parse single chain of events (as it
+    keeps the state between :meth:`dispatch` calls) and therefore a brand new
+    instance must be created to parse another chain of events.
+
+    You can feed state machine with events by using :meth:`dispatch` method.
+    Each dispatched event may cause state traversal, or event rejection (if the
+    input chain of events could not be parsed using defined state machine). It
+    is recommended, although not required, to call :meth:`close` once all the
+    events are dispatched.
+
+    The state machine can also be used as a context manager to automatically
+    call :meth:`close` on context exit::
+
+        sm = StateMachine(...)
+        with sm:
+            for event in sequence_of_events:
+                sm.dispatch(event)
+
+    :param definition:
+        State machine definition as a sequence of state traversals defined
+        using :class:`tinyfsm.interface.Traversal` objects.
+
+    :param listener:
+        Instance of :class:`StateMachineListener` protocol.
+
+        This object will receive notifications from the state machine once it
+        is processing events.
+
+    :param initial_state:
+        The name of the initial state.
+
+        It is required to have at least one initial state name used in the
+        state machine definition as a :attr:`tinyfsm.interface.Traversal.src`
+        attribute.
+
+    :param final_state:
+        The name of the final state.
+
+        It is required to have at least one final state name used in the state
+        machine definition as a :attr:`tinyfsm.interface.Traversal.dest`
+        attribute.
+    """
+
+    def __init__(
+        self,
+        definition: Sequence[Traversal[T]],
+        listener: StateMachineListener[T],
+        initial_state: str = "initial",
+        final_state: str = "final",
+    ):
+        self.__traversal_map: dict[str, list[Traversal]] = {}
+        has_initial = has_final = False
+        for traversal in definition:
+            if traversal.src == initial_state:
+                has_initial = True
+            if traversal.dest == final_state:
+                has_final = True
+            self.__traversal_map.setdefault(traversal.src, []).append(traversal)
+        if not has_initial:
+            raise TypeError(f"no initial state found: {initial_state}")
+        if not has_final:
+            raise TypeError(f"no final state found: {final_state}")
+        self.__listener = listener
+        self.__initial_state = initial_state
+        self.__final_state = final_state
+        self.__current_state = self.__initial_state
+        self.__last_event: Optional[T] = None
+
+    def __enter__(self) -> "StateMachineRunner":
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        if exc is not None:
+            return None
+        return self.close()
+
+    def dispatch(self, event: T):
+        """Dispatch event 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.
+
+        :param event:
+            The event object to dispatch.
+        """
+        self.__last_event = event
+        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)
+        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)
+                self.__current_state = next_state
+                break
+        else:
+            raise EventRejectedError(event, self.__current_state)
+        self.__listener.on_dispatch_done(event, 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
+        :exc:`tinyfsm.exc.FinalStateNotReached` error.
+        """
+        if not self.is_final():
+            raise FinalStateNotReached(self.__last_event, self.__final_state, self.__current_state)
+
+    def is_final(self) -> bool:
+        """Check if the final state is reached."""
+        return self.__current_state == self.__final_state