effecton 0.2.0__tar.gz → 0.2.1__tar.gz

effecton-0.2.1/CHANGELOG.md

@@ -0,0 +1,29 @@
+# effecton
+
+## 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.2.0 → effecton-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: effecton
-Version: 0.2.0
+Version: 0.2.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>
@@ -129,7 +129,7 @@ More examples: [`test_run_sync.py`](https://github.com/krzkaczor/effecton/blob/m
 
 ### Running effects
 
-Effects are inert values; a runner interprets one. Each runner comes in a throwing form that returns the value and an `_exit` form that returns an `Exit`:
+Effects are inert values; a runner interprets one. The sync and async runners come in a throwing form that returns the value and an `_exit` form that returns an `Exit`. Use `run_main` at a process entry point to report failures and choose exit codes:
 
 | Runner | Runs | Returns |
 |---|---|---|
@@ -137,9 +137,10 @@ Effects are inert values; a runner interprets one. Each runner comes in a throwi
 | `run_sync_exit(effect)` | synchronously | `Exit[A, E]` |
 | `run_async(effect)` | on a fresh asyncio loop (`asyncio.run` inside) | the value, raising on failure |
 | `run_async_exit(effect)` | on a fresh asyncio loop (`asyncio.run` inside) | `Exit[A, E]` |
+| `run_main(effect)` | on a fresh asyncio loop | the value, logging and exiting on failure |
 | `await run_async_coroutine(effect)` | inside a loop you already own | `Exit[A, E]` |
 
-The throwing forms raise a typed failure as the error itself (every `EffectonError` is an `Exception`), re-raise an exception defect as it is, wrap any other defect in `UnhandledDefect`, and re-raise the exception carried by an interruption:
+`run_sync` and `run_async` raise a typed failure as the error itself (every `EffectonError` is an `Exception`), re-raise an exception defect as it is, wrap any other defect in `UnhandledDefect`, and re-raise the exception carried by an interruption:
 
 ```python
 try:
@@ -170,6 +171,43 @@ Running an effect that contains a `coroutine` effect synchronously doesn't await
 
 More examples: [`test_run_sync.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/test_run_sync.py), [`test_run_async.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/test_run_async.py).
 
+### Main programs
+
+`E.run_main(effect)` runs sync and async effects, returning the successful value so a CLI can print its result:
+
+```python
+from dataclasses import dataclass
+from typing import ClassVar, final
+
+import effecton as E
+
+
+@final
+@dataclass(frozen=True)
+class InvalidName(E.EffectonError):
+    name: str
+    exit_code: ClassVar[int] = 2
+
+    def __str__(self) -> str:
+        return f"Invalid name: {self.name!r}"
+
+
+def greet(name: str) -> E.Effect[str, InvalidName]:
+    if not name.strip():
+        return E.fail(InvalidName(name))
+    return E.success(f"Hello, {name}!")
+
+
+if __name__ == "__main__":
+    print(E.run_main(greet("world")))
+```
+
+Typed failures log their message at ERROR; exception defects start with `Defect occurred`, followed by Python's exception formatting, including any traceback and exception chain, and other defects render as `Unhandled defect: ...`. The report uses the default effecton logger and pretty formatting, independently of logging requirements provided inside the program. It then raises `SystemExit(1)`, or uses an integer `exit_code` attribute on the error or defect. Missing and non-integer attributes (including booleans), as well as codes outside `0..255`, fall back to `1`. A successful integer is returned as a value, never treated as an exit code.
+
+Ctrl+C and cancellation exit quietly with `130`; SIGTERM exits with `143`. The first signal determines the code. Finalizers finish and the event loop closes before control returns or `SystemExit` is raised, and previous signal handlers are restored. Repeated signals continue cancellation without bypassing finalizers; there is no cleanup timeout. Cancellation is cooperative, so blocking synchronous work can delay shutdown. An explicit `SystemExit` inside the effect retains its code after finalization.
+
+Call `run_main` from the main thread, outside a running event loop. Both examples use it: [`skills-cli`](packages/examples/skills-cli/src/skills_cli/cli.py) and [`changesets`](packages/changesets/src/changesets/status/cli.py).
+
 ### Error handling
 
 Use `catch_all` to handle errors:
@@ -242,7 +280,7 @@ E.run_sync(E.require_implicit(Greeting))  # Greeting("hello") — nothing provid
 E.run_sync(E.provide_implicit(E.require_implicit(Greeting), Greeting("hi")))
 ```
 
-`provide_implicit(effect, value)` is keyed by `type(value)`, so mark implicit requirement classes `@final`. Overrides also compose in a `provide` chain: `effect.provide(Greeting)(Greeting("hi"))`. `require_implicit` is a separate accessor rather than an overload on `require` because the overload pair silently drops requirements from `R` in some inference positions (pinned in `test_types_implicit_requirement.py`). One footgun: the runtime check only tests that a `default` attribute exists, so a plain requirement class that defines one gets the default fallback instead of a `MissingRequirement` defect.
+`provide_implicit(effect, value)` is keyed by `type(value)`, so mark implicit requirement classes `@final`. A `typing.Protocol` that extends `ImplicitRequirement` with a concrete `default()` is an implicit requirement too; its implementations are provided with `effect.provide(Protocol)(impl)` (the std `Clock` service works this way). Overrides also compose in a `provide` chain: `effect.provide(Greeting)(Greeting("hi"))`. `require_implicit` is a separate accessor rather than an overload on `require` because the overload pair silently drops requirements from `R` in some inference positions (pinned in `test_types_implicit_requirement.py`). One footgun: the runtime check only tests that a `default` attribute exists, so a plain requirement class that defines one gets the default fallback instead of a `MissingRequirement` defect.
 
 More examples: [`test_implicit_requirement.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/test_implicit_requirement.py).
 
@@ -314,7 +352,7 @@ More examples: [`test_attempt.py`](https://github.com/krzkaczor/effecton/blob/ma
 
 ### Wrapping async code
 
-`coroutine` defers an awaitable the way `sync` defers a thunk: the thunk builds a fresh awaitable on every run, because a coroutine object can be awaited only once. Exceptions become defects. `attempt_async` is the `attempt` counterpart that maps expected exceptions into the error channel. Only the `run_async` family can interpret either:
+`coroutine` defers an awaitable the way `sync` defers a thunk: the thunk builds a fresh awaitable on every run, because a coroutine object can be awaited only once. Exceptions become defects. `attempt_async` is the `attempt` counterpart that maps expected exceptions into the error channel. `run_main` and the `run_async` family can interpret either:
 
 ```python
 client = httpx.AsyncClient()
@@ -370,12 +408,98 @@ E.run_sync(
 
 More examples: [`test_logger.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_logger.py), [`test_pretty_logger.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_pretty_logger.py).
 
+### Clock
+
+`E.now()` reads the current time and `E.sleep(duration)` pauses, both through the implicit `E.Clock` service, so neither enters `R`. `now()` returns a timezone-aware UTC `datetime` and is what the logger stamps `LogData.date` with. Sleeping depends on the runner, so the `Clock` protocol has no `default()`; instead there are two live clocks and each runner injects the matching one: `run_sync` installs `E.Clock.SyncLive`, whose sleep blocks the thread, and the `run_async` family (including `run_main`) installs `E.Clock.AsyncLive`, whose sleep awaits `asyncio.sleep`, keeps the loop turning and is interrupted by a cancellation like any coroutine effect.
+
+```python
+E.run_sync(E.now())  # datetime.now(UTC), no setup needed
+E.run_sync(E.sleep(timedelta(seconds=1)))  # blocks for a second
+E.run_async(E.sleep(timedelta(seconds=1)))  # awaits asyncio.sleep(1)
+```
+
+In tests, use `E.Clock.Test` and move it by hand with `adjust(delta)` or `set_time(time)`. Both return effects and are async only, like the clock's `sleep`, which parks until a move reaches its wake time (a sleep of zero returns at once). effecton ships a pytest plugin, loaded automatically wherever the package is installed, that runs a test returning an effect (typically a `@E.gen` function) under the async runner and reports a failure as its cause. A test that requests the `test_clock` fixture gets that clock provided to its effect, so `E.now()`, `E.sleep()` and the movers all see it:
+
+```python
+@E.gen
+def test_reads_move_with_the_clock(test_clock: E.Clock.Test) -> E.EffectGen[None]:
+    yield from test_clock.set_time(datetime(2024, 1, 1, tzinfo=UTC))
+
+    first = yield from E.now()
+    yield from test_clock.adjust(timedelta(minutes=5))
+    second = yield from E.now()
+
+    assert second == first + timedelta(minutes=5)
+```
+
+A sleeping program has to run concurrently with the moves: `E.fork` it and settle on the returned fiber. Each move yields to the loop before and after, so a program forked just before reaches its sleep, and a woken program progresses before the test continues.
+
+Provide clocks with `.provide(E.Clock.Protocol)(...)`: `provide_implicit` is keyed by `type(value)`, so it would register a `Test` clock under `Test` rather than `Protocol`. This repo's ruff config bans direct time reads and sleeps (`datetime.now`, `time.time`, `time.monotonic`, `time.sleep`, `asyncio.sleep`, ...) outside the clock module, so all code goes through `E.now()` and `E.sleep()`.
+
+More examples: [`test_clock.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_clock.py).
+
+### Fibers
+
+`E.fork(effect)` starts an effect concurrently and returns an `E.Fiber`. `fiber.join()` is the fiber's value, failing with the fiber's own cause; `fiber.wait()` is its `Exit` and never fails; `fiber.poll()` peeks without waiting; `fiber.interrupt()` cancels it, lets its finalizers run and returns the `Exit`; `E.yield_now()` lets other fibers take a turn. Fibers are asyncio tasks underneath, so `fork` is async only and a forked run starts with a fresh environment: provide what it needs.
+
+```python
+@E.gen
+def program() -> E.EffectGen[int]:
+    fiber = yield from E.fork(fetch_total())  # runs concurrently
+    other = yield from do_other_work()
+    total = yield from fiber.join()  # Effect[int, FetchError]
+    return total + other
+```
+
+More examples: [`test_fiber.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_fiber.py).
+
+### Racing
+
+`E.race_first(left, right)` returns the first completed outcome, whether success, typed failure, defect, or interruption. It interrupts the loser and awaits its finalizers; loser cleanup cannot replace the winner's outcome. The left wins when both are complete at selection. Cancelling the parent waits for both branches to finish cleanup.
+
+Both branches inherit surrounding requirements, including the Clock, and the result carries the union of their value, error, and requirement types. Racing is async only: synchronous runners report `AsyncEffectInSyncRun`.
+
+```python
+# Stop the heartbeat when the operation completes; a heartbeat failure
+# also stops the operation.
+program = E.race_first(fetch_total(), heartbeat_forever())
+```
+
+Resource lifetime follows the owning scope: use `branch.scoped()` to release that branch's resources before the race returns. Resources acquired into a surrounding scope live until that scope closes. Racing `fiber.join()` interrupts the waiter; the independently forked fiber keeps running.
+
+More examples: [`test_race.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_race.py).
+
+### Timeouts
+
+`effect.timeout(duration)` composes `race_first` with Clock sleep followed by a typed `TimeoutException`. If the deadline wins, it interrupts the effect and awaits its finalizers. The effect's own outcome, or a defect in the clock, otherwise propagates unchanged. Timeouts are async only, with the same requirement inheritance and cleanup rules as racing.
+
+```python
+fetch_total().timeout(
+    timedelta(seconds=5)
+)  # Effect[int, FetchError | TimeoutException]
+
+
+@E.timeout(timedelta(seconds=5))
+@E.gen
+def fetch_user(user_id: int) -> E.EffectGen[User, FetchError]: ...
+
+
+fetch_user(1).catch(E.TimeoutException)(lambda _: E.success(None))
+# Effect[User | None, FetchError]
+```
+
+`E.timeout(duration)(effect)` is the curried form; decorating an effect-returning function wraps each result and preserves its call signature. Durations are `timedelta` values. Cancellation is cooperative: blocking synchronous work can delay a timeout, and cleanup can extend the total time beyond the deadline.
+
+For deterministic tests, provide `E.Clock.Test` around the timeout, fork the program, then advance the clock and await the fiber. Both race branches start eagerly when the race runs, so the timer is registered before a subsequent clock adjustment.
+
+More examples: [`test_timeout.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_timeout.py).
+
 ## Roadmap
 
 - [x] `ty` support
 - [x] Support for async/sync code
 - [ ] Retries
-- [ ] Timeouts
+- [x] Timeouts
 - [ ] `Random` implicit service
 - [ ] More examples of integrations with existing ecosystem (fastapi, pydantic etc.)
 

{effecton-0.2.0 → effecton-0.2.1}/README.md

@@ -113,7 +113,7 @@ More examples: [`test_run_sync.py`](https://github.com/krzkaczor/effecton/blob/m
 
 ### Running effects
 
-Effects are inert values; a runner interprets one. Each runner comes in a throwing form that returns the value and an `_exit` form that returns an `Exit`:
+Effects are inert values; a runner interprets one. The sync and async runners come in a throwing form that returns the value and an `_exit` form that returns an `Exit`. Use `run_main` at a process entry point to report failures and choose exit codes:
 
 | Runner | Runs | Returns |
 |---|---|---|
@@ -121,9 +121,10 @@ Effects are inert values; a runner interprets one. Each runner comes in a throwi
 | `run_sync_exit(effect)` | synchronously | `Exit[A, E]` |
 | `run_async(effect)` | on a fresh asyncio loop (`asyncio.run` inside) | the value, raising on failure |
 | `run_async_exit(effect)` | on a fresh asyncio loop (`asyncio.run` inside) | `Exit[A, E]` |
+| `run_main(effect)` | on a fresh asyncio loop | the value, logging and exiting on failure |
 | `await run_async_coroutine(effect)` | inside a loop you already own | `Exit[A, E]` |
 
-The throwing forms raise a typed failure as the error itself (every `EffectonError` is an `Exception`), re-raise an exception defect as it is, wrap any other defect in `UnhandledDefect`, and re-raise the exception carried by an interruption:
+`run_sync` and `run_async` raise a typed failure as the error itself (every `EffectonError` is an `Exception`), re-raise an exception defect as it is, wrap any other defect in `UnhandledDefect`, and re-raise the exception carried by an interruption:
 
 ```python
 try:
@@ -154,6 +155,43 @@ Running an effect that contains a `coroutine` effect synchronously doesn't await
 
 More examples: [`test_run_sync.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/test_run_sync.py), [`test_run_async.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/test_run_async.py).
 
+### Main programs
+
+`E.run_main(effect)` runs sync and async effects, returning the successful value so a CLI can print its result:
+
+```python
+from dataclasses import dataclass
+from typing import ClassVar, final
+
+import effecton as E
+
+
+@final
+@dataclass(frozen=True)
+class InvalidName(E.EffectonError):
+    name: str
+    exit_code: ClassVar[int] = 2
+
+    def __str__(self) -> str:
+        return f"Invalid name: {self.name!r}"
+
+
+def greet(name: str) -> E.Effect[str, InvalidName]:
+    if not name.strip():
+        return E.fail(InvalidName(name))
+    return E.success(f"Hello, {name}!")
+
+
+if __name__ == "__main__":
+    print(E.run_main(greet("world")))
+```
+
+Typed failures log their message at ERROR; exception defects start with `Defect occurred`, followed by Python's exception formatting, including any traceback and exception chain, and other defects render as `Unhandled defect: ...`. The report uses the default effecton logger and pretty formatting, independently of logging requirements provided inside the program. It then raises `SystemExit(1)`, or uses an integer `exit_code` attribute on the error or defect. Missing and non-integer attributes (including booleans), as well as codes outside `0..255`, fall back to `1`. A successful integer is returned as a value, never treated as an exit code.
+
+Ctrl+C and cancellation exit quietly with `130`; SIGTERM exits with `143`. The first signal determines the code. Finalizers finish and the event loop closes before control returns or `SystemExit` is raised, and previous signal handlers are restored. Repeated signals continue cancellation without bypassing finalizers; there is no cleanup timeout. Cancellation is cooperative, so blocking synchronous work can delay shutdown. An explicit `SystemExit` inside the effect retains its code after finalization.
+
+Call `run_main` from the main thread, outside a running event loop. Both examples use it: [`skills-cli`](packages/examples/skills-cli/src/skills_cli/cli.py) and [`changesets`](packages/changesets/src/changesets/status/cli.py).
+
 ### Error handling
 
 Use `catch_all` to handle errors:
@@ -226,7 +264,7 @@ E.run_sync(E.require_implicit(Greeting))  # Greeting("hello") — nothing provid
 E.run_sync(E.provide_implicit(E.require_implicit(Greeting), Greeting("hi")))
 ```
 
-`provide_implicit(effect, value)` is keyed by `type(value)`, so mark implicit requirement classes `@final`. Overrides also compose in a `provide` chain: `effect.provide(Greeting)(Greeting("hi"))`. `require_implicit` is a separate accessor rather than an overload on `require` because the overload pair silently drops requirements from `R` in some inference positions (pinned in `test_types_implicit_requirement.py`). One footgun: the runtime check only tests that a `default` attribute exists, so a plain requirement class that defines one gets the default fallback instead of a `MissingRequirement` defect.
+`provide_implicit(effect, value)` is keyed by `type(value)`, so mark implicit requirement classes `@final`. A `typing.Protocol` that extends `ImplicitRequirement` with a concrete `default()` is an implicit requirement too; its implementations are provided with `effect.provide(Protocol)(impl)` (the std `Clock` service works this way). Overrides also compose in a `provide` chain: `effect.provide(Greeting)(Greeting("hi"))`. `require_implicit` is a separate accessor rather than an overload on `require` because the overload pair silently drops requirements from `R` in some inference positions (pinned in `test_types_implicit_requirement.py`). One footgun: the runtime check only tests that a `default` attribute exists, so a plain requirement class that defines one gets the default fallback instead of a `MissingRequirement` defect.
 
 More examples: [`test_implicit_requirement.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/test_implicit_requirement.py).
 
@@ -298,7 +336,7 @@ More examples: [`test_attempt.py`](https://github.com/krzkaczor/effecton/blob/ma
 
 ### Wrapping async code
 
-`coroutine` defers an awaitable the way `sync` defers a thunk: the thunk builds a fresh awaitable on every run, because a coroutine object can be awaited only once. Exceptions become defects. `attempt_async` is the `attempt` counterpart that maps expected exceptions into the error channel. Only the `run_async` family can interpret either:
+`coroutine` defers an awaitable the way `sync` defers a thunk: the thunk builds a fresh awaitable on every run, because a coroutine object can be awaited only once. Exceptions become defects. `attempt_async` is the `attempt` counterpart that maps expected exceptions into the error channel. `run_main` and the `run_async` family can interpret either:
 
 ```python
 client = httpx.AsyncClient()
@@ -354,12 +392,98 @@ E.run_sync(
 
 More examples: [`test_logger.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_logger.py), [`test_pretty_logger.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_pretty_logger.py).
 
+### Clock
+
+`E.now()` reads the current time and `E.sleep(duration)` pauses, both through the implicit `E.Clock` service, so neither enters `R`. `now()` returns a timezone-aware UTC `datetime` and is what the logger stamps `LogData.date` with. Sleeping depends on the runner, so the `Clock` protocol has no `default()`; instead there are two live clocks and each runner injects the matching one: `run_sync` installs `E.Clock.SyncLive`, whose sleep blocks the thread, and the `run_async` family (including `run_main`) installs `E.Clock.AsyncLive`, whose sleep awaits `asyncio.sleep`, keeps the loop turning and is interrupted by a cancellation like any coroutine effect.
+
+```python
+E.run_sync(E.now())  # datetime.now(UTC), no setup needed
+E.run_sync(E.sleep(timedelta(seconds=1)))  # blocks for a second
+E.run_async(E.sleep(timedelta(seconds=1)))  # awaits asyncio.sleep(1)
+```
+
+In tests, use `E.Clock.Test` and move it by hand with `adjust(delta)` or `set_time(time)`. Both return effects and are async only, like the clock's `sleep`, which parks until a move reaches its wake time (a sleep of zero returns at once). effecton ships a pytest plugin, loaded automatically wherever the package is installed, that runs a test returning an effect (typically a `@E.gen` function) under the async runner and reports a failure as its cause. A test that requests the `test_clock` fixture gets that clock provided to its effect, so `E.now()`, `E.sleep()` and the movers all see it:
+
+```python
+@E.gen
+def test_reads_move_with_the_clock(test_clock: E.Clock.Test) -> E.EffectGen[None]:
+    yield from test_clock.set_time(datetime(2024, 1, 1, tzinfo=UTC))
+
+    first = yield from E.now()
+    yield from test_clock.adjust(timedelta(minutes=5))
+    second = yield from E.now()
+
+    assert second == first + timedelta(minutes=5)
+```
+
+A sleeping program has to run concurrently with the moves: `E.fork` it and settle on the returned fiber. Each move yields to the loop before and after, so a program forked just before reaches its sleep, and a woken program progresses before the test continues.
+
+Provide clocks with `.provide(E.Clock.Protocol)(...)`: `provide_implicit` is keyed by `type(value)`, so it would register a `Test` clock under `Test` rather than `Protocol`. This repo's ruff config bans direct time reads and sleeps (`datetime.now`, `time.time`, `time.monotonic`, `time.sleep`, `asyncio.sleep`, ...) outside the clock module, so all code goes through `E.now()` and `E.sleep()`.
+
+More examples: [`test_clock.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_clock.py).
+
+### Fibers
+
+`E.fork(effect)` starts an effect concurrently and returns an `E.Fiber`. `fiber.join()` is the fiber's value, failing with the fiber's own cause; `fiber.wait()` is its `Exit` and never fails; `fiber.poll()` peeks without waiting; `fiber.interrupt()` cancels it, lets its finalizers run and returns the `Exit`; `E.yield_now()` lets other fibers take a turn. Fibers are asyncio tasks underneath, so `fork` is async only and a forked run starts with a fresh environment: provide what it needs.
+
+```python
+@E.gen
+def program() -> E.EffectGen[int]:
+    fiber = yield from E.fork(fetch_total())  # runs concurrently
+    other = yield from do_other_work()
+    total = yield from fiber.join()  # Effect[int, FetchError]
+    return total + other
+```
+
+More examples: [`test_fiber.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_fiber.py).
+
+### Racing
+
+`E.race_first(left, right)` returns the first completed outcome, whether success, typed failure, defect, or interruption. It interrupts the loser and awaits its finalizers; loser cleanup cannot replace the winner's outcome. The left wins when both are complete at selection. Cancelling the parent waits for both branches to finish cleanup.
+
+Both branches inherit surrounding requirements, including the Clock, and the result carries the union of their value, error, and requirement types. Racing is async only: synchronous runners report `AsyncEffectInSyncRun`.
+
+```python
+# Stop the heartbeat when the operation completes; a heartbeat failure
+# also stops the operation.
+program = E.race_first(fetch_total(), heartbeat_forever())
+```
+
+Resource lifetime follows the owning scope: use `branch.scoped()` to release that branch's resources before the race returns. Resources acquired into a surrounding scope live until that scope closes. Racing `fiber.join()` interrupts the waiter; the independently forked fiber keeps running.
+
+More examples: [`test_race.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_race.py).
+
+### Timeouts
+
+`effect.timeout(duration)` composes `race_first` with Clock sleep followed by a typed `TimeoutException`. If the deadline wins, it interrupts the effect and awaits its finalizers. The effect's own outcome, or a defect in the clock, otherwise propagates unchanged. Timeouts are async only, with the same requirement inheritance and cleanup rules as racing.
+
+```python
+fetch_total().timeout(
+    timedelta(seconds=5)
+)  # Effect[int, FetchError | TimeoutException]
+
+
+@E.timeout(timedelta(seconds=5))
+@E.gen
+def fetch_user(user_id: int) -> E.EffectGen[User, FetchError]: ...
+
+
+fetch_user(1).catch(E.TimeoutException)(lambda _: E.success(None))
+# Effect[User | None, FetchError]
+```
+
+`E.timeout(duration)(effect)` is the curried form; decorating an effect-returning function wraps each result and preserves its call signature. Durations are `timedelta` values. Cancellation is cooperative: blocking synchronous work can delay a timeout, and cleanup can extend the total time beyond the deadline.
+
+For deterministic tests, provide `E.Clock.Test` around the timeout, fork the program, then advance the clock and await the fiber. Both race branches start eagerly when the race runs, so the timer is registered before a subsequent clock adjustment.
+
+More examples: [`test_timeout.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_timeout.py).
+
 ## Roadmap
 
 - [x] `ty` support
 - [x] Support for async/sync code
 - [ ] Retries
-- [ ] Timeouts
+- [x] Timeouts
 - [ ] `Random` implicit service
 - [ ] More examples of integrations with existing ecosystem (fastapi, pydantic etc.)
 

effecton-0.2.1/conftest.py

@@ -0,0 +1 @@
+pytest_plugins = ["pytester"]

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

@@ -1,6 +1,6 @@
 [project]
 name = "effecton"
-version = "0.2.0"
+version = "0.2.1"
 description = "A typed effect system for Python, inspired by Effect-TS"
 readme = "README.md"
 license = "MIT"
@@ -20,6 +20,9 @@ dependencies = [
 [project.urls]
 Repository = "https://github.com/krzkaczor/effecton"
 
+[project.entry-points.pytest11]
+effecton = "effecton.pytest_plugin"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -37,3 +40,4 @@ unused-ignore-comment = "error"
 [tool.pytest.ini_options]
 testpaths = ["src"]
 addopts = "-q"
+collect_imported_tests = false

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

@@ -21,12 +21,17 @@ from effecton.implicit_requirement import (
     require_implicit,
 )
 from effecton.run_async import run_async, run_async_coroutine, run_async_exit
+from effecton.run_main import run_main
 from effecton.run_sync import (
     AsyncEffectInSyncRun,
     MissingRequirement,
     run_sync,
     run_sync_exit,
 )
+from effecton.std import clock as Clock
+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
 from effecton.std.logger import (
     CurrentLogAnnotations,
     CurrentLoggers,
@@ -46,12 +51,15 @@ from effecton.std.logger import (
     log_warning,
 )
 from effecton.std.pretty_logger import PrettyFormatter, pretty_logger
+from effecton.std.race import race_first
 from effecton.std.scope import Scope, acquire_and_release, add_finalizer, scoped
+from effecton.std.timeout import TimeoutException, timeout
 from effecton.suspend import suspend
 
 __all__ = [
     "AsyncEffectInSyncRun",
     "Cause",
+    "Clock",
     "CurrentLogAnnotations",
     "CurrentLogLevel",
     "CurrentLoggers",
@@ -63,6 +71,7 @@ __all__ = [
     "Exit",
     "Fail",
     "Failure",
+    "Fiber",
     "ImplicitRequirement",
     "Interrupt",
     "LogData",
@@ -73,6 +82,7 @@ __all__ = [
     "Scope",
     "Severity",
     "Succeeded",
+    "TimeoutException",
     "UnhandledDefect",
     "acquire_and_release",
     "add_finalizer",
@@ -82,6 +92,7 @@ __all__ = [
     "coroutine",
     "die",
     "fail",
+    "fork",
     "gen",
     "log",
     "log_debug",
@@ -90,17 +101,23 @@ __all__ = [
     "log_info",
     "log_trace",
     "log_warning",
+    "now",
     "pretty_logger",
     "provide_implicit",
+    "race_first",
     "require",
     "require_implicit",
     "run_async",
     "run_async_coroutine",
     "run_async_exit",
+    "run_main",
     "run_sync",
     "run_sync_exit",
     "scoped",
+    "sleep",
     "success",
     "suspend",
     "sync",
+    "timeout",
+    "yield_now",
 ]

{effecton-0.2.0 → effecton-0.2.1}/src/effecton/attempt.py

@@ -30,7 +30,7 @@ def attempt_async[A, E: EffectonError](
     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.
+    defect. run_main and the run_async family can interpret the result.
     """
 
     async def go() -> Effect[A, E]:

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

@@ -1,5 +1,6 @@
 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_extensions import TypeForm
@@ -8,6 +9,7 @@ if TYPE_CHECKING:
     from effecton.catch import CatchBinder
     from effecton.provide import ProvideBinder
     from effecton.std.scope import Scope
+    from effecton.std.timeout import TimeoutException
 
 
 @dataclass(frozen=True)
@@ -82,6 +84,11 @@ class Effect[A, E: EffectonError = Never, R = Never]:
 
         return scoped(self)
 
+    def timeout(self, duration: timedelta) -> Effect[A, E | TimeoutException, R]:
+        from effecton.std.timeout import timeout
+
+        return timeout(duration)(self)
+
     def __iter__(self) -> Generator[Effect[A, E, R], Any, A]:
         """Make ``x = yield from effect`` infer ``x`` as A inside @gen.
 
@@ -160,6 +167,14 @@ class OnExit[A, E: EffectonError, R](Effect[A, E, R]):
     kind: Literal["on_exit"] = "on_exit"
 
 
+@final
+@dataclass(frozen=True)
+class RaceFirst[A, E: EffectonError, R](Effect[A, E, R]):
+    left: Effect[A, E, R]
+    right: Effect[A, E, R]
+    kind: Literal["race_first"] = "race_first"
+
+
 Node = (
     Success[Any]
     | Sync[Any]
@@ -170,6 +185,7 @@ Node = (
     | Require[Any]
     | ProvideRequirement[Any, Any, Any]
     | OnExit[Any, Any, Any]
+    | RaceFirst[Any, Any, Any]
 )
 
 
@@ -182,7 +198,7 @@ def sync[A](fn: Callable[[], A]) -> Effect[A]:
 
 
 def coroutine[A](fn: Callable[[], Awaitable[A]]) -> Effect[A]:
-    """Defer an awaitable; only the run_async family can interpret it.
+    """Defer an awaitable; run_main and 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

effecton-0.2.1/src/effecton/pytest_plugin.py

@@ -0,0 +1,54 @@
+"""pytest plugin that runs test functions written as effects.
+
+Registered through the pytest11 entry point, so it loads wherever
+effecton is installed. A test that returns an Effect, typically a
+@E.gen generator function, is interpreted with run_async_exit and 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.
+"""
+
+import inspect
+import warnings
+from typing import Any, cast
+
+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
+
+
+@pytest.fixture
+def test_clock() -> clock.Test:
+    """A Test clock at the Unix epoch, provided to the test's effect."""
+    return clock.Test()
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_pyfunc_call(pyfuncitem: pytest.Function) -> bool | None:
+    function = pyfuncitem.obj
+    if inspect.iscoroutinefunction(function):
+        return None
+
+    arguments = {
+        name: pyfuncitem.funcargs[name] for name in pyfuncitem._fixtureinfo.argnames
+    }
+    result = function(**arguments)
+    if isinstance(result, Effect):
+        effect = cast("Effect[Any, Any]", result)
+        if "test_clock" in arguments:
+            provided = cast("clock.Test", arguments["test_clock"])
+            effect = effect.provide(clock.Protocol)(provided)
+        unwrap(run_async_exit(effect))
+    elif result is not None:
+        warnings.warn(
+            pytest.PytestReturnNotNoneWarning(
+                f"Test functions should return None, "
+                f"but {pyfuncitem.nodeid} returned {type(result)!r}"
+            ),
+            stacklevel=2,
+        )
+    return True