Index
Contents
Chapter 46 · Solutions

Stateless: Solutions

Each listing below is self-contained. It redeclares the Console and greet() it needs instead of importing them from the chapter, so a solution keeps working when a chapter listing changes.

1. A Console that reads as well as prints

Add a read() method to the Console protocol in console_protocol.py and write ask_and_greet(), an Effect that asks for a name and greets the result. Supply a scripted Console in a test and a real one in a demo, and confirm ask_and_greet() stays unchanged between them.

Where to look

Supplying an Interface shows a Protocol standing in for a base class. need(Console) hands back the object you pass to supply(). Add read() to the protocol, then write ask_and_greet() as a generator that gets the Console with need() and calls read() and print() on it. In the test, pass supply() a scripted object that returns a canned answer, and in the demo, an object wrapping input().

Done when

uv run pytest passes your test, which asserts that a scripted Console printed the greeting built from its canned answer, and your demo greets the name it reads. uv run ty check accepts both run() calls, and ask_and_greet() is the same text in both.

Solution

The solution wraps each supplied object in as_type(Console):

# test_ch46_ask_and_greet.py
from dataclasses import dataclass, field
from typing import Protocol, runtime_checkable
from stateless import (Depend, Need, as_type, need,
                       run, supply)

@runtime_checkable
class Console(Protocol):
    def print(self, message: str) -> None: ...
    def read(self, prompt: str) -> str: ...

class Terminal:
    def print(self, message: str) -> None:
        print(message)

    def read(self, prompt: str) -> str:
        return input(prompt)

@dataclass
class Scripted:
    answer: str
    printed: list[str] = field(default_factory=list)

    def print(self, message: str) -> None:
        self.printed.append(message)

    def read(self, prompt: str) -> str:
        return self.answer

def ask_and_greet() -> Depend[Need[Console], None]:
    console = yield from need(Console)
    name = console.read("What is your name? ")
    console.print(f"Hello, {name}!")

def test_ask_and_greet_uses_the_answer_it_reads() -> None:
    scripted = Scripted("Alice")
    run(supply(as_type(Console)(scripted))(ask_and_greet)())
    assert scripted.printed == ["Hello, Alice!"]

scripted = Scripted("Bob")
run(supply(as_type(Console)(scripted))(ask_and_greet)())
print(scripted.printed)
#: ['Hello, Bob!']

Supplying a real Console is the same call with Terminal() in place of Scripted(...), and the session reads:

What is your name? Alice
Hello, Alice!

The demo in test_ch46_ask_and_greet.py supplies Scripted rather than Terminal, so it runs without waiting at the keyboard.

Request an interface, not a class. ask_and_greet() is the same function, character for character, with either object supplied. Terminal, Scripted, and any third implementation are interchangeable because none of them appears in the Effect. Adding read() to the protocol changes which classes qualify: a class now needs both methods.

Supply under the protocol’s type. supply() reads the Ability from the static type of its argument, so supply(scripted) builds a handler for Need[Scripted] rather than the Need[Console] that ask_and_greet() requests. In the test and in the demo, as_type(Console) changes the argument’s static type from Scripted to Console. At runtime as_type(Console)(scripted) returns scripted. The handler answers the Need[Console] request with that object, because Console is @runtime_checkable and isinstance() accepts a Scripted as a Console by structure.

If you pass scripted to supply() without as_type(Console), the demo still prints ['Hello, Bob!'], but ty reports an invalid-argument-type at each run() call. To the type checker, supply(scripted) handles Need[Scripted], so the Need[Console] that ask_and_greet() requests stays in the type of the Effect passed to run().

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

2. An undeclared need, declared

Take undeclared_need.py, remove the # type: ignore, and run ty check on it. Fix the error by changing only the annotation, then check what greet_all()’s callers must now declare.

Where to look

Effects Propagate shows what ty reports when a function’s annotation leaves out a request that greet() makes. Read the error’s yield type, then change the return annotation of greet_all() so it declares the request that yield from relays from greet(). That request propagates to every caller of greet_all(), so look at what its callers declare next.

The shape
# The shape of exercise_2.py
from stateless import Depend, Need, need, run, supply

class Console:
    def print(self, message: str) -> None:
        ...

def greet(name: str) -> Depend[Need[Console], None]:
    ...

def greet_all(names: list[str]) -> Depend[
    Need[Console], None
]:
    ...
Done when

uv run ty check passes on your file with the # type: ignore gone and only the annotation of greet_all() changed, and running it with a Console supplied prints Hello, Alice! and Hello, Bob!. The type checker reports an invalid-argument-type for a call that hands greet_all() to run() with no Console supplied.

Solution

If you remove the # type: ignore from undeclared_need.py, ty reports:

error[invalid-yield]: Yield expression type does not match annotation
 --> undeclared_need.py:7:20
  |
5 | def greet_all(names: list[str]) -> Success[None]:
  |                                    ------------- Function annotated
  |                                    with yield type `Never` here
6 |     for name in names:
7 |         yield from greet(name)
  |                    ^^^^^^^^^^^ expression of type `Need[Console]`,
  |                    expected `Never`

Success[None] is Effect[Never, Never, None]: an Effect with empty Ability and error channels and a None result. Never in the yield channel means the function may yield no value of any type, so the Need[Console] that yield from greet(name) relays contradicts the annotation.

The fix is the annotation, and only the annotation:

# exercise_2.py
from stateless import Depend, Need, need, run, supply

class Console:
    def print(self, message: str) -> None:
        print(message)

def greet(name: str) -> Depend[Need[Console], None]:
    console = yield from need(Console)
    console.print(f"Hello, {name}!")

def greet_all(names: list[str]) -> Depend[
    Need[Console], None
]:
    for name in names:
        yield from greet(name)

run(supply(Console())(greet_all)(["Alice", "Bob"]))
#: Hello, Alice!
#: Hello, Bob!

Fix the signature, not the body. The body of greet_all() was correct before the fix. Its signature described a pure function.

The new annotation changes what greet_all()’s callers must declare. Before the fix, a caller could hand greet_all() to run() with no environment: run(greet_all(names)). Now every caller has two options, the same two greet()’s callers have. A caller can supply a Console, which ends the requirement, or declare Need[Console] in its own return type, which puts the same choice to its callers. Those two are the only options, so the dependency stays visible. The requirement appears in the signature of every function between the one that uses the Console and the one that supplies it. The type checker reports an error at any of those functions that leaves out the requirement.

If you fix the annotation but keep a caller that runs greet_all() with no environment, as run(greet_all(["Alice", "Bob"])) does, ty reports an invalid-argument-type at that run() call. At runtime that call raises a MissingAbilityError before the first greeting prints. The solution therefore wraps greet_all() in supply(Console()) before calling run().

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

3. Catching an error that is already handled

Apply reveal_type() to catch(ValueError)(one_unhandled) and run ty check. Explain why its result type differs from all_handled()’s result type, given that both have handled every error read_score() declares.

Where to look

Turning an Error Into a Value shows catch() moving a declared error out of the error channel. Compare the two result types and ask what catch() leaves in each return type. Then look at what a match over the caught value does to that type, and which function in the pair has a match that covers every error read_score() declares.

The shape
# The shape of exercise_3.py
from typing import Final, assert_never, reveal_type
from stateless import Success, Try, catch, throws

RAW: Final[dict[str, str]] = {"Alice": "42", "Bob": "seven"}

@throws(KeyError, ValueError)
def read_score(name: str) -> int:
    ...

def all_handled(name: str) -> Success[str]:
    ...

def one_unhandled(name: str) -> Try[ValueError, str]:
    ...
Done when

ty check reveals (name: str) -> Generator[Never, Any, str | ValueError] for catch(ValueError)(one_unhandled), and your explanation says which channel catch() moves the ValueError into and what in all_handled() leaves its return type a bare str.

Solution
# exercise_3.py
from typing import Final, assert_never, reveal_type
from stateless import Success, Try, catch, throws

RAW: Final[dict[str, str]] = {"Alice": "42", "Bob": "seven"}

@throws(KeyError, ValueError)
def read_score(name: str) -> int:
    text = RAW[name]  # KeyError
    return int(text)  # ValueError

both = catch(KeyError, ValueError)(read_score)
one = catch(KeyError)(read_score)

def all_handled(name: str) -> Success[str]:
    value: int | KeyError | ValueError = yield from both(
        name)
    match value:
        case KeyError():
            return f"{name}: unknown"
        case ValueError():
            return f"{name}: unreadable"
        case int():
            return f"{name}: {value}"
        case _:
            assert_never(value)

def one_unhandled(name: str) -> Try[ValueError, str]:
    value: int | KeyError = yield from one(name)
    match value:
        case KeyError():
            return f"{name}: unknown"
        case int():
            return f"{name}: {value}"
        case _:
            assert_never(value)

if __name__ == "__main__":
    reveal_type(catch(ValueError)(one_unhandled))

ty reveals:

info[revealed-type]: Revealed type
`(name: str) -> Generator[Never, Any, str | ValueError]`

all_handled() returns a Success[str], which expands to Generator[Never, Any, str]. The revealed type and all_handled()’s return type both have Never in the yield channel, so neither can yield a failure to its caller. They differ in the return channel: str for all_handled(), str | ValueError for the wrapped one_unhandled().

Consume every caught error. The difference is which function consumes each caught error. The match in all_handled() has a case for each of the three types and returns a str from it, so no error remains in its return type. The type checker accepts the assert_never() under case _ because those three cover every type in value’s annotation.

Pass the remaining error up. The ValueError in one_unhandled() stays declared, as Try[ValueError, str] says, so it is still in the yield channel when catch(ValueError) wraps one_unhandled(). catch() does not delete an error. It moves the error from the yield channel to the return channel, as a value. So the yield type becomes Never, and the return type becomes str | ValueError. A caller needing a bare str has one case left to handle.

Both functions have handled every error read_score() declares. Only all_handled() has turned what it caught into a result. catch() turns a failure into a value, and a match turns that value into a result. Skipping the match leaves the caught error in the return type.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

4. A Log protocol, and a test that records both

Rewrite audit_log.py so Log is a Protocol rather than a concrete class, then write a test that supplies a recording Log and a recording Console at once and asserts on both.

Where to look

Retrofitting an Effect builds Log as an Ability alongside Console, and Supplying an Interface shows how a Protocol replaces a concrete class. Declare Log with a write() method, and define one recording class that has the methods of both protocols. Pass its instance to supply() once for each protocol, in one call, run the Effect, and assert on the recorder’s two lists.

Done when

uv run pytest passes your test, which runs greet_all() under one supply() call and asserts both the greetings (Hello, Alice!, Hello, Bob!) and the log entries (greeted Alice, greeted Bob). uv run ty check accepts the file, and Log is a Protocol.

Solution

If you declare Log as a Protocol without @runtime_checkable, the type checker accepts the listing, but the program raises a TypeError at the first request for a Log. supply() matches each request with isinstance(), and isinstance() raises a TypeError on a Protocol without that decorator. The solution puts the decorator on both protocols, as console_protocol.py does on Console.

# test_ch46_audit_log.py
from dataclasses import dataclass, field
from typing import Protocol, runtime_checkable
from stateless import (Depend, Need, as_type, need,
                       run, supply)

@runtime_checkable
class Console(Protocol):
    def print(self, message: str) -> None: ...

@runtime_checkable
class Log(Protocol):
    def write(self, entry: str) -> None: ...

def greet(name: str) -> Depend[Need[Console], None]:
    console = yield from need(Console)
    console.print(f"Hello, {name}!")

def greet_logged(
    name: str,
) -> Depend[Need[Console] | Need[Log], None]:
    yield from greet(name)
    log = yield from need(Log)
    log.write(f"greeted {name}")

def greet_all(
    names: list[str],
) -> Depend[Need[Console] | Need[Log], None]:
    for name in names:
        yield from greet_logged(name)

@dataclass
class Recorder:
    printed: list[str] = field(default_factory=list)
    entries: list[str] = field(default_factory=list)

    def print(self, message: str) -> None:
        self.printed.append(message)

    def write(self, entry: str) -> None:
        self.entries.append(entry)

def test_greeting_and_logging_are_both_recorded() -> None:
    recorder = Recorder()
    environment = supply(
        as_type(Console)(recorder), as_type(Log)(recorder))
    run(environment(greet_all)(["Alice", "Bob"]))
    assert recorder.printed == ["Hello, Alice!",
                                "Hello, Bob!"]
    assert recorder.entries == ["greeted Alice",
                                "greeted Bob"]

recorder = Recorder()
run(supply(as_type(Console)(recorder),
           as_type(Log)(recorder))(greet_all)(["Cyd"]))
print(recorder.printed, recorder.entries)
#: ['Hello, Cyd!'] ['greeted Cyd']

Fill both roles with one object. In audit_log.py, Log is a dataclass that holds its own entries, so a test constructs one and reads log.entries afterward. For one object to fill both roles there, it must belong to a class that inherits from both Log and Console. As a Protocol, Log requires a write() method and no base class, so one Recorder satisfies both Log and Console by defining write() and print().

Supply one object under two types. The two as_type() calls pass one object to supply() under two static types, Console and Log. supply() reads the Ability from each argument’s static type, so without the wrappers, supply(recorder, recorder) builds a handler for Need[Recorder], while greet_all() requests Need[Console] and Need[Log]. Each wrapper names the role this instance fills.

Check the greeting and the log together. One test holds both assertions because it supplies the whole environment. The test reads both of the recorder’s lists, with no capture of stdout and no temporary file. Each need() makes a request that the handler answers with the recorder, so the test chooses what printing and logging do.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

5. A third material in the table

Add a Metal material to test_nailer.py with a strength that survives the robotic nailer, and add its two rows to the table. Then explain why the test function body stays the same.

Where to look

One Effect, Many Environments shows parametrize running holds() against a table of materials and nailers. Define a Metal value whose strength exceeds the robotic nailer’s force, and add one row for each nailer. Consider what holds() asks for by type, and whether a new instance of that type changes the request.

Done when

uv run pytest collects six test_holds cases and all pass, including your Metal against ROBOTIC with True expected, and the body of test_holds() is unchanged. You can say what in holds() makes a new row enough.

Solution

If you give METAL a strength of 11 or less, the (METAL, ROBOTIC, True) row fails with assert False is True. holds() compares with a strict <, so a material survives a nailer when its strength exceeds the force, not when strength and force are equal. The solution picks 20, well above both forces.

# test_ch46_nailer.py
from typing import Final
import pytest
from record import record
from stateless import Depend, Need, need, run, supply

@record
class Material:
    strength: int

@record
class Nailer:
    force: int

def holds() -> Depend[Need[Material] | Need[Nailer], bool]:
    material = yield from need(Material)
    nailer = yield from need(Nailer)
    return nailer.force < material.strength

WOOD: Final[Material] = Material(strength=5)
PLASTIC: Final[Material] = Material(strength=10)
METAL: Final[Material] = Material(strength=20)
HAND: Final[Nailer] = Nailer(force=4)
ROBOTIC: Final[Nailer] = Nailer(force=11)

@pytest.mark.parametrize("material, nailer, expected", [
    (WOOD, HAND, True),
    (PLASTIC, HAND, True),
    (METAL, HAND, True),
    (WOOD, ROBOTIC, False),
    (PLASTIC, ROBOTIC, False),
    (METAL, ROBOTIC, True),
])
def test_holds(
    material: Material, nailer: Nailer, expected: bool
) -> None:
    assert run(
        supply(material, nailer)(holds)()) is expected

print(run(supply(METAL, ROBOTIC)(holds)()))
#: True

Pick a strength above both forces. METAL at strength 20 exceeds the robotic nailer’s force of 11, so both its rows read True.

Build each environment from a row. The test function body stays the same because every material and nailer arrives as an argument. The parametrize table decides which material and nailer the body receives, so a new row adds a case and leaves the function body that runs it as it is.

That split between the table and the body is the chapter’s split between an Effect and its environment, applied to a test. holds() declares two requirements and leaves the instances to supply(), so every combination of instances is a valid environment for it. The parametrize table is a list of environments, and the test body is the driver that runs the Effect in each one. Six rows share one assertion. A version constructing its own Material inside holds() needs three copies of the function, one per material, and a version that also constructs its own Nailer needs six, one per row.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

6. A handler that builds what the request names

This one looks ahead to handle(), which Abilities Are Not Special covers. default_console.py defaults by supplying an instance. Write the other kind of default, one that builds the type the request names. handle() reads its handler’s parameter annotation to decide what it answers, so a function annotated Need[Console] and returning ability.t() hands back a default-constructed instance of the requested class. Run it against greeter.py’s greet(), whose Console constructs with no arguments, and confirm the greeting prints. Then declare a second Ability and request that one too, and report which requests your handler answered at runtime and which ones the type checker believes it answered. Account for the difference, using handle()’s t = get_origin(t) or t as the evidence.

Where to look

Layering Handlers shows a default supplied under a more specific handler, and Abilities Are Not Special covers handle(). Write a handler function that takes a Need[Console] parameter and returns a new instance of the class the request carries in ability.t. Wrap it with handle(), then compare what runs against what the annotation tells the type checker.

The shape
# The shape of exercise_6.py
from stateless import Depend, Need, handle, need, run

class Console:
    def print(self, message: str) -> None:
        ...

class Clock:
    def now(self) -> str:
        ...

def greet(name: str) -> Depend[Need[Console], None]:
    ...

def stamped(
    name: str,
) -> Depend[Need[Console] | Need[Clock], None]:
    ...

def default(ability: Need[Console]) -> Console:
    ...
Done when

your handler, wrapped with handle(), makes greeter.py’s greet() print its greeting, and an Effect that also requests a second Ability runs to completion, with a print() in the handler showing it answered both requests. ty reports an invalid-argument-type at that second run(), naming the leftover Need, until a # type: ignore on that line silences the report.

Solution

If you return Console() in place of ability.t(), greet() still prints its greeting, but stamped() fails with AttributeError: 'Console' object has no attribute 'now'. In that version the handler answers the Clock request too, as it answers every Need, and its answer is a Console. The type checker accepts return Console(), since default() declares that it returns a Console. The solution calls ability.t(), which constructs an instance of the class the request names, so the Clock request receives a Clock.

# exercise_6.py
from stateless import Depend, Need, handle, need, run

class Console:
    def print(self, message: str) -> None:
        print(message)

class Clock:
    def now(self) -> str:
        return "noon"

def greet(name: str) -> Depend[Need[Console], None]:
    console = yield from need(Console)
    console.print(f"Hello, {name}!")

def stamped(
    name: str,
) -> Depend[Need[Console] | Need[Clock], None]:
    clock = yield from need(Clock)
    console = yield from need(Console)
    console.print(f"[{clock.now()}] Hello, {name}!")

def default(ability: Need[Console]) -> Console:
    print(f"handler answered a request "
          f"for {ability.t.__name__}")
    return ability.t()

defaults = handle(default)
run(defaults(greet)("Alice"))
#: handler answered a request for Console
#: Hello, Alice!
run(defaults(stamped)("Bob"))  # type: ignore
#: handler answered a request for Clock
#: handler answered a request for Console
#: [noon] Hello, Bob!

Build the class the request names. default() names Console only in its annotations. It reads ability.t, the class the request carries, and calls that class, so each answer is a new instance of the requested class. That is the other kind of default. default_console.py supplies one prepared instance, whereas default() builds the type the request names each time a request arrives.

Run both Effects through one handler. At runtime the handler answered three requests across the two run() calls, two for Console and one for Clock, although default() annotates its parameter Need[Console]. The type checker removes Need[Console] from the requirements and leaves Need[Clock] open, so the second run() needs a # type: ignore. Without that pragma, the type checker reports an invalid-argument-type that names the leftover Need[Clock].

handle()’s t = get_origin(t) or t is the evidence. handle() reads the annotation, reduces Need[Console] to its origin, Need, and tests each request with isinstance(ability, Need). That test ignores the type argument, so every Need[...] request passes it. The type checker reads the same annotation with its type argument kept, subtracts Need[Console] from the requirements, and leaves Need[Clock] in place.

handle() and the type checker are each right about what they describe. isinstance() cannot test a type argument. Need[Clock] and Need[Console] are the same runtime class. The two requests differ in their t field, which default() prints, but handle()’s isinstance(ability, Need) test accepts both. The annotation holds the type argument, and the type checker reads it there. A handler like default() therefore answers more requests than its annotation declares. A handler that assumes ability.t is a Console receives a Need[Clock] request unchecked.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

7. Two ways to drop a yield from

Break audit_log.py by removing the yield from in front of greet(name) in greet_logged(). Run ty check, ruff check, and the script, and record what each reports and what the program prints. Explain where the greetings went and why no tool reports an error. Then restore that yield from, and instead remove the yield from in front of need(Console) in greeter.py’s greet(). This time the type checker produces two diagnostics. Explain what each one catches, and why the checker catches assigning a dropped request but not discarding one.

Where to look

Nothing Runs Yet shows that calling a generator function builds an Effect without running its body, and Why yield from explains what the keyword does. Ask whether a discarded generator breaks any rule ty or ruff checks. For the second case, read both diagnostics and ask what the function has become once it loses its only yield from, and whether the next line uses the dropped value.

Done when

for the first deletion your record shows ty check and ruff check silent and the script printing ['greeted Alice', 'greeted Bob'] with no greetings, and for the second it shows invalid-implicit-return and missing-attribute. You can say which line makes the second break visible to the type checker.

Solution

With the yield from in front of greet(name) removed, greet_logged() reads:

def greet_logged(
    name: str,
) -> Depend[Need[Console] | Need[Log], None]:
    greet(name)  # Was: yield from greet(name)
    log = yield from need(Log)
    log.write(f"greeted {name}")

ty check and ruff check both accept the file. The script runs to completion and prints:

['greeted Alice', 'greeted Bob']

The log entries are the whole output. greet() is a generator function, so calling greet(name) builds an Effect and returns it. The statement discards that Effect before its body starts, so the body never yields its Need[Console] request.

The log entries appear because the deletion changes the greeting line and leaves the two logging lines as they were. The surviving entries make the failure harder to notice. The program looks like it worked and produced most of its output.

Both tools accept the file because the code follows every rule they check. Building a value and discarding it is legal Python, and greet(name)’s value is a generator like any other. Generators’s exercise 4 drops a yield from in a generator with no Effect in it. There ty reports an invalid-assignment on the annotated profile: Result = interview(). Once the exercise removes that annotation, ty check accepts the file, as it accepts the broken audit_log.py. The declared Need[Console] in the return type still holds, since a declaration says what the function may request, not what it must. The chapter warns about this deletion. A bare greet(name) passes every check and discards the greeting.

If you remove the yield from in front of need(Console) in greet(), the type checker reports two diagnostics:

def greet(name: str) -> Depend[Need[Console], None]:
    console = need(Console)  # Was: yield from need(Console)
    console.print(f"Hello, {name}!")
error[invalid-implicit-return]: Function always implicitly returns `None`,
which is not assignable to return type
`Generator[Need[Console], Any, None]`
 --> greeter.py:8:25
  |
8 | def greet(name: str) -> Depend[Need[Console], None]:
  |                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^

error[missing-attribute]: Object of type
`Generator[Need[Console], Any, Console]` has no attribute `print`
  --> greeter.py:10:5
   |
10 |     console.print(f"Hello, {name}!")
   |     ^^^^^^^^^^^^^

The invalid-implicit-return error follows from greet() becoming an ordinary function. That yield from was the body’s only yield expression, so without it greet() returns None where its annotation declares a Generator. The missing-attribute error reports the type of the value in console: a Generator, where the console.print() call needs a Console.

The difference between the two cases is whether anything later uses the dropped value. The discarded greet(name) is a complete statement, so the type checker checks that statement alone and accepts it. Assigning need(Console) binds a generator to console, and the next line calls print() on it as if it were a Console. The type checker checks that call and rejects it. A type checker verifies how a program uses its values, so an unused value goes unchecked.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

8. A registry of Effects, and why retry() takes a function

Build a registry of Effects: a dict[str, Success[None]] that maps each of two names to supply(Console())(greet)(name). Run every entry, then run every entry a second time, and record what prints on each pass. Change the values to functions that build the Effect when called, and run both passes again. Explain which of the two shapes retry() requires, and why it takes a schedule and returns a decorator of type Callable[P, Effect[...]] -> Callable[P, Effect[...]], rather than being an operation on an Effect.

Where to look

An Effect Runs Once shows a spent Effect returning None when you run it again. Store the Effects in one dictionary and functions that build them in another, then run each twice. retry() starts the work over after a failure, so consider what it needs to call each time.

The shape
# The shape of exercise_8.py
from collections.abc import Callable
from functools import partial
from typing import Final
from stateless import (Depend, Need, Success, need,
                       run, supply)

class Console:
    def print(self, message: str) -> None:
        ...

def greet(name: str) -> Depend[Need[Console], None]:
    ...

NAMES: Final[list[str]] = ["Alice", "Bob"]

def make(name: str) -> Success[None]:
    ...
Done when

your four passes print Hello, Alice! and Hello, Bob! three times: the first pass over the stored Effects prints them, the second runs silently, and both passes over the functions print them. You can say why a retry needs something it can call once per attempt.

Solution
# exercise_8.py
from collections.abc import Callable
from functools import partial
from typing import Final
from stateless import (Depend, Need, Success, need,
                       run, supply)

class Console:
    def print(self, message: str) -> None:
        print(message)

def greet(name: str) -> Depend[Need[Console], None]:
    console = yield from need(Console)
    console.print(f"Hello, {name}!")

NAMES: Final[list[str]] = ["Alice", "Bob"]

built: dict[str, Success[None]] = {
    name: supply(Console())(greet)(name) for name in NAMES
}
for effect in built.values():
    run(effect)
#: Hello, Alice!
#: Hello, Bob!
# The same objects, a second time
for effect in built.values():
    run(effect)

def make(name: str) -> Success[None]:
    return supply(Console())(greet)(name)

builders: dict[str, Callable[[], Success[None]]] = {
    name: partial(make, name) for name in NAMES
}
for builder in builders.values():
    run(builder())
#: Hello, Alice!
#: Hello, Bob!
# A fresh Effect each time
for builder in builders.values():
    run(builder())
#: Hello, Alice!
#: Hello, Bob!

Run each stored Effect twice. The second pass over built is silent, and run() returns None for each entry. Each Effect in built is a generator, and a generator runs once. The exceptions are a success() Effect, which gives every run() its value, and a memoize() Effect, which hands a second run() its cached result. Resuming a finished generator raises StopIteration immediately, with None as its value, and run() returns that value. So run() gives the same result for a spent Effect as for one that succeeds and returns None.

Build a fresh Effect per run. The stored value changes from a generator, which run() consumes once, to a function, which a caller can call each time it needs a fresh Effect.

Because a function can build a fresh Effect again and again, retry() takes a schedule and returns a decorator of type Callable[P, Effect[...]] -> Callable[P, Effect[...]] rather than a function of type Effect[...] -> Effect[...]. Retrying means running the same work more than once. An Effect supplies one run. By the time the first attempt fails, that attempt has run the generator to its end, and a finished generator stays finished. retry() needs a fresh Effect per attempt, and the function that builds the Effect supplies one on each call. So retry() decorates the function, calls it once per attempt, and hands back a function that takes the decorated function’s arguments.

The Effect the returned function builds has a wider type. retry() adds Need[Time] and Async for the sleeps between attempts and replaces the error with a RetryError.

The same reasoning explains repeat() and memoize(). It also explains the mistake in storing Effects in a registry, a queue, or a cache. A stored Effect works on its first run and silently returns None on its second. Store the function, and apply the arguments where you need the Effect.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

9. Three reports, one Effect

Write report_all(), which calls stateless_coroutine.py’s report() for three URLs with yield from and returns the three results. Work out what report_all()’s annotation must be, and confirm it with the type checker. Then call it from inside an async def, once with run() and once with await run_async(), and record what each one does. Explain why the type checker accepts both.

Where to look

Waiting on a Coroutine shows wait() putting an Async request into an Effect, and Where to Call run() covers running one from inside an event loop. Loop over the URLs, delegate to report() with yield from, and collect the results in a list. The annotation declares the Async request. The two runners differ in whether they start their own event loop.

The shape
# The shape of exercise_9.py
import asyncio
from exceptions import expect
from stateless import Async, Depend, run, run_async, wait

async def fetch(url: str) -> str:
    ...

def report(url: str) -> Depend[Async, str]:
    ...

def report_all(urls: list[str]) -> Depend[Async, list[str]]:
    ...

async def main() -> None:
    ...
Done when

uv run ty check passes with your annotation on report_all(), and inside your async def the run() call raises a RuntimeError (asyncio.run() cannot be called from a running event loop) while await run_async() returns three reports, one per URL, in order.

Solution
# exercise_9.py
import asyncio
from exceptions import expect
from stateless import Async, Depend, run, run_async, wait

async def fetch(url: str) -> str:
    await asyncio.sleep(0.01)
    return f"fetched {url}"

def report(url: str) -> Depend[Async, str]:
    body = yield from wait(fetch(url))
    return f"{body = }"

def report_all(urls: list[str]) -> Depend[Async, list[str]]:
    reports: list[str] = []
    for url in urls:
        reports.append((yield from report(url)))
    return reports

async def main() -> None:
    expect(RuntimeError, run, report_all(["a"]))
    for line in await run_async(
            report_all(["a", "b", "c"])):
        print(line)

asyncio.run(main())
#: [RuntimeError] asyncio.run() cannot be called from a
#: running event loop
#: body = 'fetched a'
#: body = 'fetched b'
#: body = 'fetched c'

Relay the request, collect the results. report() declares Async, and yield from relays each Async request to report_all()’s caller, so report_all() must declare it too. The Ability channel becomes a union such as Need[Console] | Need[Log] when the delegated Effects request different Abilities. Here every delegation is to report(), so the Ability channel stays Async. The return type changes, from one str to a list[str], since report_all() collects the results rather than relaying them.

Drive the Effect from a coroutine. run(effect) is asyncio.run(run_async(effect)). asyncio.run() raises a RuntimeError when called inside a running event loop, so calling run() from main() fails. run_async() is the same driver in coroutine form, so main() awaits it on the running loop.

The type checker accepts both calls because both are correctly typed. run() takes an Effect and returns its result. run_async() takes an Effect and returns an awaitable of its result. report_all(["a"]) satisfies either signature. Nothing in the type system records that this call site sits inside a coroutine. Whether an event loop is running is a fact about the moment of the call, not about the types involved. A run() inside a coroutine therefore passes the type checker and fails at runtime, with the RuntimeError above. The rule is positional rather than type-based: run() at the outermost edge of a synchronous program, run_async() anywhere inside an asynchronous one.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

10. A second failure in the channel

announce() declares Effect[Need[Console], KeyError, None]. Give it a second failure: a helper that formats the score and raises a ValueError on a negative one, lifted with @throws(ValueError). Follow the type checker until the program builds, add a negative score to scores.py’s SCORES so the new failure can occur, then run it on a name that produces each failure and on one that succeeds, and say where the program reported each failure. Then delete ValueError from announce()’s annotation and record what the type checker reports and at which line.

Where to look

Multiple Errors shows an Effect declaring more than one failure, and The Error Channel covers @throws. Lift the helper with @throws(ValueError), then widen announce()’s failure type to a union and call the helper with yield from. Run the three names and note whether each failure comes out of run() as an exception. If you delete ValueError from the annotation, the type checker reports an error at the yield from of the helper.

The shape
# The shape of exercise_10.py
from typing import Final
from exceptions import expected
from stateless import (Effect, Need, need, run, supply,
                       throws)

class Console:
    def print(self, message: str) -> None:
        ...

SCORES: Final[dict[str, int]] = {
    "Alice": 42, "Bob": 7, "Cyd": -3}

@throws(KeyError)
def score(name: str) -> int:
    ...

@throws(ValueError)
def format_score(name: str, value: int) -> str:
    ...

def announce(
    name: str,
) -> Effect[Need[Console], KeyError | ValueError, None]:
    ...
Done when

uv run ty check passes. For a name with a positive score the program prints one line, for a name with a negative score run() raises a ValueError, and for a name missing from SCORES it raises a KeyError. With ValueError deleted from announce()’s annotation, ty reports invalid-yield at your helper’s yield from.

Solution
# exercise_10.py
from typing import Final
from exceptions import expected
from stateless import (Effect, Need, need, run, supply,
                       throws)

class Console:
    def print(self, message: str) -> None:
        print(message)

SCORES: Final[dict[str, int]] = {
    "Alice": 42, "Bob": 7, "Cyd": -3}

@throws(KeyError)
def score(name: str) -> int:
    return SCORES[name]

@throws(ValueError)
def format_score(name: str, value: int) -> str:
    if value < 0:
        raise ValueError(
            f"negative score for {name}: {value}")
    return f"{name}: {value}"

def announce(
    name: str,
) -> Effect[Need[Console], KeyError | ValueError, None]:
    value: int = yield from score(name)
    line: str = yield from format_score(name, value)
    console = yield from need(Console)
    console.print(line)

bound = supply(Console())(announce)
for who in ("Alice", "Cyd", "Dana"):
    with expected((KeyError, ValueError)):
        run(bound(who))
#: Alice: 42
#: [ValueError] negative score for Cyd: -3
#: [KeyError] 'Dana'

Lift the helper into an Effect. @throws(ValueError) turns format_score() from a function that raises an exception into one that returns an Effect declaring it, so the Effect yields the exception as a value instead of letting it propagate up the stack.

Declare the second failure. Following the type checker until the program builds means one edit: widening announce()’s error parameter from KeyError to KeyError | ValueError.

The listing annotates line and value by choice, not because the type checker requires it. yield from on a @throws function has the declared success type. When you write that type on the variable, the type checker compares its inference with your annotation.

Let run() raise each failure. Cyd has a score, so the lookup succeeds and format_score() fails. Dana is missing from SCORES, so the lookup fails and the Effect ends before it calls format_score(). In both cases each yield from relays the error value unchanged, through announce() and the supply() handler, to the driver. run() is the first code to act on the error, and it raises the error as an ordinary exception.

Declaring a failure is not handling it. The declaration says the failure can occur. catch() turns it into a value the program handles.

If you delete ValueError from the annotation, ty reports:

error[invalid-yield]: Yield expression type does not match annotation
  --> exercise_10.py:29:28
   |
27 | ) -> Effect[Need[Console], KeyError, None]:
   |      ------------------------------------- Function annotated with
   |      yield type `Need[Console] | KeyError` here
28 |     value: int = yield from score(name)
29 |     line: str = yield from format_score(name, value)
   |                            ^^^^^^^^^^^^^^^^^^^^^^^^^
   |                            expression of type `ValueError`,
   |                            expected `Need[Console] | KeyError`

ty reports the error on line 29, the yield from that introduces the undeclared failure, not on the signature and not at the call site. That statement is the useful place for the diagnostic. The diagnostic gives the undeclared failure’s type and marks the delegation that yields it, so the fix is either to declare the failure or to catch it, right there.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

11. Making the ambiguity a type error

ambiguous_supply.py picks its Console by argument order. Add a third implementation and predict, before running it, which of the six orderings send Alice’s greeting where. Then follow the advice in When Two Implementations Match: give the recording implementation a method name the screen one does not have, declare each as its own Protocol, and show that handing the wrong implementation to an Effect is now a type error rather than a silent choice. Two implementations sharing one method name stay ambiguous under both Protocols, so say what the technique does and does not prevent.

Where to look

When Two Implementations Match explains why supply() takes the first argument that satisfies the request. Predict from argument order. If you give each implementation its own Protocol with a differently named method, the type checker rejects an implementation that lacks the method the Effect requests. Then check whether the type checker can distinguish two classes that share one method name.

The shape
# The shape of exercise_11.py
from dataclasses import dataclass, field
from typing import Protocol, runtime_checkable
from stateless import (Depend, Need, as_type, need,
                       run, supply)

@runtime_checkable
class Screen(Protocol):
    def print(self, message: str) -> None: ...

@runtime_checkable
class Recorder(Protocol):
    def record(self, message: str) -> None: ...

@dataclass
class Terminal:
    def print(self, message: str) -> None:
        ...

@dataclass
class Capture:
    messages: list[str] = field(default_factory=list)
    def record(self, message: str) -> None:
        ...

def to_screen(name: str) -> Depend[Need[Screen], None]:
    ...

def to_log(name: str) -> Depend[Need[Recorder], None]:
    ...
Done when

your six predictions for ambiguous_supply.py with a third implementation match your six runs. supply() hands the request to the first argument that satisfies it. With separate Protocols, the type checker reports an invalid-argument-type that names the missing method when you hand Terminal to the recording Effect, and you can name the case that two Protocols still leave to argument order.

Solution

With a third implementation added to ambiguous_supply.py, the three implementations have six orderings, and one rule predicts them all. supply() scans its arguments and takes the first that satisfies the request, so the implementation listed first answers it. Two of the six orderings put Terminal first and send the greeting to the screen. The remaining four split evenly between Capture and the third implementation. Every ordering supplies the same three implementations, each of which satisfies the request, so all six orderings find a match and run to completion.

The fix replaces the one Protocol that every implementation satisfies with two:

# exercise_11.py
from dataclasses import dataclass, field
from typing import Protocol, runtime_checkable
from stateless import (Depend, Need, as_type, need,
                       run, supply)

@runtime_checkable
class Screen(Protocol):
    def print(self, message: str) -> None: ...

@runtime_checkable
class Recorder(Protocol):
    def record(self, message: str) -> None: ...

@dataclass
class Terminal:
    def print(self, message: str) -> None:
        print(message)

@dataclass
class Capture:
    messages: list[str] = field(default_factory=list)
    def record(self, message: str) -> None:
        self.messages.append(message)

def to_screen(name: str) -> Depend[Need[Screen], None]:
    device = yield from need(Screen)
    device.print(f"Hello, {name}!")

def to_log(name: str) -> Depend[Need[Recorder], None]:
    device = yield from need(Recorder)
    device.record(f"Hello, {name}!")

capture = Capture()
run(supply(as_type(Screen)(Terminal()))(to_screen)("Alice"))
#: Hello, Alice!
run(supply(as_type(Recorder)(capture))(to_log)("Bob"))
print(capture.messages)
#: ['Hello, Bob!']

Give each role its own protocol. The fix renames Capture.print() to record(), gives each method its own Protocol, Screen and Recorder, and splits greet() into one Effect per Protocol. The two Protocols now declare different methods, so each implementation satisfies one of them, and each Effect requests the Protocol it needs.

That change turns the silent choice into a diagnostic. If you append to the listing a line that hands to_log() a Terminal instead of a Capture, ty rejects that line before the program runs:

error[invalid-argument-type]: Argument is incorrect
  --> exercise_11.py:40:30
   |
40 | run(supply(as_type(Recorder)(Terminal()))(to_log)("Carol"))
   |                              ^^^^^^^^^^ Expected `Recorder`, found `Terminal`
info: type `Terminal` is not assignable to protocol `Recorder`
info: └── protocol member `record` is not defined on type `Terminal`

In the second info line, the type checker gives the reason as a missing method, record. Structural typing means that Terminal fails for the method it lacks, not for the class it is.

If you keep print() on both implementations and declare it in both Protocols, each implementation satisfies both, and the type checker accepts as_type(Recorder)(Terminal()). Handing that object to to_log() prints Hello, Carol! to the screen while capture.messages stays ['Hello, Bob!'], with no diagnostic. Two Protocols that share one method name describe one structure under two names.

One limit remains. Distinct method names remove the ambiguity between Abilities and leave two implementations of the same Ability ambiguous. A second recorder, an Audit that also defines record(), brings the ambiguity back. Supplying both capture and audit through as_type(Recorder) leaves the choice to argument order, with no diagnostic.

Because that ambiguity remains, When Two Implementations Match gives its advice in two halves. No type can enforce the second half, “supply one implementation per Ability.” Because supply() scans its arguments at runtime to answer a request, a duplicate is a fact about the call rather than about the types. ZIO rejects this case at compile time, which is the difference that section describes.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.