Metadata-Version: 2.4
Name: modern-di-aiogram
Version: 3.0.0
Summary: modern-di integration for aiogram
Keywords: dependency-injection,di,ioc-container,modern-di,aiogram,telegram,python
Author: Artur Shiriev
Author-email: Artur Shiriev <me@shiriev.ru>
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: aiogram>=3.2,<4
Requires-Dist: modern-di>=3,<4
Requires-Python: >=3.10, <4
Project-URL: Homepage, https://modern-di.modern-python.org
Project-URL: Documentation, https://modern-di.modern-python.org/integrations/aiogram/
Project-URL: Repository, https://github.com/modern-python/modern-di-aiogram
Project-URL: Issues, https://github.com/modern-python/modern-di-aiogram/issues
Project-URL: Changelog, https://github.com/modern-python/modern-di-aiogram/releases
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/modern-di-aiogram/lockup-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/modern-di-aiogram/lockup-light.svg">
    <img alt="modern-di-aiogram" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/modern-di-aiogram/lockup.png" width="420">
  </picture>
</p>

[![PyPI version](https://img.shields.io/pypi/v/modern-di-aiogram.svg)](https://pypi.org/project/modern-di-aiogram/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/modern-di-aiogram.svg)](https://pypi.org/project/modern-di-aiogram/)
[![Downloads](https://static.pepy.tech/badge/modern-di-aiogram/month)](https://pepy.tech/projects/modern-di-aiogram)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/modern-di-aiogram/actions/workflows/ci.yml)
[![CI](https://github.com/modern-python/modern-di-aiogram/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/modern-di-aiogram/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/modern-python/modern-di-aiogram.svg)](https://github.com/modern-python/modern-di-aiogram/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/modern-python/modern-di-aiogram)](https://github.com/modern-python/modern-di-aiogram/stargazers)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)

[Modern-DI](https://github.com/modern-python/modern-di) integration for [aiogram](https://docs.aiogram.dev) 3.x.

Full guide: [aiogram integration docs](https://modern-di.modern-python.org/integrations/aiogram/)

## Installation

```bash
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). `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.

```python
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()
setup_di(dispatcher, Container(groups=[AppGroup], validate=True))


@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. The current `aiogram.types.Update` and the concrete event it carries (`Message`, `CallbackQuery`, …) are resolvable within DI via the pre-built `aiogram_update_provider` / `aiogram_event_provider` context providers. [aiogram-dialog](https://github.com/Tishka17/aiogram_dialog) getters and callbacks are supported via `modern_di_aiogram.dialog` — see the docs.

## API

| Symbol | Description |
|---|---|
| `setup_di(dispatcher, container, *, auto_inject=False)` | Stores the container on the dispatcher, registers the update/event providers, wires `dispatcher.startup`/`dispatcher.shutdown` to open/close it, and installs the per-update middleware. With `auto_inject=True`, also wraps every handler already registered at startup |
| `FromDI(dependency)` | Inert marker (used with `@inject`) that resolves a provider or type from the per-update child container |
| `inject(handler)` | Decorator for an aiogram handler; resolves its `FromDI`-annotated parameters. Not needed when `setup_di(..., auto_inject=True)` is used |
| `fetch_di_container(dispatcher)` | Returns the root `Container` stored on the dispatcher |
| `aiogram_update_provider` | `ContextProvider` for the current `aiogram.types.Update` (`REQUEST` scope) |
| `aiogram_event_provider` | `ContextProvider` for the current `aiogram.types.TelegramObject` (`REQUEST` scope) — the concrete event unwrapped from the `Update` |

## 📦 [PyPI](https://pypi.org/project/modern-di-aiogram)

## 📝 [License](LICENSE)

## Part of `modern-python`

Built on [`modern-di`](https://github.com/modern-python/modern-di), a dependency-injection framework with IoC container and scopes.

Browse the full list of templates and libraries in
[`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.
