The repository or configuration that created this release differ from a previous release. View details.
aiogram-idle
Source development and releases are maintained in the aiogram-kit monorepo. See the workspace contributing guide; package examples live under packages/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.3.1 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.3.0,<0.4; 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.
Format 3 and optional native engine
Version 0.3 adds explicit storage_format=3 for fresh backends, individual Redis
receipt TTLs, bounded recovery and a canonical optional navigation ledger. Existing
namespaces require drained, verified migration. Python remains the default engine;
Rust is an explicitly selected, separately built companion with no runtime fallback.
See migration, replay retention and engine selection.
The recorded 0.3.0 native CPU gate failed (Rust used about 6.6% more CPU on the selected
representative workload). The native companion remains source-only: no native PyPI
release, tag or extra is provided. Keep the default Python engine.
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.3.1
# Optional standalone Redis backend:
python -m pip install 'aiogram-idle[redis]==0.3.1'
# Optional navigation integration, with or without Redis:
python -m pip install 'aiogram-idle[nav]==0.3.1'
python -m pip install 'aiogram-idle[nav,redis]==0.3.1'
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
- Define named
ExemptPolicy,PromptPolicyorQuietRestorePolicyvalues. - Supply application
inspect,resume,abandonandrestoreadapters. - Construct
IdleRuntimewithMemoryIdleBackendorRedisIdleBackendand a presenter. - Install its context middleware and controls on a dispatcher.
- 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.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Change of provenance
The repository or configuration that created these release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiogram_idle-0.3.1.tar.gz | 552.9 kB | With provenance | Details for aiogram_idle-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiogram_idle-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for aiogram_idle-0.3.1-py3-none-any.whl |
Total release size: 752.2 kB
Release files / aiogram_idle-0.3.1.tar.gz
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | aiogram_idle-0.3.1.tar.gz |
|---|---|
| Size | 552.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fefac3d5aedf1116f51b814051aeb6c23ce4bdb787133c13b30d21dd334c3c98
|
|
BLAKE2b-256 checksum How to use checksums |
e28230c9931e5a43449fca93784ce0816632c69f8307fd9e482a0b3a075f017d
|
| 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 11, 2026.
Transparency logRelease files / aiogram_idle-0.3.1-py3-none-any.whl
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | aiogram_idle-0.3.1-py3-none-any.whl |
|---|---|
| Size | 199.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0653e9a3ba8523de428768cb711effa207243cc609e89bc80b36c5a2d8c11b13
|
|
BLAKE2b-256 checksum How to use checksums |
6d30f67f44199f162e7b293c14999b295f607fac1d57e72d129881cfb7ee3e81
|
| 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 11, 2026.
Transparency logSecurity for aiogram-idle 0.3.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.
Change of provenance
The repository and configuration that created this release differ from a previous release.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Repository
- Removed 0.3.0 github.com/ArmanAvanesyan/aiogram-idle
- Added 0.3.1 github.com/ArmanAvanesyan/aiogram-kit
Attestation for aiogram_idle-0.3.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 11, 2026.
Transparency logA 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.