effecton 0.2.0__py3-none-any.whl

effecton/__init__.py

@@ -0,0 +1,106 @@
+from effecton.attempt import attempt, attempt_async
+from effecton.effect import (
+    Cause,
+    Die,
+    Effect,
+    EffectonError,
+    Fail,
+    Interrupt,
+    coroutine,
+    die,
+    fail,
+    require,
+    success,
+    sync,
+)
+from effecton.exit import Exit, Failure, Succeeded, UnhandledDefect
+from effecton.gen import EffectGen, gen
+from effecton.implicit_requirement import (
+    ImplicitRequirement,
+    provide_implicit,
+    require_implicit,
+)
+from effecton.run_async import run_async, run_async_coroutine, run_async_exit
+from effecton.run_sync import (
+    AsyncEffectInSyncRun,
+    MissingRequirement,
+    run_sync,
+    run_sync_exit,
+)
+from effecton.std.logger import (
+    CurrentLogAnnotations,
+    CurrentLoggers,
+    CurrentLogLevel,
+    EffectonLogger,
+    LogData,
+    LogLevel,
+    MinimumLogLevel,
+    Severity,
+    annotate_logs,
+    log,
+    log_debug,
+    log_error,
+    log_fatal,
+    log_info,
+    log_trace,
+    log_warning,
+)
+from effecton.std.pretty_logger import PrettyFormatter, pretty_logger
+from effecton.std.scope import Scope, acquire_and_release, add_finalizer, scoped
+from effecton.suspend import suspend
+
+__all__ = [
+    "AsyncEffectInSyncRun",
+    "Cause",
+    "CurrentLogAnnotations",
+    "CurrentLogLevel",
+    "CurrentLoggers",
+    "Die",
+    "Effect",
+    "EffectGen",
+    "EffectonError",
+    "EffectonLogger",
+    "Exit",
+    "Fail",
+    "Failure",
+    "ImplicitRequirement",
+    "Interrupt",
+    "LogData",
+    "LogLevel",
+    "MinimumLogLevel",
+    "MissingRequirement",
+    "PrettyFormatter",
+    "Scope",
+    "Severity",
+    "Succeeded",
+    "UnhandledDefect",
+    "acquire_and_release",
+    "add_finalizer",
+    "annotate_logs",
+    "attempt",
+    "attempt_async",
+    "coroutine",
+    "die",
+    "fail",
+    "gen",
+    "log",
+    "log_debug",
+    "log_error",
+    "log_fatal",
+    "log_info",
+    "log_trace",
+    "log_warning",
+    "pretty_logger",
+    "provide_implicit",
+    "require",
+    "require_implicit",
+    "run_async",
+    "run_async_coroutine",
+    "run_async_exit",
+    "run_sync",
+    "run_sync_exit",
+    "scoped",
+    "success",
+    "suspend",
+    "sync",
+]

effecton/attempt.py

@@ -0,0 +1,42 @@
+from collections.abc import Awaitable, Callable
+
+from effecton.effect import Effect, EffectonError, coroutine, fail, success
+from effecton.suspend import suspend
+
+
+@suspend
+def attempt[A, E: EffectonError](
+    thunk: Callable[[], A], on_error: Callable[[Exception], E]
+) -> Effect[A, E]:
+    """Run an exception-throwing thunk lazily, with typed failures.
+
+    The thunk runs once per run of the effect, like sync. When it raises,
+    on_error maps the exception into the typed error channel — under sync,
+    every exception becomes an uncatchable defect. To keep an unexpected
+    exception a defect, re-raise it from on_error.
+    """
+    try:
+        return success(thunk())
+    except Exception as e:
+        return fail(on_error(e))
+
+
+def attempt_async[A, E: EffectonError](
+    thunk: Callable[[], Awaitable[A]], on_error: Callable[[Exception], E]
+) -> Effect[A, E]:
+    """Await an exception-throwing thunk lazily, with typed failures.
+
+    The async counterpart of attempt: the thunk builds a fresh awaitable
+    once per run of the effect, like coroutine, and on_error maps an
+    exception raised by the thunk or by the await into the typed error
+    channel. Re-raise from on_error to keep an unexpected exception a
+    defect. Only the run_async family can interpret the result.
+    """
+
+    async def go() -> Effect[A, E]:
+        try:
+            return success(await thunk())
+        except Exception as e:
+            return fail(on_error(e))
+
+    return coroutine(go).flat_map(lambda effect: effect)

effecton/catch.py

@@ -0,0 +1,36 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, Never, TypeVar, final
+
+from effecton.effect import Effect, EffectonError, OnFailure, fail
+
+# Old-style TypeVars declare the variance ty cannot infer across the
+# Effect ↔ CatchBinder reference cycle; see the ty inference notes in
+# AGENTS.md.
+A = TypeVar("A", covariant=True)
+E = TypeVar("E", bound=EffectonError, covariant=True)
+R = TypeVar("R", covariant=True)
+T = TypeVar("T", bound=EffectonError)
+
+
+@final
+@dataclass(frozen=True)
+class CatchBinder(Generic[A, E, R, T]):  # noqa: UP046
+    """One step of ``effect.catch(T)(handler)``: T is bound, handler pending.
+
+    Catch particular error E, return new Effect.
+    """
+
+    effect: Effect[A, E, R]
+    error_type: type[T]
+
+    def __call__[A2, B, E3: EffectonError, R2, R3, E2: EffectonError = Never](
+        self: CatchBinder[A2, T | E2, R2, T],
+        handler: Callable[[T], Effect[B, E3, R3]],
+    ) -> Effect[A2 | B, E2 | E3, R2 | R3]:
+        error_type = self.error_type
+
+        return OnFailure[A2 | B, E2 | E3, R2 | R3](
+            self.effect,
+            lambda e: handler(e) if isinstance(e, error_type) else fail(e),
+        )

effecton/effect.py

@@ -0,0 +1,206 @@
+from collections.abc import Awaitable, Callable, Generator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Never, final
+
+from typing_extensions import TypeForm
+
+if TYPE_CHECKING:
+    from effecton.catch import CatchBinder
+    from effecton.provide import ProvideBinder
+    from effecton.std.scope import Scope
+
+
+@dataclass(frozen=True)
+class EffectonError(Exception):
+    def __str__(self) -> str:
+        # The dataclass __init__ never fills Exception.args, so the
+        # inherited __str__ renders every error as an empty string.
+        return repr(self)
+
+
+@final
+@dataclass(frozen=True)
+class Fail[E: EffectonError]:
+    error: E
+
+
+@final
+@dataclass(frozen=True)
+class Die:
+    defect: Any
+
+
+@final
+@dataclass(frozen=True)
+class Interrupt:
+    """The effect was cut short by a cancellation.
+
+    Carries the BaseException that signalled it, such as
+    asyncio.CancelledError. The runner consumes the cancellation and
+    settles as Failure(Interrupt(exception)); a caller whose task should
+    stop re-raises the exception. Like Die, it is not an error: catch_all
+    and catch only handle Fail.
+    """
+
+    exception: BaseException
+
+
+type Cause[E: EffectonError] = Fail[E] | Die | Interrupt
+
+
+class Effect[A, E: EffectonError = Never, R = Never]:
+    def flat_map[B, E2: EffectonError, R2](
+        self, f: Callable[[A], Effect[B, E2, R2]]
+    ) -> Effect[B, E | E2, R | R2]:
+        return FlatMap(self, f)
+
+    def map[B](self, f: Callable[[A], B]) -> Effect[B, E, R]:
+        return self.flat_map(lambda a: Success(f(a)))
+
+    def catch_all[B, E2: EffectonError, R2](
+        self, f: Callable[[E], Effect[B, E2, R2]]
+    ) -> Effect[A | B, E2, R | R2]:
+        return OnFailure[A | B, E2, R | R2](self, f)
+
+    def catch[T: EffectonError](self, error_type: type[T]) -> CatchBinder[A, E, R, T]:
+        from effecton.catch import CatchBinder
+
+        return CatchBinder(effect=self, error_type=error_type)
+
+    def on_exit[R2](self, finalizer: Effect[Any, Never, R2]) -> Effect[A, E, R | R2]:
+        return OnExit(self, finalizer)
+
+    def provide[T](self, requirement_type: TypeForm[T]) -> ProvideBinder[A, E, R, T]:
+        from effecton.provide import ProvideBinder
+
+        return ProvideBinder(effect=self, requirement_type=requirement_type)
+
+    def scoped[A2, E2: EffectonError, R2 = Never](
+        self: Effect[A2, E2, Scope | R2],
+    ) -> Effect[A2, E2, R2]:
+        from effecton.std.scope import scoped
+
+        return scoped(self)
+
+    def __iter__(self) -> Generator[Effect[A, E, R], Any, A]:
+        """Make ``x = yield from effect`` infer ``x`` as A inside @gen.
+
+        A bare ``yield`` types as the generator's single send type (Any).
+        ``yield from`` takes this method's return type parameter instead,
+        so the value the interpreter sends back is typed per expression.
+        """
+        return (yield self)
+
+
+@final
+@dataclass(frozen=True)
+class Success[A](Effect[A]):
+    value: A
+    kind: Literal["success"] = "success"
+
+
+@final
+@dataclass(frozen=True)
+class Sync[A](Effect[A]):
+    fn: Callable[[], A]
+    kind: Literal["sync"] = "sync"
+
+
+@final
+@dataclass(frozen=True)
+class Coroutine[A](Effect[A]):
+    fn: Callable[[], Awaitable[A]]
+    kind: Literal["coroutine"] = "coroutine"
+
+
+@final
+@dataclass(frozen=True)
+class FailCause[E: EffectonError](Effect[Never, E]):
+    cause: Cause[E]
+    kind: Literal["fail"] = "fail"
+
+
+@final
+@dataclass(frozen=True)
+class FlatMap[B, E: EffectonError, R](Effect[B, E, R]):
+    first: Effect[Any, Any, Any]
+    and_then: Callable[[Any], Effect[B, E, R]]
+    kind: Literal["flat_map"] = "flat_map"
+
+
+@final
+@dataclass(frozen=True)
+class OnFailure[A, E: EffectonError, R](Effect[A, E, R]):
+    first: Effect[A, Any, Any]
+    handler: Callable[[Any], Effect[A, E, R]]
+    kind: Literal["on_failure"] = "on_failure"
+
+
+@final
+@dataclass(frozen=True)
+class Require[R](Effect[R, Never, R]):
+    requirement_type: TypeForm[R]
+    kind: Literal["require"] = "require"
+
+
+@final
+@dataclass(frozen=True)
+class ProvideRequirement[A, E: EffectonError, R](Effect[A, E, R]):
+    first: Effect[A, E, Any]
+    requirement_type: TypeForm[Any]
+    requirement_impl: Any
+    kind: Literal["provide_requirement"] = "provide_requirement"
+
+
+@final
+@dataclass(frozen=True)
+class OnExit[A, E: EffectonError, R](Effect[A, E, R]):
+    first: Effect[Any, Any, Any]
+    finalizer: Effect[Any, Any, Any]
+    kind: Literal["on_exit"] = "on_exit"
+
+
+Node = (
+    Success[Any]
+    | Sync[Any]
+    | Coroutine[Any]
+    | FailCause[Any]
+    | FlatMap[Any, Any, Any]
+    | OnFailure[Any, Any, Any]
+    | Require[Any]
+    | ProvideRequirement[Any, Any, Any]
+    | OnExit[Any, Any, Any]
+)
+
+
+def success[A](value: A) -> Effect[A]:
+    return Success(value)
+
+
+def sync[A](fn: Callable[[], A]) -> Effect[A]:
+    return Sync(fn)
+
+
+def coroutine[A](fn: Callable[[], Awaitable[A]]) -> Effect[A]:
+    """Defer an awaitable; only the run_async family can interpret it.
+
+    The thunk runs once per run of the effect and must build a fresh
+    awaitable each time, because a coroutine object can be awaited only
+    once. Every exception, whether raised by the thunk or by the await,
+    becomes a defect; use attempt_async for typed failures. Interpreting
+    the effect with run_sync_exit settles as Die(AsyncEffectInSyncRun());
+    run_sync raises it.
+    """
+    return Coroutine(fn)
+
+
+def fail[E: EffectonError](error: E) -> Effect[Never, E]:
+    return FailCause(cause=Fail(error=error))
+
+
+def die(defect: Any) -> Effect[Never]:  # noqa: ANN401
+    return FailCause(cause=Die(defect=defect))
+
+
+def require[R](requirement_type: TypeForm[R]) -> Effect[R, Never, R]:
+    return Require(requirement_type=requirement_type)

effecton/exit.py

@@ -0,0 +1,63 @@
+from dataclasses import dataclass
+from typing import Any, Literal, Never, assert_never, final
+
+from effecton.effect import Cause, Die, EffectonError, Fail, Interrupt
+
+
+@final
+@dataclass(frozen=True)
+class Succeeded[A]:
+    value: A
+    kind: Literal["succeeded"] = "succeeded"
+
+
+@final
+@dataclass(frozen=True)
+class Failure[E: EffectonError = Never]:
+    cause: Cause[E]
+    kind: Literal["failure"] = "failure"
+
+
+type Exit[A, E: EffectonError = Never] = Succeeded[A] | Failure[E]
+
+
+@final
+@dataclass(frozen=True)
+class UnhandledDefect(Exception):
+    """Raised by a throwing runner for a defect that is not an exception.
+
+    Exception defects are re-raised as they are; any other value, such
+    as the argument of ``die("boom")``, is wrapped here so it can still
+    propagate through Python's exception machinery.
+    """
+
+    defect: Any
+
+    def __str__(self) -> str:
+        return f"Unhandled defect: {self.defect!r}"
+
+
+def unwrap[A, E: EffectonError](exit: Exit[A, E]) -> A:
+    """Return the value of a successful Exit, or raise its cause.
+
+    A typed failure raises the error itself, a defect re-raises the
+    exception (or UnhandledDefect for a non-exception value) and an
+    interruption re-raises the exception that signalled it.
+    """
+    match exit:
+        case Succeeded(value):
+            return value
+        case Failure(cause):
+            match cause:
+                case Fail(error):
+                    raise error
+                case Die(defect):
+                    if isinstance(defect, BaseException):
+                        raise defect
+                    raise UnhandledDefect(defect)
+                case Interrupt(exception):
+                    raise exception
+                case _:
+                    assert_never(cause)
+        case _:
+            assert_never(exit)

effecton/gen.py

@@ -0,0 +1,47 @@
+import functools
+from collections.abc import Callable, Generator
+from typing import Any, Never, cast
+
+from effecton.effect import Effect, EffectonError, success
+from effecton.suspend import suspend
+
+type EffectGen[A, E: EffectonError = Never, R = Never] = Generator[
+    Effect[Any, E, R], Any, A
+]
+"""Return type for @gen generator functions: yields effects, returns A."""
+
+
+def gen[**P, A2, E2: EffectonError, R2](
+    f: Callable[P, EffectGen[A2, E2, R2]],
+) -> Callable[P, Effect[A2, E2, R2]]:
+    """Turn a generator function into a factory of effects.
+
+    The interpreter runs each yielded effect and sends its result back;
+    the generator's return value becomes the effect's success value.
+    Use ``x = yield from effect`` instead of ``x = yield effect`` so the
+    type of ``x`` is inferred correctly.
+    The error and requirement channels flow from the annotated yield type
+    either way.
+
+    Each run creates a fresh generator, so the returned effect is a
+    reusable value. A failing yielded effect abandons the generator:
+    ``try/except`` around a ``yield`` never observes effect failures (use
+    catch_all), and ``finally`` blocks run only when the abandoned
+    generator is garbage collected.
+    """
+
+    @functools.wraps(f)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> Effect[A2, E2, R2]:
+        return suspend(lambda: _step(f(*args, **kwargs), None))
+
+    return wrapper
+
+
+def _step[A2, E2: EffectonError, R2](
+    g: EffectGen[A2, E2, R2], to_send: object
+) -> Effect[A2, E2, R2]:
+    try:
+        yielded = g.send(to_send)
+    except StopIteration as e:
+        return cast("Effect[A2, E2, R2]", success(e.value))
+    return yielded.flat_map(lambda v: _step(g, v))

effecton/implicit_requirement.py

@@ -0,0 +1,40 @@
+from typing import Any, Protocol, Self, cast, runtime_checkable
+
+from effecton.effect import Effect, EffectonError, ProvideRequirement, Require
+
+
+@runtime_checkable
+class ImplicitRequirement(Protocol):
+    """A requirement that carries its own default value.
+
+    The default is computed once per process and shared by every later
+    interpretation, so it must be an immutable value.
+    """
+
+    @classmethod
+    def default(cls) -> Self: ...
+
+
+# Implicits are lazily initialized. Once initialized, the default is
+# shared across all runs.
+_implicit_defaults: dict[type[ImplicitRequirement], Any] = {}
+
+
+def resolve_default[S: ImplicitRequirement](requirement_type: type[S]) -> S:
+    if requirement_type not in _implicit_defaults:
+        _implicit_defaults[requirement_type] = requirement_type.default()
+    return cast("S", _implicit_defaults[requirement_type])
+
+
+def require_implicit[S: ImplicitRequirement](
+    requirement_type: type[S],
+) -> Effect[S]:
+    return cast("Effect[S]", Require(requirement_type=requirement_type))
+
+
+def provide_implicit[S: ImplicitRequirement, A, E: EffectonError, R](
+    effect: Effect[A, E, R], value: S
+) -> Effect[A, E, R]:
+    return ProvideRequirement(
+        first=effect, requirement_type=type(value), requirement_impl=value
+    )

effecton/provide.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from typing import Generic, Never, TypeVar, final
+
+from typing_extensions import TypeForm
+
+from effecton.effect import Effect, EffectonError, ProvideRequirement
+
+# Old-style TypeVars declare the variance ty cannot infer across the
+# Effect ↔ ProvideBinder reference cycle; see the ty inference notes in
+# AGENTS.md.
+A = TypeVar("A", covariant=True)
+E = TypeVar("E", bound=EffectonError, covariant=True)
+R = TypeVar("R", covariant=True)
+T = TypeVar("T")
+
+
+@final
+@dataclass(frozen=True)
+class ProvideBinder(Generic[A, E, R, T]):  # noqa: UP046
+    """One step of ``effect.provide(T)(impl)``: T is bound, impl pending.
+
+    Calling it subtracts T from the effect's R and returns the effect
+    with the remaining requirements.
+    """
+
+    effect: Effect[A, E, R]
+    requirement_type: TypeForm[T]
+
+    def __call__[A2, E2: EffectonError, R2 = Never](
+        self: ProvideBinder[A2, E2, T | R2, T], impl: T
+    ) -> Effect[A2, E2, R2]:
+        return ProvideRequirement(
+            first=self.effect,
+            requirement_type=self.requirement_type,
+            requirement_impl=impl,
+        )