raito.plugins.scenes.manager module

class raito.plugins.scenes.manager.SceneManager(router, states, data_type)

Bases: Generic[TSceneData]

A scene: the steps of a StatesGroup, its draft type, and its handlers.

Returned by raito.Router.scene(). Register handlers through the per-event registrars on_message, on_callback_query, on_edited_message — scene.on_message.enter(...) to start, scene.on_message(state, ...) / scene.on_callback_query(state, ...) for steps. A SceneMiddleware calls cleanup() before them to drop a stale scene, and each active handler receives a Scene handle that persists the draft through persist() / clear().

Parameters:

• router (Router)

• states (type[StatesGroup])

• data_type (type[TSceneData])

async cleanup(state, raw_state)

Clear the active scene if raw_state belongs to it but no longer exists.

Cheap when the update is not sitting in this scene: it returns False after a string check, without touching storage.

Parameters:

• state (FSMContext | None) – FSM context for the current chat/user, if any

• raw_state (str | None) – state aiogram already resolved for this update

Returns:

whether a stale scene was cleared

Return type:

bool

async persist(state, draft, base)

Snapshot the draft into FSM storage.

Parameters:

• state (FSMContext) – FSM context for the current chat/user

• draft (TSceneData) – draft to store

• base (dict[str, Any] | None) – FSM data already read this update, or None to read it now

Return type:

None

async clear(state, base)

Remove only this scene’s payload and reset the FSM state.

Parameters:

• state (FSMContext) – FSM context for the current chat/user

• base (dict[str, Any] | None) – FSM data already read this update, or None to read it now

Return type:

None

async begin(state, base, data, *, at=None)

Seed a fresh draft for this scene and switch to a step.

Used by Scene.start() and Scene.restart() to (re)enter a scene; it replaces whatever scene payload is currently stored under the FSM key.

Parameters:

• state (FSMContext) – FSM context for the current chat/user

• base (dict[str, Any] | None) – FSM data already read this update, or None to read it now

• data (dict[str, object]) – initial fields for the draft, validated against the SceneData

• at (State | None) – step to open at; defaults to the first step

Raises:

ValueError – if at is not a step of this scene

Return type:

None

build_handler(callback, event_name, *, entry)

Wrap a user callback into a scene handler.

The wrapper hydrates a Scene handle — a fresh draft for an entry handler, the stored one for a step handler — and injects both the event (under event_name) and scene into the callback. The step is resolved from raw_state at call time, so one wrapper serves a specific step or SceneRegistry.any().

Parameters:

• callback (CallbackType) – user handler

• event_name (str) – name the event is passed under (message, callback_query, …)

• entry (bool) – whether this handler starts the scene from a fresh draft

Returns:

the wrapped handler to register on an observer

Return type:

CallbackType