Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

aiogram-sentinel

Source development and releases are maintained in the aiogram-kit monorepo. See the workspace contributing guide; package examples live under packages/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.

Native companion: publication withheld

The source includes optional engine="rust" memory infrastructure, but the native companion remains withheld for 1.3.1: serial qualification of the 1.3.0 kernels measured 11.65% and 7.63% CPU reductions in the selected workloads, below the required 20%. Latency measurements were unstable, so no tail-latency gain is claimed. Python remains the default and the optimized base package can ship independently. There is no native release or [native] extra; the core remains available from source. See the host-specific benchmark decision and engine selection and semantics.

Metadata

Release files for aiogram-sentinel 1.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)

Source distribution for aiogram-sentinel 1.3.1
File Size Uploaded Provenance Actions
aiogram_sentinel-1.3.1.tar.gz 355.9 kB With provenance Details for aiogram_sentinel-1.3.1.tar.gz

Built distribution (wheel)

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

Total release size: 395.9 kB

Release files / aiogram_sentinel-1.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_sentinel-1.3.1.tar.gz
Size 355.9 kB
Tags Source
SHA-256 checksum
How to use checksums
252eef06f0282b46991faa3ca1eb9861f3ec2eefaa7be0ffa0e994c439ac9d60
BLAKE2b-256 checksum
How to use checksums
4bd40fcb259bfca69913b748f6d2e6cc4ca41d68ed35ed16b6461987e322d7df
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 log

Release files / aiogram_sentinel-1.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_sentinel-1.3.1-py3-none-any.whl
Size 40.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c97a7fefb617bd27a413a1c624581976b70807f7000caac1d2d4cdd42779ce5d
BLAKE2b-256 checksum
How to use checksums
c8a339ec75a54ada4f737f1c1d4c6142014f721e18f0334fd608152782f17c85
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 log

Security for aiogram-sentinel 1.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.

Select from 2 files

Attestation for aiogram_sentinel-1.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 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