pyeffect 0.1.0__tar.gz

pyeffect-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.3
+Name: pyeffect
+Version: 0.1.0
+Summary: A fully typed functional core for Python: Result, Option, Effect, and composition utilities.
+Author: Tomperez98
+Author-email: Tomperez98 <tomasperezalvarez@gmail.com>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# pyeffect
+
+Handle expected failures as **values** — a fully typed `Result`, `Option`,
+and lazy `Effect` core for Python 3.14+.
+
+```python
+from pyeffect import Err, Ok, Result, attempt
+
+result: Result[int, str] = attempt(lambda: int("42")).map(lambda n: n * 2)
+match result:
+    case Ok(value):
+        print(value)  # 84
+    case Err(error):
+        print(f"failed: {error}")
+```
+
+## What it is
+
+`pyeffect` is a functional core for Python that turns expected failure
+(network errors, bad input, absence) into values you can compose, instead of
+exceptions you must catch. `Result` and `Option` handle the data; `Effect`
+defers side effects until you run them.
+
+### The one rule
+
+> **Bugs panic, expected failures return values.**
+
+- **Panic** when the program reaches a state that should be impossible —
+  `unwrap()` on `Err`/`Nothing`, a broken retry `Policy`, an over-arity
+  `curry`. The damage stops at the exact line.
+- **Return a value** when failure is expected — network errors, bad input,
+  absence. The caller decides what to do with it.
+
+## Install
+
+Not on PyPI yet — clone the repo and install from source:
+
+```bash
+uv sync
+```
+
+That installs `pyeffect` and the dev dependencies (pytest, ruff, ty) into
+`.venv`.
+
+## A complete example
+
+Paste this and it runs — expected output is in the comments:
+
+```python
+from pyeffect import Effect, Err, Ok, Result, attempt, from_optional
+
+# Expected failure is a value the caller handles.
+result: Result[int, str] = attempt(lambda: int("42")).map(lambda n: n * 2)
+match result:
+    case Ok(value):
+        print(value)  # 84
+    case Err(error):
+        print(f"failed: {error}")
+
+# Absence is a value too.
+assert from_optional({"a": 1}.get("b")).unwrap_or(0) == 0
+
+# Side effects are deferred until you run them.
+effect = (
+    Effect.attempt(lambda: open("config.json").read())
+    .map(str.strip)
+    .context("while loading config")
+    .catch(lambda e: Effect.success("{}"))
+)
+print(effect.run())  # {} — the read failed, the fallback ran
+```
+
+## What's inside
+
+| Module | Types |
+|---|---|
+| `pyeffect.result` | `Ok` / `Err` / `Result[T, E]`, `attempt`, `guard`, `traverse`, `flatten`, `transpose`, `ErrorContext` |
+| `pyeffect.option` | `Some` / `Nothing` / `Option[T]`, `from_optional`, `flatten`, `transpose` |
+| `pyeffect.effect` | `Effect[T, E]` — a lazy, re-runnable computation; `sequence`, `attempt`, `retry_result` |
+| `pyeffect.retry` | `retry` + `Policy` — deterministic, injectable backoff |
+| `pyeffect.pipe` | `pipe(value, f, g, ...)` — left-to-right threading |
+| `pyeffect.compose` | `compose`, `curry`, `lift` / `lift2` / `lift3`, `identity`, `tap`, `flip`, `unpack`, `constant`, `partial` |
+
+The combinators are methods: `Effect` carries `map`, `and_then`, `catch`,
+`context`, `inspect`, `inspect_err`, `map_or`, `flatten`, `zip`, and `retry`;
+every variant has the eager boolean combinators `and_` / `or_` (trailing
+underscore because `and`/`or` are Python keywords), plus `Option.xor`.
+
+`flatten` and `transpose` are module-level functions on `result` and
+`option` (`from pyeffect.result import flatten, transpose`) because Python's
+invariant generics make the equivalent methods untypeable at call sites.
+
+## `Effect` is the impurity boundary
+
+Python is eager: every call executes immediately, so purity is lost the
+moment you touch IO or time. `Effect` restores it — **constructing and
+composing run nothing; `run()` / `run_result()` are the only impure
+moments.** Dependencies (readers, clocks, backends) are captured in the
+thunk's closure, and `sleep` is injected, so tests run with zero delay and
+no real I/O.
+
+The library is **sync-first by design**: the value layer (`Result`,
+`Option`, `pipe`, `compose`) is pure and async-agnostic, and `Effect` is a
+sync thunk over `Result`. An `AsyncEffect` sibling (awaitable thunks,
+`asyncio.sleep`-injected retry) is planned for when network use-cases
+demand it — not before.
+
+## Typing notes
+
+Every combinator is checked with [`ty`](https://github.com/astral-sh/ty) as
+part of the test suite (`tests/typing/` pins the contracts, including
+intentional failures that must stay rejected). Known constraints of Python
+generics, documented in the module docstrings:
+
+- **No variance in PEP 695** — `Effect.success` / `Effect.failure` leave the
+  unbound slot as `Any`; anchor the chain with an annotation or an operation
+  that fixes the slot (`attempt`'s `catch`, `map_err`, `context`).
+- **No higher-kinded types** — there are no generic `Functor` / `Monad`
+  typeclasses; each type implements `map` / `and_then` structurally.
+- **Fixed arity ceilings** — `pipe` / `compose` type-check up to ten
+  functions, `curry` up to five; the runtimes accept more.
+
+## Development
+
+```bash
+uv run pytest      # runtime + doctest tests
+uv run ty check src tests   # typing contract; also gates the tests/typing/ fixtures
+uv run ruff check src tests
+```

pyeffect-0.1.0/README.md

@@ -0,0 +1,129 @@
+# pyeffect
+
+Handle expected failures as **values** — a fully typed `Result`, `Option`,
+and lazy `Effect` core for Python 3.14+.
+
+```python
+from pyeffect import Err, Ok, Result, attempt
+
+result: Result[int, str] = attempt(lambda: int("42")).map(lambda n: n * 2)
+match result:
+    case Ok(value):
+        print(value)  # 84
+    case Err(error):
+        print(f"failed: {error}")
+```
+
+## What it is
+
+`pyeffect` is a functional core for Python that turns expected failure
+(network errors, bad input, absence) into values you can compose, instead of
+exceptions you must catch. `Result` and `Option` handle the data; `Effect`
+defers side effects until you run them.
+
+### The one rule
+
+> **Bugs panic, expected failures return values.**
+
+- **Panic** when the program reaches a state that should be impossible —
+  `unwrap()` on `Err`/`Nothing`, a broken retry `Policy`, an over-arity
+  `curry`. The damage stops at the exact line.
+- **Return a value** when failure is expected — network errors, bad input,
+  absence. The caller decides what to do with it.
+
+## Install
+
+Not on PyPI yet — clone the repo and install from source:
+
+```bash
+uv sync
+```
+
+That installs `pyeffect` and the dev dependencies (pytest, ruff, ty) into
+`.venv`.
+
+## A complete example
+
+Paste this and it runs — expected output is in the comments:
+
+```python
+from pyeffect import Effect, Err, Ok, Result, attempt, from_optional
+
+# Expected failure is a value the caller handles.
+result: Result[int, str] = attempt(lambda: int("42")).map(lambda n: n * 2)
+match result:
+    case Ok(value):
+        print(value)  # 84
+    case Err(error):
+        print(f"failed: {error}")
+
+# Absence is a value too.
+assert from_optional({"a": 1}.get("b")).unwrap_or(0) == 0
+
+# Side effects are deferred until you run them.
+effect = (
+    Effect.attempt(lambda: open("config.json").read())
+    .map(str.strip)
+    .context("while loading config")
+    .catch(lambda e: Effect.success("{}"))
+)
+print(effect.run())  # {} — the read failed, the fallback ran
+```
+
+## What's inside
+
+| Module | Types |
+|---|---|
+| `pyeffect.result` | `Ok` / `Err` / `Result[T, E]`, `attempt`, `guard`, `traverse`, `flatten`, `transpose`, `ErrorContext` |
+| `pyeffect.option` | `Some` / `Nothing` / `Option[T]`, `from_optional`, `flatten`, `transpose` |
+| `pyeffect.effect` | `Effect[T, E]` — a lazy, re-runnable computation; `sequence`, `attempt`, `retry_result` |
+| `pyeffect.retry` | `retry` + `Policy` — deterministic, injectable backoff |
+| `pyeffect.pipe` | `pipe(value, f, g, ...)` — left-to-right threading |
+| `pyeffect.compose` | `compose`, `curry`, `lift` / `lift2` / `lift3`, `identity`, `tap`, `flip`, `unpack`, `constant`, `partial` |
+
+The combinators are methods: `Effect` carries `map`, `and_then`, `catch`,
+`context`, `inspect`, `inspect_err`, `map_or`, `flatten`, `zip`, and `retry`;
+every variant has the eager boolean combinators `and_` / `or_` (trailing
+underscore because `and`/`or` are Python keywords), plus `Option.xor`.
+
+`flatten` and `transpose` are module-level functions on `result` and
+`option` (`from pyeffect.result import flatten, transpose`) because Python's
+invariant generics make the equivalent methods untypeable at call sites.
+
+## `Effect` is the impurity boundary
+
+Python is eager: every call executes immediately, so purity is lost the
+moment you touch IO or time. `Effect` restores it — **constructing and
+composing run nothing; `run()` / `run_result()` are the only impure
+moments.** Dependencies (readers, clocks, backends) are captured in the
+thunk's closure, and `sleep` is injected, so tests run with zero delay and
+no real I/O.
+
+The library is **sync-first by design**: the value layer (`Result`,
+`Option`, `pipe`, `compose`) is pure and async-agnostic, and `Effect` is a
+sync thunk over `Result`. An `AsyncEffect` sibling (awaitable thunks,
+`asyncio.sleep`-injected retry) is planned for when network use-cases
+demand it — not before.
+
+## Typing notes
+
+Every combinator is checked with [`ty`](https://github.com/astral-sh/ty) as
+part of the test suite (`tests/typing/` pins the contracts, including
+intentional failures that must stay rejected). Known constraints of Python
+generics, documented in the module docstrings:
+
+- **No variance in PEP 695** — `Effect.success` / `Effect.failure` leave the
+  unbound slot as `Any`; anchor the chain with an annotation or an operation
+  that fixes the slot (`attempt`'s `catch`, `map_err`, `context`).
+- **No higher-kinded types** — there are no generic `Functor` / `Monad`
+  typeclasses; each type implements `map` / `and_then` structurally.
+- **Fixed arity ceilings** — `pipe` / `compose` type-check up to ten
+  functions, `curry` up to five; the runtimes accept more.
+
+## Development
+
+```bash
+uv run pytest      # runtime + doctest tests
+uv run ty check src tests   # typing contract; also gates the tests/typing/ fixtures
+uv run ruff check src tests
+```

pyeffect-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "pyeffect"
+version = "0.1.0"
+description = "A fully typed functional core for Python: Result, Option, Effect, and composition utilities."
+readme = "README.md"
+authors = [
+    { name = "Tomperez98", email = "tomasperezalvarez@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.5",
+    "ty>=0.0.77",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyeffect-0.1.0/src/pyeffect/__init__.py

@@ -0,0 +1,69 @@
+"""pyeffect: a fully typed functional core for Python."""
+
+from pyeffect.compose import (
+    compose,
+    constant,
+    curry,
+    flip,
+    identity,
+    lift,
+    lift2,
+    lift3,
+    partial,
+    tap,
+    unpack,
+)
+from pyeffect.effect import Effect, sequence
+from pyeffect.option import (
+    Nothing,
+    Option,
+    Some,
+    UnwrapNothingError,
+    flatten,
+    from_optional,
+)
+from pyeffect.pipe import pipe
+from pyeffect.result import (
+    Err,
+    ErrorContext,
+    Ok,
+    Result,
+    UnwrapError,
+    attempt,
+    guard,
+    traverse,
+)
+from pyeffect.retry import Policy, retry
+
+__all__ = [
+    "Effect",
+    "Err",
+    "ErrorContext",
+    "Nothing",
+    "Ok",
+    "Option",
+    "Policy",
+    "Result",
+    "Some",
+    "UnwrapError",
+    "UnwrapNothingError",
+    "attempt",
+    "compose",
+    "constant",
+    "curry",
+    "flatten",
+    "flip",
+    "from_optional",
+    "guard",
+    "identity",
+    "lift",
+    "lift2",
+    "lift3",
+    "partial",
+    "pipe",
+    "retry",
+    "sequence",
+    "tap",
+    "traverse",
+    "unpack",
+]

pyeffect-0.1.0/src/pyeffect/compose.py

@@ -0,0 +1,342 @@
+# ruff: noqa: UP047 -- PEP 695 type params on @overload are not checked by ty;
+# classic TypeVars required. Non-overload functions below use PEP 695.
+"""Function composition: ``compose``, ``tap``, and small combinators.
+
+``compose`` builds a new function from existing ones, right to left::
+
+    >>> from pyeffect.compose import compose
+    >>> compose(str, lambda x: x + 1)(2)
+    '3'
+
+``tap`` runs a side effect on a value and passes it through unchanged — a
+convenient debug step inside a ``pipe``.
+
+``curry`` turns a multi-argument function into nested single-argument
+calls; ``lift``/``lift2``/``lift3`` push plain functions into the
+``Result`` domain::
+
+    >>> from pyeffect.compose import curry, lift2
+    >>> from pyeffect.result import Ok
+    >>> curry(lambda a, b: a + b)(2)(3)
+    5
+    >>> lift2(lambda a, b: a + b)(Ok(1), Ok(2))
+    Ok(value=3)
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from functools import partial
+from typing import Any, TypeVar, overload
+
+from pyeffect.result import Err, Ok, Result
+
+__all__ = [
+    "compose",
+    "constant",
+    "curry",
+    "flip",
+    "identity",
+    "lift",
+    "lift2",
+    "lift3",
+    "partial",
+    "tap",
+    "unpack",
+]
+
+_A = TypeVar("_A")
+_B = TypeVar("_B")
+_C = TypeVar("_C")
+_D = TypeVar("_D")
+_E = TypeVar("_E")
+_F = TypeVar("_F")
+_G = TypeVar("_G")
+_H = TypeVar("_H")
+_I = TypeVar("_I")
+_J = TypeVar("_J")
+_K = TypeVar("_K")
+
+
+@overload
+def compose() -> Callable[[_A], _A]: ...
+@overload
+def compose(f: Callable[[_A], _B]) -> Callable[[_A], _B]: ...
+@overload
+def compose(f: Callable[[_A], _B], g: Callable[[_C], _A]) -> Callable[[_C], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+) -> Callable[[_D], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+) -> Callable[[_E], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+) -> Callable[[_F], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+) -> Callable[[_G], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+) -> Callable[[_H], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+    m: Callable[[_I], _H],
+) -> Callable[[_I], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+    m: Callable[[_I], _H],
+    n: Callable[[_J], _I],
+) -> Callable[[_J], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+    m: Callable[[_I], _H],
+    n: Callable[[_J], _I],
+    o: Callable[[_K], _J],
+) -> Callable[[_K], _B]: ...
+def compose(*functions: Callable[[Any], Any]) -> Callable[[Any], Any]:
+    """Compose functions right to left: ``compose(f, g)(x) == f(g(x))``.
+
+    ``compose()`` (no functions) is the identity function. Up to ten
+    functions are fully type-checked; the runtime accepts any number.
+    """
+    if not functions:
+        return identity
+
+    def composed(value: Any) -> Any:
+        for fn in reversed(functions):
+            value = fn(value)
+        return value
+
+    return composed
+
+
+def identity[A](value: A) -> A:
+    """Return ``value`` unchanged."""
+
+    return value
+
+
+def tap[A](fn: Callable[[A], object]) -> Callable[[A], A]:
+    """Return a function that runs ``fn`` on the value, then returns it.
+
+    The return value of ``fn`` is discarded — ``tap`` is for side effects
+    (logging, recording) inside a pipeline.
+    """
+
+    def tapped(value: A) -> A:
+        fn(value)
+        return value
+
+    return tapped
+
+
+def constant[A](value: A) -> Callable[..., A]:
+    """Return a function that ignores its arguments and yields ``value``."""
+
+    def const(*args: object, **kwargs: object) -> A:
+        return value
+
+    return const
+
+
+def flip[A, B, C](f: Callable[[A, B], C]) -> Callable[[B, A], C]:
+    """Swap the first two arguments of a binary function."""
+
+    def flipped(b: B, a: A) -> C:
+        return f(a, b)
+
+    return flipped
+
+
+@overload
+def unpack[A, R](f: Callable[[A], R]) -> Callable[[tuple[A]], R]: ...
+@overload
+def unpack[A, B, R](f: Callable[[A, B], R]) -> Callable[[tuple[A, B]], R]: ...
+@overload
+def unpack[A, B, C, R](f: Callable[[A, B, C], R]) -> Callable[[tuple[A, B, C]], R]: ...
+def unpack(f: Callable[..., Any]) -> Callable[[tuple[Any, ...]], Any]:
+    """Return a function that applies ``f`` to the elements of a tuple.
+
+    ``unpack(f)((1, 2))`` is ``f(1, 2)``. Arities 1-3 are fully
+    type-checked; the runtime accepts any arity.
+    """
+
+    def applied(args: tuple[Any, ...]) -> Any:
+        return f(*args)
+
+    return applied
+
+
+def _positional_arity(f: Callable[..., Any]) -> int:
+    """Count the fixed positional parameters of ``f``.
+
+    Currying must know when a call has supplied every positional argument.
+    A ``*args`` parameter makes that unknowable, and a required
+    keyword-only parameter can never be supplied positionally — both are
+    defects and crash at construction instead of misbehaving at call time.
+    """
+    parameters = inspect.signature(f).parameters.values()
+    for parameter in parameters:
+        if parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+            raise TypeError(f"curry requires a fixed arity, got variadic {f!r}")
+        if (
+            parameter.kind is inspect.Parameter.KEYWORD_ONLY
+            and parameter.default is inspect.Parameter.empty
+        ):
+            raise TypeError(
+                f"curry requires positional parameters only, got required "
+                f"keyword-only {parameter.name!r} in {f!r}"
+            )
+    return sum(
+        1
+        for parameter in parameters
+        if parameter.kind
+        in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    )
+
+
+@overload
+def curry[R](f: Callable[[], R]) -> Callable[[], R]: ...
+@overload
+def curry[A, R](f: Callable[[A], R]) -> Callable[[A], R]: ...
+@overload
+def curry[A, B, R](
+    f: Callable[[A, B], R],
+) -> Callable[[A], Callable[[B], R]]: ...
+@overload
+def curry[A, B, C, R](
+    f: Callable[[A, B, C], R],
+) -> Callable[[A], Callable[[B], Callable[[C], R]]]: ...
+@overload
+def curry[A, B, C, D, R](
+    f: Callable[[A, B, C, D], R],
+) -> Callable[[A], Callable[[B], Callable[[C], Callable[[D], R]]]]: ...
+@overload
+def curry[A, B, C, D, E, R](
+    f: Callable[[A, B, C, D, E], R],
+) -> Callable[[A], Callable[[B], Callable[[C], Callable[[D], Callable[[E], R]]]]]: ...
+def curry(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Curry ``f`` so each step supplies one positional argument.
+
+    ``curry(f)(a)(b)(c)`` is ``f(a, b, c)``; a step may also supply
+    several arguments at once (``curry(f)(a, b)(c)``), and the step that
+    completes the arity runs ``f`` immediately. Arities 1-5 are fully
+    type-checked; the runtime accepts any fixed arity. Variadic ``*args``
+    callables and required keyword-only parameters are rejected at
+    construction — the arity is unknowable or unreachable positionally.
+    """
+    arity = _positional_arity(f)
+
+    def curried(*args: Any) -> Any:
+        if len(args) >= arity:
+            return f(*args)
+        return curry(partial(f, *args))
+
+    return curried
+
+
+def lift[T, U, E](
+    f: Callable[[T], U],
+) -> Callable[[Result[T, E]], Result[U, E]]:
+    """Lift a unary function into the ``Result`` domain.
+
+    ``lift(f)(r)`` is ``r.map(f)`` as a reusable value — useful when the
+    function must be passed somewhere instead of called on a receiver.
+    """
+
+    def lifted(result: Result[T, E]) -> Result[U, E]:
+        if isinstance(result, Ok):
+            return Ok(f(result.value))
+        return result
+
+    return lifted
+
+
+def lift2[T, U, R, E](
+    f: Callable[[T, U], R],
+) -> Callable[[Result[T, E], Result[U, E]], Result[R, E]]:
+    """Lift a binary function into the ``Result`` domain (applicative style).
+
+    ``lift2(f)(r1, r2)`` applies ``f`` to both values, failing fast on the
+    first ``Err``.
+    """
+
+    def lifted(first: Result[T, E], second: Result[U, E]) -> Result[R, E]:
+        if isinstance(first, Err):
+            return first
+        if isinstance(second, Err):
+            return second
+        return Ok(f(first.value, second.value))
+
+    return lifted
+
+
+def lift3[T, U, V, R, E](
+    f: Callable[[T, U, V], R],
+) -> Callable[[Result[T, E], Result[U, E], Result[V, E]], Result[R, E]]:
+    """Lift a ternary function into the ``Result`` domain (applicative style).
+
+    ``lift3(f)(r1, r2, r3)`` applies ``f`` to all three values, failing
+    fast on the first ``Err``.
+    """
+
+    def lifted(
+        first: Result[T, E], second: Result[U, E], third: Result[V, E]
+    ) -> Result[R, E]:
+        if isinstance(first, Err):
+            return first
+        if isinstance(second, Err):
+            return second
+        if isinstance(third, Err):
+            return third
+        return Ok(f(first.value, second.value, third.value))
+
+    return lifted