An atom holding the services a layer builds (R_co, failing with
ER_co), and the maker of atoms whose effects use them.
Attributes#
| Attribute | Type | Description |
|---|---|---|
factory | = factory | |
layer | = layer |
Functions#
__init__#
__init__(read, factory, layer) -> None| Parameter | Type | Description |
|---|---|---|
read | Callable[[AtomContext], AsyncResult[Context[Any], Any]] | |
factory | RuntimeFactory | |
layer | Atom[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 = layeratom#
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
create | Stream[A, E, _Services | R_co] | Callable[[AtomContext], Stream[A, E, _Services | R_co]] | |
disable_accumulation | bool = 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.
| Parameter | Type | Description |
|---|---|---|
create | Effect[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| Parameter | Type | Description |
|---|---|---|
f | Callable[[Self], B] |
Returns B
def pipe[B](self, f: Callable[[Self], B], /) -> B:
return f(self)keep_alive#
keep_alive() -> SelfThis 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() -> SelfThis 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) -> SelfFalse: rebuilt as soon as a dependency changes, not when next
read.
| Parameter | Type | Description |
|---|---|---|
lazy | bool |
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) -> SelfKeep this atom duration after it is last used; an infinite
duration keeps it alive.
| Parameter | Type | Description |
|---|---|---|
duration | DurationInput |
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) -> SelfValues equals calls equal are not a change: no notification,
no rebuild of dependents.
| Parameter | Type | Description |
|---|---|---|
equals | Callable[[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) -> SelfName this atom (with where the label was set).
| Parameter | Type | Description |
|---|---|---|
name | str |
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) -> SelfRefresh this atom when keys are invalidated through the
registry's Reactivity (the default runtime's).
| Parameter | Type | Description |
|---|---|---|
keys | Keys |
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) -> SelfMark 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.
| Parameter | Type | Description |
|---|---|---|
key | str | |
schema | Codec[A_co, Any, Never, Never] | |
skip_initial_run | bool = 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) -> SelfThe value get_server_value reports for this atom.
| Parameter | Type | Description |
|---|---|---|
read | Callable[[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.
| Parameter | Type | Description |
|---|---|---|
f | Callable[[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.
| Parameter | Type | Description |
|---|---|---|
f | Callable[[AtomContext, Self], B] | |
initial_value_target | Atom[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.
| Parameter | Type | Description |
|---|---|---|
f | Callable[[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.
| Parameter | Type | Description |
|---|---|---|
fallback | Atom[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.
| Parameter | Type | Description |
|---|---|---|
duration | DurationInput |
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.
| Parameter | Type | Description |
|---|---|---|
duration | DurationInput |
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)).
| Parameter | Type | Description |
|---|---|---|
signal | Atom[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).
| Parameter | Type | Description |
|---|---|---|
stale_time | DurationInput | |
revalidate_on_mount | bool = True | |
revalidate_on_focus | bool | Literal['always'] = False | |
focus_signal | Atom[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)