Standalone navigation quickstart¶
Install the initial alpha release in your bot environment:
pip install aiogram-nav==0.3.0
# Optional persistent storage:
pip install 'aiogram-nav[redis]==0.3.0'
The package requires Python 3.10+ and aiogram 3.22 or newer in the 3.x series. It
requires neither aiogram-idle nor Redis. An optional idle integration
is available separately. Optional Redis navigation storage
is available through the redis extra.
Run the neutral demo¶
From the checkout:
uv sync --python 3.12
uv run python examples/demo.py --help
Set BOT_TOKEN in the environment before running a bot, then choose a style:
uv run python -m examples.reply_only.main
uv run python -m examples.inline_only.main
uv run python -m examples.commands_only.main
uv run python -m examples.hybrid.main --fsm
The same application also accepts --style reply, --style inline,
--style commands or --style hybrid through examples/demo.py. --fsm puts the
sample draft in application-owned FSM storage instead of its plain dictionary.
Both stores are memory-only and disappear when the process restarts.
Send /start to install the initial screen. Open a panel, go Back, open the draft
editor and enter sample text. Back preserves the draft; Cancel calls the explicit
application hook that discards it. /status reports node/revision metadata and the
saved character count, without logging draft content. The command-only variant
uses /panel, /edit, /back, /home, /cancel and /refresh. /start is the
bootstrap command for every variant.
Examples enable safe development logging only in their CLI entry point. Constructing
build_demo(bot, args) does not poll Telegram or make network calls. The library
does not configure logging globally and never reads BOT_TOKEN itself.
Connect an application¶
- Register roots and immutable nodes with stable IDs and renderer keys.
- Construct a
MemoryNavigationRepository, a presenter andNavigation. - Bind only the commands, reply labels and inline actions your application wants.
- Install navigation before including business routers.
- In handlers, use the injected
nav_context; record accepted draft input withtouch(), rather than treating every received update as activity.
See concepts, the public API, and migration for the responsibilities at each boundary.