effecton 0.2.1__tar.gz → 0.3.0__tar.gz

{effecton-0.2.1 → effecton-0.3.0}/.gitignore

@@ -11,3 +11,11 @@ wheels/
 
 # 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

effecton-0.3.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# effecton
+
+## 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.2.1 → effecton-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: effecton
-Version: 0.2.1
+Version: 0.3.0
 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>
@@ -11,6 +11,8 @@ 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
 
@@ -223,9 +225,9 @@ E.run_sync(p)  # "recovered from oops"
 Use `catch` to handle one error type and leave the rest in the error channel. The handler receives the narrowed error, and defects (`Die`) pass through untouched:
 
 ```python
-n = random.randint(1, 4)
+roll = E.random().flat_map(lambda rng: rng.randint(1, 4))
 
-p = E.success(n).flat_map(
+p = roll.flat_map(
     lambda r: E.fail(FatalError()) if r == 2 else E.fail(RecoverableError())
 )  # Effect[Never, FatalError | RecoverableError]
 
@@ -301,6 +303,14 @@ program = conn.flat_map(
 ).scoped()  # Scope discharged; close() runs when program settles
 ```
 
+`on_exit` also takes a function that receives the `Exit` and returns the finalizer, so cleanup can depend on how the effect settled:
+
+```python
+E.success(21).on_exit(
+    lambda exit: E.log_info("settled", exit)
+)  # Succeeded(21), or Failure(cause) carrying Fail, Die or Interrupt
+```
+
 A finalizer that dies doesn't skip the remaining finalizers; its defect surfaces in the final `Exit`.
 
 More examples: [`test_scope.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_scope.py).
@@ -438,6 +448,168 @@ Provide clocks with `.provide(E.Clock.Protocol)(...)`: `provide_implicit` is key
 
 More examples: [`test_clock.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_clock.py).
 
+### Random
+
+`E.random()` resolves the implicit `E.Random` service, so it never enters `R`. Its methods keep the names of the `random` standard library and each returns an effect: `random()`, `uniform(a, b)`, `randint(a, b)`, `choice(seq)` and `shuffle(seq)`, where `shuffle` returns a new list and leaves its input untouched. The default is `E.Random.Live`, which draws from the process-global generator behind the `random` module.
+
+```python
+@E.gen
+def roll() -> E.EffectGen[int]:
+    rng = yield from E.random()
+
+    return (yield from rng.randint(1, 6))
+
+
+E.run_sync(roll())  # 1..6, no setup needed
+```
+
+In tests, provide `E.Random.Test(seed)`: every draw is a function of the seed, and one instance advances as a single sequence, so the same seed always reproduces the same run. A test that requests the `test_random` fixture gets a `Test` seeded with 0 provided to its effect:
+
+```python
+@E.gen
+def test_rolls_are_reproducible(test_random: E.Random.Test) -> E.EffectGen[None]:
+    first = yield from roll()
+    second = yield from roll()
+
+    assert (first, second) == (4, 4)
+```
+
+Provide generators with `.provide(E.Random.Protocol)(...)`, as with the Clock. This repo's ruff config bans the `random` module's drawing functions (`random.random`, `random.randint`, `random.choice`, ...) outside the service module, so all code goes through `E.random()`; building a `random.Random(seed)` to compute expected values in a test is still allowed.
+
+More examples: [`test_random.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_random.py).
+
+### Tracing
+
+`E.with_span(effect, name)` opens a span around an effect: one named, timed unit that nests. A span opened inside another becomes its child and shares its trace id, and it ends with the effect's `Exit` when the effect settles, on success, typed failure, defect and interruption alike. Spans go through the implicit `E.Tracer` service, so nothing enters `R`; timestamps come from `E.now()` and ids are drawn through `E.random()`. `with_span` takes the effect first, like `annotate_logs`, and is also a method:
+
+```python
+@E.gen
+def fetch_user(user_id: int) -> E.EffectGen[User, FetchError]:
+    yield from E.annotate_current_span(user_id=user_id)  # attributes on the open span
+    ...
+
+
+traced = E.with_span(fetch_user(1), "fetch_user")
+program = traced.with_span("handle_request", kind="server", route="/users/1")
+```
+
+`E.annotate_current_span(**attributes)` adds attributes to the innermost open span and is a no-op outside one; `E.current_span()` returns that span and fails with `E.Tracer.NoCurrentSpan` outside one. The default tracer, `E.Tracer.Live`, opens in-memory spans that nothing collects, so tracing costs nothing until a tracer that exports them is provided: an OpenTelemetry exporter would be another implementation of `E.Tracer.Protocol`, and the hex ids already match the W3C `traceparent` header. A forked fiber starts with a fresh environment, so it opens root spans unless the parent is passed along with `E.provide_implicit(forked, E.Tracer.ParentSpan(span))`, `span` being the result of `E.current_span()`; `race_first` and `timeout` inherit the current span.
+
+In tests, provide `E.Tracer.Test`, which records every span it opens in `spans`, in opening order. Each span carries `name`, `kind`, `attributes`, `parent`, `trace_id`, `span_id` and a `status` that is `Started(start_time)` while open and `Ended(start_time, end_time, exit)` afterwards. A test that requests the `test_tracer` fixture gets one provided to its effect:
+
+```python
+@E.gen
+def test_opens_a_span_per_request(test_tracer: E.Tracer.Test) -> E.EffectGen[None]:
+    yield from fetch_user(1).with_span("handle_request", kind="server")
+
+    request, user = test_tracer.spans
+    assert (request.name, user.parent) == ("handle_request", request)
+    assert isinstance(user.status, E.Tracer.Ended)
+```
+
+More examples: [`test_tracer.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_tracer.py).
+
+### FileSystem
+
+`E.FileSystem` reads and writes the disk. It is an explicit requirement: a program that needs it says so in `R` through `E.require(E.FileSystem.Protocol)`, and forgetting to provide an implementation is a type error rather than a surprise write to the real disk. Its methods follow the names of Effect-TS's FileSystem and each returns an effect with a precise error union: `exists`, `stat`, `read_file`, `read_file_string`, `write_file`, `write_file_string`, `make_directory(path, recursive=...)`, `read_directory`, `remove(path, recursive=...)`, `rename`, `copy_file`, `symlink(target, link)` and `read_link`. The working and home directories are not file I/O and live on `E.Process`. Errors are cause-specific (`FileNotFound`, `PermissionDenied`, `PathIsADirectory`, `PathIsNotADirectory`, `PathAlreadyExists`, `DirectoryNotEmpty`), so `catch(E.FileSystem.FileNotFound)` handles exactly the missing-file case; anything else the disk can do, such as running out of space, stays a defect.
+
+```python
+@E.gen
+def read_config(
+    root: E.Path,
+) -> E.EffectGen[str, E.FileSystem.ReadError, E.FileSystem.Protocol]:
+    fs = yield from E.require(E.FileSystem.Protocol)
+
+    return (yield from fs.read_file_string(root / "config.toml"))
+
+
+program = read_config(E.Path("/repo"))
+E.run_sync(program.provide(E.FileSystem.Protocol)(E.FileSystem.SyncLive()))
+```
+
+There are two live implementations, one per runner, like the Clock: `E.FileSystem.SyncLive` blocks the thread on the `os` calls and suits `run_sync`; `E.FileSystem.AsyncLive` makes the same calls through [aiofiles](https://github.com/Tinche/aiofiles), so the loop keeps turning under `run_async` and `run_main`. aiofiles is a dependency of effecton, so both implementations are always available.
+
+In tests, provide `E.FileSystem.Test`, an in-memory tree seeded with `files` (text or bytes), `directories` and `links`; every ancestor of a seeded path is created for you. It enforces the same rules as the disk, so a program gets the same `Exit` against `Test` as against a live implementation, and its state stays inspectable afterwards:
+
+```python
+def test_reads_the_config():
+    fs = E.FileSystem.Test(files={E.Path("/repo/config.toml"): "[packages]\n"})
+
+    result = E.run_sync(read_config(E.Path("/repo")).provide(E.FileSystem.Protocol)(fs))
+
+    assert result == "[packages]\n"
+```
+
+More examples: [`test_file_system.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_file_system.py).
+
+### Path
+
+`E.Path` is the only path type effecton code touches: an immutable value that joins with `/`, compares, hashes and sorts, and exposes `parent`, `parents`, `name`, `suffix`, `stem` and `parts`. Unlike `pathlib.Path` it has no I/O methods, so a path can never reach the disk on its own; every read and write goes through `E.FileSystem`. Joining follows the standard library's rules: an absolute right-hand side replaces the left, and redundant separators collapse.
+
+```python
+config = E.Path("/repo") / ".changeset" / "config.toml"
+config.parent  # Path('/repo/.changeset')
+config.suffix  # '.toml'
+```
+
+This repo's ruff config bans `pathlib`, `os.path`, `shutil`, `tempfile` and the `os` file functions outside the FileSystem and Process modules, so all code goes through `E.FileSystem`, `E.Process` and `E.Path`.
+
+### Process
+
+`E.Process` is what the running process knows about its environment: `cwd()` and `home()` today, with environment variables to follow. Both return an `E.Path`. It is an explicit requirement like the FileSystem, so a CLI reads its starting directory through it and a test pins that directory with `E.Process.Test(current_directory=..., home_directory=...)` instead of depending on where pytest happens to run.
+
+```python
+def from_cwd(program):
+    return E.require(E.Process.Protocol).flat_map(lambda p: p.cwd()).flat_map(program)
+
+
+E.run_main(
+    from_cwd(status)
+    .provide(E.Process.Protocol)(E.Process.Live())
+    .provide(E.FileSystem.Protocol)(E.FileSystem.AsyncLive())
+)
+```
+
+### HttpClient
+
+`E.HttpClient` talks HTTP. It is an explicit requirement like the FileSystem: a program that needs it says so in `R` through `E.require(E.HttpClient.Protocol)`, and forgetting to provide an implementation is a type error rather than a surprise request. `execute(request)` sends an `E.HttpClient.Request`, and the conveniences build one for you: `get`, `head`, `options` and `delete` take `url, *, headers, params`; `post`, `put` and `patch` add `body` (text or bytes) or `json`, which is serialized and sets the content type. Each returns an `E.HttpClient.Response` with `status`, lowercase `headers`, `body` bytes, a `text` property decoded with the content-type charset and a `json()` effect that fails with `InvalidJson`. As in Effect-TS, every status is a success: `E.HttpClient.filter_status_ok` is the opt-in that turns a non-2xx into `StatusError`. The one request error is `TransportError`, the Transport reason of Effect-TS: the connection could not be made or was lost, or the reply was not HTTP, so `catch(E.HttpClient.TransportError)` handles exactly the network misbehaving. A URL without a scheme is a programming error and stays a defect, as does anything else.
+
+```python
+@E.gen
+def fetch_readme(
+    url: str,
+) -> E.EffectGen[
+    str, E.HttpClient.TransportError | E.HttpClient.StatusError, E.HttpClient.Protocol
+]:
+    http = yield from E.require(E.HttpClient.Protocol)
+
+    response = yield from http.get(url)
+    response = yield from E.HttpClient.filter_status_ok(response)
+    return response.text
+
+
+program = fetch_readme(
+    "https://raw.githubusercontent.com/krzkaczor/effecton/main/README.md"
+)
+E.run_sync(program.provide(E.HttpClient.Protocol)(E.HttpClient.SyncLive()))
+```
+
+There are two live implementations, one per runner, like the Clock: `E.HttpClient.SyncLive` blocks the thread on an [httpx2](https://github.com/pydantic/httpx2) client and suits `run_sync`; `E.HttpClient.AsyncLive` awaits `httpx2.AsyncClient`, so the loop keeps turning under `run_async` and `run_main`. httpx2 is a dependency of effecton, so both are always available. Neither sets an HTTP-level timeout or follows redirects: bound a request the effecton way with `.timeout(...)` (under the async runners), and a 3xx comes back as a `Response`. Each request opens a fresh client for now, so there is no connection pooling yet.
+
+In tests, provide `E.HttpClient.Test`. Seed it with `responses`, a URL-to-body mapping answered with a 200 where any other URL gets a 404, or give it a `handler` that receives the normalized `Request` and returns a `Response` or a request error to fail with. Either way every request is recorded in `requests`:
+
+```python
+def test_fetches_the_readme():
+    http = E.HttpClient.Test(responses={URL: "# Effecton"})
+
+    result = E.run_sync(fetch_readme(URL).provide(E.HttpClient.Protocol)(http))
+
+    assert result == "# Effecton"
+    assert http.requests == [E.HttpClient.Request("GET", URL)]
+```
+
+More examples: [`test_http_client.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_http_client.py). This repo's ruff config bans `httpx`, `httpx2`, `urllib.request` and `http.client` outside the service module, so all requests go through `E.HttpClient`.
+
 ### 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.
@@ -494,13 +666,42 @@ For deterministic tests, provide `E.Clock.Test` around the timeout, fork the pro
 
 More examples: [`test_timeout.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_timeout.py).
 
+### Retries
+
+`effect.retry(schedule=None, times=None, until=...)` re-runs an effect on a typed failure while the schedule recurs, sleeping through the Clock for each delay. `times` caps the retries at that many more attempts; `retry(times=3)` alone retries up to three times without waiting, and `retry()` with neither recurs forever. Defects and interrupts are never retried. When the schedule is exhausted, `times` is used up, or `until` holds for the error, the retry fails with that last error, so the error channel is unchanged.
+
+```python
+fetch_total().retry(times=3)  # Effect[int, FetchError]
+
+fetch_total().retry(E.Schedule.exponential(timedelta(seconds=1)), times=5)
+
+fetch_user(1).retry(
+    E.Schedule.exponential(timedelta(seconds=1)),
+    until=lambda e: isinstance(e, NotFound),
+)  # Effect[User, FetchError | NotFound]
+```
+
+`E.Schedule.recurs(times)` recurs up to `times` more times without waiting, `E.Schedule.spaced(delay)` waits `delay` before every attempt, and `E.Schedule.exponential(base, factor=2.0)` waits `base`, then `base * factor`, and so on. The last two are unbounded; bound them with `times=` or `until`. `schedule.jittered(min=0.8, max=1.2)` scales every delay by a factor drawn uniformly from `[min, max]` through the `E.Random` service, so `E.Random.Test(seed)` makes the jitter reproducible. Every run of the retried effect starts its schedule over.
+
+```python
+fetch_user(1).retry(E.Schedule.exponential(timedelta(seconds=1)).jittered())
+```
+
+A schedule is a factory of steps, and each step is an effect yielding the next delay, which is what lets `jittered` consult `Random`. Build a custom one with `E.Schedule.from_delays(...)` from any callable that yields a fresh iterator of `timedelta` values, or with `E.Schedule(steps=...)` when the delays are computed by effects.
+
+There is no decorator form because `until` is typed by the effect's error channel, which a decorator cannot see. `recurs` needs no waiting and works under `run_sync`; for deterministic tests of delayed schedules, provide `E.Clock.Test`, fork the program, then advance the clock once per gap and await the fiber. A forked run starts with a fresh environment, so provide the test clock and a seeded `E.Random.Test` inside the forked program.
+
+More examples: [`test_retry.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_retry.py).
+
 ## Roadmap
 
 - [x] `ty` support
 - [x] Support for async/sync code
-- [ ] Retries
+- [x] Retries
 - [x] Timeouts
-- [ ] `Random` implicit service
+- [x] `Random` implicit service
+- [x] `FileSystem` service and `Path`
+- [x] `HttpClient` service
 - [ ] More examples of integrations with existing ecosystem (fastapi, pydantic etc.)
 
 ## Inspirations

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

@@ -207,9 +207,9 @@ E.run_sync(p)  # "recovered from oops"
 Use `catch` to handle one error type and leave the rest in the error channel. The handler receives the narrowed error, and defects (`Die`) pass through untouched:
 
 ```python
-n = random.randint(1, 4)
+roll = E.random().flat_map(lambda rng: rng.randint(1, 4))
 
-p = E.success(n).flat_map(
+p = roll.flat_map(
     lambda r: E.fail(FatalError()) if r == 2 else E.fail(RecoverableError())
 )  # Effect[Never, FatalError | RecoverableError]
 
@@ -285,6 +285,14 @@ program = conn.flat_map(
 ).scoped()  # Scope discharged; close() runs when program settles
 ```
 
+`on_exit` also takes a function that receives the `Exit` and returns the finalizer, so cleanup can depend on how the effect settled:
+
+```python
+E.success(21).on_exit(
+    lambda exit: E.log_info("settled", exit)
+)  # Succeeded(21), or Failure(cause) carrying Fail, Die or Interrupt
+```
+
 A finalizer that dies doesn't skip the remaining finalizers; its defect surfaces in the final `Exit`.
 
 More examples: [`test_scope.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_scope.py).
@@ -422,6 +430,168 @@ Provide clocks with `.provide(E.Clock.Protocol)(...)`: `provide_implicit` is key
 
 More examples: [`test_clock.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_clock.py).
 
+### Random
+
+`E.random()` resolves the implicit `E.Random` service, so it never enters `R`. Its methods keep the names of the `random` standard library and each returns an effect: `random()`, `uniform(a, b)`, `randint(a, b)`, `choice(seq)` and `shuffle(seq)`, where `shuffle` returns a new list and leaves its input untouched. The default is `E.Random.Live`, which draws from the process-global generator behind the `random` module.
+
+```python
+@E.gen
+def roll() -> E.EffectGen[int]:
+    rng = yield from E.random()
+
+    return (yield from rng.randint(1, 6))
+
+
+E.run_sync(roll())  # 1..6, no setup needed
+```
+
+In tests, provide `E.Random.Test(seed)`: every draw is a function of the seed, and one instance advances as a single sequence, so the same seed always reproduces the same run. A test that requests the `test_random` fixture gets a `Test` seeded with 0 provided to its effect:
+
+```python
+@E.gen
+def test_rolls_are_reproducible(test_random: E.Random.Test) -> E.EffectGen[None]:
+    first = yield from roll()
+    second = yield from roll()
+
+    assert (first, second) == (4, 4)
+```
+
+Provide generators with `.provide(E.Random.Protocol)(...)`, as with the Clock. This repo's ruff config bans the `random` module's drawing functions (`random.random`, `random.randint`, `random.choice`, ...) outside the service module, so all code goes through `E.random()`; building a `random.Random(seed)` to compute expected values in a test is still allowed.
+
+More examples: [`test_random.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_random.py).
+
+### Tracing
+
+`E.with_span(effect, name)` opens a span around an effect: one named, timed unit that nests. A span opened inside another becomes its child and shares its trace id, and it ends with the effect's `Exit` when the effect settles, on success, typed failure, defect and interruption alike. Spans go through the implicit `E.Tracer` service, so nothing enters `R`; timestamps come from `E.now()` and ids are drawn through `E.random()`. `with_span` takes the effect first, like `annotate_logs`, and is also a method:
+
+```python
+@E.gen
+def fetch_user(user_id: int) -> E.EffectGen[User, FetchError]:
+    yield from E.annotate_current_span(user_id=user_id)  # attributes on the open span
+    ...
+
+
+traced = E.with_span(fetch_user(1), "fetch_user")
+program = traced.with_span("handle_request", kind="server", route="/users/1")
+```
+
+`E.annotate_current_span(**attributes)` adds attributes to the innermost open span and is a no-op outside one; `E.current_span()` returns that span and fails with `E.Tracer.NoCurrentSpan` outside one. The default tracer, `E.Tracer.Live`, opens in-memory spans that nothing collects, so tracing costs nothing until a tracer that exports them is provided: an OpenTelemetry exporter would be another implementation of `E.Tracer.Protocol`, and the hex ids already match the W3C `traceparent` header. A forked fiber starts with a fresh environment, so it opens root spans unless the parent is passed along with `E.provide_implicit(forked, E.Tracer.ParentSpan(span))`, `span` being the result of `E.current_span()`; `race_first` and `timeout` inherit the current span.
+
+In tests, provide `E.Tracer.Test`, which records every span it opens in `spans`, in opening order. Each span carries `name`, `kind`, `attributes`, `parent`, `trace_id`, `span_id` and a `status` that is `Started(start_time)` while open and `Ended(start_time, end_time, exit)` afterwards. A test that requests the `test_tracer` fixture gets one provided to its effect:
+
+```python
+@E.gen
+def test_opens_a_span_per_request(test_tracer: E.Tracer.Test) -> E.EffectGen[None]:
+    yield from fetch_user(1).with_span("handle_request", kind="server")
+
+    request, user = test_tracer.spans
+    assert (request.name, user.parent) == ("handle_request", request)
+    assert isinstance(user.status, E.Tracer.Ended)
+```
+
+More examples: [`test_tracer.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_tracer.py).
+
+### FileSystem
+
+`E.FileSystem` reads and writes the disk. It is an explicit requirement: a program that needs it says so in `R` through `E.require(E.FileSystem.Protocol)`, and forgetting to provide an implementation is a type error rather than a surprise write to the real disk. Its methods follow the names of Effect-TS's FileSystem and each returns an effect with a precise error union: `exists`, `stat`, `read_file`, `read_file_string`, `write_file`, `write_file_string`, `make_directory(path, recursive=...)`, `read_directory`, `remove(path, recursive=...)`, `rename`, `copy_file`, `symlink(target, link)` and `read_link`. The working and home directories are not file I/O and live on `E.Process`. Errors are cause-specific (`FileNotFound`, `PermissionDenied`, `PathIsADirectory`, `PathIsNotADirectory`, `PathAlreadyExists`, `DirectoryNotEmpty`), so `catch(E.FileSystem.FileNotFound)` handles exactly the missing-file case; anything else the disk can do, such as running out of space, stays a defect.
+
+```python
+@E.gen
+def read_config(
+    root: E.Path,
+) -> E.EffectGen[str, E.FileSystem.ReadError, E.FileSystem.Protocol]:
+    fs = yield from E.require(E.FileSystem.Protocol)
+
+    return (yield from fs.read_file_string(root / "config.toml"))
+
+
+program = read_config(E.Path("/repo"))
+E.run_sync(program.provide(E.FileSystem.Protocol)(E.FileSystem.SyncLive()))
+```
+
+There are two live implementations, one per runner, like the Clock: `E.FileSystem.SyncLive` blocks the thread on the `os` calls and suits `run_sync`; `E.FileSystem.AsyncLive` makes the same calls through [aiofiles](https://github.com/Tinche/aiofiles), so the loop keeps turning under `run_async` and `run_main`. aiofiles is a dependency of effecton, so both implementations are always available.
+
+In tests, provide `E.FileSystem.Test`, an in-memory tree seeded with `files` (text or bytes), `directories` and `links`; every ancestor of a seeded path is created for you. It enforces the same rules as the disk, so a program gets the same `Exit` against `Test` as against a live implementation, and its state stays inspectable afterwards:
+
+```python
+def test_reads_the_config():
+    fs = E.FileSystem.Test(files={E.Path("/repo/config.toml"): "[packages]\n"})
+
+    result = E.run_sync(read_config(E.Path("/repo")).provide(E.FileSystem.Protocol)(fs))
+
+    assert result == "[packages]\n"
+```
+
+More examples: [`test_file_system.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_file_system.py).
+
+### Path
+
+`E.Path` is the only path type effecton code touches: an immutable value that joins with `/`, compares, hashes and sorts, and exposes `parent`, `parents`, `name`, `suffix`, `stem` and `parts`. Unlike `pathlib.Path` it has no I/O methods, so a path can never reach the disk on its own; every read and write goes through `E.FileSystem`. Joining follows the standard library's rules: an absolute right-hand side replaces the left, and redundant separators collapse.
+
+```python
+config = E.Path("/repo") / ".changeset" / "config.toml"
+config.parent  # Path('/repo/.changeset')
+config.suffix  # '.toml'
+```
+
+This repo's ruff config bans `pathlib`, `os.path`, `shutil`, `tempfile` and the `os` file functions outside the FileSystem and Process modules, so all code goes through `E.FileSystem`, `E.Process` and `E.Path`.
+
+### Process
+
+`E.Process` is what the running process knows about its environment: `cwd()` and `home()` today, with environment variables to follow. Both return an `E.Path`. It is an explicit requirement like the FileSystem, so a CLI reads its starting directory through it and a test pins that directory with `E.Process.Test(current_directory=..., home_directory=...)` instead of depending on where pytest happens to run.
+
+```python
+def from_cwd(program):
+    return E.require(E.Process.Protocol).flat_map(lambda p: p.cwd()).flat_map(program)
+
+
+E.run_main(
+    from_cwd(status)
+    .provide(E.Process.Protocol)(E.Process.Live())
+    .provide(E.FileSystem.Protocol)(E.FileSystem.AsyncLive())
+)
+```
+
+### HttpClient
+
+`E.HttpClient` talks HTTP. It is an explicit requirement like the FileSystem: a program that needs it says so in `R` through `E.require(E.HttpClient.Protocol)`, and forgetting to provide an implementation is a type error rather than a surprise request. `execute(request)` sends an `E.HttpClient.Request`, and the conveniences build one for you: `get`, `head`, `options` and `delete` take `url, *, headers, params`; `post`, `put` and `patch` add `body` (text or bytes) or `json`, which is serialized and sets the content type. Each returns an `E.HttpClient.Response` with `status`, lowercase `headers`, `body` bytes, a `text` property decoded with the content-type charset and a `json()` effect that fails with `InvalidJson`. As in Effect-TS, every status is a success: `E.HttpClient.filter_status_ok` is the opt-in that turns a non-2xx into `StatusError`. The one request error is `TransportError`, the Transport reason of Effect-TS: the connection could not be made or was lost, or the reply was not HTTP, so `catch(E.HttpClient.TransportError)` handles exactly the network misbehaving. A URL without a scheme is a programming error and stays a defect, as does anything else.
+
+```python
+@E.gen
+def fetch_readme(
+    url: str,
+) -> E.EffectGen[
+    str, E.HttpClient.TransportError | E.HttpClient.StatusError, E.HttpClient.Protocol
+]:
+    http = yield from E.require(E.HttpClient.Protocol)
+
+    response = yield from http.get(url)
+    response = yield from E.HttpClient.filter_status_ok(response)
+    return response.text
+
+
+program = fetch_readme(
+    "https://raw.githubusercontent.com/krzkaczor/effecton/main/README.md"
+)
+E.run_sync(program.provide(E.HttpClient.Protocol)(E.HttpClient.SyncLive()))
+```
+
+There are two live implementations, one per runner, like the Clock: `E.HttpClient.SyncLive` blocks the thread on an [httpx2](https://github.com/pydantic/httpx2) client and suits `run_sync`; `E.HttpClient.AsyncLive` awaits `httpx2.AsyncClient`, so the loop keeps turning under `run_async` and `run_main`. httpx2 is a dependency of effecton, so both are always available. Neither sets an HTTP-level timeout or follows redirects: bound a request the effecton way with `.timeout(...)` (under the async runners), and a 3xx comes back as a `Response`. Each request opens a fresh client for now, so there is no connection pooling yet.
+
+In tests, provide `E.HttpClient.Test`. Seed it with `responses`, a URL-to-body mapping answered with a 200 where any other URL gets a 404, or give it a `handler` that receives the normalized `Request` and returns a `Response` or a request error to fail with. Either way every request is recorded in `requests`:
+
+```python
+def test_fetches_the_readme():
+    http = E.HttpClient.Test(responses={URL: "# Effecton"})
+
+    result = E.run_sync(fetch_readme(URL).provide(E.HttpClient.Protocol)(http))
+
+    assert result == "# Effecton"
+    assert http.requests == [E.HttpClient.Request("GET", URL)]
+```
+
+More examples: [`test_http_client.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_http_client.py). This repo's ruff config bans `httpx`, `httpx2`, `urllib.request` and `http.client` outside the service module, so all requests go through `E.HttpClient`.
+
 ### 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.
@@ -478,13 +648,42 @@ For deterministic tests, provide `E.Clock.Test` around the timeout, fork the pro
 
 More examples: [`test_timeout.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_timeout.py).
 
+### Retries
+
+`effect.retry(schedule=None, times=None, until=...)` re-runs an effect on a typed failure while the schedule recurs, sleeping through the Clock for each delay. `times` caps the retries at that many more attempts; `retry(times=3)` alone retries up to three times without waiting, and `retry()` with neither recurs forever. Defects and interrupts are never retried. When the schedule is exhausted, `times` is used up, or `until` holds for the error, the retry fails with that last error, so the error channel is unchanged.
+
+```python
+fetch_total().retry(times=3)  # Effect[int, FetchError]
+
+fetch_total().retry(E.Schedule.exponential(timedelta(seconds=1)), times=5)
+
+fetch_user(1).retry(
+    E.Schedule.exponential(timedelta(seconds=1)),
+    until=lambda e: isinstance(e, NotFound),
+)  # Effect[User, FetchError | NotFound]
+```
+
+`E.Schedule.recurs(times)` recurs up to `times` more times without waiting, `E.Schedule.spaced(delay)` waits `delay` before every attempt, and `E.Schedule.exponential(base, factor=2.0)` waits `base`, then `base * factor`, and so on. The last two are unbounded; bound them with `times=` or `until`. `schedule.jittered(min=0.8, max=1.2)` scales every delay by a factor drawn uniformly from `[min, max]` through the `E.Random` service, so `E.Random.Test(seed)` makes the jitter reproducible. Every run of the retried effect starts its schedule over.
+
+```python
+fetch_user(1).retry(E.Schedule.exponential(timedelta(seconds=1)).jittered())
+```
+
+A schedule is a factory of steps, and each step is an effect yielding the next delay, which is what lets `jittered` consult `Random`. Build a custom one with `E.Schedule.from_delays(...)` from any callable that yields a fresh iterator of `timedelta` values, or with `E.Schedule(steps=...)` when the delays are computed by effects.
+
+There is no decorator form because `until` is typed by the effect's error channel, which a decorator cannot see. `recurs` needs no waiting and works under `run_sync`; for deterministic tests of delayed schedules, provide `E.Clock.Test`, fork the program, then advance the clock once per gap and await the fiber. A forked run starts with a fresh environment, so provide the test clock and a seeded `E.Random.Test` inside the forked program.
+
+More examples: [`test_retry.py`](https://github.com/krzkaczor/effecton/blob/main/packages/effecton/src/effecton/std/test_retry.py).
+
 ## Roadmap
 
 - [x] `ty` support
 - [x] Support for async/sync code
-- [ ] Retries
+- [x] Retries
 - [x] Timeouts
-- [ ] `Random` implicit service
+- [x] `Random` implicit service
+- [x] `FileSystem` service and `Path`
+- [x] `HttpClient` service
 - [ ] More examples of integrations with existing ecosystem (fastapi, pydantic etc.)
 
 ## Inspirations

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

@@ -1,6 +1,6 @@
 [project]
 name = "effecton"
-version = "0.2.1"
+version = "0.3.0"
 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"