effecton 0.2.1__tar.gz → 0.3.1__tar.gz

effecton-0.3.1/.gitignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Copied from the repo root by the release workflow
+packages/effecton/LICENSE
+
+# Docs site (vocs)
+docs/node_modules
+docs/dist
+docs/.vocs
+docs/src/pages.gen.ts
+# Generated by `uv run api-reference` (docs predev/prebuild)
+docs/src/pages/api.md
+
+# Agent working artifacts: implementation plans and SDD ledgers stay local.
+# Design specs are committed under docs/specs instead (see AGENTS.md).
+docs/superpowers/
+.superpowers/

effecton-0.3.1/CHANGELOG.md

@@ -0,0 +1,54 @@
+# effecton
+
+## 0.3.1
+
+### Patch Changes
+
+- Add E.Schema: two-way schemas with Struct classes, combinators, guarded transforms (`to=`, `S.instance_of`) and `Check` refinements applied with `schema.check(...)`, whose decode and encode fail with a ParseError listing every issue ([#32](https://github.com/krzkaczor/effecton/pull/32))
+- Add E.Cli: annotated Args classes decoded through E.Schema, nested commands, --help, --version and a UsageError carrying the reason; add E.Process.argv() ([#34](https://github.com/krzkaczor/effecton/pull/34))
+
+## 0.3.0
+
+### Minor Changes
+
+- Launch the docs site: a landing page, an introduction, and a generated API Reference, with every Python snippet type-checked by ty at build time. ([#26](https://github.com/krzkaczor/effecton/pull/26))
+
+### Patch Changes
+
+- Add the E.HttpClient service: SyncLive and AsyncLive on httpx2, Test with canned responses or a handler, Request/Response values and filter_status_ok; HTTP client libraries are banned outside the service ([#24](https://github.com/krzkaczor/effecton/pull/24))
+- sleep, timeout and Schedule.spaced/exponential accept a duration as timedelta's keyword parts (seconds=5, minutes=1, ...) in place of a timedelta. ([#26](https://github.com/krzkaczor/effecton/pull/26))
+- Add the `E.Tracer` service: `E.with_span(effect, name, kind=..., **attributes)` opens a span around an effect (also as `effect.with_span`), `E.annotate_current_span` adds attributes, `E.current_span` reads the open span, `E.Tracer.Live` is the in-memory default, `E.Tracer.Test` records its spans, and the `test_tracer` pytest fixture provides one ([#25](https://github.com/krzkaczor/effecton/pull/25))
+- Add `effect.retry(schedule, until=...)` with `E.Schedule.recurs`, `E.Schedule.spaced`, and `E.Schedule.exponential` ([#19](https://github.com/krzkaczor/effecton/pull/19))
+- Effect.retry takes an optional schedule and a `times` keyword, as in Effect-TS: `retry(times=3)` retries up to three times without waiting, `retry(schedule, times=5)` caps the schedule at five more recurrences, and `retry()` with neither recurs forever. ([#26](https://github.com/krzkaczor/effecton/pull/26))
+- Add `schedule.jittered(min=0.8, max=1.2)`, which scales every delay by a factor drawn through `E.random()`; schedule steps are now effects, so build a plain custom schedule with `E.Schedule.from_delays(...)` and an effectful one with `E.Schedule(steps=...)` ([#22](https://github.com/krzkaczor/effecton/pull/22))
+- Add the `E.FileSystem` service (`SyncLive`, `AsyncLive` on aiofiles, in-memory `Test`) the immutable `E.Path`, and the `E.Process` service (`cwd`, `home`); stdlib path and file APIs are banned outside the service ([#23](https://github.com/krzkaczor/effecton/pull/23))
+- `on_exit` also accepts a function receiving the effect's `Exit` and returning the finalizer, so cleanup can depend on how the effect settled ([#25](https://github.com/krzkaczor/effecton/pull/25))
+- Add the `E.Random` implicit service: `E.random()` resolves it, its methods keep the `random` module names (`random`, `uniform`, `randint`, `choice`, `shuffle`), `E.Random.Live` is the default, `E.Random.Test(seed)` is deterministic, and the `test_random` pytest fixture provides one seeded with 0 ([#22](https://github.com/krzkaczor/effecton/pull/22))
+
+## 0.2.1
+
+### Patch Changes
+
+- Ship a pytest plugin, registered through the pytest11 entry point so it loads wherever effecton is installed. A test that returns an Effect (typically an @E.gen function) runs under the async runner and a failure is reported as its cause. The test_clock fixture provides an E.Clock.Test to the test's effect. ([#16](https://github.com/krzkaczor/effecton/pull/16))
+- Add E.now() and E.sleep() backed by the implicit E.Clock service, with SyncLive, AsyncLive and Test clocks; each runner installs the matching live clock. ([#16](https://github.com/krzkaczor/effecton/pull/16))
+- Add `E.run_main` to execute sync and async programs with failure logging, defect tracebacks, custom exit codes, and graceful signal handling. ([#14](https://github.com/krzkaczor/effecton/pull/14))
+- Add E.fork, E.Fiber (join, wait, poll, interrupt) and E.yield_now backed by asyncio tasks, and make the Test clock's adjust and set_time return effects. ([#16](https://github.com/krzkaczor/effecton/pull/16))
+- Add E.race_first(left, right) and E.timeout(duration) ([#18](https://github.com/krzkaczor/effecton/pull/18))
+
+## 0.2.0
+
+### Minor Changes
+
+- Add `run_async`, `coroutine` and `attempt_async` for awaitable-backed effects ([#12](https://github.com/krzkaczor/effecton/pull/12))
+- Split the runners: `run_sync` and `run_async` now return the value and raise on failure (the error, the defect, or `UnhandledDefect` for a non-exception defect); `run_sync_exit`, `run_async_exit` and the coroutine `run_async_coroutine` return the `Exit` ([#13](https://github.com/krzkaczor/effecton/pull/13))
+
+### Patch Changes
+
+- Add `Effect.catch`: handle one error type and subtract it from the error channel. ([#10](https://github.com/krzkaczor/effecton/pull/10))
+- Add `Interrupt` as a third `Cause` state, produced when a cancellation unwinds `run_async` ([#12](https://github.com/krzkaczor/effecton/pull/12))
+
+## 0.1.1
+
+### Patch Changes
+
+- Migrate from mypy to ty. Simplify api where possible. ([#1](https://github.com/krzkaczor/effecton/pull/1))

effecton-0.3.1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.5
+Name: effecton
+Version: 0.3.1
+Summary: A typed effect system for Python, inspired by Effect-TS
+Project-URL: Repository, https://github.com/krzkaczor/effecton
+Author-email: Krzysztof Kaczor <chris@kaczor.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dependency-injection,effect-system,effect-ts,functional,typed
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiofiles>=25.1
+Requires-Dist: httpx2>=2.12
+Requires-Dist: typing-extensions>=4.16.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://effecton.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/krzkaczor/effecton/main/docs/public/logo-wordmark-white.svg">
+      <img alt="effecton" src="https://raw.githubusercontent.com/krzkaczor/effecton/main/docs/public/logo-wordmark.svg" width="320">
+    </picture>
+  </a>
+</p>
+
+<p align="center">A typed effect system for Python, inspired by <a href="https://effect.website/">Effect-TS</a>.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/effecton/"><img alt="PyPI" src="https://img.shields.io/pypi/v/effecton?logo=pypi&logoColor=white"></a>
+  <a href="https://discord.gg/fNhY7AxMyh"><img alt="Discord" src="https://img.shields.io/badge/Discord-join%20chat-5865F2?logo=discord&logoColor=white"></a>
+</p>
+
+<p align="center">
+  <a href="https://effecton.dev/introduction">Documentation</a> ·
+  <a href="https://effecton.dev/api">API Reference</a> ·
+  <a href="https://github.com/krzkaczor/effecton/blob/main/CONTRIBUTING.md">Contributing</a>
+</p>
+
+```sh
+uv add effecton
+```

effecton-0.3.1/README.md

@@ -0,0 +1,25 @@
+<p align="center">
+  <a href="https://effecton.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/krzkaczor/effecton/main/docs/public/logo-wordmark-white.svg">
+      <img alt="effecton" src="https://raw.githubusercontent.com/krzkaczor/effecton/main/docs/public/logo-wordmark.svg" width="320">
+    </picture>
+  </a>
+</p>
+
+<p align="center">A typed effect system for Python, inspired by <a href="https://effect.website/">Effect-TS</a>.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/effecton/"><img alt="PyPI" src="https://img.shields.io/pypi/v/effecton?logo=pypi&logoColor=white"></a>
+  <a href="https://discord.gg/fNhY7AxMyh"><img alt="Discord" src="https://img.shields.io/badge/Discord-join%20chat-5865F2?logo=discord&logoColor=white"></a>
+</p>
+
+<p align="center">
+  <a href="https://effecton.dev/introduction">Documentation</a> ·
+  <a href="https://effecton.dev/api">API Reference</a> ·
+  <a href="https://github.com/krzkaczor/effecton/blob/main/CONTRIBUTING.md">Contributing</a>
+</p>
+
+```sh
+uv add effecton
+```

{effecton-0.2.1 → effecton-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "effecton"
-version = "0.2.1"
+version = "0.3.1"
 description = "A typed effect system for Python, inspired by Effect-TS"
 readme = "README.md"
 license = "MIT"
@@ -14,6 +14,8 @@ classifiers = [
 ]
 requires-python = ">=3.14"
 dependencies = [
+    "aiofiles>=25.1",
+    "httpx2>=2.12",
     "typing-extensions>=4.16.0",
 ]
 
@@ -23,6 +25,9 @@ Repository = "https://github.com/krzkaczor/effecton"
 [project.entry-points.pytest11]
 effecton = "effecton.pytest_plugin"
 
+[dependency-groups]
+dev = ["types-aiofiles>=25.1"]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

{effecton-0.2.1 → effecton-0.3.1}/src/effecton/__init__.py

@@ -28,7 +28,14 @@ from effecton.run_sync import (
     run_sync,
     run_sync_exit,
 )
+from effecton.std import cli as Cli
 from effecton.std import clock as Clock
+from effecton.std import file_system as FileSystem
+from effecton.std import http_client as HttpClient
+from effecton.std import process as Process
+from effecton.std import random as Random
+from effecton.std import schema as Schema
+from effecton.std import tracer as Tracer
 from effecton.std.clock import _now as now
 from effecton.std.clock import _sleep as sleep
 from effecton.std.fiber import Fiber, fork, yield_now
@@ -50,15 +57,22 @@ from effecton.std.logger import (
     log_trace,
     log_warning,
 )
+from effecton.std.path import Path
 from effecton.std.pretty_logger import PrettyFormatter, pretty_logger
 from effecton.std.race import race_first
+from effecton.std.random import _random as random
+from effecton.std.schedule import Schedule
 from effecton.std.scope import Scope, acquire_and_release, add_finalizer, scoped
 from effecton.std.timeout import TimeoutException, timeout
+from effecton.std.tracer import _annotate_current_span as annotate_current_span
+from effecton.std.tracer import _current_span as current_span
+from effecton.std.tracer import _with_span as with_span
 from effecton.suspend import suspend
 
 __all__ = [
     "AsyncEffectInSyncRun",
     "Cause",
+    "Cli",
     "Clock",
     "CurrentLogAnnotations",
     "CurrentLogLevel",
@@ -72,24 +86,34 @@ __all__ = [
     "Fail",
     "Failure",
     "Fiber",
+    "FileSystem",
+    "HttpClient",
     "ImplicitRequirement",
     "Interrupt",
     "LogData",
     "LogLevel",
     "MinimumLogLevel",
     "MissingRequirement",
+    "Path",
     "PrettyFormatter",
+    "Process",
+    "Random",
+    "Schedule",
+    "Schema",
     "Scope",
     "Severity",
     "Succeeded",
     "TimeoutException",
+    "Tracer",
     "UnhandledDefect",
     "acquire_and_release",
     "add_finalizer",
+    "annotate_current_span",
     "annotate_logs",
     "attempt",
     "attempt_async",
     "coroutine",
+    "current_span",
     "die",
     "fail",
     "fork",
@@ -105,6 +129,7 @@ __all__ = [
     "pretty_logger",
     "provide_implicit",
     "race_first",
+    "random",
     "require",
     "require_implicit",
     "run_async",
@@ -119,5 +144,6 @@ __all__ = [
     "suspend",
     "sync",
     "timeout",
+    "with_span",
     "yield_now",
 ]

{effecton-0.2.1 → effecton-0.3.1}/src/effecton/effect.py

@@ -1,15 +1,19 @@
 from collections.abc import Awaitable, Callable, Generator
 from dataclasses import dataclass
 from datetime import timedelta
-from typing import TYPE_CHECKING, Any, Literal, Never, final
+from typing import TYPE_CHECKING, Any, Literal, Never, Unpack, final, overload
 
 from typing_extensions import TypeForm
 
 if TYPE_CHECKING:
     from effecton.catch import CatchBinder
+    from effecton.exit import Exit, Failure, Succeeded
     from effecton.provide import ProvideBinder
+    from effecton.std.duration import Parts
+    from effecton.std.schedule import Schedule
     from effecton.std.scope import Scope
     from effecton.std.timeout import TimeoutException
+    from effecton.std.tracer import SpanKind
 
 
 @dataclass(frozen=True)
@@ -69,7 +73,32 @@ class Effect[A, E: EffectonError = Never, R = Never]:
 
         return CatchBinder(effect=self, error_type=error_type)
 
-    def on_exit[R2](self, finalizer: Effect[Any, Never, R2]) -> Effect[A, E, R | R2]:
+    @overload
+    def on_exit[R2](
+        self, finalizer: Effect[Any, Never, R2]
+    ) -> Effect[A, E, R | R2]: ...
+
+    @overload
+    def on_exit[R2](
+        # Spelled out rather than Exit[A, E]: ty infers variance through
+        # the alias as invariant, which would break covariance in A and E.
+        self,
+        finalizer: Callable[[Succeeded[A] | Failure[E]], Effect[Any, Never, R2]],
+    ) -> Effect[A, E, R | R2]: ...
+
+    def on_exit(
+        self,
+        finalizer: Effect[Any, Any, Any] | Callable[[Any], Effect[Any, Any, Any]],
+    ) -> Effect[Any, Any, Any]:
+        """Run a finalizer once this effect settles, on any outcome.
+
+        The finalizer is an effect, or a function receiving the Exit
+        (Succeeded, or Failure carrying Fail, Die or Interrupt) that
+        returns one. A finalizer that fails or raises replaces the
+        outcome with its defect.
+        """
+        if isinstance(finalizer, Effect):
+            return OnExit(self, lambda _: finalizer)
         return OnExit(self, finalizer)
 
     def provide[T](self, requirement_type: TypeForm[T]) -> ProvideBinder[A, E, R, T]:
@@ -84,10 +113,32 @@ class Effect[A, E: EffectonError = Never, R = Never]:
 
         return scoped(self)
 
-    def timeout(self, duration: timedelta) -> Effect[A, E | TimeoutException, R]:
+    def timeout(
+        self, duration: timedelta | None = None, **parts: Unpack[Parts]
+    ) -> Effect[A, E | TimeoutException, R]:
+        """Fail with TimeoutException after a timedelta or its parts (seconds=...)."""
         from effecton.std.timeout import timeout
 
-        return timeout(duration)(self)
+        return timeout(duration, **parts)(self)
+
+    def retry(
+        self,
+        schedule: Schedule | None = None,
+        *,
+        times: int | None = None,
+        until: Callable[[E], bool] | None = None,
+    ) -> Effect[A, E, R]:
+        """Re-run on failure while the schedule recurs, at most times more times."""
+        from effecton.std.retry import retry
+
+        return retry(self, schedule, times=times, until=until)
+
+    def with_span(
+        self, name: str, *, kind: SpanKind = "internal", **attributes: object
+    ) -> Effect[A, E, R]:
+        from effecton.std.tracer import _with_span
+
+        return _with_span(self, name, kind=kind, **attributes)
 
     def __iter__(self) -> Generator[Effect[A, E, R], Any, A]:
         """Make ``x = yield from effect`` infer ``x`` as A inside @gen.
@@ -163,7 +214,7 @@ class ProvideRequirement[A, E: EffectonError, R](Effect[A, E, R]):
 @dataclass(frozen=True)
 class OnExit[A, E: EffectonError, R](Effect[A, E, R]):
     first: Effect[Any, Any, Any]
-    finalizer: Effect[Any, Any, Any]
+    finalizer: Callable[[Exit[Any, Any]], Effect[Any, Any, Any]]
     kind: Literal["on_exit"] = "on_exit"
 
 

{effecton-0.2.1 → effecton-0.3.1}/src/effecton/exit.py

@@ -1,19 +1,25 @@
 from dataclasses import dataclass
-from typing import Any, Literal, Never, assert_never, final
+from typing import Any, Generic, Literal, Never, TypeVar, assert_never, final
 
 from effecton.effect import Cause, Die, EffectonError, Fail, Interrupt
 
+# Old-style TypeVars declare the covariance ty does not infer for a
+# generic dataclass; without it, an Exit in an Effect method signature
+# would make A and E invariant. See the ty inference notes in CLAUDE.md.
+A = TypeVar("A", covariant=True)
+E = TypeVar("E", bound=EffectonError, covariant=True, default=Never)
+
 
 @final
 @dataclass(frozen=True)
-class Succeeded[A]:
+class Succeeded(Generic[A]):  # noqa: UP046
     value: A
     kind: Literal["succeeded"] = "succeeded"
 
 
 @final
 @dataclass(frozen=True)
-class Failure[E: EffectonError = Never]:
+class Failure(Generic[E]):
     cause: Cause[E]
     kind: Literal["failure"] = "failure"
 

{effecton-0.2.1 → effecton-0.3.1}/src/effecton/pytest_plugin.py

@@ -6,7 +6,10 @@ effecton is installed. A test that returns an Effect, typically a
 failure raises its cause, so pytest reports a typed error, a defect or
 an interruption like any exception. A test that requests the test_clock
 fixture has that clock provided to its effect, so E.now(), E.sleep()
-and the clock's movers all see the same clock.
+and the clock's movers all see the same clock; likewise test_random
+provides a seeded Random, so every draw through E.random() is
+reproducible, and test_tracer provides a recording Tracer, so every
+span the test opens can be inspected afterwards.
 """
 
 import inspect
@@ -18,7 +21,7 @@ import pytest
 from effecton.effect import Effect
 from effecton.exit import unwrap
 from effecton.run_async import run_async_exit
-from effecton.std import clock
+from effecton.std import clock, random, tracer
 
 
 @pytest.fixture
@@ -27,6 +30,18 @@ def test_clock() -> clock.Test:
     return clock.Test()
 
 
+@pytest.fixture
+def test_random() -> random.Test:
+    """A Random seeded with 0, provided to the test's effect."""
+    return random.Test()
+
+
+@pytest.fixture
+def test_tracer() -> tracer.Test:
+    """A recording Tracer, provided to the test's effect."""
+    return tracer.Test()
+
+
 @pytest.hookimpl(tryfirst=True)
 def pytest_pyfunc_call(pyfuncitem: pytest.Function) -> bool | None:
     function = pyfuncitem.obj
@@ -42,6 +57,12 @@ def pytest_pyfunc_call(pyfuncitem: pytest.Function) -> bool | None:
         if "test_clock" in arguments:
             provided = cast("clock.Test", arguments["test_clock"])
             effect = effect.provide(clock.Protocol)(provided)
+        if "test_random" in arguments:
+            seeded = cast("random.Test", arguments["test_random"])
+            effect = effect.provide(random.Protocol)(seeded)
+        if "test_tracer" in arguments:
+            recording = cast("tracer.Test", arguments["test_tracer"])
+            effect = effect.provide(tracer.Protocol)(recording)
         unwrap(run_async_exit(effect))
     elif result is not None:
         warnings.warn(

{effecton-0.2.1 → effecton-0.3.1}/src/effecton/run_async.py

@@ -29,6 +29,7 @@ from effecton.run_sync import (
     OnExitFrame,
     RestoreEnv,
     default_or_die,
+    exit_of,
     run_fn_or_die,
 )
 from effecton.std import clock
@@ -179,7 +180,9 @@ async def _interpret[A, E: EffectonError](
                         case OnExitFrame(finalizer):
                             stack.append(Finalizing(outcome=current))
                             finalizing += 1
-                            current = finalizer  # ty: ignore[invalid-assignment]
+                            current = guarded(
+                                run_fn_or_die, finalizer, exit_of(current)
+                            )
                             break
                         case Finalizing(outcome):
                             finalizing -= 1
@@ -205,7 +208,9 @@ async def _interpret[A, E: EffectonError](
                         case OnExitFrame(finalizer):
                             stack.append(Finalizing(outcome=current))
                             finalizing += 1
-                            current = finalizer  # ty: ignore[invalid-assignment]
+                            current = guarded(
+                                run_fn_or_die, finalizer, exit_of(current)
+                            )
                             break
                         case Finalizing():
                             # The finalizer died; its defect replaces the

{effecton-0.2.1 → effecton-0.3.1}/src/effecton/run_sync.py

@@ -65,7 +65,7 @@ class RestoreEnv:
 @final
 @dataclass(frozen=True)
 class OnExitFrame:
-    finalizer: Effect[Any, Any, Any]
+    finalizer: Callable[[Exit[Any, Any]], Effect[Any, Any, Any]]
 
 
 Frame = FlatMap[Any, Any, Any] | OnFailure[Any, Any, Any] | RestoreEnv | OnExitFrame
@@ -103,7 +103,8 @@ def run_sync_exit[A, E: EffectonError](effect: Effect[A, E]) -> Exit[A, E]:
                         case RestoreEnv():
                             env = item.env
                         case OnExitFrame(finalizer):
-                            current = finalizer.flat_map(resume(current))  # ty: ignore[invalid-assignment]
+                            cleanup = run_fn_or_die(finalizer, exit_of(current))
+                            current = cleanup.flat_map(resume(current))  # ty: ignore[invalid-assignment]
                             break
                         case FlatMap():
                             current = run_fn_or_die(item.and_then, value)
@@ -123,7 +124,8 @@ def run_sync_exit[A, E: EffectonError](effect: Effect[A, E]) -> Exit[A, E]:
                         case RestoreEnv():
                             env = item.env
                         case OnExitFrame(finalizer):
-                            current = finalizer.flat_map(resume(current))  # ty: ignore[invalid-assignment]
+                            cleanup = run_fn_or_die(finalizer, exit_of(current))
+                            current = cleanup.flat_map(resume(current))  # ty: ignore[invalid-assignment]
                             break
                         case FlatMap():
                             continue
@@ -195,6 +197,15 @@ def run_fn_or_die(f: Callable[[Any], Effect[Any, Any]], value: object) -> Node:
         return FailCause(cause=Die(defect=e))
 
 
+def exit_of(outcome: Success[Any] | FailCause[Any]) -> Exit[Any, Any]:
+    """The settled outcome as the Exit an on_exit finalizer receives."""
+    match outcome:
+        case Success(value):
+            return Succeeded(value=value)
+        case FailCause(cause):
+            return Failure(cause=cause)
+
+
 # Captures the current outcome by closure.
 def resume(outcome: Node) -> Callable[[Any], Effect[Any, Any, Any]]:
     def resume(_: object) -> Effect[Any, Any, Any]: