GitHub

AtomRuntime

API reference for AtomRuntime.

An atom holding the services a layer builds (R_co, failing with ER_co), and the maker of atoms whose effects use them.

Attributes

AttributeTypeDescription
factory= factory
layer= layer

Functions

__init__

__init__(read, factory, layer) -> None
ParameterTypeDescription
readCallable[[AtomContext], AsyncResult[Context[Any], Any]]
factoryRuntimeFactory
layerAtom[Layer[Any, Any, Any]]
def __init__(
    self,
    read: Callable[[AtomContext], AsyncResult[Context[Any], Any]],
    factory: RuntimeFactory,
    layer: Atom[Layer[Any, Any, Any]],
) -> None:
    super().__init__(read)
    self.factory = factory
    self.layer = layer

atom

atom[A, E = Never](effect: Effect[A, E, _Services | R_co], /, *, initial_value: A = ..., uninterruptible: bool = False) -> Atom[AsyncResult[A, E | ER_co]]
atom[A, E = Never](stream: Stream[A, E, _Services | R_co], /, *, initial_value: A = ...) -> Atom[AsyncResult[A, E | ER_co | NoSuchElementException]]
atom[A, E = Never](create: Callable[[AtomContext], Effect[A, E, _Services | R_co]], /, *, initial_value: A = ..., uninterruptible: bool = False) -> Atom[AsyncResult[A, E | ER_co]]
atom[A, E = Never](create: Callable[[AtomContext], Stream[A, E, _Services | R_co]], /, *, initial_value: A = ...) -> Atom[AsyncResult[A, E | ER_co | NoSuchElementException]]

atom.make of an effect or stream (or a function making one) that may use this runtime's services. While the runtime builds (or if it failed) the atom shows its result.

ParameterTypeDescription
arg
initial_value= MISSING
uninterruptible= False
@overload
def atom[A, E = Never](
    self,
    effect: Effect[A, E, _Services | R_co],
    /,
    *,
    initial_value: A = ...,
    uninterruptible: bool = False,
) -> Atom[AsyncResult[A, E | ER_co]]: ...
@overload
def atom[A, E = Never](
    self,
    stream: Stream[A, E, _Services | R_co],
    /,
    *,
    initial_value: A = ...,
) -> Atom[AsyncResult[A, E | ER_co | NoSuchElementException]]: ...
@overload
def atom[A, E = Never](
    self,
    create: Callable[[AtomContext], Effect[A, E, _Services | R_co]],
    /,
    *,
    initial_value: A = ...,
    uninterruptible: bool = False,
) -> Atom[AsyncResult[A, E | ER_co]]: ...
@overload
def atom[A, E = Never](
    self,
    create: Callable[[AtomContext], Stream[A, E, _Services | R_co]],
    /,
    *,
    initial_value: A = ...,
) -> Atom[AsyncResult[A, E | ER_co | NoSuchElementException]]: ...
def atom(
    self, arg: Any, /, *, initial_value: object = MISSING, uninterruptible: bool = False
) -> Atom[Any]:
    """``atom.make`` of an effect or stream (or a function making one)
    that may use this runtime's services. While the runtime builds (or
    if it failed) the atom shows its result."""
    read = cast(
        "Callable[[AtomContext, Context[Any]], Any]",
        make_read(arg, initial_option(initial_value), uninterruptible),
    )

    def read_with_runtime(get: AtomContext) -> Any:
        services = get(self)
        if not isinstance(services, Success):
            return _replace_previous(services, get)
        return read(get, services.value)

    return readable(read_with_runtime)

fn

fn[Arg, A, E = Never](f: Callable[[Arg, FnContext], Effect[A, E, _Services | R_co]], /, *, initial_value: A = ..., reactivity_keys: Keys | None = None, concurrent: bool = False) -> AtomResultFn[Arg, A, E | ER_co]
fn[Arg, A, E = Never](f: Callable[[Arg, FnContext], Stream[A, E, _Services | R_co]], /, *, initial_value: A = ..., reactivity_keys: Keys | None = None, concurrent: bool = False) -> AtomResultFn[Arg, A, E | ER_co | NoSuchElementException]

atom.fn with this runtime's services; with reactivity_keys a success invalidates them.

ParameterTypeDescription
f
initial_value= MISSING
reactivity_keys= None
concurrent= False
@overload
def fn[Arg, A, E = Never](
    self,
    f: Callable[[Arg, FnContext], Effect[A, E, _Services | R_co]],
    /,
    *,
    initial_value: A = ...,
    reactivity_keys: Keys | None = None,
    concurrent: bool = False,
) -> AtomResultFn[Arg, A, E | ER_co]: ...
@overload
def fn[Arg, A, E = Never](
    self,
    f: Callable[[Arg, FnContext], Stream[A, E, _Services | R_co]],
    /,
    *,
    initial_value: A = ...,
    reactivity_keys: Keys | None = None,
    concurrent: bool = False,
) -> AtomResultFn[Arg, A, E | ER_co | NoSuchElementException]: ...
def fn(
    self,
    f: Callable[[Any, FnContext], Any],
    /,
    *,
    initial_value: object = MISSING,
    reactivity_keys: Keys | None = None,
    concurrent: bool = False,
) -> Writable[Any, Any]:
    """``atom.fn`` with this runtime's services; with
    ``reactivity_keys`` a success invalidates them."""
    run = f
    if reactivity_keys is not None:
        keys = reactivity_keys

        def mutating(arg: Any, get: FnContext) -> Any:
            value = f(arg, get)
            if isinstance(value, Effect):
                return _reactivity.mutation(cast("Effect[Any, Any, Any]", value), keys)
            stream = cast("Stream[Any, Any, Any]", value)
            return stream.on_end(_reactivity.invalidate(keys))

        run = mutating

    read, write, arg_atom = make_result_fn(run, initial_option(initial_value), concurrent)

    def read_with_runtime(get: AtomContext) -> Any:
        get.get(arg_atom)
        services = get.get(self)
        if not isinstance(services, Success):
            return _replace_previous(services, get)
        return read(get, services.value)

    return writable(read_with_runtime, write)

pull

pull[A, E = Never](create, *, disable_accumulation=False) -> Writable[PullResult[A, E | ER_co], None]

atom.pull with this runtime's services.

ParameterTypeDescription
createStream[A, E, _Services | R_co] | Callable[[AtomContext], Stream[A, E, _Services | R_co]]
disable_accumulationbool = False

Returns Writable[PullResult[A, E | ER_co], None]

def pull[A, E = Never](
    self,
    create: Stream[A, E, _Services | R_co]
    | Callable[[AtomContext], Stream[A, E, _Services | R_co]],
    *,
    disable_accumulation: bool = False,
) -> Writable[PullResult[A, E | ER_co], None]:
    """``atom.pull`` with this runtime's services."""
    pull_signal: Writable[int, int] = remove_ttl(state(0))

    def read(get: AtomContext) -> Any:
        services = get(self)
        if not isinstance(services, Success):
            return _replace_previous(services, get)
        effect = make_stream_pull_effect(get, pull_signal, create, disable_accumulation)
        return make_effect(get, effect, async_result.initial(waiting=True), services.value)

    return make_stream_pull(pull_signal, readable(read))

subscription_ref

subscription_ref[A, E = Never](create) -> Writable[AsyncResult[A, E | ER_co], A]

atom.subscription_ref with this runtime's services.

ParameterTypeDescription
createEffect[SubscriptionRef[A], E, _Services | R_co] | Callable[[AtomContext], Effect[SubscriptionRef[A], E, _Services | R_co]]

Returns Writable[AsyncResult[A, E | ER_co], A]

def subscription_ref[A, E = Never](
    self,
    create: Effect[SubscriptionRef[A], E, _Services | R_co]
    | Callable[[AtomContext], Effect[SubscriptionRef[A], E, _Services | R_co]],
) -> Writable[AsyncResult[A, E | ER_co], A]:
    """``atom.subscription_ref`` with this runtime's services."""
    make_ref = ref_atom_read(create, lambda get: cast("Any", get(self)).value)

    def read_ref(get: AtomContext) -> Any:
        services = get(self)
        if not isinstance(services, Success):
            return _replace_previous(services, get)
        return make_ref(get)

    def read(get: AtomContext, ref: Any) -> Any:
        services = async_result.get_or_raise(get(self))
        return read_subscription_ref(get, ref, services)

    return make_sub_ref(remove_ttl(readable(read_ref)), read)

pipe

pipe[B](f) -> B
ParameterTypeDescription
fCallable[[Self], B]

Returns B

def pipe[B](self, f: Callable[[Self], B], /) -> B:
    return f(self)

keep_alive

keep_alive() -> Self

This atom, kept when nothing uses it.

Returns Self

def keep_alive(self) -> Self:
    """This atom, kept when nothing uses it."""
    return self._with(kept_alive=True)

auto_dispose

auto_dispose() -> Self

This atom, removed when nothing uses it.

Returns Self

def auto_dispose(self) -> Self:
    """This atom, removed when nothing uses it."""
    return self._with(kept_alive=False)

set_lazy

set_lazy(lazy) -> Self

False: rebuilt as soon as a dependency changes, not when next read.

ParameterTypeDescription
lazybool

Returns Self

def set_lazy(self, lazy: bool) -> Self:
    """``False``: rebuilt as soon as a dependency changes, not when next
    read."""
    return self._with(lazy=lazy)

set_idle_ttl

set_idle_ttl(duration) -> Self

Keep this atom duration after it is last used; an infinite duration keeps it alive.

ParameterTypeDescription
durationDurationInput

Returns Self

def set_idle_ttl(self, duration: DurationInput) -> Self:
    """Keep this atom ``duration`` after it is last used; an infinite
    duration keeps it alive."""
    from pyfect.reactivity.atom._combinators import set_idle_ttl

    return set_idle_ttl(self, duration)

with_equality

with_equality(equals) -> Self

Values equals calls equal are not a change: no notification, no rebuild of dependents.

ParameterTypeDescription
equalsCallable[[A_co, A_co], bool]

Returns Self

def with_equality(self, equals: Callable[[A_co, A_co], bool]) -> Self:
    """Values ``equals`` calls equal are not a change: no notification,
    no rebuild of dependents."""
    return self._with(equals=equals)

with_label

with_label(name) -> Self

Name this atom (with where the label was set).

ParameterTypeDescription
namestr

Returns Self

def with_label(self, name: str) -> Self:
    """Name this atom (with where the label was set)."""
    from pyfect.reactivity.atom._combinators import label_site

    return self._with(label=(name, label_site(2)))

with_reactivity

with_reactivity(keys) -> Self

Refresh this atom when keys are invalidated through the registry's Reactivity (the default runtime's).

ParameterTypeDescription
keysKeys

Returns Self

def with_reactivity(self, keys: Keys) -> Self:
    """Refresh this atom when ``keys`` are invalidated through the
    registry's ``Reactivity`` (the default runtime's)."""
    from pyfect.reactivity.atom._runtime import runtime

    return runtime.with_reactivity(keys)(self)

serializable

serializable(*, key, schema, skip_initial_run=False) -> Self

Mark this atom for Hydration: its value is encoded with schema (as JSON) under key, which also identifies its node. schema's type must be the atom's value.

ParameterTypeDescription
keystr
schemaCodec[A_co, Any, Never, Never]
skip_initial_runbool = False

Returns Self

def serializable(
    self,
    *,
    key: str,
    # Effect's `S extends ConstraintCodec<Type<R>, any>`
    schema: Codec[A_co, Any, Never, Never],
    skip_initial_run: bool = False,
) -> Self:
    """Mark this atom for ``Hydration``: its value is encoded with
    ``schema`` (as JSON) under ``key``, which also identifies its node.
    ``schema``'s type must be the atom's value."""
    from pyfect.reactivity.atom._serializable import serializable

    return serializable(self, key=key, schema=schema, skip_initial_run=skip_initial_run)

with_server_value

with_server_value(read) -> Self

The value get_server_value reports for this atom.

ParameterTypeDescription
readCallable[[Callable[[Atom[Any]], Any]], A_co]

Returns Self

def with_server_value(self, read: Callable[[Callable[[Atom[Any]], Any]], A_co]) -> Self:
    """The value ``get_server_value`` reports for this atom."""
    return self._with(server_value=read)

map

map[B](f) -> Atom[B]

An atom of f of this one's value.

ParameterTypeDescription
fCallable[[A_co], B]

Returns Atom[B]

def map[B](self, f: Callable[[A_co], B]) -> Atom[B]:
    """An atom of ``f`` of this one's value."""
    from pyfect.reactivity.atom._combinators import transform

    return transform(self, lambda get, atom: f(get(atom)))

transform

transform[B](f, *, initial_value_target=None) -> Atom[B]

An atom read by f, which gets this atom; writes go to this atom, and refreshing it refreshes this one.

ParameterTypeDescription
fCallable[[AtomContext, Self], B]
initial_value_targetAtom[B] | None = None

Returns Atom[B]

def transform[B](
    self,
    f: Callable[[AtomContext, Self], B],
    *,
    initial_value_target: Atom[B] | None = None,
) -> Atom[B]:
    """An atom read by ``f``, which gets this atom; writes go to this
    atom, and refreshing it refreshes this one."""
    from pyfect.reactivity.atom._combinators import transform

    return transform(self, f, initial_value_target=initial_value_target)

map_result

map_result[A, E, B](f) -> Atom[AsyncResult[B, E]]

map over the value of an AsyncResult.

ParameterTypeDescription
fCallable[[A], B]

Returns Atom[AsyncResult[B, E]]

def map_result[A, E, B](
    self: Atom[AsyncResult[A, E]], f: Callable[[A], B]
) -> Atom[AsyncResult[B, E]]:
    """``map`` over the value of an ``AsyncResult``."""
    from pyfect.reactivity import async_result

    return self.map(lambda result: async_result.map(result, f))

with_fallback

with_fallback[A, E, A2, E2](fallback) -> Atom[AsyncResult[A | A2, E | E2]]

While this atom is Initial, fallback's result, marked waiting.

ParameterTypeDescription
fallbackAtom[AsyncResult[A2, E2]]

Returns Atom[AsyncResult[A | A2, E | E2]]

def with_fallback[A, E, A2, E2](
    self: Atom[AsyncResult[A, E]], fallback: Atom[AsyncResult[A2, E2]]
) -> Atom[AsyncResult[A | A2, E | E2]]:
    """While this atom is ``Initial``, ``fallback``'s result, marked
    waiting."""
    from pyfect.reactivity.atom._combinators import with_fallback

    return with_fallback(self, fallback)

debounce

debounce(duration) -> Atom[A_co]

Changes reach this atom duration after the last one.

ParameterTypeDescription
durationDurationInput

Returns Atom[A_co]

def debounce(self, duration: DurationInput) -> Atom[A_co]:
    """Changes reach this atom ``duration`` after the last one."""
    from pyfect.reactivity.atom._combinators import debounce

    return debounce(self, duration)

with_refresh

with_refresh(duration) -> Atom[A_co]

Refresh this atom duration after each build.

ParameterTypeDescription
durationDurationInput

Returns Atom[A_co]

def with_refresh(self, duration: DurationInput) -> Atom[A_co]:
    """Refresh this atom ``duration`` after each build."""
    from pyfect.reactivity.atom._combinators import with_refresh

    return with_refresh(self, duration)

refresh_on_signal

refresh_on_signal(signal) -> Atom[A_co]

Refresh this atom whenever signal changes (Effect's makeRefreshOnSignal(signal)(self)).

ParameterTypeDescription
signalAtom[object]

Returns Atom[A_co]

def refresh_on_signal(self, signal: Atom[object]) -> Atom[A_co]:
    """Refresh this atom whenever ``signal`` changes (Effect's
    ``makeRefreshOnSignal(signal)(self)``)."""
    from pyfect.reactivity.atom._combinators import make_refresh_on_signal

    return make_refresh_on_signal(signal)(self)

refresh_on_window_focus

refresh_on_window_focus() -> Atom[A_co]

refresh_on_signal(window_focus_signal): with no browser window, the signal never changes.

Returns Atom[A_co]

def refresh_on_window_focus(self) -> Atom[A_co]:
    """``refresh_on_signal(window_focus_signal)``: with no browser
    window, the signal never changes."""
    from pyfect.reactivity.atom._combinators import window_focus_signal

    return self.refresh_on_signal(window_focus_signal)

swr

swr[A, E](*, stale_time, revalidate_on_mount=True, revalidate_on_focus=False, focus_signal=None) -> Atom[AsyncResult[A, E]]

Stale-while-revalidate: a value older than stale_time is shown while a refresh runs (on mount, and on focus_signal with revalidate_on_focus; "always" refreshes on every focus).

ParameterTypeDescription
stale_timeDurationInput
revalidate_on_mountbool = True
revalidate_on_focusbool | Literal['always'] = False
focus_signalAtom[object] | None = None

Returns Atom[AsyncResult[A, E]]

def swr[A, E](
    self: Atom[AsyncResult[A, E]],
    *,
    stale_time: DurationInput,
    revalidate_on_mount: bool = True,
    revalidate_on_focus: bool | Literal["always"] = False,
    focus_signal: Atom[object] | None = None,
) -> Atom[AsyncResult[A, E]]:
    """Stale-while-revalidate: a value older than ``stale_time`` is
    shown while a refresh runs (on mount, and on ``focus_signal`` with
    ``revalidate_on_focus``; ``"always"`` refreshes on every focus)."""
    from pyfect.reactivity.atom._swr import swr

    return swr(
        self,
        stale_time=stale_time,
        revalidate_on_mount=revalidate_on_mount,
        revalidate_on_focus=revalidate_on_focus,
        focus_signal=focus_signal,
    )

optimistic

optimistic() -> Writable[A_co, Atom[AsyncResult[A_co, object]]]

An atom showing optimistic values while the transitions written to it run, then this atom's value (refreshed after a success).

Returns Writable[A_co, Atom[AsyncResult[A_co, object]]]

def optimistic(self) -> Writable[A_co, Atom[AsyncResult[A_co, object]]]:
    """An atom showing optimistic values while the transitions written
    to it run, then this atom's value (refreshed after a success)."""
    from pyfect.reactivity.atom._optimistic import optimistic

    return optimistic(self)