Skip to main content

aiogram-coordination

Shared task-scoped ownership for aiogram applications and independent libraries. The package has no dependency on aiogram-idle, aiogram-nav or aiogram-kit.

Initial alpha version: 0.1.0. Requires Python 3.10+ and aiogram 3.22–3.x.

pip install aiogram-coordination==0.1.0
# Optional renewable Redis coordination:
pip install 'aiogram-coordination[redis]==0.1.0'

Memory coordination

from aiogram_coordination import CoordinationKey, MemoryCoordinator

coordinator = MemoryCoordinator()
key = CoordinationKey("bot", bot_id=123, chat_id=42, user_id=42)


async def protected_operation():
    async with coordinator.hold(key):
        scope = coordinator.scope_token(key)
        assert scope is not None
        # Invoke application code only while this task owns the scope.

Memory scopes serialize one process and one event loop. A child task does not inherit reentrant ownership. Identical structural conversation keys from independent libraries normalize to one full identity; arbitrary generic Hashable keys remain supported by the memory coordinator.

Existing application FSM isolation

Wrap isolation explicitly when constructing the Dispatcher, not after startup:

from aiogram import Dispatcher
from aiogram.fsm.storage.memory import SimpleEventIsolation
from aiogram_coordination import TrackedEventIsolation

application_isolation = SimpleEventIsolation()
tracked = TrackedEventIsolation(application_isolation)
dispatcher = Dispatcher(events_isolation=tracked)

A custom application isolation requires an explicit IsolationProvider tied to the exact same instance. It must return a key-bound, live LeaseHandle and signal loss. Unknown opaque locks, disabled isolation and unsupported proof are rejected. Custom isolation includes the contract and Redis reference.

Redis reference

from aiogram_coordination import RenewableRedisEventIsolation, TrackedEventIsolation

# application_redis is an existing redis.asyncio client owned by your app.
application_isolation = RenewableRedisEventIsolation(redis=application_redis)
tracked = TrackedEventIsolation(application_isolation)

This explicit renewable provider exposes ownership; it does not pretend to renew an opaque aiogram RedisEventIsolation lock. It reuses the caller's Redis client and public aiogram key builder. Client closure remains application-owned.

Use RedisCoordinator(redis=application_redis, prefix="application") for fenced conversation storage coordination. Its default lease/renew/wait/poll/I/O limits are 30/10/30/0.05/5 seconds. Lost leases revoke effect authority and cancel owners. A Lua storage transaction must check the returned fence token and positive PTTL; a local ownership check cannot make an external API transactional.

External sessions

SessionAuthority.current(key) returns an immutable ExternalSession or None. It reads only; it never creates, extends or clears application sessions. Outages raise SessionAuthorityUnavailable and are distinct from missing authorization. Session rules separate immutable absolute lifetime from a sliding application inactivity deadline.

Compatibility and verification

Component Supported / CI targets
Python 3.10–3.14
aiogram 3.22 minimum and latest resolvable 3.x
Redis client 5.0.8 minimum and latest below 8, optional
Redis server 7+ single writable primary; CI uses real Redis 7 and 8
Base install Neither Redis nor Idle/Nav/Kit is required

CI exercises installed wheels/sdists, task isolation, real Redis renewal/loss and process death. Verification evidence distinguishes executed checks from configured jobs. CONTRIBUTING.md documents commands, SECURITY.md reporting and release guidance the explicit tag-only publication procedure. Nothing configures logging globally on import. The CLI example enables only scoped development debug logging.

MIT licensed; see LICENSE.

Metadata

Release files for aiogram-coordination 0.1.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-coordination 0.1.0
File Size Uploaded Provenance Actions
aiogram_coordination-0.1.0.tar.gz 257.5 kB With provenance Details for aiogram_coordination-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiogram-coordination 0.1.0
File Interpreter ABI Platform Actions
aiogram_coordination-0.1.0-py3-none-any.whl Python 3 none any Details for aiogram_coordination-0.1.0-py3-none-any.whl

Total release size: 278.6 kB

Release files / aiogram_coordination-0.1.0.tar.gz

Download URL aiogram_coordination-0.1.0.tar.gz
Size 257.5 kB
Tags Source
SHA-256 checksum
How to use checksums
775ed78a71a51fc862b7394cd00a7ca6ca4a11013bb7c286e57e2b059f5471b1
BLAKE2b-256 checksum
How to use checksums
924e16d6b97b482201bf930799777ee4a8c17b8414610f503ed2d005fdad6221
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_coordination-0.1.0-py3-none-any.whl

Download URL aiogram_coordination-0.1.0-py3-none-any.whl
Size 21.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c3b44457924a327adf40963abcb5b6d22618539fe7968216df74b524c99f3da4
BLAKE2b-256 checksum
How to use checksums
f5391b507749cea1a8860a478c13daf20dea619290cb4a152e14f0d22e9b3298
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-coordination 0.1.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_coordination-0.1.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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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