Module

reducers

Composable reducer combinators for common interaction patterns.

Decorators that wrap reducers to handle boilerplate key handling — quit on escape, cursor navigation, enter to confirm — so the inner reducer only contains app-specific logic.

Usage::

@quit_on("q", SpecialKey.ESCAPE)
@with_cursor("items", wrap=True)
@with_confirm()
def reducer(state, action):
    # only app-specific logic here
    ...
5Functions

Functions

_match_key 2 bool ▼
Check if a Key matches a target (char string or SpecialKey).
def _match_key(key: Key, target: str | SpecialKey) -> bool
Parameters
Name Type Description
key Key
target str | SpecialKey
Returns
bool
_unwrap_state 1 Any ▼
Extract plain state from a ReducerResult if needed.
def _unwrap_state(result: Any) -> Any
Parameters
Name Type Description
result Any
Returns
Any
quit_on 1 Callable ▼
Decorator: return Quit(state) when any of the specified keys are pressed. Keys…
def quit_on(*keys: str | SpecialKey) -> Callable

Decorator: return Quit(state) when any of the specified keys are pressed.

Keys can be character strings ("q") or SpecialKey enums (SpecialKey.ESCAPE). The inner reducer runs first so it can perform app-specific quit logic (e.g. setting flags); if it already returnedQuit, the wrapper passes it through unchanged.

Usage::

@quit_on("q", SpecialKey.ESCAPE)
def reducer(state, action):
    ...
Parameters
Name Type Description
*keys str | SpecialKey
Returns
Callable
with_cursor 3 Callable ▼
Decorator: add up/down arrow cursor navigation over a list field. Expects *sta…
def with_cursor(items_field: str, cursor_field: str = 'cursor', *, wrap: bool = False) -> Callable

Decorator: add up/down arrow cursor navigation over a list field.

Expects state to be a frozen dataclass with an attribute named items_field (the sequence) and cursor_field (anint). HandlesSpecialKey.UP and SpecialKey.DOWN, clamping or wrapping as configured.

The inner reducer runs first. If it returnsQuitor ReducerResult, the wrapper does not interfere.

Usage::

@with_cursor("entries", wrap=True)
def reducer(state, action):
    ...
Parameters
Name Type Description
items_field str
cursor_field str Default:'cursor'
wrap bool Default:False
Returns
Callable
with_confirm 1 Callable ▼
Decorator: return Quit(state) when the confirm key is pressed. Useful for sele…
def with_confirm(key: str | SpecialKey = SpecialKey.ENTER) -> Callable

Decorator: return Quit(state) when the confirm key is pressed.

Useful for selection-style apps where pressing Enter chooses the current item. The inner reducer runs first; if it already returned Quit, the wrapper does nothing.

Usage::

@with_confirm()
@with_cursor("items")
@quit_on("q", SpecialKey.ESCAPE)
def reducer(state, action):
    ...
Parameters
Name Type Description
key str | SpecialKey Default:SpecialKey.ENTER
Returns
Callable