Skip to main content

ADC AppKit

Компонентная архитектура для async Python приложений: декларативные компоненты, dependency injection, request scope.

Install

pip install adc-appkit

Quick start

import asyncio
from adc_appkit import BaseApp, component
from adc_appkit.components.component import Component

class Database:
    def __init__(self, host: str, port: int):
        self.host = host
        self.port = port

    async def close(self):
        pass

class DatabaseComponent(Component[Database]):
    async def _start(self, host: str, port: int, **kw) -> Database:
        return Database(host, port)

    async def _stop(self) -> None:
        await self.obj.close()

class App(BaseApp):
    db = component(DatabaseComponent, config_key="db")

async def main():
    app = App(components_config={"db": {"host": "localhost", "port": 5432}})
    await app.start()

    # дескриптор возвращает объект напрямую
    print(app.db.host)  # "localhost"

    health = await app.healthcheck()  # {"db": True}
    await app.stop()

asyncio.run(main())

Core concepts

Component[T]

Базовый класс для компонентов с управляемым жизненным циклом:

class PGComponent(Component[Pool]):
    async def _start(self, dsn: str, **kw) -> Pool:
        return await asyncpg.create_pool(dsn)

    async def _stop(self) -> None:
        await self.obj.close()

    async def is_alive(self) -> bool:
        return not self.obj._closed
  • _start(**config) — создает и возвращает управляемый объект
  • _stop() — освобождает ресурсы
  • is_alive() — healthcheck (по умолчанию True)

create_component(cls)

Оборачивает обычный класс в Component без написания boilerplate. Конструктор класса вызывается с параметрами из конфига:

from adc_appkit.components.component import create_component

class DAO:
    def __init__(self, pool: Pool):
        self.pool = pool

    async def get_user(self, user_id):
        return await self.pool.fetchrow("SELECT * FROM users WHERE id=$1", user_id)

class App(BaseApp):
    pg = component(PGComponent, config_key="pg")
    dao = component(create_component(DAO), config_key="dao", dependencies={"pool": "pg"})

При остановке create_component автоматически вызывает close() (sync или async) на объекте, если метод существует.

Strategies: SINGLETON vs REQUEST

from adc_appkit import ComponentStrategy

class App(BaseApp):
    # создается один раз при app.start(), живет до app.stop()
    pg = component(PGComponent, config_key="pg")

    # создается на каждый request_scope, уничтожается при выходе
    current_user = component(
        CurrentUserComponent,
        config_key="current_user",
        strategy=ComponentStrategy.REQUEST,
    )

SINGLETON (по умолчанию) — один экземпляр на всё приложение. REQUEST — новый экземпляр на каждый request scope; изолирован через contextvars.ContextVar.

Dependency injection

Зависимости объявляются как маппинг {имя_параметра: имя_компонента}. При старте компонента в _start() автоматически передается .obj зависимости:

class App(BaseApp):
    pg = component(PGComponent, config_key="pg")
    dao = component(create_component(DAO), config_key="dao", dependencies={"pool": "pg"})
    #                                                                       ^^^^^   ^^^^
    #                                                        параметр в __init__    имя компонента

Правила:

  • SINGLETON может зависеть от SINGLETON
  • REQUEST может зависеть от SINGLETON и REQUEST
  • SINGLETON не может зависеть от REQUEST (защита от утечки request-scoped состояния)

Компоненты запускаются в топологическом порядке: зависимости стартуют раньше зависимых.

Request scope

Request scope управляет жизненным циклом REQUEST компонентов. Контекст (ctx) передает параметры, специфичные для запроса:

async with app.request_scope({"current_user": {"user_id": uid}}) as scope:
    # все REQUEST компоненты созданы и запущены
    user = app.current_user  # obj напрямую через дескриптор
    # или
    user = scope.use("current_user")

Конфиг REQUEST компонента собирается в порядке: base config -> ctx overrides -> DI injection. Ключ в ctx должен совпадать с config_key компонента.

Real-world patterns

App с PG + DAO + request-scoped identity

Паттерн из реального auth-сервиса: PG pool (SINGLETON) -> DAO (SINGLETON, зависит от PG) -> CurrentIdentity (REQUEST, получает sub из JWT и dao как зависимость):

from adc_appkit import BaseApp, ComponentStrategy, component
from adc_appkit.components.component import Component, create_component
from adc_appkit.components.pg import PG

class DAO:
    def __init__(self, pool):
        self.pool = pool

    async def get_user_by_id(self, user_id):
        return await self.pool.fetchrow("SELECT * FROM users WHERE id=$1", user_id)

class CurrentIdentity(Component):
    """REQUEST-scoped: загружает текущего пользователя по ID из JWT."""

    async def _start(self, sub, dao, **kw):
        user = await dao.get_user_by_id(sub)
        if not user:
            raise ValueError(f"User {sub} not found")
        return user

    async def _stop(self):
        pass

class App(BaseApp):
    pg = component(PG, config_key="pg")
    dao = component(create_component(DAO), config_key="dao", dependencies={"pool": "pg"})
    current_identity = component(
        CurrentIdentity,
        config_key="current_identity",
        strategy=ComponentStrategy.REQUEST,
        dependencies={"dao": "dao"},
    )

Endpoint: request_scope с контекстом из JWT

async def logout_handler(request):
    app: App = request.app.state.app
    user_id = decode_jwt(request.headers["Authorization"]).sub

    async with app.request_scope({"current_identity": {"sub": user_id}}):
        # app.current_identity — загруженный из БД пользователь
        await app.revoke_session(session_id)

Значение "sub" из ctx объединяется с base config и DI-зависимостью dao, а затем передается в CurrentIdentity._start(sub=..., dao=...).

Healthcheck

health = await app.healthcheck()
# {"pg": True, "dao": True}  — только SINGLETON компоненты

Architecture

  • Топологическая сортировка — компоненты запускаются и останавливаются в порядке, учитывающем зависимости
  • ContextVar изоляция — каждый request scope хранит свой кэш компонентов в contextvars.ContextVar, безопасно для concurrent asyncio tasks
  • Сборка через MRO — дескрипторы компонентов собираются с учетом наследования (reversed(cls.mro()))
  • Graceful cleanup — при ошибке старта REQUEST компонента уже запущенные компоненты корректно останавливаются

Built-in components

Компонент Модуль Описание
PG adc_appkit.components.pg PostgreSQL connection pool (asyncpg)
HTTP adc_appkit.components.http HTTP client (aiohttp)
S3 adc_appkit.components.s3 S3 client (boto3/aioboto3)

Development

uv sync --dev
uv run pytest -v
uv run black adc_appkit tests
uv run isort adc_appkit tests
uv run mypy adc_appkit

Metadata

Release files for adc-appkit 0.2.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 adc-appkit 0.2.0
File Size Uploaded Provenance Actions
adc_appkit-0.2.0.tar.gz 47.2 kB Without provenance Details for adc_appkit-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adc-appkit 0.2.0
File Interpreter ABI Platform Actions
adc_appkit-0.2.0-py3-none-any.whl Python 3 none any Details for adc_appkit-0.2.0-py3-none-any.whl

Total release size: 65.2 kB

Release files / adc_appkit-0.2.0.tar.gz

Download URL adc_appkit-0.2.0.tar.gz
Size 47.2 kB
Tags Source
SHA-256 checksum
How to use checksums
abc6db47c08e6ab0535c6aa056e41167ffd845fb48ee8ff7adbfe74c5512ab04
BLAKE2b-256 checksum
How to use checksums
66571ac6435ba2f66265c7c8fadbaeb081a5a2f7ea208301ab133f591e2af9fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.16

Release files / adc_appkit-0.2.0-py3-none-any.whl

Download URL adc_appkit-0.2.0-py3-none-any.whl
Size 18.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7f93b4c9c39d34fe58281a84717a1d58f6a842dc66993350349f3fc3a32657e5
BLAKE2b-256 checksum
How to use checksums
58396dae5a15e303d6a3daa10ba407f8a5846493d0587bd8f4dfba6b35b74e8e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.16

Security for adc-appkit 0.2.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.2.0 This release

2 release files No 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