GitHub

Atoms

Reactive values kept in a registry: derived atoms that update when what they read changes, atoms backed by effects and streams, families, RPC and HTTP API queries, and state handed from a server to a client.

An atom is a recipe for a value: a constant, a function of other atoms, an effect or a stream. An atom holds nothing itself. A registry builds the atoms you read, keeps their values while something uses them, and rebuilds an atom when an atom it read changes. pyfect.reactivity follows Effect's effect/reactivity: atom, atom_registry, atom_rpc, atom_http_api and hydration are submodules of it.

Atoms and derived atoms

atom.make(1) is a writable atom holding 1; atom.state[tuple[str, ...]](()) is one whose type you give, where the value alone would be too narrow (Effect's Atom.make<A>(value)). atom.make(lambda get: get(count) * 2) is a derived atom: get reads another atom and records it as a dependency, so setting count rebuilds doubled and notifies its subscribers. atom.family(f) gives one atom per key, compared with Equal, so todo(1) is the same atom each time it is called.

atoms.py
import pyfect as fx
from pyfect.reactivity import atom, atom_registry

# An atom is a recipe for a value; a registry computes it and holds it.
count = atom.make(1)
doubled = atom.make(lambda get: get(count) * 2)


# A family makes one atom per key, so `todo(1)` is the same atom every time.
@atom.family
def todo(id: int) -> atom.Writable[str, str]:
    return atom.make(f"todo {id}")


@fx.gen
def program():
    registry = atom_registry.make()
    yield from fx.add_finalizer(lambda _: fx.sync(registry.dispose))

    print("doubled:", registry.get(doubled))
    cancel = registry.subscribe(doubled, lambda value: print("doubled is now", value))
    registry.set(count, 5)
    registry.update(count, lambda n: n + 1)
    cancel()

    print(todo(1) is todo(1), registry.get(todo(2)))


fx.run_main(fx.scoped(program))

atom_registry.make() creates a registry on the running fiber's scheduler. registry.get, set, update and subscribe work on it directly, and subscribe returns the function that unsubscribes. An atom that no subscriber, mount or other live atom uses is removed from the registry, and built again when it is read next; keep_alive() keeps it, and set_idle_ttl("30 seconds") keeps it that long after its last use (a bare number is milliseconds). Methods like map, with_fallback and debounce derive a new atom from one.

registryinvalidatesSuccessnew valuenew valueregistry.set(count, 5)count node: 5doubled node: 10effect fiberuser node: AsyncResultsubscribers
registryinvalidatesSuccessnew valuenew valueregistry.set(count, 5)count node: 5doubled node: 10effect fiberuser node: AsyncResultsubscribers

Effect and stream atoms

An atom made from an effect holds an AsyncResult: Initial while the effect runs, then Success or Failure. The registry runs the effect when the atom is built and interrupts it when the atom is removed. A stream atom holds a result of the stream's latest item. atom.fn(f) is a function atom: writing an argument to it runs f(arg, get), and a new write interrupts the run in progress. atom.runtime(layer) builds a layer once per registry, and its atom and fn make atoms whose effects use that layer's services.

The effects atom.get, atom.set and atom.get_result use the registry that atom_registry.layer provides. get_result waits for an atom's first Success or Failure, and with suspend_on_waiting=True for one that is not still running.

effects.py
from dataclasses import dataclass

import pyfect as fx
from pyfect import layer, stream
from pyfect.reactivity import atom, atom_registry
from pyfect.reactivity.atom import FnContext

# An effect atom holds an AsyncResult: Initial while it runs, then Success or Failure.
user = atom.make(fx.sleep("50 millis").as_("Ada"))

# A stream atom holds a result of the latest item.
latest = atom.make(stream.make(1, 2, 3))


# A function atom runs its effect each time an argument is written to it.
def greet(name: str, get: FnContext) -> fx.Effect[str]:
    return fx.succeed(f"hello, {name}")


greeting = atom.fn(greet)


# A runtime atom builds a layer; its atoms' effects can use the layer's services.
@dataclass
class Prices:
    table: dict[str, int]


class PriceTable(fx.Tag[Prices]): ...


prices = atom.runtime(layer.succeed(PriceTable, Prices({"tea": 3})))
tea = prices.atom(PriceTable().map(lambda p: p.table["tea"]))


@fx.gen
def program():
    registry = yield from atom_registry.AtomRegistry()
    print(registry.get(user))
    print("user:", (yield from atom.get_result(user)))
    print("latest:", (yield from atom.get_result(latest)))

    yield from atom.set(greeting, "Grace")
    print((yield from atom.get_result(greeting, suspend_on_waiting=True)))
    print("tea:", (yield from atom.get_result(tea)))


fx.run_main(program.pipe(fx.provide(atom_registry.layer)))

RPC and HTTP API atoms

atom_rpc.make(Tag, group=..., protocol=...) turns an RPC group into atoms. client.query(rpc, payload) is an atom of the call's result, one per payload, and client.mutation(rpc) a function atom taking a MutationRequest. A query's reactivity_keys tie it to the mutations that change it: a mutation written with the same keys refreshes those queries once it succeeds. A query also takes headers, time_to_live and a serialization_key for hydration.

rpc.py
import pyfect as fx
from pyfect import schema as S
from pyfect.reactivity import atom, atom_registry, atom_rpc
from pyfect.rpc import RpcGroup, RpcRequest, make
from pyfect.rpc import test as rpc_test


class Todos(RpcGroup):
    list_todos = make("ListTodos", success=S.Array(S.String))
    add_todo = make("AddTodo", payload=S.String, success=S.Int)


todos = ["write docs"]


def add_todo(request: RpcRequest[str]) -> fx.Effect[int]:
    def add() -> int:
        todos.append(request.payload)
        return len(todos)

    return fx.sync(add)


TodosLive = Todos.to_layer(
    Todos.handlers()
    .handle(Todos.list_todos)(lambda _: fx.sync(lambda: tuple(todos)))
    .handle(Todos.add_todo)(add_todo)
)


class TodosClient(fx.Tag[Todos]): ...


# `protocol` is the client's transport layer; here the handlers run in memory.
client = atom_rpc.make(
    TodosClient, group=Todos, protocol=TodosLive, make_effect=rpc_test.make_client(Todos)
)
# A query is an atom of the RPC's result, one per payload.
all_todos = client.query(Todos.list_todos, None, reactivity_keys=["todos"])
# A mutation is a function atom; its reactivity keys refresh the queries with those keys.
add = client.mutation(Todos.add_todo)


@fx.gen
def program():
    yield from atom.mount(all_todos)
    print((yield from atom.get_result(all_todos)))
    yield from atom.set(add, {"payload": "ship it", "reactivity_keys": ["todos"]})
    yield from atom.get_result(add, suspend_on_waiting=True)
    print((yield from atom.get_result(all_todos, suspend_on_waiting=True)))


fx.run_main(fx.scoped(program).pipe(fx.provide(atom_registry.layer)))

atom_http_api.make(Tag, api=..., http_client=...) does the same for an HTTP API: query(Group, endpoint, params=..., payload=...) and mutation(Group, endpoint), typed from the endpoint's schemas. Prefer query_of(Group, endpoint)(params=..., payload=...), the same atom: pyright rejects a wrong request part there, while query(...) widens the endpoint's types to accept it. mutate(Group, endpoint) is the mutation as a function of the endpoint's request parts: calling it with keywords (and reactivity_keys) gives the effect that runs the mutation and waits for its result. Prefer it to writing a MutationRequest dict to the mutation atom, which pyright cannot check when the endpoint lacks a part. Both clients build their transport in an atom runtime, which does not see the program's services, so the layer you pass provides all of it: here it wraps the program's HTTP client, which knows the test server's address.

http_api.py
from typing import TypedDict

import pyfect as fx
from pyfect import layer
from pyfect import schema as S
from pyfect.http import router, uvicorn_server
from pyfect.http.client import HttpClient
from pyfect.http_api import HttpApi, HttpApiGroup, builder, client, endpoint
from pyfect.reactivity import atom, atom_http_api, atom_registry


class Name(TypedDict):
    name: str


class Greetings(HttpApiGroup, identifier="greetings"):
    hello = endpoint.get("hello", "/hello/:name", params=S.Struct(Name), success=S.String)
    greeted = endpoint.get("greeted", "/greeted", success=S.Array(S.String))
    greet = endpoint.post("greet", "/greeted", payload=S.Struct(Name), success=S.String)


api = HttpApi.make("example").add(Greetings)
names: list[str] = []


def greet(name: str) -> str:
    names.append(name)
    return f"greeted {name}"


ApiLive = builder.layer(api).pipe(
    layer.provide(
        builder.group(
            api,
            Greetings,
            lambda handlers: (
                handlers.handle(Greetings.hello)(
                    lambda request: fx.succeed(f"hello, {request.params['name']}")
                )
                .handle(Greetings.greeted)(lambda _: fx.sync(lambda: tuple(names)))
                .handle(Greetings.greet)(
                    lambda request: fx.sync(lambda: greet(request.payload["name"]))
                )
            ),
        )
    )
)


class ExampleClient(fx.Tag[client.Client[Greetings]]): ...


@fx.gen
def program():
    http = yield from HttpClient()
    # The atoms' client sends its requests with this HttpClient.
    api_atoms = atom_http_api.make(
        ExampleClient, api=api, http_client=layer.succeed(HttpClient, http)
    )
    hello = api_atoms.query_of(Greetings, Greetings.hello)(params={"name": "Ada"})
    print((yield from atom.get_result(hello)))

    # A query with reactivity keys is refreshed by a mutation made with the same keys.
    greeted = api_atoms.query(Greetings, Greetings.greeted, reactivity_keys=["greeted"])
    yield from atom.mount(greeted)
    print("before:", (yield from atom.get_result(greeted)))
    greet_one = api_atoms.mutate(Greetings, Greetings.greet)
    print((yield from greet_one(payload={"name": "Grace"}, reactivity_keys=["greeted"])))
    print("after:", (yield from atom.get_result(greeted, suspend_on_waiting=True)))


served = router.serve(ApiLive, disable_logger=True, disable_listen_log=True)
fx.run_main(
    fx.scoped(program)
    .pipe(fx.provide(atom_registry.layer))
    .pipe(fx.provide(served))
    .pipe(fx.provide(uvicorn_server.layer_test()))
)

A query of a Server-Sent Events endpoint holds the open stream, not an event. A stream atom over it, atom.make(lambda get: stream.unwrap(get.result(events, suspend_on_waiting=True))), holds the latest event and is waiting while the stream is open, so other atoms can depend on it or be refreshed by it with refresh_on_signal. Once it is no longer waiting the stream has ended (the server went away or closed it): refresh the query to connect again.

sse.py
import pyfect as fx
from pyfect import layer, stream
from pyfect import schema as S
from pyfect.http import router, uvicorn_server
from pyfect.http.client import HttpClient
from pyfect.http_api import HttpApi, HttpApiGroup, builder, client, endpoint
from pyfect.http_api import schema as api_schema
from pyfect.reactivity import atom, atom_http_api, atom_registry


class Status(HttpApiGroup, identifier="status"):
    # Server-Sent Events: the success is a stream of the events' data.
    changes = endpoint.get("changes", "/changes", success=api_schema.StreamSse(data=S.String))
    connected = endpoint.get("connected", "/connected", success=S.Int)


api = HttpApi.make("status").add(Status)
connections = [0]


def changes() -> fx.Effect[fx.Stream[str]]:
    """Each connection sends two events, then the stream ends."""
    connections[0] += 1
    n = connections[0]
    return fx.succeed(stream.make(f"connection {n}: up", f"connection {n}: down"))


ApiLive = builder.layer(api).pipe(
    layer.provide(
        builder.group(
            api,
            Status,
            lambda handlers: handlers.handle(Status.changes)(lambda _: changes()).handle(
                Status.connected
            )(lambda _: fx.sync(lambda: connections[0])),
        )
    )
)


class StatusClient(fx.Tag[client.Client[Status]]): ...


@fx.gen
def program():
    http = yield from HttpClient()
    api_atoms = atom_http_api.make(
        StatusClient, api=api, http_client=layer.succeed(HttpClient, http)
    )
    # The query holds the open stream, not an event.
    events = api_atoms.query(Status, Status.changes)
    # A stream atom over it holds the latest event, waiting while the stream is open.
    # suspend_on_waiting: once the query is refreshed, read the new stream, not the old one.
    latest = atom.make(lambda get: stream.unwrap(get.result(events, suspend_on_waiting=True)))
    # Another query, fetched again whenever an event arrives.
    connected = api_atoms.query(Status, Status.connected).refresh_on_signal(latest)
    yield from atom.mount(latest)
    yield from atom.mount(connected)
    print((yield from atom.get_result(latest, suspend_on_waiting=True)))

    # Not waiting means the stream has ended: refresh the query to connect again.
    yield from atom.refresh(events)
    print((yield from atom.get_result(latest, suspend_on_waiting=True)))
    print("connections:", (yield from atom.get_result(connected, suspend_on_waiting=True)))


served = router.serve(ApiLive, disable_logger=True, disable_listen_log=True)
fx.run_main(
    fx.scoped(program)
    .pipe(fx.provide(atom_registry.layer))
    .pipe(fx.provide(served))
    .pipe(fx.provide(uvicorn_server.layer_test()))
)

Hydration

atom.serializable(key=..., schema=...) marks an atom whose value can leave the process. hydration.dehydrate(registry) encodes the serializable atoms a registry holds, and DehydratedAtom.to_json() writes each entry as Effect does, so a Python server can hand state to an Effect client and back. hydration.hydrate(registry, entries) preloads another registry by key before its atoms are read. An effect atom still runs once it is built unless it is marked skip_initial_run=True, which keeps the hydrated value until the atom is refreshed or a dependency changes.

While that first run goes on, the atom shows the hydrated value, and it is not marked waiting: get_result(atom, suspend_on_waiting=True) returns it at once. A result that arrives later replaces it, a failure keeping it as its previous success. A run that settles while the atom is being built (an effect with nothing to wait for) is dropped, and the hydrated value stays until the atom is refreshed. This is what Effect does. To tell a hydrated value from a fresh one, compare a Success's timestamp (epoch milliseconds, kept through hydration) with when your program started, or refresh the atom and wait with suspend_on_waiting=True. async_result.Schema encodes an AsyncResult the way Effect's AsyncResult.Schema does.

hydration.py
import json

import pyfect as fx
from pyfect import schema as S
from pyfect.reactivity import async_result, atom, atom_registry, hydration
from pyfect.reactivity.hydration import DehydratedAtom

loads: list[str] = []


def load_cart() -> tuple[str, ...]:
    loads.append("cart")
    return ("tea", "scones")


# A serializable atom has a key and a schema for its value (here an AsyncResult).
cart = atom.make(fx.sync(load_cart)).serializable(
    key="cart",
    schema=async_result.Schema(success=S.Array(S.String)),
    skip_initial_run=True,  # keep a hydrated value instead of loading again
)


@fx.gen
def program():
    # The server loads the cart and sends what its registry holds as JSON.
    server = atom_registry.make()
    yield from atom_registry.get_result(server, cart)
    sent = json.dumps([entry.to_json() for entry in hydration.dehydrate(server)])

    # The client hydrates its registry before it reads the atom.
    client = atom_registry.make()
    hydration.hydrate(client, [DehydratedAtom.from_json(entry) for entry in json.loads(sent)])
    print("client:", async_result.get_or_raise(client.get(cart)))
    print("loads:", loads)
    server.dispose()
    client.dispose()


fx.run_main(program)

Effect's React, Solid and Vue bindings are JavaScript UI adapters and are not ported.

Reference: pyfect.reactivity.atom, atom_registry, async_result, atom_rpc, atom_http_api, hydration.