stolas 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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."""
+    ...

stolas/logic/flow.py

@@ -0,0 +1,37 @@
+"""Flow control helpers: check, strict."""
+
+from typing import Any, Callable, TypeVar
+
+from stolas.types.result import Error, Ok
+
+T = TypeVar("T")
+
+
+def check(
+    predicate: Callable[[T], bool], error_msg: str
+) -> Callable[[T], Ok[T] | Error[str]]:
+    """Validate value with predicate, return Ok or Error.
+
+    Usage: Ok(val) >> check(_ > 0, "must be positive")
+    """
+
+    def wrapper(x: T) -> Ok[T] | Error[str]:
+        if predicate(x):
+            return Ok(x)
+        return Error(error_msg)
+
+    return wrapper
+
+
+def strict(type_: type[T]) -> Callable[[Any], Ok[T] | Error[TypeError]]:
+    """Validate that value is instance of type, return Ok or Error.
+
+    Usage: Ok(val) >> strict(int)
+    """
+
+    def wrapper(x: Any) -> Ok[T] | Error[TypeError]:
+        if isinstance(x, type_):
+            return Ok(x)
+        return Error(TypeError(f"Expected {type_.__name__}, got {type(x).__name__}"))
+
+    return wrapper

stolas/logic/flow.pyi

@@ -0,0 +1,16 @@
+"""Type stubs for flow module."""
+
+from typing import Any, Callable, TypeVar
+from stolas.types.result import Ok, Error
+
+T = TypeVar("T")
+
+def check(
+    predicate: Callable[[T], bool], error_msg: str
+) -> Callable[[T], Ok[T] | Error[str]]:
+    """Validate with predicate, return Ok or Error."""
+    ...
+
+def strict(type_: type[T]) -> Callable[[Any], Ok[T] | Error[TypeError]]:
+    """Type validation returning Ok or Error."""
+    ...