Skip to main content

aiogram-idle

Standalone inactivity policies for aiogram 3, with typed session/activity contracts and memory or optional Redis storage. Add Continue/Cancel questions or quiet cleanup to ordinary handlers and FSM conversations without adopting a navigation framework.

Version 0.2.0 supports Python 3.10+ and aiogram 3.22 or newer within the 3.x series.

Compatibility

Component Supported / tested
Python 3.10–3.14 in CI
aiogram 3.22.0 minimum; latest resolvable 3.x
Redis server 7 and 8, single writable primary, noeviction
redis-py extra >=5.0.8,<8; minimum/current in CI
aiogram-coordination >=0.1.0,<0.2; required, Redis optional
aiogram-nav extra >=0.2.0,<0.3; never installed by the base package

Minimum aiogram is tested on Python 3.10–3.13; Python 3.14 uses current aiogram because historical dependency wheels do not support it. See testing for actual local evidence versus configured CI.

Application-owned integration in 0.2

Use ActivityRegistration and idle_context.activate(...) to enter a flow without constructing snapshots. An optional read-only SessionAuthority binds activity to an existing application session after explicit storage-format activation. Public tracked isolation supports verified application locks without replacing FSM storage. The application integration guide and 0.2 migration explain setup, authority failures, manual navigation routing and staged activation.

Install

python -m pip install aiogram-idle==0.2.0
# Optional standalone Redis backend:
python -m pip install 'aiogram-idle[redis]==0.2.0'
# Optional navigation integration, with or without Redis:
python -m pip install 'aiogram-idle[nav]==0.2.0'
python -m pip install 'aiogram-idle[nav,redis]==0.2.0'

The core runtime dependency is aiogram 3. Redis and aiogram-nav are not installed by the base package. The Redis backend requires Redis 7 or newer.

See Redis setup and recovery. The optional aiogram-nav integration is available through [nav] or [nav,redis]; neither base nor Redis-only installs require navigation.

Run the examples

Clone the repository to run its examples, install the frozen development requirements with uv sync --frozen --python 3.12, then set BOT_TOKEN in your environment and choose the prompt controls:

uv run --no-sync python examples/demo.py --controls reply
uv run --no-sync python examples/demo.py --controls inline
uv run --no-sync python examples/demo.py --controls commands
uv run --no-sync python examples/demo.py --controls hybrid
uv run --no-sync python examples/demo.py --controls inline --fsm

/draft starts the sample activity. Accepted text updates its draft and resets inactivity. After the configured delay, the bot asks whether to continue. Continue preserves the draft; Cancel or grace expiry runs the application's abandonment and restoration adapters. /status reports safe current lifecycle state. Use --after and --grace to adjust the demonstration intervals.

The examples configure safe debug logging and read the token only from the environment. They send real Telegram messages when run with a token; automated tests use a fake bot session instead.

How it fits

  1. Define named ExemptPolicy, PromptPolicy or QuietRestorePolicy values.
  2. Supply application inspect, resume, abandon and restore adapters.
  3. Construct IdleRuntime with MemoryIdleBackend or RedisIdleBackend and a presenter.
  4. Install its context middleware and controls on a dispatcher.
  5. Explicitly enter an activity or touch it after accepted input.

Activity keys are opaque application labels, not navigation nodes. Draft storage and business rules stay in the application. Inactivity creation is disabled by default; examples explicitly enable it.

See the standalone guide for contracts and integration details, and failure semantics for the recovery boundaries.

Guarantees and limits

  • Memory storage is for one event loop in one process and loses all state, deadlines and recovery receipts on restart.
  • Generation guards and conditional transitions protect current activity state. They do not create a transaction with an application database or Telegram.
  • Explicit operation IDs identify logical substeps. Reusing one ID with different inputs is an error.
  • Inline controls bind to a prompt generation. Reply text and bare commands resolve only the current authorized prompt and cannot identify an older originating prompt.
  • Unknown Telegram responses are not blindly resent by default. A lease cannot retract an already in-flight request.
  • Silent Telegram messages can still notify without sound.
  • Redis storage supports coordinated multi-process workers on a standalone writable primary with noeviction. Infrastructure persistence and replication determine durability; there is no memory fallback.
  • Private chats are the initial supported presentation context. The optional navigation adapter is available separately. External session stores, Redis Cluster and a durable analytics outbox remain deferred.

See the Redis concurrency and FSM audit for the latest corrected failure paths, and the memory audit for adapter replay requirements.

Development

uv sync --frozen --extra redis
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync pyright
AIOGRAM_IDLE_REDIS_URL=redis://localhost:6379/0 AIOGRAM_IDLE_REQUIRE_REDIS=1 uv run --no-sync pytest --cov=aiogram_idle --cov-report=term-missing
uv build
uv run --no-sync twine check dist/*

CI tests Python 3.10–3.14 with the latest resolvable aiogram 3 release, and aiogram 3.22.0 on Python 3.10–3.13. The minimum aiogram endpoint pins dependencies predating Python 3.14 support, so that combination is excluded. CI then builds and installs artifacts in clean environments. It has no publishing or deployment step.

See local verification results for the tested matrix and deferred capabilities.

See installation, API contracts, architecture and testing for contributor guidance. CI also requires strict documentation and security checks and runs a separate optional-navigation job; standalone jobs remain navigation-free. Dependency auditing uses Python 3.11+; CI uses 3.12.

Read CONTRIBUTING.md, SECURITY.md and the code of conduct. Maintainers use the release checklist; a repository push does not publish.

License

MIT. See LICENSE.

For a source checkout, use uv sync --frozen and uv run --no-sync .... Selecting the nav extra resolves published dependencies; adjacent peer checkouts are not required. See installation for explicit joint-development overrides.

Metadata

Release files for aiogram-idle 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiogram-idle 0.2.1
File Size Uploaded Provenance Actions
aiogram_idle-0.2.1.tar.gz 437.1 kB With provenance Details for aiogram_idle-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiogram-idle 0.2.1
File Interpreter ABI Platform Actions
aiogram_idle-0.2.1-py3-none-any.whl Python 3 none any Details for aiogram_idle-0.2.1-py3-none-any.whl

Total release size: 563.9 kB

Release files / aiogram_idle-0.2.1.tar.gz

Download URL aiogram_idle-0.2.1.tar.gz
Size 437.1 kB
Tags Source
SHA-256 checksum
How to use checksums
11394d924b44f78daad04a49ff52a83892eb28da401c88300f7fe66f56d7b57f
BLAKE2b-256 checksum
How to use checksums
38cd64ffe4864c419f8acff43862a2393501eb1dc037d8a21d85f3c38e539cb6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / aiogram_idle-0.2.1-py3-none-any.whl

Download URL aiogram_idle-0.2.1-py3-none-any.whl
Size 126.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
02d05bebc398751e4819e5d868bbf0529d7376c5d9e57cc9ddbff25173e2dc1f
BLAKE2b-256 checksum
How to use checksums
6d999ec7205a34cc4e49aba7509e14eb9504f4446409ef60641cfdfcbfd582d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for aiogram-idle 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiogram_idle-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page