How gsmyridis/isos works
Main Components
a. Core Modules (each in src/isos/):
• Error (error.py): Defines the Error base class and custom error-creation mechanism.
• Option (option.py): Implements Option[T] with variants Some(value) and Nothing.
• Result (result.py): Implements Result[T, E] with variants Ok(value) and Err(error).
• Utility (__init__.py, py.typed): Exposes the public API and signals typing support.
b. External Touchpoints:
• Consumer Code: Any Python application or library that imports Option/Result.
• Custom Errors: User-defined subclasses of Error.
• Test Suite (tests/): Unit tests verifying behavior of Option and Result.
Relationships & Data Flow
• Option → Result: Option can be transformed into a Result (e.g., mapping a missing value into an error).
• Result → Chaining: map(), and_then() and other combinators let Results drive data flow.
• Error Handling: Both Option and Result route errors back through the Error class hierarchy.
• Consumer Invocations: User code creates and manipulates Option/Result objects, chaining operations and handling outcomes explicitly—no exceptions escape unless deliberately thrown.
Architectural Patterns & Principles
• Functional Error Handling: Values (Option/Result) instead of exceptions.
• Extensibility Point: Users subclass Error to define domain-specific errors.
• Type Safety: Via generics (T, E) and py.typed stub signaling.
Technologies & Tooling
• Python 3.x: Runtime and typing system.
• pyproject.toml: Build & dependency config.
• ruff, pre-commit, GitHub Actions: Linting, formatting, CI.
Detail
• Extension points (where user code plugs in).
• “no exception” principle: mark that error paths return Err/Nothing rather than throwing.