Skip to main content

aiogram-sentinel

Rate limiting and debouncing for aiogram 3. Sentinel protects handlers on its router and descendant routers while retaining application authorization middleware.

Install

pip install aiogram-sentinel
# Optional shared Redis storage:
pip install 'aiogram-sentinel[redis]'

Protect an application router

from aiogram import Dispatcher, Router
from aiogram_sentinel import ActionPolicy, Sentinel, SentinelConfig, ThrottleCfg

app = Router()
features = Router()
app.include_router(features)
# Register application handlers on features or app, then during async startup:
dp = Dispatcher()
router, infra = await Sentinel.setup(
    dp,
    SentinelConfig(
        bucket_mode="action_kind",
        action_policies={
            "message": ActionPolicy(throttle=ThrottleCfg(rate=5, per=10)),
            "command": ActionPolicy(throttle=ThrottleCfg(rate=3, per=10)),
            "callback_query": ActionPolicy(throttle=ThrottleCfg(rate=20, per=10)),
        },
    ),
    router=app,
)

These rates are examples, not new defaults. bucket_mode="shared" remains the default, with the existing limit of 5 events per 10 seconds and 2-second debounce. A command is a message with an initial Telegram bot_command entity. Command, message and callback namespaces are distinct only when explicitly requested.

Attachment matters: middleware on a sibling router does not wrap another router's handlers. Pass the application's ancestor router to setup, or register handlers on the returned router. Startup warns once when its protected subtree has no message/callback handlers. Do not attach the router to the Dispatcher before calling setup.

Named handler policies and legacy decorators now resolve the registered aiogram callback, including on aiogram 3.31. See configuration for precedence and explicit /start or callback-prefix exemptions. Exemptions bypass only Sentinel spam protections, never application guards.

Infrastructure failures

ErrorConfig(reraise_exceptions=(TimeoutError,)) propagates matching exceptions unchanged instead of sending friendly feedback. Add redis.exceptions.RedisError when using Redis, and aiogram_sentinel.exceptions.BackendOperationError for failures wrapped by Sentinel storage. This alone does not select an HTTP status: Dispatcher error handlers must re-raise, and a foreground webhook adapter must map the failure to 503. Background acknowledgement cannot be changed retroactively.

See the application integration guide for existing-client ownership, middleware/error ordering and the webhook recipe.

Compatibility and verification

Component Supported/tested contract
Python 3.10–3.13 in required CI
aiogram >=3.0,<4; minimum 3.0 and current 3.x tested
redis-py Optional >=5.0.8,<8; minimum/current endpoints tested
Redis server 7 and 8 tested; older servers are not qualified
Memory storage Single process/event loop; sliding-window rate limiter
Redis storage Shared clients; fixed-window counter with atomic expiry

Redis rate limiting requires EVAL, INCR, TTL, EXPIRE, GET; debounce requires SET with NX/EX. The middleware's retry-after lookup also uses TTL. No INFO, ROLE or CONFIG privileges are required by Sentinel. Availability, eviction and persistence remain deployment responsibilities; Sentinel does not provide Idle/Nav scheduling or durable business-effect recovery.

The library never configures logging globally. Examples enable scoped debug output and use recording Telegram sessions in tests; no real messages are sent by tests.

Metadata

Release files for aiogram-sentinel 1.2.0

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-sentinel 1.2.0
File Size Uploaded Provenance Actions
aiogram_sentinel-1.2.0.tar.gz 291.3 kB With provenance Details for aiogram_sentinel-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiogram-sentinel 1.2.0
File Interpreter ABI Platform Actions
aiogram_sentinel-1.2.0-py3-none-any.whl Python 3 none any Details for aiogram_sentinel-1.2.0-py3-none-any.whl

Total release size: 329.0 kB

Release files / aiogram_sentinel-1.2.0.tar.gz

Download URL aiogram_sentinel-1.2.0.tar.gz
Size 291.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bc06a19db3718fb5869dcc82cf5699cfd3162478b7929db59afc17ae64b22c36
BLAKE2b-256 checksum
How to use checksums
1ee2020f9a1073c2c448944f3f6b1ac2069bd5281a810bb67b4f443b1fb2ee8d
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_sentinel-1.2.0-py3-none-any.whl

Download URL aiogram_sentinel-1.2.0-py3-none-any.whl
Size 37.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ee5851a1a96933db6177fc8309268505eceb689cbc3c9d455be4560c06fa42c8
BLAKE2b-256 checksum
How to use checksums
0e7df22b2b9da25dfd5703cfa4450c95d34297bbd2e5027d3b897bbc4820a01e
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-sentinel 1.2.0

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_sentinel-1.2.0.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