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. 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. - **States**: Unique nodes in the machine.
- **Transitions**: Directed connections between states triggered by specific inputs. - **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. - **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 ## 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 ```bash
# Install in editable mode # Install in editable mode
@@ -46,7 +46,7 @@ python -m build
## Quick Start (Binary Inverter) ## 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 ```python
from typing import Tuple, TypedDict from typing import Tuple, TypedDict
@@ -94,7 +94,7 @@ if __name__ == '__main__':
## Advanced Usage (Sequence Detector & Fallback Matching) ## 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 ```python
from typing import TypedDict from typing import TypedDict
@@ -152,50 +152,50 @@ def detector(input_string: str) -> int:
| Class/Type | Description | | 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. | | `InputProtocol` | 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`). | | `TransitionInputEnum` | 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. | | `State` | 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. | | `Transition` | 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. | | `Machine` | The core finite state machine runner. |
--- ---
### API Details ### API Details
#### [InputProtocol](file:///Users/davidgildegomezperez/PycharmProjects/snanosm/src/snanosm/mealy.py#L6) #### `InputProtocol`
```python ```python
class InputProtocol(Protocol): class InputProtocol(Protocol):
def __eq__(self, __o: Self) -> bool: ... def __eq__(self, __o: Self) -> bool: ...
def __hash__(self) -> int: ... 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. - `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. - `get_name() -> str`: Returns the state's name.
- `__str__() -> str`: Returns `[State <state_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. - `execute_output(context)`: Executes the output callback if it was supplied.
- `get_destination_name_hash() -> int`: Returns the hash of the destination state name. - `get_destination_name_hash() -> int`: Returns the hash of the destination state name.
- `__str__() -> str`: Returns `[Transition (<origin>, <destination>, <input>)]`. - `__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. - `__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. - `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] > [!WARNING]
> State names must not start with `#` (reserved for internal configurations). A machine cannot have multiple start states. > 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. - `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. - `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. - `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 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 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`. - 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`. - `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. - `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. - `__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 ## 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 ```bash
PYTHONPATH=src python -m unittest discover -s tests PYTHONPATH=src python -m unittest discover -s tests