Module

_types

Frozen dataclasses, enums, and type aliases — no internal imports.

Classes

SpecialKey 0
Key 5
Single keypress.

Single keypress.

Attributes

Name Type Description
char str
name SpecialKey | None
ctrl bool
alt bool
shift bool
Action 2
Event dispatched to a reducer.

Event dispatched to a reducer.

Attributes

Name Type Description
type str
payload Any
AppStatus 0
RenderTarget 0
Screen 3
Named screen config: template name + reducer reference.

Named screen config: template name + reducer reference.

Attributes

Name Type Description
name str
template str
reducer Callable
Transition 3
Flow edge between screens.

Flow edge between screens.

Attributes

Name Type Description
from_screen str
to_screen str
on_action str
FieldType 0
FieldSpec 7
Declarative field configuration.

Declarative field configuration.

Attributes

Name Type Description
name str
label str
field_type FieldType
choices tuple[str, ...]
default Any
validator Callable | None
placeholder str
FieldState 5
Runtime state for a single field.

Runtime state for a single field.

Attributes

Name Type Description
value Any
cursor int
error str
focused bool
selected_index int
FormState 4
Full form state.

Full form state.

Attributes

Name Type Description
fields tuple[FieldState, ...]
specs tuple[FieldSpec, ...]
active_index int
submitted bool
Call 3
Call a function, resume saga with its return value.

Call a function, resume saga with its return value.

Attributes

Name Type Description
fn Callable
args tuple
kwargs dict
Put 1
Dispatch an action back to the store.

Dispatch an action back to the store.

Attributes

Name Type Description
action Action
Select 1
Read current state, resume saga with it.

Read current state, resume saga with it.

Attributes

Name Type Description
selector Callable | None
Fork 1
Run another saga concurrently.

Run another saga concurrently.

Attributes

Name Type Description
saga Callable | Generator
Delay 1
Sleep for N seconds.

Sleep for N seconds.

Attributes

Name Type Description
seconds float
Retry 7
Call a function with retry and backoff on failure. Usage in a saga:: result = yield Retry(fet…

Call a function with retry and backoff on failure.

Usage in a saga::

result = yield Retry(fetch_data, args=(url,), max_attempts=3, backoff="exponential")

Attributes

Name Type Description
fn Callable
args tuple
kwargs dict
max_attempts int
backoff str
base_delay float
max_delay float
Cmd 1
Lightweight command: a thunk that returns an Action (or None). Simpler than sagas for one-shot eff…

Lightweight command: a thunk that returns an Action (or None).

Simpler than sagas for one-shot effects::

def fetch_cmd():
    data = fetch_json(url)
    return Action("FETCH_DONE", payload=data)

return ReducerResult(state, cmds=(Cmd(fetch_cmd),))

Attributes

Name Type Description
fn Callable
Batch 1
Run commands concurrently with no ordering guarantees. Usage:: return ReducerResult(state, cm…

Run commands concurrently with no ordering guarantees.

Usage::

return ReducerResult(state, cmds=(Batch(cmd_a, cmd_b, cmd_c),))

Attributes

Name Type Description
cmds tuple[Cmd | Batch | Sequence, ...]
Sequence 1
Run commands serially, in order. Each command's result is dispatched before the next starts:: …

Run commands serially, in order.

Each command's result is dispatched before the next starts::

return ReducerResult(state, cmds=(Sequence(cmd_a, cmd_b),))

Attributes

Name Type Description
cmds tuple[Cmd | Batch | Sequence, ...]
TickCmd 1
Schedule a single @@TICK after *interval* seconds. Return from a reducer to start ticking. Return …

Schedule a single @@TICK after interval seconds.

Return from a reducer to start ticking. Return another TickCmd when you receive @@TICK to keep the loop going; omit to stop::

case "@@TICK":
    if state.loading:
        return ReducerResult(new_state, cmds=(TickCmd(0.15),))
    return new_state

Attributes

Name Type Description
interval float
ViewState 4
Declarative terminal state returned alongside rendered content. The renderer diffs previous vs. cu…

Declarative terminal state returned alongside rendered content.

The renderer diffs previous vs. current ViewState and applies only the changes. Attach to ReducerResult to control terminal features from your reducer::

return ReducerResult(state, view=ViewState(cursor_visible=True))

Attributes

Name Type Description
alt_screen bool | None
cursor_visible bool | None
window_title str | None
mouse_mode bool | None
ReducerResult 4
Reducer can return this to trigger side effects.

Reducer can return this to trigger side effects.

Attributes

Name Type Description
state Any
sagas tuple[Callable, ...]
cmds tuple[Cmd | Batch | Sequence | TickCmd, ...]
view ViewState | None
Quit 5
Signal the app to exit. Return from a reducer to stop the event loop.

Signal the app to exit. Return from a reducer to stop the event loop.

Attributes

Name Type Description
state Any
code int
sagas tuple[Callable, ...]
cmds tuple[Cmd | Batch | Sequence | TickCmd, ...]
view ViewState | None

Functions

compact_cmds 1 tuple
Strip None entries and simplify command tuples. Returns an empty tuple for no …
def compact_cmds(*cmds: Cmd | Batch | Sequence | TickCmd | None) -> tuple

Strip None entries and simplify command tuples.

Returns an empty tuple for no commands, a single-element tuple for one, and the full tuple otherwise. Avoids unnecessary allocations for the common zero-or-one-command case.

Parameters
Name Type Description
*cmds Cmd | Batch | Sequence | TickCmd | None
Returns
tuple