stolas 0.1.0__tar.gz

stolas-0.1.0/LICENSE.md

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

stolas-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.1
+Name: stolas
+Version: 0.1.0
+Summary: The strict, multi-paradigm framework enabling pure functional patterns in Python.
+Author: Stolas Contributors
+Project-URL: Homepage, https://github.com/eaksit-bua/stolas
+Project-URL: Repository, https://github.com/eaksit-bua/stolas
+Project-URL: Documentation, https://github.com/eaksit-bua/stolas#readme
+Keywords: functional,monads,immutable,struct,trait
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: dev
+Requires-Dist: mypy>=1.19.1; extra == "dev"
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+
+# 🦉 Stolas
+
+**The strict, multi-paradigm framework enabling pure functional patterns in Python.**
+
+*Wisdom through pure functional patterns* — Safe separation of data and behavior with monadic safety, immutability, and type-safe composition.
+
+## 🦉 The S-T-O-L-A-S Framework
+
+### **S**truct
+Fast, immutable data classes with `@struct` and polymorphic `@trait` for behavior dispatch.
+
+### **T**ypes  
+Safe monadic containers: `Result`, `Option`, `Validated`, `Effect`, `Many`
+
+### **O**perands
+Powerful decorators: `@ops`, `@cases`, `@binary`, `@as_result`, `concurrent()`
+
+### **L**ogic
+Ergonomic functional combinators: `get`, `at`, `where`, `apply`, `_` placeholder, and 20+ utilities
+
+### **A-S**
+*(Reserved for future expansion)*
+
+## 🦉 Key Features
+
+- ✅ **Strictness**: Runtime type checking + `__slots__` for memory efficiency
+- ✅ **Sealed ADTs**: `@cases` decorator with pattern matching and monadic compatibility
+- ✅ **Functional Composition**: Pipeline chaining with `>>`
+- ✅ **Async Concurrency**: Parallel workflows with `concurrent()`
+- ✅ **Polymorphism**: Trait-based dispatch for decoupled behavior
+- ✅ **Type Safety**: Full `mypy --strict` compatibility
+
+## 🦉 Installation
+
+```bash
+pip install stolas
+```
+
+## 🦉 Quick Example
+
+```python
+from stolas.struct import struct
+from stolas.types import Many
+from stolas.operand import binary, as_result, ops
+from stolas.logic import where, apply, _
+
+# Immutable data
+@struct
+class User:
+    id: int
+    name: str
+    email: str
+
+# Safe, curried operations
+@ops(binary, as_result)
+def divide(a: int, b: int) -> float:
+    return a / b
+
+# Functional pipelines with placeholder
+users = Many([
+    User(1, "Alice", "alice@example.com"),
+    User(2, "Bob", "bob@example.com"),
+])
+
+result = users >> where(_.id > 1) >> apply(_.name)  # Many(["Bob"])
+
+# Monadic safety
+divide(10)(2)  # Ok(5.0)
+divide(10)(0)  # Error(ZeroDivisionError(...))
+```
+
+## 🦉 Documentation
+
+For detailed documentation, see the **[docs/](docs/)** directory:
+
+- **[Struct & Trait](docs/struct.md)** - Polymorphism (`@trait`) and immutable data (`@struct`)
+- **[Monadic Types](docs/types.md)** - `Result`, `Option`, `Validated`, `Effect`, `Many`
+- **[Operands](docs/operands.md)** - Decorators `@cases`, `@safe`, and Concurrency
+- **[Logic Reference](docs/logic.md)** - Combinators and Placeholder (`_`)
+
+## 🦉 Testing
+
+```bash
+# Run tests
+python -m pytest tests/
+
+# Type checking
+mypy src/stolas --strict
+```
+
+**Status:** 🦉 739 tests passing • 100% coverage • 100% mypy strict compliance
+
+## 🦉 License
+
+MIT License

stolas-0.1.0/README.md

@@ -0,0 +1,95 @@
+# 🦉 Stolas
+
+**The strict, multi-paradigm framework enabling pure functional patterns in Python.**
+
+*Wisdom through pure functional patterns* — Safe separation of data and behavior with monadic safety, immutability, and type-safe composition.
+
+## 🦉 The S-T-O-L-A-S Framework
+
+### **S**truct
+Fast, immutable data classes with `@struct` and polymorphic `@trait` for behavior dispatch.
+
+### **T**ypes  
+Safe monadic containers: `Result`, `Option`, `Validated`, `Effect`, `Many`
+
+### **O**perands
+Powerful decorators: `@ops`, `@cases`, `@binary`, `@as_result`, `concurrent()`
+
+### **L**ogic
+Ergonomic functional combinators: `get`, `at`, `where`, `apply`, `_` placeholder, and 20+ utilities
+
+### **A-S**
+*(Reserved for future expansion)*
+
+## 🦉 Key Features
+
+- ✅ **Strictness**: Runtime type checking + `__slots__` for memory efficiency
+- ✅ **Sealed ADTs**: `@cases` decorator with pattern matching and monadic compatibility
+- ✅ **Functional Composition**: Pipeline chaining with `>>`
+- ✅ **Async Concurrency**: Parallel workflows with `concurrent()`
+- ✅ **Polymorphism**: Trait-based dispatch for decoupled behavior
+- ✅ **Type Safety**: Full `mypy --strict` compatibility
+
+## 🦉 Installation
+
+```bash
+pip install stolas
+```
+
+## 🦉 Quick Example
+
+```python
+from stolas.struct import struct
+from stolas.types import Many
+from stolas.operand import binary, as_result, ops
+from stolas.logic import where, apply, _
+
+# Immutable data
+@struct
+class User:
+    id: int
+    name: str
+    email: str
+
+# Safe, curried operations
+@ops(binary, as_result)
+def divide(a: int, b: int) -> float:
+    return a / b
+
+# Functional pipelines with placeholder
+users = Many([
+    User(1, "Alice", "alice@example.com"),
+    User(2, "Bob", "bob@example.com"),
+])
+
+result = users >> where(_.id > 1) >> apply(_.name)  # Many(["Bob"])
+
+# Monadic safety
+divide(10)(2)  # Ok(5.0)
+divide(10)(0)  # Error(ZeroDivisionError(...))
+```
+
+## 🦉 Documentation
+
+For detailed documentation, see the **[docs/](docs/)** directory:
+
+- **[Struct & Trait](docs/struct.md)** - Polymorphism (`@trait`) and immutable data (`@struct`)
+- **[Monadic Types](docs/types.md)** - `Result`, `Option`, `Validated`, `Effect`, `Many`
+- **[Operands](docs/operands.md)** - Decorators `@cases`, `@safe`, and Concurrency
+- **[Logic Reference](docs/logic.md)** - Combinators and Placeholder (`_`)
+
+## 🦉 Testing
+
+```bash
+# Run tests
+python -m pytest tests/
+
+# Type checking
+mypy src/stolas --strict
+```
+
+**Status:** 🦉 739 tests passing • 100% coverage • 100% mypy strict compliance
+
+## 🦉 License
+
+MIT License

stolas-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "stolas"
+version = "0.1.0"
+description = "The strict, multi-paradigm framework enabling pure functional patterns in Python."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    {name = "Stolas Contributors"}
+]
+keywords = ["functional", "monads", "immutable", "struct", "trait"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/eaksit-bua/stolas"
+Repository = "https://github.com/eaksit-bua/stolas"
+Documentation = "https://github.com/eaksit-bua/stolas#readme"
+
+[build-system]
+requires = ["setuptools>=61.0,<75.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.run]
+omit = ["src/stolas/mypy_plugin.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+]

stolas-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stolas-0.1.0/src/stolas/logic/__init__.py

@@ -0,0 +1,56 @@
+"""Logic module: functional utilities and helpers."""
+
+from stolas.logic.access import at, call, get
+from stolas.logic.collection import (
+    apply,
+    chain,
+    count,
+    find,
+    first,
+    last,
+    pair,
+    sort,
+    where,
+)
+from stolas.logic.common import const, fmt, identity, tap, tee
+from stolas.logic.predicates import both, contains, either, negate
+from stolas.logic.flow import check, strict
+from stolas.logic.placeholder import _
+from stolas.logic.utils import alt, compose, when, wrap
+
+__all__ = [
+    # Access
+    "get",
+    "at",
+    "call",
+    # Collection
+    "chain",
+    "where",
+    "apply",
+    "count",
+    "first",
+    "last",
+    "pair",
+    "find",
+    "sort",
+    # Flow
+    "check",
+    "strict",
+    # Placeholder
+    "_",
+    # Utils
+    "identity",
+    "const",
+    "tap",
+    "tee",
+    "fmt",
+    "wrap",
+    "when",
+    "compose",
+    "alt",
+    # Predicates
+    "contains",
+    "negate",
+    "both",
+    "either",
+]

stolas-0.1.0/src/stolas/logic/access.py

@@ -0,0 +1,44 @@
+"""Accessor helpers: get, at, call."""
+
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+K = TypeVar("K")
+
+
+def get(attr: str) -> Callable[[Any], Any]:
+    """Return a function that gets an attribute from an object.
+
+    Usage: Ok(user) >> get("name")
+    """
+
+    def wrapper(x: Any) -> Any:
+        return getattr(x, attr)
+
+    return wrapper
+
+
+def at(key: K) -> Callable[[Any], Any]:
+    """Return a function that gets an item by key/index.
+
+    Usage: Ok(data) >> at("id")
+           Ok(items) >> at(0)
+    """
+
+    def wrapper(x: Any) -> Any:
+        return x[key]
+
+    return wrapper
+
+
+def call(method: str, *args: Any, **kwargs: Any) -> Callable[[Any], Any]:
+    """Return a function that calls a method on an object.
+
+    Usage: Ok(s) >> call("upper")
+           Ok(s) >> call("replace", "a", "b")
+    """
+
+    def wrapper(x: Any) -> Any:
+        return getattr(x, method)(*args, **kwargs)
+
+    return wrapper

stolas-0.1.0/src/stolas/logic/access.pyi

@@ -0,0 +1,17 @@
+"""Type stubs for access module."""
+
+from typing import Any, Callable, TypeVar
+
+K = TypeVar("K")
+
+def get(attr: str) -> Callable[[Any], Any]:
+    """Get attribute from object."""
+    ...
+
+def at(key: K) -> Callable[[Any], Any]:
+    """Get item by key or index."""
+    ...
+
+def call(method: str, *args: Any, **kwargs: Any) -> Callable[[Any], Any]:
+    """Call method on object."""
+    ...

stolas-0.1.0/src/stolas/logic/collection.py

@@ -0,0 +1,137 @@
+"""Collection helpers: chain, where, apply, count, first, last, pair, find, sort."""
+
+from typing import Any, Callable, Iterable, TypeVar
+
+from stolas.types.many import Many
+from stolas.types.option import Nothing, Option, Some
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+def chain(
+    func: Callable[[T], Iterable[U]] | Callable[[T], Many[U]],
+) -> Callable[[Many[T]], Many[U]]:
+    """FlatMap helper: maps function over Many items and flattens result.
+
+    Usage: Many(...) >> chain(_.sub_items)
+    """
+
+    def wrapper(m: Many[T]) -> Many[U]:
+        results: list[U] = []
+        for x in m._items:
+            res = func(x)
+            if isinstance(res, Many):
+                results.extend(res.items)
+            elif isinstance(res, Iterable):
+                results.extend(res)
+            else:
+                raise TypeError(f"Expected Iterable or Many, got {type(res)}")
+        return Many(tuple(results))
+
+    return wrapper
+
+
+def where(predicate: Callable[[T], bool]) -> Callable[[Many[T]], Many[T]]:
+    """Filter helper: keeps items matching predicate.
+
+    Usage: Many(...) >> where(_ > 10)
+    """
+
+    def wrapper(m: Many[T]) -> Many[T]:
+        return Many(tuple(x for x in m._items if predicate(x)))
+
+    return wrapper
+
+
+def apply(func: Callable[[T], U]) -> Callable[[Many[T]], Many[U]]:
+    """Map helper: applies function to each item.
+
+    Usage: Many(...) >> apply(_.upper())
+    """
+
+    def wrapper(m: Many[T]) -> Many[U]:
+        return Many(tuple(func(x) for x in m._items))
+
+    return wrapper
+
+
+def count() -> Callable[[Many[T]], Some[int]]:
+    """Return count of items wrapped in Some.
+
+    Usage: Many(...) >> count()  # returns Some(N)
+    """
+
+    def wrapper(m: Many[T]) -> Some[int]:
+        return Some(len(m._items))
+
+    return wrapper
+
+
+def first() -> Callable[[Many[T]], Option[T]]:
+    """Return first item as Some, or Nothing if empty.
+
+    Usage: Many(...) >> first()  # returns Some(x) or Nothing
+    """
+
+    def wrapper(m: Many[T]) -> Option[T]:
+        if m._items:
+            return Some(m._items[0])
+        return Nothing
+
+    return wrapper
+
+
+def last() -> Callable[[Many[T]], Option[T]]:
+    """Return last item as Some, or Nothing if empty.
+
+    Usage: Many(...) >> last()  # returns Some(x) or Nothing
+    """
+
+    def wrapper(m: Many[T]) -> Option[T]:
+        if m._items:
+            return Some(m._items[-1])
+        return Nothing
+
+    return wrapper
+
+
+def pair(other: Many[U]) -> Callable[[Many[T]], Many[tuple[T, U]]]:
+    """Zip with another Many collection.
+
+    Usage: Many([1,2]) >> pair(Many(['a','b']))  # Many([(1,'a'), (2,'b')])
+    """
+
+    def wrapper(m: Many[T]) -> Many[tuple[T, U]]:
+        return Many(tuple(zip(m._items, other._items)))
+
+    return wrapper
+
+
+def find(predicate: Callable[[T], bool]) -> Callable[[Many[T]], Option[T]]:
+    """Find first item matching predicate.
+
+    Usage: Many(...) >> find(_ == 5)  # returns Some(5) or Nothing
+    """
+
+    def wrapper(m: Many[T]) -> Option[T]:
+        for x in m._items:
+            if predicate(x):
+                return Some(x)
+        return Nothing
+
+    return wrapper
+
+
+def sort(
+    key: Callable[[T], Any] | None = None, reverse: bool = False
+) -> Callable[[Many[T]], Many[T]]:
+    """Return sorted Many.
+
+    Usage: Many(...) >> sort(key=_.age)
+    """
+
+    def wrapper(m: Many[T]) -> Many[T]:
+        return Many(tuple(sorted(m._items, key=key, reverse=reverse)))  # type: ignore[arg-type,type-var]
+
+    return wrapper

stolas-0.1.0/src/stolas/logic/collection.pyi

@@ -0,0 +1,54 @@
+"""Type stubs for collection module."""
+
+from typing import Any, Callable, Iterable, TypeVar, overload
+from stolas.types.many import Many
+from stolas.types.option import Option, Some
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+def chain(func: Callable[[Any], Iterable[U]]) -> Callable[[Many[Any]], Many[U]]:
+    """FlatMap over Many items.
+
+    Works with any function returning Iterable (including Many).
+    """
+    ...
+
+def where(predicate: Callable[[T], bool]) -> Callable[[Many[T]], Many[T]]:
+    """Filter items by predicate."""
+    ...
+
+def apply(func: Callable[[T], U]) -> Callable[[Many[T]], Many[U]]:
+    """Map function over items."""
+    ...
+
+def count() -> Callable[[Many[Any]], Some[int]]:
+    """Count items."""
+    ...
+
+def first() -> Callable[[Many[T]], Option[T]]:
+    """Get first item."""
+    ...
+
+def last() -> Callable[[Many[T]], Option[T]]:
+    """Get last item."""
+    ...
+
+def pair(other: Many[U]) -> Callable[[Many[T]], Many[tuple[T, U]]]:
+    """Zip with another Many."""
+    ...
+
+def find(predicate: Callable[[T], bool]) -> Callable[[Many[T]], Option[T]]:
+    """Find first matching item."""
+    ...
+
+@overload
+def sort(*, reverse: bool = ...) -> Callable[[Many[Any]], Many[Any]]:
+    """Sort items with default key."""
+    ...
+
+@overload
+def sort(key: Callable[[T], Any], reverse: bool = ...) -> Callable[[Many[T]], Many[T]]:
+    """Sort items with custom key."""
+    ...
+

stolas-0.1.0/src/stolas/logic/common.py

@@ -0,0 +1,66 @@
+"""Common functional combinators: identity, const, tap, tee, fmt."""
+
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def identity(x: T) -> T:
+    """Return the input unchanged (pass-through).
+
+    Usage: stream >> identity
+    """
+    return x
+
+
+def const(value: T) -> Callable[[Any], T]:
+    """Return a function that always returns the given value.
+
+    Usage: input >> const(10)  # returns 10
+    """
+
+    def wrapper(_: Any) -> T:
+        return value
+
+    return wrapper
+
+
+def tap(func: Callable[[T], Any]) -> Callable[[T], T]:
+    """Execute func(x) for side effect and return x unchanged.
+
+    Usage: Ok(x) >> tap(print)
+    """
+
+    def wrapper(x: T) -> T:
+        func(x)
+        return x
+
+    return wrapper
+
+
+def tee(func: Callable[[T], Any]) -> Callable[[T], T]:
+    """Execute func(x) and return x. Alias for tap.
+
+    Usage: Ok(x) >> tee(log_to_db)
+    """
+
+    def wrapper(x: T) -> T:
+        func(x)
+        return x
+
+    return wrapper
+
+
+def fmt(template: str) -> Callable[[Any], str]:
+    """Format a value into a template string.
+
+    Returns a function that calls template.format(x).
+
+    Usage: Ok("Alice") >> fmt("Hello, {}!")  # Ok("Hello, Alice!")
+           compose(_.name, fmt("{}: adult"))
+    """
+
+    def wrapper(x: Any) -> str:
+        return template.format(x)
+
+    return wrapper

stolas-0.1.0/src/stolas/logic/common.pyi

@@ -0,0 +1,25 @@
+"""Type stubs for common module."""
+
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+def identity(x: T) -> T:
+    """Return input unchanged."""
+    ...
+
+def const(value: T) -> Callable[[Any], T]:
+    """Return function that always returns value."""
+    ...
+
+def tap(func: Callable[[T], Any]) -> Callable[[T], T]:
+    """Execute side-effect and return input."""
+    ...
+
+def tee(func: Callable[[T], Any]) -> Callable[[T], T]:
+    """Alias for tap."""
+    ...
+
+def fmt(template: str) -> Callable[[Any], str]:
+    """Format value into template string."""
+    ...