effecton 0.2.0__py3-none-any.whl

effecton/run_async.py

@@ -0,0 +1,237 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, assert_never, final
+
+from typing_extensions import TypeForm
+
+from effecton.effect import (
+    Coroutine,
+    Die,
+    Effect,
+    EffectonError,
+    Fail,
+    FailCause,
+    FlatMap,
+    Interrupt,
+    Node,
+    OnExit,
+    OnFailure,
+    ProvideRequirement,
+    Require,
+    Success,
+    Sync,
+)
+from effecton.exit import Exit, Failure, Succeeded, unwrap
+from effecton.run_sync import (
+    Frame,
+    OnExitFrame,
+    RestoreEnv,
+    default_or_die,
+    run_fn_or_die,
+)
+
+
+@final
+@dataclass(frozen=True)
+class Finalizing:
+    """Interpreter stack frame delimiting a running finalizer.
+
+    Holds the outcome the finalizer interrupts, to resume once it settles.
+    While one is on the stack, awaits are shielded from cancellation.
+    """
+
+    outcome: Node
+
+
+def run_async[A, E: EffectonError](effect: Effect[A, E]) -> A:
+    """Run an effect on a fresh asyncio loop and return its value.
+
+    Owns the event loop through asyncio.run, so it cannot be called from
+    a running loop; use run_async_coroutine there. 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. Use run_async_exit to receive the Exit
+    instead.
+    """
+    return unwrap(run_async_exit(effect))
+
+
+def run_async_exit[A, E: EffectonError](effect: Effect[A, E]) -> Exit[A, E]:
+    """Run an effect on a fresh asyncio loop and return its Exit.
+
+    Owns the event loop through asyncio.run, so it cannot be called from
+    a running loop; use run_async_coroutine there.
+    """
+    return asyncio.run(run_async_coroutine(effect))
+
+
+async def run_async_coroutine[A, E: EffectonError](effect: Effect[A, E]) -> Exit[A, E]:
+    """Interpret an effect under asyncio, awaiting every coroutine effect.
+
+    This is the coroutine form for a caller that already owns a loop:
+    pass it to asyncio.run, create_task or await it directly.
+
+    A cancellation, or any other BaseException raised by an await, a
+    thunk or a callback, unwinds the effect with an Interrupt cause so
+    finalizers run, and the run settles as Failure(Interrupt(exception)).
+    The cancellation is consumed: a caller whose task should stop
+    re-raises the carried exception. Finalizers are shielded: a
+    cancellation that arrives while one is awaiting is remembered, the
+    finalizer runs to completion, and the interruption is applied once
+    it settles.
+    """
+    stack: list[Frame | Finalizing] = []
+    env: dict[TypeForm[Any], Any] = {}
+    cancelled: BaseException | None = None
+    finalizing = 0
+    current: Node = effect  # ty: ignore[invalid-assignment]
+
+    def unwind(e: BaseException) -> Node:
+        nonlocal cancelled
+        if isinstance(e, Exception):
+            return FailCause(cause=Die(defect=e))
+        if cancelled is None:
+            cancelled = e
+        return FailCause(cause=Interrupt(exception=e))
+
+    def guarded[**P](f: Callable[P, Node], *args: P.args, **kwargs: P.kwargs) -> Node:
+        try:
+            return f(*args, **kwargs)
+        except BaseException as e:
+            return unwind(e)
+
+    async def awaited(fn: Callable[[], Awaitable[Any]]) -> Node:
+        try:
+            return Success(await fn())
+        except BaseException as e:
+            return unwind(e)
+
+    async def awaited_uninterruptibly(fn: Callable[[], Awaitable[Any]]) -> Node:
+        async def run() -> Any:  # noqa: ANN401
+            return await fn()
+
+        # The finalizer runs as its own task so a cancellation of this
+        # task lands on the shield instead of aborting it. It shares this
+        # task's Context rather than a copy, so context variables it sets
+        # or resets behave as if it ran inline.
+        task = asyncio.current_task()
+        inner = asyncio.get_running_loop().create_task(
+            run(), context=task.get_context() if task is not None else None
+        )
+
+        # Remember the cancellation and keep waiting for the finalizer.
+        while not inner.done():
+            try:
+                await asyncio.shield(inner)
+            except BaseException as e:
+                unwind(e)
+        return guarded(lambda: Success(inner.result()))
+
+    while True:
+        match current:
+            case Success(value):
+                while stack:
+                    item = stack.pop()
+
+                    match item:
+                        case RestoreEnv():
+                            env = item.env
+                        case OnExitFrame(finalizer):
+                            stack.append(Finalizing(outcome=current))
+                            finalizing += 1
+                            current = finalizer  # ty: ignore[invalid-assignment]
+                            break
+                        case Finalizing(outcome):
+                            finalizing -= 1
+                            current = _interrupted(cancelled, finalizing) or outcome
+                            break
+                        case FlatMap():
+                            current = guarded(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):
+                            stack.append(Finalizing(outcome=current))
+                            finalizing += 1
+                            current = finalizer  # ty: ignore[invalid-assignment]
+                            break
+                        case Finalizing():
+                            # The finalizer died; its defect replaces the
+                            # outcome it was finalizing.
+                            finalizing -= 1
+                            interrupted = _interrupted(cancelled, finalizing)
+                            if interrupted is not None:
+                                current = interrupted
+                                break
+                        case FlatMap():
+                            continue
+                        case OnFailure():
+                            if isinstance(cause, Fail):
+                                current = guarded(
+                                    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  # ty: ignore[invalid-assignment]
+
+            case OnFailure(first):
+                stack.append(current)
+                current = first  # ty: ignore[invalid-assignment]
+
+            case Sync(fn):
+                current = guarded(lambda: Success(fn()))
+
+            case Coroutine(fn):
+                current = await (
+                    awaited_uninterruptibly(fn) if finalizing else awaited(fn)
+                )
+
+            case Require(requirement_type):
+                if requirement_type in env:
+                    current = Success(env[requirement_type])
+                else:
+                    current = guarded(lambda: default_or_die(requirement_type))
+
+            case ProvideRequirement(first, requirement_type, requirement_impl):
+                stack.append(RestoreEnv(env))
+                env = {**env, requirement_type: requirement_impl}
+                current = first  # ty: ignore[invalid-assignment]
+
+            case OnExit(first, finalizer):
+                stack.append(OnExitFrame(finalizer))
+                current = first  # ty: ignore[invalid-assignment]
+
+            case _:
+                assert_never(current)
+
+
+def _interrupted(cancelled: BaseException | None, finalizing: int) -> Node | None:
+    """The node to resume with once the outermost finalizer settles.
+
+    Interruption is sticky: a cancellation noted while finalizers ran is
+    applied as soon as the run becomes interruptible again, overriding a
+    resumed success or a finalizer defect. Inside a nested finalizer it
+    is deferred, so the enclosing finalizer runs to completion.
+    """
+    if cancelled is None or finalizing > 0:
+        return None
+    return FailCause(cause=Interrupt(exception=cancelled))

effecton/run_sync.py

@@ -0,0 +1,199 @@
+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 (
+    Coroutine,
+    Die,
+    Effect,
+    EffectonError,
+    Fail,
+    FailCause,
+    FlatMap,
+    Node,
+    OnExit,
+    OnFailure,
+    ProvideRequirement,
+    Require,
+    Success,
+    Sync,
+)
+from effecton.exit import Exit, Failure, Succeeded, unwrap
+from effecton.implicit_requirement import ImplicitRequirement, resolve_default
+
+
+@final
+@dataclass(frozen=True)
+class MissingRequirement(Exception):
+    """Defect for a requirement requested at runtime without being provided.
+
+    Unreachable through fully typed code. run_sync_exit settles as
+    Failure(Die(MissingRequirement(...))); run_sync raises it.
+    """
+
+    requirement_type: TypeForm[Any]
+
+    def __str__(self) -> str:
+        return f"No implementation provided for requirement {self.requirement_type!r}"
+
+
+@final
+@dataclass(frozen=True)
+class AsyncEffectInSyncRun(Exception):
+    """Defect for a coroutine effect reached by a synchronous runner.
+
+    Only the run_async family can await. run_sync_exit settles as
+    Failure(Die(AsyncEffectInSyncRun())); run_sync raises it.
+    """
+
+    def __str__(self) -> str:
+        return "A coroutine effect cannot run synchronously; run it with run_async"
+
+
+@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]) -> A:
+    """Interpret an effect and return its value, raising on failure.
+
+    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. Use
+    run_sync_exit to receive the Exit instead.
+    """
+    return unwrap(run_sync_exit(effect))
+
+
+def run_sync_exit[A, E: EffectonError](effect: Effect[A, E]) -> Exit[A, E]:
+    """Interpret an effect and return its Exit.
+
+    Coroutine effects are not awaited: reaching one settles the run as
+    Failure(Die(AsyncEffectInSyncRun())), and finalizers still run.
+    """
+    stack: list[Frame] = []
+    env: dict[TypeForm[Any], Any] = {}
+    current: Node = effect  # ty: ignore[invalid-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))  # ty: ignore[invalid-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))  # ty: ignore[invalid-assignment]
+                            break
+                        case FlatMap():
+                            continue
+                        case OnFailure():
+                            if isinstance(cause, Fail):
+                                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  # ty: ignore[invalid-assignment]
+
+            case OnFailure(first):
+                stack.append(current)
+                current = first  # ty: ignore[invalid-assignment]
+
+            case Sync(fn):
+                try:
+                    current = Success(fn())
+                except Exception as e:
+                    current = FailCause(cause=Die(defect=e))
+
+            case Coroutine():
+                current = FailCause(cause=Die(defect=AsyncEffectInSyncRun()))
+
+            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  # ty: ignore[invalid-assignment]
+
+            case OnExit(first, finalizer):
+                stack.append(OnExitFrame(finalizer))
+                current = first  # ty: ignore[invalid-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)  # ty: ignore[invalid-return-type]
+    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."""

effecton/std/logger.py

@@ -0,0 +1,214 @@
+import logging
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Literal, assert_never, final
+
+from effecton.effect import Effect, EffectonError, ProvideRequirement
+from effecton.gen import EffectGen, gen
+from effecton.implicit_requirement import ImplicitRequirement, require_implicit
+
+
+@final
+class LogLevel(Enum):
+    ALL = "all"
+    TRACE = "trace"
+    DEBUG = "debug"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+    FATAL = "fatal"
+    NONE = "none"
+
+
+type Severity = Literal[
+    LogLevel.TRACE,
+    LogLevel.DEBUG,
+    LogLevel.INFO,
+    LogLevel.WARN,
+    LogLevel.ERROR,
+    LogLevel.FATAL,
+]
+"""Levels a message can be logged at.
+
+Excludes the ALL and NONE sentinels, which are only meaningful as a
+MinimumLogLevel threshold: ALL passes everything, NONE silences everything.
+"""
+
+
+def log_level_order(level: LogLevel) -> int:
+    """Position in the severity ordering; only relative order matters."""
+    match level:
+        case LogLevel.ALL:
+            return 0
+        case LogLevel.TRACE:
+            return 1
+        case LogLevel.DEBUG:
+            return 2
+        case LogLevel.INFO:
+            return 3
+        case LogLevel.WARN:
+            return 4
+        case LogLevel.ERROR:
+            return 5
+        case LogLevel.FATAL:
+            return 6
+        case LogLevel.NONE:
+            return 7
+        case _:
+            assert_never(level)
+
+
+@final
+@dataclass(frozen=True)
+class LogData:
+    message: tuple[object, ...]
+    log_level: Severity
+    date: datetime
+    annotations: Mapping[str, object]
+
+
+@final
+@dataclass(frozen=True)
+class EffectonLogger:
+    log: Callable[[LogData], None]
+
+
+_TRACE_LEVEL = 5
+logging.addLevelName(_TRACE_LEVEL, "TRACE")
+
+
+def _to_python_logger_level(level: Severity) -> int:
+    match level:
+        case LogLevel.TRACE:
+            return _TRACE_LEVEL
+        case LogLevel.DEBUG:
+            return logging.DEBUG
+        case LogLevel.INFO:
+            return logging.INFO
+        case LogLevel.WARN:
+            return logging.WARNING
+        case LogLevel.ERROR:
+            return logging.ERROR
+        case LogLevel.FATAL:
+            return logging.CRITICAL
+        case _:
+            assert_never(level)
+
+
+@final
+@dataclass(frozen=True)
+class CurrentLoggers(ImplicitRequirement):
+    loggers: tuple[EffectonLogger, ...]
+
+    @classmethod
+    def default(cls) -> CurrentLoggers:
+        from effecton.std.pretty_logger import pretty_logger
+
+        return CurrentLoggers((pretty_logger,))
+
+
+@final
+@dataclass(frozen=True)
+class MinimumLogLevel(ImplicitRequirement):
+    level: LogLevel
+
+    @classmethod
+    def default(cls) -> MinimumLogLevel:
+        return MinimumLogLevel(LogLevel.INFO)
+
+
+@final
+@dataclass(frozen=True)
+class CurrentLogLevel(ImplicitRequirement):
+    """The level a bare log(...) call logs at."""
+
+    level: Severity
+
+    @classmethod
+    def default(cls) -> CurrentLogLevel:
+        return CurrentLogLevel(LogLevel.INFO)
+
+
+@final
+@dataclass(frozen=True)
+class CurrentLogAnnotations(ImplicitRequirement):
+    annotations: Mapping[str, object]
+
+    @classmethod
+    def default(cls) -> CurrentLogAnnotations:
+        return CurrentLogAnnotations({})
+
+
+def log(*message: object) -> Effect[None]:
+    return _log_with_level(None, message)
+
+
+def log_trace(*message: object) -> Effect[None]:
+    return _log_with_level(LogLevel.TRACE, message)
+
+
+def log_debug(*message: object) -> Effect[None]:
+    return _log_with_level(LogLevel.DEBUG, message)
+
+
+def log_info(*message: object) -> Effect[None]:
+    return _log_with_level(LogLevel.INFO, message)
+
+
+def log_warning(*message: object) -> Effect[None]:
+    return _log_with_level(LogLevel.WARN, message)
+
+
+def log_error(*message: object) -> Effect[None]:
+    return _log_with_level(LogLevel.ERROR, message)
+
+
+def log_fatal(*message: object) -> Effect[None]:
+    return _log_with_level(LogLevel.FATAL, message)
+
+
+def annotate_logs[A, E: EffectonError, R](
+    effect: Effect[A, E, R], **annotations: object
+) -> Effect[A, E, R]:
+    """Merge annotations into every log call inside the wrapped effect."""
+    return require_implicit(CurrentLogAnnotations).flat_map(
+        lambda current: ProvideRequirement(
+            first=effect,
+            requirement_type=CurrentLogAnnotations,
+            requirement_impl=CurrentLogAnnotations(
+                {**current.annotations, **annotations}
+            ),
+        )
+    )
+
+
+@gen
+def _log_with_level(
+    level: Severity | None, message: tuple[object, ...]
+) -> EffectGen[None]:
+    minimum = yield from require_implicit(MinimumLogLevel)
+    log_level = (
+        level
+        if level is not None
+        else (yield from require_implicit(CurrentLogLevel)).level
+    )
+
+    if log_level_order(log_level) < log_level_order(minimum.level):
+        return None
+
+    loggers = yield from require_implicit(CurrentLoggers)
+    annotations = yield from require_implicit(CurrentLogAnnotations)
+
+    date = datetime.now()
+    for logger in loggers.loggers:
+        logger.log(
+            LogData(
+                message=message,
+                log_level=log_level,
+                date=date,
+                annotations=annotations.annotations,
+            )
+        )
+    return None