effecton 0.1.0__py3-none-any.whl

effecton/__init__.py

@@ -0,0 +1,91 @@
+from effecton.attempt import attempt
+from effecton.effect import (
+    Cause,
+    Die,
+    Effect,
+    EffectonError,
+    Fail,
+    die,
+    fail,
+    require,
+    success,
+    sync,
+)
+from effecton.exit import Exit, Failure, Succeeded
+from effecton.gen import EffectGen, gen
+from effecton.implicit_requirement import (
+    ImplicitRequirement,
+    provide_implicit,
+    require_implicit,
+)
+from effecton.provide import RequirementProvider
+from effecton.run_sync import MissingRequirement, run_sync
+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__ = [
+    "Cause",
+    "CurrentLogAnnotations",
+    "CurrentLogLevel",
+    "CurrentLoggers",
+    "Die",
+    "Effect",
+    "EffectGen",
+    "EffectonError",
+    "EffectonLogger",
+    "Exit",
+    "Fail",
+    "Failure",
+    "ImplicitRequirement",
+    "LogData",
+    "LogLevel",
+    "MinimumLogLevel",
+    "MissingRequirement",
+    "PrettyFormatter",
+    "RequirementProvider",
+    "Scope",
+    "Severity",
+    "Succeeded",
+    "acquire_and_release",
+    "add_finalizer",
+    "annotate_logs",
+    "attempt",
+    "die",
+    "fail",
+    "gen",
+    "log",
+    "log_debug",
+    "log_error",
+    "log_fatal",
+    "log_info",
+    "log_trace",
+    "log_warning",
+    "pretty_logger",
+    "provide_implicit",
+    "require",
+    "require_implicit",
+    "run_sync",
+    "scoped",
+    "success",
+    "suspend",
+    "sync",
+]

effecton/attempt.py

@@ -0,0 +1,24 @@
+from collections.abc import Callable
+
+from effecton.effect import Effect, EffectonError, fail, success
+from effecton.suspend import 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.
+    """
+
+    def go() -> Effect[A, E]:
+        try:
+            return success(thunk())
+        except Exception as e:
+            return fail(on_error(e))
+
+    return suspend(go)

effecton/effect.py

@@ -0,0 +1,155 @@
+from collections.abc import Callable, Generator
+from dataclasses import dataclass
+from typing import Any, Generic, Literal, Never, TypeVar, final
+
+from typing_extensions import TypeForm
+
+
+@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
+
+
+type Cause[E] = Fail[E] | Die
+
+# Variance is declared through old-style TypeVars: mypy's PEP 695
+# inference wrongly makes A, E, and R invariant once the class has a
+# third type parameter. This might be unnecessary once we switch to ty.
+A = TypeVar("A", covariant=True)
+E = TypeVar("E", bound=EffectonError, covariant=True, default=Never)
+R = TypeVar("R", covariant=True, default=Never)
+
+
+class Effect(Generic[A, E, R]):
+    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)))  # type: ignore[misc]
+
+    def catch_all[B, E2: EffectonError, R2](
+        self, f: Callable[[E], Effect[B, E2, R2]]
+    ) -> Effect[A | B, E2, R | R2]:
+        return OnFailure(self, f)
+
+    def on_exit[R2](self, finalizer: Effect[Any, Never, R2]) -> Effect[A, E, R | R2]:
+        return OnExit(self, finalizer)
+
+    def __iter__(self) -> Generator[Effect[A, E, R], A, 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 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]
+    | 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 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,21 @@
+from dataclasses import dataclass
+from typing import Literal, Never, final
+
+from effecton.effect import Cause, EffectonError
+
+
+@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]

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,48 @@
+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.
+
+    Extend it explicitly — ``class Foo(ImplicitRequirement)`` — so mypy
+    rejects the definition site when ``default()`` is missing or
+    mis-typed. As a Protocol, any class with a matching ``default()``
+    classmethod also qualifies structurally, but explicit inheritance is
+    the convention. Requiring one never enters the R channel: the
+    interpreter falls back to the memoized default on a miss, and
+    ordinary provision still overrides it.
+
+    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 run_sync executions.
+_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,60 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Never, cast, final
+
+from typing_extensions import TypeForm
+
+from effecton.effect import Effect, EffectonError, ProvideRequirement
+
+if TYPE_CHECKING:
+    from effecton.std.scope import Scope
+
+
+@final
+@dataclass(frozen=True)
+class RequirementProvider[R = Never]:
+    """Accumulates provided requirements, then discharges them in one apply.
+
+    mypy limitations dictate this design: all requirements must be
+    provided at once; otherwise the remaining requirements are not
+    subtracted correctly and collapse to object.
+    """
+
+    _links: tuple[tuple[TypeForm[Any], Any], ...] = ()
+
+    def and_provide[R2](
+        self, requirement_type: TypeForm[R2]
+    ) -> ChainedRequirementBinder[R, R2]:
+        return ChainedRequirementBinder(requirement_type=requirement_type, _rest=self)
+
+    def and_scoped[A, E: EffectonError](
+        self, effect: Effect[A, E, Scope | R]
+    ) -> Effect[A, E]:
+        """Discharge the chain plus a Scope created fresh per interpretation."""
+        from effecton.std.scope import scoped
+
+        return self.apply(scoped(effect))
+
+    def apply[A, E: EffectonError](self, effect: Effect[A, E, R]) -> Effect[A, E]:
+        result: Effect[A, E, Any] = effect
+        for requirement_type, requirement_impl in self._links:
+            result = ProvideRequirement(
+                first=result,
+                requirement_type=requirement_type,
+                requirement_impl=requirement_impl,
+            )
+        return cast("Effect[A, E]", result)
+
+
+@final
+@dataclass(frozen=True)
+class ChainedRequirementBinder[R, R2]:
+    requirement_type: TypeForm[R2]
+    _rest: RequirementProvider[Any]
+
+    def __call__(self, requirement_impl: R2) -> RequirementProvider[R | R2]:
+        return cast(
+            "RequirementProvider[R | R2]",
+            RequirementProvider(
+                _links=(*self._rest._links, (self.requirement_type, requirement_impl))
+            ),
+        )

effecton/run_sync.py

@@ -0,0 +1,161 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, assert_never, final
+
+from typing_extensions import TypeForm
+
+from effecton.effect import (
+    Die,
+    Effect,
+    EffectonError,
+    FailCause,
+    FlatMap,
+    Node,
+    OnExit,
+    OnFailure,
+    ProvideRequirement,
+    Require,
+    Success,
+    Sync,
+)
+from effecton.exit import Exit, Failure, Succeeded
+from effecton.implicit_requirement import ImplicitRequirement, resolve_default
+
+
+@final
+@dataclass(frozen=True)
+class MissingRequirement:
+    """Defect raised when an unprovided requirement is requested at runtime.
+
+    Unreachable through fully typed code.
+    """
+
+    requirement_type: TypeForm[Any]
+
+
+@final
+@dataclass(frozen=True)
+class RestoreEnv:
+    """Interpreter stack frame delimiting a ProvideRequirement scope."""
+
+    env: dict[TypeForm[Any], Any]
+
+
+@final
+@dataclass(frozen=True)
+class OnExitFrame:
+    finalizer: Effect[Any, Any, Any]
+
+
+Frame = FlatMap[Any, Any, Any] | OnFailure[Any, Any, Any] | RestoreEnv | OnExitFrame
+
+
+def run_sync[A, E: EffectonError](effect: Effect[A, E]) -> Exit[A, E]:
+    stack: list[Frame] = []
+    env: dict[TypeForm[Any], Any] = {}
+    current: Node = effect  # type: ignore[assignment]
+
+    while True:
+        match current:
+            case Success(value):
+                while stack:
+                    item = stack.pop()
+
+                    match item:
+                        case RestoreEnv():
+                            env = item.env
+                        case OnExitFrame(finalizer):
+                            current = finalizer.flat_map(_resume(current))  # type: ignore[assignment]
+                            break
+                        case FlatMap():
+                            current = _run_fn_or_die(item.and_then, value)
+                            break
+                        case OnFailure():
+                            continue
+                        case _:
+                            assert_never(item)
+                else:
+                    return Succeeded(value=value)
+
+            case FailCause(cause):
+                while stack:
+                    item = stack.pop()
+
+                    match item:
+                        case RestoreEnv():
+                            env = item.env
+                        case OnExitFrame(finalizer):
+                            current = finalizer.flat_map(_resume(current))  # type: ignore[assignment]
+                            break
+                        case FlatMap():
+                            continue
+                        case OnFailure():
+                            if not isinstance(cause, Die):
+                                current = _run_fn_or_die(item.handler, cause.error)
+                                break
+                        case _:
+                            assert_never(item)
+                else:
+                    return Failure(cause=cause)
+
+            case FlatMap(first):
+                stack.append(current)
+                current = first  # type: ignore[assignment]
+
+            case OnFailure(first):
+                stack.append(current)
+                current = first  # type: ignore[assignment]
+
+            case Sync(fn):
+                try:
+                    current = Success(fn())
+                except Exception as e:
+                    current = FailCause(cause=Die(defect=e))
+
+            case Require(requirement_type):
+                if requirement_type in env:
+                    current = Success(env[requirement_type])
+                else:
+                    current = _default_or_die(requirement_type)
+
+            case ProvideRequirement(first, requirement_type, requirement_impl):
+                stack.append(RestoreEnv(env))
+                env = {**env, requirement_type: requirement_impl}
+                current = first  # type: ignore[assignment]
+
+            case OnExit(first, finalizer):
+                stack.append(OnExitFrame(finalizer))
+                current = first  # type: ignore[assignment]
+
+            case _:
+                assert_never(current)
+
+
+def _default_or_die(requirement_type: TypeForm[Any]) -> Node:
+    if (
+        isinstance(requirement_type, type)
+        and issubclass(requirement_type, ImplicitRequirement)
+        # Exclude the protocol class itself
+        and not getattr(requirement_type, "_is_protocol", False)
+    ):
+        try:
+            return Success(resolve_default(requirement_type))
+        except Exception as e:
+            return FailCause(cause=Die(defect=e))
+
+    return FailCause(cause=Die(defect=MissingRequirement(requirement_type)))
+
+
+def _run_fn_or_die(f: Callable[[Any], Effect[Any, Any]], value: object) -> Node:
+    try:
+        return f(value)  # type: ignore[return-value]
+    except Exception as e:
+        return FailCause(cause=Die(defect=e))
+
+
+# Captures the current outcome by closure.
+def _resume(outcome: Node) -> Callable[[Any], Effect[Any, Any, Any]]:
+    def resume(_: object) -> Effect[Any, Any, Any]:
+        return outcome
+
+    return resume

effecton/std/__init__.py

@@ -0,0 +1 @@
+"""Standard-library modules built on the effecton kernel."""