api.mdx

title	Referencia de API
description	Referencia detallada de tipos, funciones, parámetros, retornos, adaptadores y ciclo de vida de PyDux.
icon	braces

Referencia de API

Action

Action(type: str, payload: Any = None, meta: dict[str, Any] = {})

Action es un dataclass inmutable que describe una transición de estado.

Parámetro	Tipo	Valor por defecto	Descripción
type	str	obligatorio	Tipo no vacío, normalmente slice/acción.
payload	Any	None	Dato que consume el reducer.
meta	dict[str, Any]	{}	Metadatos que no pertenecen al estado.

Un type vacío o que no sea string lanza ValueError.

create_slice

create_slice(name, initial_state, reducers, extra_reducers=None) -> Slice

Parámetro	Tipo	Descripción
name	str	Namespace no vacío de acciones generadas.
initial_state	Any	Valor inicial; se copia profundamente antes de mutarlo.
reducers	dict[str, Callable[[state, action], Any]]	Reducers locales por nombre corto.
extra_reducers	dict[str, Callable[[state, action], Any]] | None	Reducers para tipos externos completos.

Un reducer recibe un borrador mutable y un Action. Modifica el borrador y retorna None, o devuelve un estado completo de reemplazo.

todos = create_slice(
    name="todos",
    initial_state=[],
    reducers={
        "add": lambda state, action: state.append(action.payload),
        "clear": lambda state, action: [],
    },
)

todos.actions.add({"title": "Documentar"})  # tipo: todos/add

Miembro de Slice	Descripción
name	Namespace del slice.
initial_state	Definición original del estado inicial.
actions	Creadores de acciones accesibles con punto.
reducer	Función compatible con configure_store.

Una acción desconocida deja intacto el objeto de estado del slice. Una acción generada inexistente lanza AttributeError.

configure_store

configure_store(
    reducer,
    preloaded_state=None,
    middleware=None,
    devtools=True,
    inspector_auto_start=True,
    inspector_host="127.0.0.1",
    inspector_port=8765,
    inspector_log=True,
) -> Store

Parámetro	Tipo	Default	Descripción
reducer	Reducer o dict[str, Reducer | Slice]	obligatorio	Reducer raíz o mapa de ramas.
preloaded_state	Any | None	None	Estado inicial; las claves dadas reemplazan defaults de slices.
middleware	Sequence[Middleware] | None	None	Middleware después del thunk incorporado.
devtools	bool | PyDuxDevTools	True	Tracker interno, uno personalizado o False.
inspector_auto_start	bool	True	Inicia inspector cuando DevTools está activo.
inspector_host / port	str / int	localhost / 8765	Destino del inspector; un puerto ocupado cambia a uno libre.
inspector_log	bool	True	Imprime la URL al iniciar.

El middleware de thunks siempre se instala. DevTools añade store.devtools; el inspector exitoso añade store.inspector.

Store

Método	Firma	Comportamiento
get_state	() -> TState	Devuelve el estado raíz; no lo modifiques.
dispatch	(action: Action | Callable) -> Any	Ejecuta el pipeline y devuelve el resultado.
select	(selector, listener, equality_fn=None, fire_immediately=False) -> unsubscribe	Crea una suscripción selectiva.
subscribe	(listener) -> unsubscribe	Se llama tras cada dispatch.

select evalúa el selector al suscribirse. Con fire_immediately=True llama al listener con ese valor. Después sólo lo llama si equality_fn(anterior, actual) es falso; por defecto usa shallow_equal.

Llamar unsubscribe() varias veces es seguro. Un error del listener se registra y no cancela el dispatch. Despachar algo que no sea Action directamente al Store lanza TypeError; despachar dentro de un reducer lanza RuntimeError.

Selectores, thunks y DevTools

create_selector(*inputs, combiner, equality_fn=shallow_equal) requiere al menos un selector de entrada y un combiner; de otro modo lanza ValueError. El resultado expone recomputations y reset_recomputations().

Helper	Comportamiento
is_identical(a, b)	Compara con is.
shallow_equal(a, b)	Compara identidad y luego valores de primer nivel.
deep_equal(a, b)	Usa igualdad recursiva (a == b).

create_async_thunk(prefix, creator) emite prefix/pending, prefix/fulfilled con el resultado, o prefix/rejected con el mensaje del error y meta={"error": True}. Resuelve awaitables y vuelve a lanzar el error original.

PyDuxDevTools(max_history=100) registra trazas con index, action, estados anterior/siguiente, timestamp, duración y rutas cambiadas. Sus métodos son undo(), redo(), jump_to_state(index), subscribe_traces(listener) y export_trace_json().

Adaptadores

ReactiveBinding(store, selector, target, equality_fn=None, bridge=None)
connect(store, map_state_to_props=None, bridge=None)
Reactive.bind_selector(store, selector, on_change, equality_fn=None) -> unsubscribe
connect_qyro(store, selectors)

ReactiveBinding se suscribe de inmediato y programa target(value) con su bridge; dispose() cancela. connect asigna a la instancia cada entrada producida por map_state_to_props(state) y llama opcionalmente a on_props_changed().

Reactive.bind_selector difiere el primer callback al tick Qt, Tkinter o Kivy, rastrea unsubscribers y los libera en component_will_unmount. connect_qyro recibe {nombre_atributo: selector}, escribe atributos, llama opcionalmente a on_state_change(copia_de_props) y limpia al desmontar.