Core API¶
Error Handling¶
Configuration for error handling middleware.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/errors.py
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
use_friendly_messages = True
class-attribute
instance-attribute
¶
domain_classifier = None
class-attribute
instance-attribute
¶
message_resolver = None
class-attribute
instance-attribute
¶
locale_resolver = None
class-attribute
instance-attribute
¶
on_error = None
class-attribute
instance-attribute
¶
sync_retry_after = True
class-attribute
instance-attribute
¶
respond_strategy = 'answer'
class-attribute
instance-attribute
¶
show_alert_for_callbacks = False
class-attribute
instance-attribute
¶
send_strategy = None
class-attribute
instance-attribute
¶
Bases: BaseEvent
Event emitted when an error occurs.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/events.py
21 22 23 24 25 26 27 28 29 30 31 | |
Bases: BaseMiddleware
Middleware for centralized error handling.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/errors.py
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 | |
__call__(handler, event, data)
async
¶
Process the event through error handling middleware.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/errors.py
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | |
__init__(cfg, key_builder, rate_limiter=None)
¶
Initialize the error handling middleware.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cfg
|
ErrorConfig
|
Error configuration |
required |
key_builder
|
KeyBuilder
|
KeyBuilder instance for key generation |
required |
rate_limiter
|
RateLimiterBackend | None
|
Optional rate limiter for RetryAfter sync |
None
|
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/errors.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 | |
Policy Registry¶
Registry for managing named policies.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 | |
register(policy)
¶
Register a new policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
policy
|
Policy
|
Policy to register |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If policy name already exists |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
78 79 80 81 82 83 84 85 86 87 88 89 90 | |
get(name)
¶
Get policy by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Policy name |
required |
Returns:
| Type | Description |
|---|---|
Policy
|
Policy instance |
Raises:
| Type | Description |
|---|---|
ValueError
|
If policy not found, with suggestions |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
all()
¶
Get all registered policies in registration order.
Returns:
| Type | Description |
|---|---|
list[Policy]
|
List of all policies |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
119 120 121 122 123 124 125 | |
clear()
¶
Clear all registered policies.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
127 128 129 | |
A named policy configuration.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 | |
Configuration for throttling policy.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | |
Configuration for debouncing policy.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
35 36 37 38 39 40 41 42 43 44 45 46 47 | |
Policy registry and configuration for aiogram-sentinel.
DebounceCfg
dataclass
¶
Configuration for debouncing policy.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
35 36 37 38 39 40 41 42 43 44 45 46 47 | |
__post_init__()
¶
Validate configuration after initialization.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
44 45 46 47 | |
Policy
dataclass
¶
A named policy configuration.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 | |
__post_init__()
¶
Validate policy after initialization.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
59 60 61 62 63 64 65 66 67 68 | |
PolicyRegistry
¶
Registry for managing named policies.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 | |
__init__()
¶
Initialize empty registry.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
74 75 76 | |
all()
¶
Get all registered policies in registration order.
Returns:
| Type | Description |
|---|---|
list[Policy]
|
List of all policies |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
119 120 121 122 123 124 125 | |
clear()
¶
Clear all registered policies.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
127 128 129 | |
get(name)
¶
Get policy by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Policy name |
required |
Returns:
| Type | Description |
|---|---|
Policy
|
Policy instance |
Raises:
| Type | Description |
|---|---|
ValueError
|
If policy not found, with suggestions |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
register(policy)
¶
Register a new policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
policy
|
Policy
|
Policy to register |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If policy name already exists |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
78 79 80 81 82 83 84 85 86 87 88 89 90 | |
ThrottleCfg
dataclass
¶
Configuration for throttling policy.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | |
__post_init__()
¶
Validate configuration after initialization.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
27 28 29 30 31 32 | |
coerce_scope(scope)
¶
Coerce string scope to Scope enum with deprecation warning.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scope
|
str | Scope | None
|
String, Scope enum, or None |
required |
Returns:
| Type | Description |
|---|---|
Scope | None
|
Scope enum or None |
Raises:
| Type | Description |
|---|---|
ValueError
|
If string scope is invalid |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
convert_from_legacy_debounce(config)
¶
Convert legacy debouncing config to DebounceCfg.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
tuple[Any, ...] | dict[str, Any]
|
Legacy config tuple or dict |
required |
Returns:
| Type | Description |
|---|---|
DebounceCfg
|
DebounceCfg instance |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 | |
convert_from_legacy_throttle(config)
¶
Convert legacy throttling config to ThrottleCfg.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
tuple[Any, ...] | dict[str, Any]
|
Legacy config tuple or dict |
required |
Returns:
| Type | Description |
|---|---|
ThrottleCfg
|
ThrottleCfg instance |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | |
policy(*names)
¶
Decorator to attach policies to handlers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*names
|
str
|
Policy names to attach |
()
|
Returns:
| Type | Description |
|---|---|
Callable[[Callable[..., Any]], Callable[..., Any]]
|
Decorator function |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no policy names provided |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | |
resolve_scope(user_id, chat_id, cap)
¶
Resolve scope with cap constraint.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user_id
|
int | None
|
User identifier |
required |
chat_id
|
int | None
|
Chat identifier |
required |
cap
|
Scope | None
|
Maximum scope allowed (cap constraint) |
required |
Returns:
| Type | Description |
|---|---|
Scope | None
|
Resolved scope or None if cannot satisfy cap |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | |
Coerce string scope to Scope enum with deprecation warning.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scope
|
str | Scope | None
|
String, Scope enum, or None |
required |
Returns:
| Type | Description |
|---|---|
Scope | None
|
Scope enum or None |
Raises:
| Type | Description |
|---|---|
ValueError
|
If string scope is invalid |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
Resolve scope with cap constraint.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user_id
|
int | None
|
User identifier |
required |
chat_id
|
int | None
|
Chat identifier |
required |
cap
|
Scope | None
|
Maximum scope allowed (cap constraint) |
required |
Returns:
| Type | Description |
|---|---|
Scope | None
|
Resolved scope or None if cannot satisfy cap |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | |
Main Classes¶
Main setup class for aiogram-sentinel.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/sentinel.py
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
setup(dp, cfg, router=None, *, infra=None, error_config=None)
async
staticmethod
¶
Setup aiogram-sentinel middlewares.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dp
|
Dispatcher
|
Dispatcher instance |
required |
cfg
|
SentinelConfig
|
Configuration |
required |
router
|
Router | None
|
Optional router to use (creates new one if not provided) |
None
|
infra
|
InfraBundle | None
|
Optional infrastructure bundle (builds from config if not provided) |
None
|
error_config
|
ErrorConfig | None
|
Optional error handling configuration |
None
|
Returns:
| Type | Description |
|---|---|
tuple[Router, InfraBundle]
|
Tuple of (router, infra_bundle) |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/sentinel.py
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | |
add_hooks(router, infra, cfg, *, on_rate_limited=None)
staticmethod
¶
Update this router's owned hook without replacing any middleware.
The router, infrastructure and configuration must come from the same
successful setup call. Passing None removes the hook.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/sentinel.py
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
Configuration for aiogram-sentinel.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/config.py
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | |
throttling_default_max = 5
class-attribute
instance-attribute
¶
throttling_default_per_seconds = 10
class-attribute
instance-attribute
¶
debounce_default_window = 2
class-attribute
instance-attribute
¶
backend = 'memory'
class-attribute
instance-attribute
¶
redis_url = 'redis://localhost:6379'
class-attribute
instance-attribute
¶
redis_prefix = 'sentinel'
class-attribute
instance-attribute
¶
__init__(backend='memory', redis_url='redis://localhost:6379', redis_prefix='sentinel', throttling_default_max=5, throttling_default_per_seconds=10, debounce_default_window=2, require_registration=False, action_policies=(lambda: dict[ActionKind, ActionPolicy]())(), bucket_mode='shared', exemptions=SentinelExemptions(), engine='python')
¶
Bundle of infrastructure backends managed by the library.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/types.py
13 14 15 16 17 18 19 20 21 22 23 24 25 | |
Bases: Protocol
Protocol for rate limiting storage backend.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/base.py
10 11 12 13 14 15 16 17 18 19 20 | |
allow(key, max_events, per_seconds)
async
¶
Check if request is allowed and increment counter.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/base.py
14 15 16 | |
Composite key builder with collision-proof scheme.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | |
__init__(app, sep=':')
¶
Initialize KeyBuilder.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
app
|
str
|
Application prefix (typically from redis_prefix config) |
required |
sep
|
str
|
Key separator character |
':'
|
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
50 51 52 53 54 55 56 57 58 59 60 61 62 63 | |
for_update(parts, *, method=None, bucket=None)
¶
Build canonical key for storage/metrics with stable ordering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parts
|
KeyParts
|
Key parts containing namespace, scope, and identifiers |
required |
method
|
str | None
|
Optional method name (e.g., "sendMessage") |
None
|
bucket
|
str | None
|
Optional bucket identifier |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Canonical key string |
Raises:
| Type | Description |
|---|---|
ValueError
|
If method or bucket contain separator characters |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | |
user(namespace, user_id, **kwargs)
¶
Build key for user scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
str
|
Key namespace (e.g., "throttle", "debounce") |
required |
user_id
|
int
|
User identifier |
required |
**kwargs
|
Any
|
Additional parameters (method, bucket) |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
User-scoped key |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
145 146 147 148 149 150 151 152 153 154 155 156 | |
chat(namespace, chat_id, **kwargs)
¶
Build key for chat scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
str
|
Key namespace (e.g., "throttle", "debounce") |
required |
chat_id
|
int
|
Chat identifier |
required |
**kwargs
|
Any
|
Additional parameters (method, bucket) |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
Chat-scoped key |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
158 159 160 161 162 163 164 165 166 167 168 169 | |
group(namespace, user_id, chat_id, **kwargs)
¶
Build key for group scope (user+chat composite).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
str
|
Key namespace (e.g., "throttle", "debounce") |
required |
user_id
|
int
|
User identifier |
required |
chat_id
|
int
|
Chat identifier |
required |
**kwargs
|
Any
|
Additional parameters (method, bucket) |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
Group-scoped key |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 | |
global_(namespace, **kwargs)
¶
Build key for global scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
str
|
Key namespace (e.g., "throttle", "debounce") |
required |
**kwargs
|
Any
|
Additional parameters (method, bucket) |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
Global-scoped key |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
187 188 189 190 191 192 193 194 195 196 197 | |
Immutable key parts for consistent key generation.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | |
Bases: Enum
Scope enumeration for key generation.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/scopes.py
13 14 15 16 17 18 19 | |
Context Extractors¶
Extract user ID from event with fallbacks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
TelegramObject
|
Telegram event object |
required |
data
|
dict[str, Any]
|
Middleware data dictionary |
required |
Returns:
| Type | Description |
|---|---|
int | None
|
User ID if found, None otherwise |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/context.py
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | |
Extract chat ID from event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
TelegramObject
|
Telegram event object |
required |
data
|
dict[str, Any]
|
Middleware data dictionary |
required |
Returns:
| Type | Description |
|---|---|
int | None
|
Chat ID if found, None otherwise |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/context.py
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | |
Extract both user and chat IDs for group scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
TelegramObject
|
Telegram event object |
required |
data
|
dict[str, Any]
|
Middleware data dictionary |
required |
Returns:
| Type | Description |
|---|---|
tuple[int | None, int | None]
|
Tuple of (user_id, chat_id) |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/context.py
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 | |
Extract event type for classification.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
TelegramObject
|
Telegram event object |
required |
data
|
dict[str, Any]
|
Middleware data dictionary |
required |
Returns:
| Type | Description |
|---|---|
str
|
Event type string |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/context.py
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | |
Extract handler bucket from event and data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
TelegramObject
|
Telegram event object |
required |
data
|
dict[str, Any]
|
Middleware data dictionary |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
Handler bucket string if found, None otherwise |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/context.py
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 | |
Extract callback bucket from callback query events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
TelegramObject
|
Telegram event object |
required |
data
|
dict[str, Any]
|
Middleware data dictionary |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
Callback bucket string if found, None otherwise |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/context.py
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 | |
Middleware¶
Bases: BaseMiddleware
Middleware for rate limiting with optional notifier hook.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/throttling.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 | |
__call__(handler, event, data)
async
¶
Process the event through throttling middleware.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/throttling.py
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 | |
__init__(rate_limiter, cfg, key_builder, on_rate_limited=None)
¶
Initialize the throttling middleware.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rate_limiter
|
RateLimiterBackend
|
Rate limiter backend instance |
required |
cfg
|
SentinelConfig
|
SentinelConfig configuration |
required |
key_builder
|
KeyBuilder
|
KeyBuilder instance for key generation |
required |
on_rate_limited
|
Callable[[TelegramObject, dict[str, Any], float], Awaitable[None]] | None
|
Optional hook called when rate limit is exceeded |
None
|
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/throttling.py
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | |
Bases: BaseMiddleware
Middleware for debouncing duplicate messages with fingerprinting.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/debouncing.py
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | |
__call__(handler, event, data)
async
¶
Process the event through debouncing middleware.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/debouncing.py
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | |
__init__(debounce_backend, cfg, key_builder)
¶
Initialize the debouncing middleware.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
debounce_backend
|
DebounceBackend
|
Debounce backend instance |
required |
cfg
|
SentinelConfig
|
SentinelConfig configuration |
required |
key_builder
|
KeyBuilder
|
KeyBuilder instance for key generation |
required |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/middlewares/debouncing.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | |
Decorators¶
Decorator to set rate limit configuration on handlers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_events
|
int
|
Maximum number of events per time window |
required |
per_seconds
|
int
|
Time window in seconds |
required |
scope
|
str | None
|
Optional scope for rate limiting |
None
|
Deprecated
Use @policy() with PolicyRegistry instead. Will be removed in v2.0.0.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/decorators.py
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | |
Decorator to set debounce configuration on handlers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
window_seconds
|
int
|
Debounce window in seconds |
required |
scope
|
str | None
|
Optional scope for debouncing |
None
|
Deprecated
Use @policy() with PolicyRegistry instead. Will be removed in v2.0.0.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/decorators.py
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | |
Decorator to attach policies to handlers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*names
|
str
|
Policy names to attach |
()
|
Returns:
| Type | Description |
|---|---|
Callable[[Callable[..., Any]], Callable[..., Any]]
|
Decorator function |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no policy names provided |
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/policy.py
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | |
Utilities¶
Key Generation¶
Build rate limiting key from user ID and handler scope.
.. deprecated:: 1.1.0
Use :class:KeyBuilder instead. This function will be removed in v2.0.0.
Migration:
.. code-block:: python
# Old
key = rate_key(user_id, handler_name, **kwargs)
# New
from aiogram_sentinel import KeyBuilder
kb = KeyBuilder(app="sentinel")
key = kb.user("throttle", user_id, bucket=handler_name, **kwargs)
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/utils/keys.py
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | |
Build debounce key from user ID and handler scope.
.. deprecated:: 1.1.0
Use :class:KeyBuilder instead. This function will be removed in v2.0.0.
Migration:
.. code-block:: python
# Old
key = debounce_key(user_id, handler_name, **kwargs)
# New
from aiogram_sentinel import KeyBuilder
kb = KeyBuilder(app="sentinel")
key = kb.user("debounce", user_id, bucket=handler_name, **kwargs)
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/utils/keys.py
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | |
Create a stable fingerprint for text content.
Source code in packages/aiogram-sentinel/src/aiogram_sentinel/utils/keys.py
111 112 113 114 115 116 117 118 119 | |