snanosm 1.0.0__tar.gz

snanosm-1.0.0/.coveragerc

@@ -0,0 +1,3 @@
+[run]
+omit =
+    tests/*

snanosm-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+.idea
+.venv
+**/__pycache__
+dist

snanosm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Studiosi
+
+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.

snanosm-1.0.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: snanosm
+Version: 1.0.0
+Summary: A pure python small Mealy state machine library
+Author-email: ITStudiosi <david@studiosi.es>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# SNanoSM
+
+A pure Python, minimalistic, and fully typed library for the implementation of **Mealy Finite State Machines**.
+
+Part of Nobody Industry's **MFFP (Made From First Principles)** set of libraries.
+
+---
+
+## Table of Contents
+1. [Overview & Core Concept](#overview--core-concept)
+2. [Installation](#installation)
+3. [Quick Start (Binary Inverter)](#quick-start-binary-inverter)
+4. [Advanced Usage (Sequence Detector & Fallback Matching)](#advanced-usage-sequence-detector--fallback-matching)
+5. [API Reference](#api-reference)
+6. [Testing & Verification](#testing--verification)
+
+---
+
+## Overview & Core Concept
+
+A **Mealy State Machine** is a finite-state machine whose output values are determined both by its current state and its current inputs. 
+
+In [mealy.py](src/snanosm/mealy.py), this is modeled by:
+- **States**: Unique nodes in the machine.
+- **Transitions**: Directed connections between states triggered by specific inputs.
+- **Action Functions (Outputs)**: Arbitrary callbacks associated with transitions that receive a mutable user-defined context object.
+
+> [!NOTE]
+> By passing a mutable context down to transition actions, you can build rich state-dependent behavior while keeping the machine's state logic simple and decoupled.
+
+---
+
+## Installation
+
+Since the library uses [pyproject.toml](pyproject.toml) with the Hatchling build backend, you can install it locally in editable mode or build it using standard tools:
+
+```bash
+# Install in editable mode
+pip install -e .
+
+# Or build the package
+python -m build
+```
+
+---
+
+## Quick Start (Binary Inverter)
+
+Here is a simple example demonstrating how to invert a binary string (`"0"` becomes `"1"`, `"1"` becomes `"0"`) using [inverter.py](examples/inverter.py).
+
+```python
+from typing import Tuple, TypedDict
+from snanosm.mealy import Machine
+
+# Define a context to hold our state machine's output and metadata
+class Context(TypedDict):
+    result: str
+    n_chars: int
+
+def add_to_result(context: Context, c: str) -> None:
+    context["result"] += c
+    context["n_chars"] += 1
+
+def inverter(input_string: str) -> Tuple[str, int]:
+    # Initialize the mutable context
+    context: Context = {
+        "result": "",
+        "n_chars": 0
+    }
+    
+    # Create the machine with the context
+    m = Machine(context)
+    
+    # Add a start state "S"
+    m.add_state("S", is_start_state=True)
+    
+    # Define transitions: when in state "S" and input is "0", execute action and stay in "S"
+    m.add_transition("0", "S", "S", lambda ctx: add_to_result(ctx, "1"))
+    m.add_transition("1", "S", "S", lambda ctx: add_to_result(ctx, "0"))
+    
+    # Process inputs sequentially
+    for c in input_string:
+        m.process_input(c)
+        
+    return context["result"], context["n_chars"]
+
+if __name__ == '__main__':
+    res, count = inverter("000011110010")
+    print(f"Result: {res}, Characters processed: {count}")
+    # Output: Result: 111100001101, Characters processed: 12
+```
+
+---
+
+## Advanced Usage (Sequence Detector & Fallback Matching)
+
+The sequence detector in [detector.py](examples/detector.py) searches for the substring `"AB"` within a stream of characters. It illustrates the use of `TransitionInputEnum` to define catch-all transitions when no specific input matches.
+
+```python
+from typing import TypedDict
+from snanosm.mealy import Machine, TransitionInputEnum
+
+class Context(TypedDict):
+    count: int
+    position: int
+    matches: int
+
+def dinc(context: Context):
+    context["count"] += 1
+
+def dset(context: Context):
+    context["position"] = context["count"]
+    context["count"] += 1
+
+def dprn(context: Context):
+    context["count"] += 1
+    print(f"SUBSTRING FOUND AT POSITION: {context['position']}")
+    context["matches"] += 1
+
+def detector(input_string: str) -> int:
+    initial_context: Context = {
+        "count": 0,
+        "position": 0,
+        "matches": 0,
+    }
+    
+    m = Machine(initial_context)
+    m.add_state("Q0", is_start_state=True)
+    m.add_state("Q1")
+    
+    # Q0 -> Q1 on 'A', saving the start position
+    m.add_transition("A", "Q0", "Q1", lambda context: dset(context))
+    # Catch-all transition: Q0 -> Q0 for any input other than 'A'
+    m.add_transition(TransitionInputEnum.MATCH_REST, "Q0", "Q0", lambda context: dinc(context))
+    
+    # Q1 -> Q0 on 'B', printing match information
+    m.add_transition("B", "Q1", "Q0", lambda context: dprn(context))
+    # Catch-all transition: Q1 -> Q0 for any input other than 'B'
+    m.add_transition(TransitionInputEnum.MATCH_REST, "Q1", "Q0", lambda context: dinc(context))
+    
+    for c in input_string:
+        m.process_input(c)
+        
+    return initial_context["matches"]
+```
+
+---
+
+## API Reference
+
+### Core Abstractions
+
+| Class/Type | Description |
+| :--- | :--- |
+| `InputProtocol` | A typing protocol requiring `__eq__` and `__hash__`. Any hashable, equatable Python object can serve as machine input. |
+| `TransitionInputEnum` | Enum containing special transition inputs (e.g., `MATCH_REST`). |
+| `State` | Represents a state node in the state machine. |
+| `Transition` | Represents an edge between states triggered by a transition input. |
+| `Machine` | The core finite state machine runner. |
+
+---
+
+### API Details
+
+#### `InputProtocol`
+```python
+class InputProtocol(Protocol):
+    def __eq__(self, __o: Self) -> bool: ...
+    def __hash__(self) -> int: ...
+```
+Any custom object used as an input to `Machine.process_input` must implement this protocol (or be natively hashable and equatable, e.g. strings, integers, frozen dataclasses).
+
+#### `TransitionInputEnum`
+- `MATCH_REST`: Activates if no matching transition input is found for the current state. Useful for defining default fallback transitions.
+
+#### `State`
+- `get_name() -> str`: Returns the state's name.
+- `__str__() -> str`: Returns `[State <state_name>]`.
+
+#### `Transition`
+- `execute_output(context)`: Executes the output callback if it was supplied.
+- `get_destination_name_hash() -> int`: Returns the hash of the destination state name.
+- `__str__() -> str`: Returns `[Transition (<origin>, <destination>, <input>)]`.
+
+#### `Machine`
+- `__init__(initial_context: object = None)`: Initializes the machine. Sets up the configuration using an optional initial context. If not provided, an empty dict `{}` is instantiated.
+- `add_state(state_name: str, is_start_state: bool = False, is_end_state: bool = False) -> None`: Registers a new state node in the machine.
+  > [!WARNING]
+  > State names must not start with `#` (reserved for internal configurations). A machine cannot have multiple start states.
+- `add_transition(transition_input: TransitionInput, origin_name: str, destination_name: str, output_function: Optional[Callable[[Optional[object]], None]]) -> None`: Registers a transition edge between two existing states.
+  - `transition_input`: An input conforming to `InputProtocol` or `TransitionInputEnum`.
+  - `output_function`: A callable accepting context, run upon transitioning.
+- `process_input(i: Input) -> None`: Processes a single input token. It evaluates transitions registered under the current state.
+  - If a transition matching `i` is registered, it will be executed.
+  - If no matching transition is found but a `MATCH_REST` transition is registered, that fallback is executed.
+  - If no valid transition is found, it raises a `ValueError`.
+- `reset() -> None`: Resets the state machine's active state back to the start state, and re-assigns the context back to `initial_context`.
+- `get_current_state() -> Optional[State]`: Returns the current `State` object, or `None` if the machine has not started or processed any inputs.
+- `is_in_final_state() -> bool`: Returns `True` if the machine's current state is registered as an end state.
+- `__str__() -> str`: Returns a structured string layout of the machine structure, lists of states, and transitions.
+
+---
+
+## Testing & Verification
+
+Unit tests are located in [test_mealy.py](tests/test_mealy.py). To run the test suite, navigate to the project directory and execute:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```

snanosm-1.0.0/README.md

@@ -0,0 +1,210 @@
+# SNanoSM
+
+A pure Python, minimalistic, and fully typed library for the implementation of **Mealy Finite State Machines**.
+
+Part of Nobody Industry's **MFFP (Made From First Principles)** set of libraries.
+
+---
+
+## Table of Contents
+1. [Overview & Core Concept](#overview--core-concept)
+2. [Installation](#installation)
+3. [Quick Start (Binary Inverter)](#quick-start-binary-inverter)
+4. [Advanced Usage (Sequence Detector & Fallback Matching)](#advanced-usage-sequence-detector--fallback-matching)
+5. [API Reference](#api-reference)
+6. [Testing & Verification](#testing--verification)
+
+---
+
+## Overview & Core Concept
+
+A **Mealy State Machine** is a finite-state machine whose output values are determined both by its current state and its current inputs. 
+
+In [mealy.py](src/snanosm/mealy.py), this is modeled by:
+- **States**: Unique nodes in the machine.
+- **Transitions**: Directed connections between states triggered by specific inputs.
+- **Action Functions (Outputs)**: Arbitrary callbacks associated with transitions that receive a mutable user-defined context object.
+
+> [!NOTE]
+> By passing a mutable context down to transition actions, you can build rich state-dependent behavior while keeping the machine's state logic simple and decoupled.
+
+---
+
+## Installation
+
+Since the library uses [pyproject.toml](pyproject.toml) with the Hatchling build backend, you can install it locally in editable mode or build it using standard tools:
+
+```bash
+# Install in editable mode
+pip install -e .
+
+# Or build the package
+python -m build
+```
+
+---
+
+## Quick Start (Binary Inverter)
+
+Here is a simple example demonstrating how to invert a binary string (`"0"` becomes `"1"`, `"1"` becomes `"0"`) using [inverter.py](examples/inverter.py).
+
+```python
+from typing import Tuple, TypedDict
+from snanosm.mealy import Machine
+
+# Define a context to hold our state machine's output and metadata
+class Context(TypedDict):
+    result: str
+    n_chars: int
+
+def add_to_result(context: Context, c: str) -> None:
+    context["result"] += c
+    context["n_chars"] += 1
+
+def inverter(input_string: str) -> Tuple[str, int]:
+    # Initialize the mutable context
+    context: Context = {
+        "result": "",
+        "n_chars": 0
+    }
+    
+    # Create the machine with the context
+    m = Machine(context)
+    
+    # Add a start state "S"
+    m.add_state("S", is_start_state=True)
+    
+    # Define transitions: when in state "S" and input is "0", execute action and stay in "S"
+    m.add_transition("0", "S", "S", lambda ctx: add_to_result(ctx, "1"))
+    m.add_transition("1", "S", "S", lambda ctx: add_to_result(ctx, "0"))
+    
+    # Process inputs sequentially
+    for c in input_string:
+        m.process_input(c)
+        
+    return context["result"], context["n_chars"]
+
+if __name__ == '__main__':
+    res, count = inverter("000011110010")
+    print(f"Result: {res}, Characters processed: {count}")
+    # Output: Result: 111100001101, Characters processed: 12
+```
+
+---
+
+## Advanced Usage (Sequence Detector & Fallback Matching)
+
+The sequence detector in [detector.py](examples/detector.py) searches for the substring `"AB"` within a stream of characters. It illustrates the use of `TransitionInputEnum` to define catch-all transitions when no specific input matches.
+
+```python
+from typing import TypedDict
+from snanosm.mealy import Machine, TransitionInputEnum
+
+class Context(TypedDict):
+    count: int
+    position: int
+    matches: int
+
+def dinc(context: Context):
+    context["count"] += 1
+
+def dset(context: Context):
+    context["position"] = context["count"]
+    context["count"] += 1
+
+def dprn(context: Context):
+    context["count"] += 1
+    print(f"SUBSTRING FOUND AT POSITION: {context['position']}")
+    context["matches"] += 1
+
+def detector(input_string: str) -> int:
+    initial_context: Context = {
+        "count": 0,
+        "position": 0,
+        "matches": 0,
+    }
+    
+    m = Machine(initial_context)
+    m.add_state("Q0", is_start_state=True)
+    m.add_state("Q1")
+    
+    # Q0 -> Q1 on 'A', saving the start position
+    m.add_transition("A", "Q0", "Q1", lambda context: dset(context))
+    # Catch-all transition: Q0 -> Q0 for any input other than 'A'
+    m.add_transition(TransitionInputEnum.MATCH_REST, "Q0", "Q0", lambda context: dinc(context))
+    
+    # Q1 -> Q0 on 'B', printing match information
+    m.add_transition("B", "Q1", "Q0", lambda context: dprn(context))
+    # Catch-all transition: Q1 -> Q0 for any input other than 'B'
+    m.add_transition(TransitionInputEnum.MATCH_REST, "Q1", "Q0", lambda context: dinc(context))
+    
+    for c in input_string:
+        m.process_input(c)
+        
+    return initial_context["matches"]
+```
+
+---
+
+## API Reference
+
+### Core Abstractions
+
+| Class/Type | Description |
+| :--- | :--- |
+| `InputProtocol` | A typing protocol requiring `__eq__` and `__hash__`. Any hashable, equatable Python object can serve as machine input. |
+| `TransitionInputEnum` | Enum containing special transition inputs (e.g., `MATCH_REST`). |
+| `State` | Represents a state node in the state machine. |
+| `Transition` | Represents an edge between states triggered by a transition input. |
+| `Machine` | The core finite state machine runner. |
+
+---
+
+### API Details
+
+#### `InputProtocol`
+```python
+class InputProtocol(Protocol):
+    def __eq__(self, __o: Self) -> bool: ...
+    def __hash__(self) -> int: ...
+```
+Any custom object used as an input to `Machine.process_input` must implement this protocol (or be natively hashable and equatable, e.g. strings, integers, frozen dataclasses).
+
+#### `TransitionInputEnum`
+- `MATCH_REST`: Activates if no matching transition input is found for the current state. Useful for defining default fallback transitions.
+
+#### `State`
+- `get_name() -> str`: Returns the state's name.
+- `__str__() -> str`: Returns `[State <state_name>]`.
+
+#### `Transition`
+- `execute_output(context)`: Executes the output callback if it was supplied.
+- `get_destination_name_hash() -> int`: Returns the hash of the destination state name.
+- `__str__() -> str`: Returns `[Transition (<origin>, <destination>, <input>)]`.
+
+#### `Machine`
+- `__init__(initial_context: object = None)`: Initializes the machine. Sets up the configuration using an optional initial context. If not provided, an empty dict `{}` is instantiated.
+- `add_state(state_name: str, is_start_state: bool = False, is_end_state: bool = False) -> None`: Registers a new state node in the machine.
+  > [!WARNING]
+  > State names must not start with `#` (reserved for internal configurations). A machine cannot have multiple start states.
+- `add_transition(transition_input: TransitionInput, origin_name: str, destination_name: str, output_function: Optional[Callable[[Optional[object]], None]]) -> None`: Registers a transition edge between two existing states.
+  - `transition_input`: An input conforming to `InputProtocol` or `TransitionInputEnum`.
+  - `output_function`: A callable accepting context, run upon transitioning.
+- `process_input(i: Input) -> None`: Processes a single input token. It evaluates transitions registered under the current state.
+  - If a transition matching `i` is registered, it will be executed.
+  - If no matching transition is found but a `MATCH_REST` transition is registered, that fallback is executed.
+  - If no valid transition is found, it raises a `ValueError`.
+- `reset() -> None`: Resets the state machine's active state back to the start state, and re-assigns the context back to `initial_context`.
+- `get_current_state() -> Optional[State]`: Returns the current `State` object, or `None` if the machine has not started or processed any inputs.
+- `is_in_final_state() -> bool`: Returns `True` if the machine's current state is registered as an end state.
+- `__str__() -> str`: Returns a structured string layout of the machine structure, lists of states, and transitions.
+
+---
+
+## Testing & Verification
+
+Unit tests are located in [test_mealy.py](tests/test_mealy.py). To run the test suite, navigate to the project directory and execute:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```

snanosm-1.0.0/examples/detector.py

@@ -0,0 +1,52 @@
+from typing import TypedDict
+
+from snanosm.mealy import Machine, TransitionInputEnum
+
+
+class Context(TypedDict):
+    count: int
+    position: int
+    matches: int
+
+
+def dinc(context: Context):
+    context["count"] += 1
+
+def dset(context: Context):
+    context["position"] = context["count"]
+    context["count"] += 1
+
+def dprn(context: Context):
+    context["count"] += 1
+    print(f"SUBSTRING FOUND AT POSITION: {context['position']}")
+    context["matches"] += 1
+
+
+# Detects the sequence AB in the string, printing the position and returning the amount of matches
+def detector(input_string: str) -> int:
+    initial_context: Context = {
+        "count": 0,
+        "position": 0,
+        "matches": 0,
+    }
+    m = Machine(initial_context)
+    m.add_state("Q0", True, False)
+    m.add_state("Q1", False, False)
+    m.add_transition("A", "Q0", "Q1", lambda context: dset(context))
+    m.add_transition(TransitionInputEnum.MATCH_REST, "Q0", "Q0", lambda context: dinc(context))
+    m.add_transition("B", "Q1", "Q0", lambda context: dprn(context))
+    m.add_transition(TransitionInputEnum.MATCH_REST, "Q1", "Q0", lambda context: dinc(context))
+    for c in input_string:
+        m.process_input(c)
+    return initial_context["matches"]
+
+if __name__ == "__main__":
+    print("== 1 ==")
+    n = detector("AAAAAAABAAAAAB")
+    print(f"Matches: {n}")
+    print("== 2 ==")
+    n = detector("AAAA")
+    print(f"Matches: {n}")
+    print("== 3 ==")
+    n = detector("ABCCBBACAB")
+    print(f"Matches: {n}")

snanosm-1.0.0/examples/inverter.py

@@ -0,0 +1,27 @@
+from typing import Tuple, TypedDict
+
+from snanosm.mealy import Machine
+
+class Context(TypedDict):
+    result: str
+    n_chars: int
+
+def add_to_result(context: Context, c: str) -> None:
+    context["result"] += c
+    context["n_chars"] += 1
+
+def inverter(input_string: str) -> Tuple[str, int]:
+    context: Context = {
+        "result": "",
+        "n_chars": 0
+    }
+    m = Machine(context)
+    m.add_state("S", True, False)
+    m.add_transition("0", "S", "S", lambda ctx: add_to_result(ctx, "1"))
+    m.add_transition("1", "S", "S", lambda ctx: add_to_result(ctx, "0"))
+    for c in input_string:
+        m.process_input(c)
+    return context["result"], context["n_chars"]
+
+if __name__ == '__main__':
+    print(inverter("000011110010"))

snanosm-1.0.0/publish.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+python3 -m build
+python3 -m twine upload --repository pypi dist/*

snanosm-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "snanosm"
+version = "1.0.0"
+authors = [
+  { name="ITStudiosi", email="david@studiosi.es" },
+]
+description = "A pure python small Mealy state machine library"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Development Status :: 2 - Pre-Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed"
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]

snanosm-1.0.0/src/snanosm/mealy.py

@@ -0,0 +1,154 @@
+from enum import Enum
+from typing import Optional, Callable, Protocol, Self, TypeVar, Generic, List, Union
+
+
+# Anything hashable and equatable can be used as an input
+class InputProtocol(Protocol):
+    def __eq__(self, __o: Self) -> bool:
+        ...
+
+    def __hash__(self) -> int:
+        ...
+
+
+class TransitionInputEnum(Enum):
+    MATCH_REST = "#TRANSITION_MATCH_REST"
+
+
+Input = TypeVar("Input", bound=InputProtocol)
+TransitionInput = TypeVar("TransitionInput", bound=Union[InputProtocol, TransitionInputEnum])
+
+
+class State:
+    def __init__(self, name: str) -> None:
+        self.__name = name
+
+    def get_name(self) -> str:
+        return self.__name
+
+    def __str__(self) -> str:
+        return f"[State {self.__name}]"
+
+
+class Transition(Generic[TransitionInput]):
+    def __init__(self, transition_input: TransitionInput, origin_name: str, destination_name: str,
+                 output_function: Optional[Callable[[Optional[object]], None]]) -> None:
+        self.__transition_input = transition_input
+        self.__origin_name = origin_name
+        self.__destination_name = destination_name
+        self.__destination_name_hash = hash(destination_name)
+        self.__output_function = output_function
+
+    def execute_output(self, context):
+        if self.__output_function is not None:
+            self.__output_function(context)
+
+    def get_destination_name_hash(self) -> int:
+        return self.__destination_name_hash
+
+    def __str__(self) -> str:
+        return f"[Transition ({self.__origin_name}, {self.__destination_name}, {self.__transition_input})]"
+
+
+class Machine(Generic[Input]):
+    def __init__(self, initial_context: object = None) -> None:
+        if initial_context is None:
+            initial_context = {}
+        self.__start_state_hash: Optional[int] = None
+        self.__end_states: List[int] = []
+        self.__current_state_hash: Optional[int] = None
+        self.__states: dict[int, State] = {}
+        # dict[hash_origin, dict[hash_transition_input, Transition]]
+        self.__transitions: dict[int, dict[int, Transition]] = {}
+        self.__initial_context = initial_context
+        self.__context = initial_context
+
+    def add_transition(self, transition_input: TransitionInput, origin_name: str, destination_name: str,
+                       output_function: Optional[Callable[[Optional[object]], None]]) -> None:
+        ho = hash(origin_name)
+        if ho not in self.__states.keys():
+            raise ValueError(f"Origin state {origin_name} does not exist.")
+        hd = hash(destination_name)
+        if hd not in self.__states.keys():
+            raise ValueError(f"Destination state {destination_name} does not exist.")
+        if isinstance(transition_input, TransitionInputEnum):
+            hi = hash(transition_input.name)
+        else:
+            hi = hash(transition_input)
+        t = Transition(transition_input, origin_name, destination_name, output_function)
+        if ho not in self.__transitions.keys():
+            self.__transitions[ho] = {hi: t}
+        elif hi not in self.__transitions[ho]:
+            self.__transitions[ho][hi] = t
+        elif hi in self.__transitions[ho]:
+            raise ValueError(f"Transition already exists for origin state {origin_name} and transition input {transition_input}.")
+
+    def add_state(self, state_name: str, is_start_state: bool = False, is_end_state: bool = False) -> None:
+        if state_name.startswith("#"):
+            raise ValueError("State names cannot start with # (reserved for special states)")
+        h: int = hash(state_name)
+        if is_start_state:
+            if self.__start_state_hash is None:
+                self.__start_state_hash = h
+            else:
+                raise ValueError("Adding a start state when one is already set.")
+        if is_end_state:
+            # Multiple end states possible
+            self.__end_states.append(h)
+        if h in self.__states.keys():
+            raise ValueError(f"State {state_name} already exists.")
+        state = State(state_name)
+        self.__states[h] = state
+
+    def process_input(self, i: Input) -> None:
+        if self.__start_state_hash is None:
+            raise ValueError("Processing input without a start state.")
+        if self.__current_state_hash is None:
+            self.__current_state_hash = self.__start_state_hash
+        # dict[hash_origin, dict[hash_transition_input, Transition]]
+        if self.__current_state_hash not in self.__transitions.keys():
+            raise ValueError("Processing input for a state with no transitions.")
+        assert self.__current_state_hash is not None
+        transitions = self.__transitions[self.__current_state_hash]
+        hi = hash(i)
+        transition: Optional[Transition] = None
+        if hi in transitions.keys():
+            # Transition found: execute and move to the destination state
+            transition = transitions[hi]
+        # No transition found, check if there's a special transition
+        if transition is None:
+            hc = hash(TransitionInputEnum.MATCH_REST)
+            if hc in transitions.keys():
+                transition = transitions[hc]
+            else:
+                raise ValueError(f"Found invalid transition while processing input {i} [{transition}].]")
+        assert transition is not None
+        transition.execute_output(self.__context)
+        self.__current_state_hash = transition.get_destination_name_hash()
+
+    def reset(self) -> None:
+        if self.__start_state_hash is None:
+            raise ValueError("Resetting a machine without starting state.")
+        self.__current_state_hash = self.__start_state_hash
+        self.__context = self.__initial_context
+
+    def get_current_state(self) -> Optional[State]:
+        if self.__current_state_hash is None:
+            return None # The machine has not started yet
+        return self.__states[self.__current_state_hash]
+
+    def is_in_final_state(self) -> bool:
+        if self.__current_state_hash is None:
+            return False
+        assert self.__current_state_hash is not None
+        return self.__current_state_hash in self.__end_states
+
+    def __str__(self) -> str:
+        r = [f"=MACHINE=", "\tSTATES"]
+        for state in self.__states.values():
+            r.append(f"\t\t{str(state)}")
+        r.append("\tTRANSITIONS")
+        for transition_origin in self.__transitions.keys():
+            for transition_input in self.__transitions[transition_origin]:
+                r.append(f"\t\t{str(self.__transitions[transition_origin][transition_input])}")
+        return "\n".join(r)

snanosm-1.0.0/tests/test_mealy.py

@@ -0,0 +1,254 @@
+from dataclasses import dataclass
+import unittest
+
+from snanosm.mealy import Machine, TransitionInputEnum, State, Transition
+
+
+# Any hashable and equatable object should suffice
+@dataclass(frozen=True)
+class TestTransitionObject:
+    attribute: str
+
+
+class TestMachine(unittest.TestCase):
+
+    def test_init(self):
+        m = Machine()
+        self.assertIsNotNone(m)
+
+    # ADD STATE
+
+    def test_add_state_two_start_states(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        with self.assertRaises(ValueError):
+            m.add_state("B", True, False)
+
+    def test_add_two_end_states(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_state("C", False, True)
+
+    def test_add_state_with_reserved_name(self):
+        m = Machine()
+        with self.assertRaises(ValueError):
+            m.add_state("#INVALID_STATE_NAME", True, False)
+
+    def test_add_state_with_duplicate_state_name(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        with self.assertRaises(ValueError):
+            m.add_state("A", False, True)
+
+    # ADD TRANSITION
+
+    def test_add_transition(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition("X", "A", "B", lambda context: print(context))
+
+    def test_add_transition_non_existent_origin_state(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        with self.assertRaises(ValueError):
+            m.add_transition("X", "C", "B", lambda context: print(context))
+
+    def test_add_transition_non_existent_destination_state(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        with self.assertRaises(ValueError):
+            m.add_transition("X", "A", "C", lambda context: print(context))
+
+    def test_add_special_transition(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition(TransitionInputEnum.MATCH_REST, "A", "B", lambda context: print(context))
+
+    def test_add_several_transitions_with_same_origin(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition("X", "A", "B", lambda context: print("1"))
+        m.add_transition("Y", "A", "B", lambda context: print("2"))
+
+    def test_add_duplicate_transition(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition("X", "A", "B", lambda context: print("1"))
+        with self.assertRaises(ValueError):
+            m.add_transition("X", "A", "B", lambda context: print("2"))
+
+    # PROCESS INPUT
+
+    def test_process_input(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, False)
+        m.add_state("C", False, True)
+        m.add_transition("X", "A", "B", lambda context: print("TEST_PROCESS_INPUT: Transition 1"))
+        m.add_transition("X", "B", "C", lambda context: print("TEST_PROCESS_INPUT: Transition 2"))
+        m.process_input("X")
+        m.process_input("X")
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "C")
+
+    def test_process_input_no_start_state(self):
+        m = Machine()
+        m.add_state("A", False, False)
+        m.add_state("B", False, False)
+        m.add_transition("X", "A", "B", lambda context: print("TEST_PROCESS_INPUT_NO_START_DATE: Transition"))
+        with self.assertRaises(ValueError):
+            m.process_input("X")
+
+    def test_process_input_state_without_transitions(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition("X", "A", "B", lambda context: print("TEST_PROCESS_INPUT_WITHOUT_TRANSITIONS: Transition"))
+        m.process_input("X")
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "B")
+        with self.assertRaises(ValueError):
+            m.process_input("X")
+
+    def test_process_input_catch_all_transition(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition(TransitionInputEnum.MATCH_REST, "A", "B", lambda context: print("A -> B"))
+        m.add_transition(TransitionInputEnum.MATCH_REST, "B", "A", lambda context: print("B -> A"))
+        m.process_input("X")
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "B")
+        m.process_input(1)
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "A")
+        m.process_input(TestTransitionObject("X"))
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "B")
+
+    def test_process_input_with_objects(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, False)
+        m.add_state("C", False, True)
+        m.add_transition(TestTransitionObject("TEST_1"), "A", "B", lambda context: print("A -> B"))
+        m.add_transition(TestTransitionObject("TEST_2"), "B", "C", lambda context: print("B -> C"))
+        m.process_input(TestTransitionObject("TEST_1"))
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "B")
+        m.process_input(TestTransitionObject("TEST_2"))
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "C")
+
+    def test_process_input_invalid_transition(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition("X", "A", "B", lambda context: print("A -> B"))
+        with self.assertRaises(ValueError):
+            m.process_input("Y")
+
+    # GET CURRENT STATE
+    def test_get_current_state_machine_not_started(self):
+        m = Machine()
+        state = m.get_current_state()
+        self.assertIsNone(state)
+
+    def test_get_current_state_machine_started(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition("X", "A", "B", lambda context: print("A -> B"))
+        m.process_input("X")
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "B")
+
+    # RESET
+
+    def test_reset(self):
+        m = Machine()
+        m.add_state("C", True, False)
+        m.add_state("D", False, True)
+        m.add_transition("X", "C", "D", lambda context: print("A -> B"))
+        m.process_input("X")
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "D")
+        m.reset()
+        current_state = m.get_current_state()
+        self.assertIsNotNone(current_state)
+        assert current_state is not None
+        self.assertEqual(current_state.get_name(), "C")
+
+    def test_reset_no_start_state(self):
+        m = Machine()
+        m.add_state("A", False, False)
+        with self.assertRaises(ValueError):
+            m.reset()
+
+    # IS_IN_FINAL_STATE
+
+    def test_is_in_final_state(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, True)
+        m.add_transition("X", "A", "B", lambda context: print("A -> B"))
+        m.process_input("X")
+        self.assertTrue(m.is_in_final_state())
+        m.reset()
+        self.assertFalse(m.is_in_final_state())
+
+    def test_is_in_final_state_not_started(self):
+        m = Machine()
+        self.assertFalse(m.is_in_final_state())
+
+    # STATE
+
+    def test_state_str(self):
+        s = State("A")
+        t = str(s)
+        self.assertEqual(t, "[State A]")
+
+    # TRANSITION
+
+    def test_transition_str(self):
+        t = Transition("TEST_1", "A", "B", lambda context: print("A -> B"))
+        self.assertEqual(str(t), "[Transition (A, B, TEST_1)]")
+
+    # MACHINE
+
+    def test_machine_str(self):
+        m = Machine()
+        m.add_state("A", True, False)
+        m.add_state("B", False, False)
+        m.add_state("C", False, True)
+        m.add_transition("TEST_1", "A", "B", lambda context: print("A -> B"))
+        m.add_transition("TEST_2", "B", "C", lambda context: print("B -> C"))
+        result = "=MACHINE=\n\tSTATES\n\t\t[State A]\n\t\t[State B]\n\t\t[State C]\n\tTRANSITIONS\n\t\t[Transition (A, B, TEST_1)]\n\t\t[Transition (B, C, TEST_2)]"
+        self.assertEqual(str(m), result)
+
+