Metadata-Version: 2.4
Name: modern-di
Version: 4.1.0
Summary: Powerful dependency-injection framework with IoC container and scopes
Keywords: dependency-injection,di,ioc-container,scopes,mocks,python,asyncio,modern-di
Author: Artur Shiriev
Author-email: Artur Shiriev <me@shiriev.ru>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: Free Threading :: 2 - Beta
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11, <4
Project-URL: Homepage, https://modern-di.modern-python.org
Project-URL: Documentation, https://modern-di.modern-python.org
Project-URL: Repository, https://github.com/modern-python/modern-di
Project-URL: Issues, https://github.com/modern-python/modern-di/issues
Project-URL: Changelog, https://github.com/modern-python/modern-di/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/lockup-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/modern-di/lockup-light.svg">
    <img alt="modern-di" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/modern-di/lockup.png" width="420">
  </picture>
</p>

[![GitHub stars](https://img.shields.io/github/stars/modern-python/modern-di)](https://github.com/modern-python/modern-di/stargazers)
[![Context7](https://img.shields.io/badge/Context7-docs-blue)](https://context7.com/modern-python/modern-di)
[![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)

| Project                                                                       | Badges                                                                                                                                                                                                                                                                 |
|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| modern-di                                                                     | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di.svg)](https://pypi.python.org/pypi/modern-di) [![downloads](https://static.pepy.tech/badge/modern-di/month)](https://pepy.tech/projects/modern-di)                                             |
| [modern-di-aiogram](https://github.com/modern-python/modern-di-aiogram)       | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-aiogram.svg)](https://pypi.python.org/pypi/modern-di-aiogram) [![downloads](https://static.pepy.tech/badge/modern-di-aiogram/month)](https://pepy.tech/projects/modern-di-aiogram)             |
| [modern-di-aiohttp](https://github.com/modern-python/modern-di-aiohttp)       | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-aiohttp.svg)](https://pypi.python.org/pypi/modern-di-aiohttp) [![downloads](https://static.pepy.tech/badge/modern-di-aiohttp/month)](https://pepy.tech/projects/modern-di-aiohttp)             |
| [modern-di-arq](https://github.com/modern-python/modern-di-arq)               | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-arq.svg)](https://pypi.python.org/pypi/modern-di-arq) [![downloads](https://static.pepy.tech/badge/modern-di-arq/month)](https://pepy.tech/projects/modern-di-arq)                             |
| [modern-di-celery](https://github.com/modern-python/modern-di-celery)         | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-celery.svg)](https://pypi.python.org/pypi/modern-di-celery) [![downloads](https://static.pepy.tech/badge/modern-di-celery/month)](https://pepy.tech/projects/modern-di-celery)                 |
| [modern-di-fastapi](https://github.com/modern-python/modern-di-fastapi)       | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-fastapi.svg)](https://pypi.python.org/pypi/modern-di-fastapi) [![downloads](https://static.pepy.tech/badge/modern-di-fastapi/month)](https://pepy.tech/projects/modern-di-fastapi)             |
| [modern-di-fastmcp](https://github.com/modern-python/modern-di-fastmcp)       | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-fastmcp.svg)](https://pypi.python.org/pypi/modern-di-fastmcp) [![downloads](https://static.pepy.tech/badge/modern-di-fastmcp/month)](https://pepy.tech/projects/modern-di-fastmcp)             |
| [modern-di-faststream](https://github.com/modern-python/modern-di-faststream) | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-faststream.svg)](https://pypi.python.org/pypi/modern-di-faststream) [![downloads](https://static.pepy.tech/badge/modern-di-faststream/month)](https://pepy.tech/projects/modern-di-faststream) |
| [modern-di-flask](https://github.com/modern-python/modern-di-flask)           | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-flask.svg)](https://pypi.python.org/pypi/modern-di-flask) [![downloads](https://static.pepy.tech/badge/modern-di-flask/month)](https://pepy.tech/projects/modern-di-flask)                     |
| [modern-di-grpc](https://github.com/modern-python/modern-di-grpc)             | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-grpc.svg)](https://pypi.python.org/pypi/modern-di-grpc) [![downloads](https://static.pepy.tech/badge/modern-di-grpc/month)](https://pepy.tech/projects/modern-di-grpc)                         |
| [modern-di-litestar](https://github.com/modern-python/modern-di-litestar)     | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-litestar.svg)](https://pypi.python.org/pypi/modern-di-litestar) [![downloads](https://static.pepy.tech/badge/modern-di-litestar/month)](https://pepy.tech/projects/modern-di-litestar)         |
| [modern-di-pytest](https://github.com/modern-python/modern-di-pytest)         | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-pytest.svg)](https://pypi.python.org/pypi/modern-di-pytest) [![downloads](https://static.pepy.tech/badge/modern-di-pytest/month)](https://pepy.tech/projects/modern-di-pytest)                 |
| [modern-di-starlette](https://github.com/modern-python/modern-di-starlette)   | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-starlette.svg)](https://pypi.python.org/pypi/modern-di-starlette) [![downloads](https://static.pepy.tech/badge/modern-di-starlette/month)](https://pepy.tech/projects/modern-di-starlette)     |
| [modern-di-taskiq](https://github.com/modern-python/modern-di-taskiq)         | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-taskiq.svg)](https://pypi.python.org/pypi/modern-di-taskiq) [![downloads](https://static.pepy.tech/badge/modern-di-taskiq/month)](https://pepy.tech/projects/modern-di-taskiq)                 |
| [modern-di-typer](https://github.com/modern-python/modern-di-typer)           | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-typer.svg)](https://pypi.python.org/pypi/modern-di-typer) [![downloads](https://static.pepy.tech/badge/modern-di-typer/month)](https://pepy.tech/projects/modern-di-typer)                     |

`modern-di` is a dependency injection container for Python 3.11+. You declare how each object is
built, and the container builds it, fills its constructor from type annotations, keeps it for as
long as its scope lives, and runs its teardown when that scope closes.

- Constructor parameters are matched by type, and you can pass explicit arguments where a type is
  ambiguous.
- Scopes (APP, REQUEST and finer ones) decide how long a cached object lives, and finalizers close
  it when its scope ends.
- `container.validate()` finds cycles and scope errors at startup instead of on the first request.
- One override replaces a dependency for the whole container tree, so HTTP handlers, workers and
  direct unit tests all see the same fake.
- Typed end to end, with no type-checker plugin.
- Integrations for aiogram, aiohttp, arq, Celery, FastAPI, FastMCP, FastStream, Flask, gRPC,
  Litestar, Starlette, taskiq and Typer, plus a pytest plugin.

## Install

```bash
uv add modern-di      # or: pip install modern-di
```

## Quick start

```python
import dataclasses
from modern_di import Container, Group, Scope, providers


@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
class Settings:
    database_url: str = "postgresql+asyncpg://localhost/app"


@dataclasses.dataclass(kw_only=True, slots=True)
class UserRepository:
    settings: Settings  # auto-injected by type


class Dependencies(Group):
    settings = providers.Factory(Settings, scope=Scope.APP)
    user_repository = providers.Factory(UserRepository, scope=Scope.REQUEST)


with Container(groups=[Dependencies]) as container:
    with container.build_child_container(scope=Scope.REQUEST) as request:
        repo = request.resolve(UserRepository)
        print(repo.settings.database_url)
```

See the [documentation](https://modern-di.modern-python.org) for scopes, lifecycles, finalizers, and framework integrations. `modern-di` is deliberately conservative; see [Design decisions](https://modern-di.modern-python.org/introduction/design-decisions/) for what it leaves out on purpose, including auto-binding, in-package integrations, and graph rendering.

Usage examples:

- with Litestar: [litestar-sqlalchemy-template](https://github.com/modern-python/litestar-sqlalchemy-template)
- with FastAPI: [fastapi-sqlalchemy-template](https://github.com/modern-python/fastapi-sqlalchemy-template)

## 📚 [Documentation](https://modern-di.modern-python.org)

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

## 📝 [License](https://github.com/modern-python/modern-di/blob/main/LICENSE)

## Part of `modern-python`

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