modern-di-aiogram 4.2.0

modern-di integration for aiogram 3.x.

Full guide: aiogram integration docs

Usage example: examples/

Installation

uv add modern-di-aiogram      # or: pip install modern-di-aiogram

Usage

aiogram has no dependency-injection system of its own, so modern-di-aiogram pairs an @inject decorator with inert FromDI markers (or auto_inject=True to skip the decorator entirely). By default setup_di opens the root container on dispatcher startup, closes it on shutdown, and installs an outer middleware that builds a per-update Scope.REQUEST child container automatically.

import typing

from aiogram import Dispatcher
from aiogram.types import Message
from modern_di import Container, Group, Scope, providers
from modern_di_aiogram import FromDI, inject, setup_di


class Settings:
    def __init__(self) -> None:
        self.greeting = "hello"


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)


dispatcher = Dispatcher()
container = Container(groups=[AppGroup])
setup_di(dispatcher, container)
container.validate()  # optional fail-fast; must come after setup_di registers its providers


@dispatcher.message()
@inject
async def greet(
    message: Message,
    settings: typing.Annotated[Settings, FromDI(AppGroup.settings)],
) -> None:
    await message.answer(f"{settings.greeting}, {message.from_user.first_name}")

Pass auto_inject=True to setup_di to wrap every handler already registered on the dispatcher, so individual handlers don't need @inject. Register handlers before startup for this to take effect. Sync handlers work with both @inject and auto_inject: aiogram runs them in a worker thread as usual, and their FromDI parameters resolve from the same per-update child container. The current aiogram.types.Update and the concrete event it carries (Message, CallbackQuery, and so on) are resolvable within DI via the pre-built aiogram_update_provider / aiogram_event_provider context providers. aiogram-dialog getters and callbacks are supported via modern_di_aiogram.dialog; see the docs.

Sharing a container

When one container serves several apps, for example a bot and a web API in the same process, exactly one owner should open and close it. Pass manage_lifespan=False so the dispatcher leaves the root container alone, and open it yourself around running the apps:

setup_di(dispatcher, container, manage_lifespan=False)

async with container:
    await dispatcher.start_polling(bot)

Each update still gets its own Scope.REQUEST child container, closed when the update is handled. APP-scoped finalizers run once, when the async with block exits.

API

📦 PyPI

📝 License

Part of modern-python

Built on modern-di, a dependency-injection framework with an IoC container and scopes.

Browse the full list of templates and libraries in modern-python; the org profile has the categorized index.