studiosi/snanosm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: changed links in documentation

Browse Source
This commit is contained in:
studiosi
2026-07-16 18:51:43 +03:00
parent 96a58747a8
commit 494cc6ca35
1 changed files with 18 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+18 -18
View File
@@ -20,7 +20,7 @@ Part of Nobody Industry's **MFFP (Made From First Principles)** set of libraries
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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py), this is modeled by:
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.
@@ -32,7 +32,7 @@ In [mealy.py](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/sna
## Installation
Since the library uses [pyproject.toml](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/pyproject.toml) with the Hatchling build backend, you can install it locally in editable mode or build it using standard tools:
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
@@ -46,7 +46,7 @@ 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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/examples/inverter.py).
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
@@ -94,7 +94,7 @@ if __name__ == '__main__':
## Advanced Usage (Sequence Detector & Fallback Matching)
The sequence detector in [detector.py](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/examples/detector.py) searches for the substring `"AB"` within a stream of characters. It illustrates the use of [TransitionInputEnum](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L14) to define catch-all transitions when no specific input matches.
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
@@ -152,50 +152,50 @@ def detector(input_string: str) -> int:
| Class/Type | Description |
| :--- | :--- |
| [InputProtocol](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L6) | A typing protocol requiring `__eq__` and `__hash__`. Any hashable, equatable Python object can serve as machine input. |
| [TransitionInputEnum](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L14) | Enum containing special transition inputs (e.g., `MATCH_REST`). |
| [State](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L22) | Represents a state node in the state machine. |
| [Transition](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L33) | Represents an edge between states triggered by a transition input. |
| [Machine](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L53) | The core finite state machine runner. |
| `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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L6)
#### `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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L103) must implement this protocol (or be natively hashable and equatable, e.g. strings, integers, frozen dataclasses).
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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L14)
#### `TransitionInputEnum`
- `MATCH_REST`: Activates if no matching transition input is found for the current state. Useful for defining default fallback transitions.
#### [State](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L22)
#### `State`
- `get_name() -> str`: Returns the state's name.
- `__str__() -> str`: Returns `[State <state_name>]`.
#### [Transition](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L33)
#### `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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L53)
#### `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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L6) or [TransitionInputEnum](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L14).
- `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](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L22) object, or `None` if the machine has not started or processed any inputs.
- `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.
@@ -203,7 +203,7 @@ Any custom object used as an input to [Machine.process_input](file:///Users/davi
## Testing & Verification
Unit tests are located in [test_mealy.py](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/tests/test_mealy.py). To run the test suite, navigate to the project directory and execute:
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