adc-stack 0.1.2

Backend toolkit: async web, PostgreSQL, S3, logging, and component lifecycle management

adc-stack

Набор async-библиотек для построения backend-сервисов на Python. Объединяет инструменты для работы с web, PostgreSQL, S3, логированием и управлением жизненным циклом компонентов приложения.

Что входит в стек

Библиотека	Назначение	Описание
adc-appkit	Ядро приложения	Компонентная архитектура, DI, управление жизненным циклом, request scope
adc-webkit	Web-фреймворк	HTTP-эндпоинты на базе Starlette, JWT-аутентификация, OpenAPI/Swagger
adc-aiopg	PostgreSQL	Async-клиент на asyncpg, query builder, DAO/Repository pattern, Alembic-миграции
adc-aios3	S3/MinIO	Async-клиент для S3-совместимого хранилища (upload, download, streaming, presigned URL)
adc-logger	Логирование	Конфигурация stdlib logging: JSON, цветной вывод, композируемые настройки

Установка

pip install git+https://github.com/ascet-dev/adc-stack.git@main

Или отдельные библиотеки:

pip install git+https://github.com/ascet-dev/adc-appkit.git@main
pip install git+https://github.com/ascet-dev/adc-webkit.git@main
pip install git+https://github.com/ascet-dev/adc-aiopg.git@main
pip install git+https://github.com/ascet-dev/adc-aios3.git@main
pip install git+https://github.com/ascet-dev/adc-logger.git@main

Быстрый старт

Пример приложения, использующего все компоненты стека:

import asyncio
from adc_appkit import BaseApp, component, ComponentStrategy
from adc_appkit.components.pg import PG
from adc_appkit.components.s3 import S3
from adc_webkit.web import Web, Route
from adc_webkit.web.endpoints import JsonEndpoint, Ctx, Response
from adc_logger import BaseLoggingConfig
from pydantic import BaseModel


# 1. Настраиваем логирование
config = BaseLoggingConfig()
config.setup_logging()


# 2. Описываем приложение с компонентами
class App(BaseApp):
    db = component(PG, config_key="pg")
    s3 = component(S3, config_key="s3")


# 3. Описываем эндпоинты
class HealthQuery(BaseModel):
    pass

class HealthEndpoint(JsonEndpoint):
    response = Response(status_code=200)

    async def execute(self, ctx: Ctx) -> dict:
        return {"status": "ok"}


# 4. Собираем web-приложение
class API(Web):
    routes = [
        Route(method="GET", path="/health", view=HealthEndpoint),
    ]


# 5. Запускаем
async def main():
    app = App(components_config={
        "pg": {"dsn": "postgresql://user:pass@localhost/db"},
        "s3": {
            "bucket": "my-bucket",
            "url": "http://localhost:9000",
            "access_key": "minioadmin",
            "secret_key": "minioadmin",
        },
    })
    await app.start()

    api = API.create()
    api.bind_component("db", app.db)
    await api.start("0.0.0.0", 8000)

asyncio.run(main())

Архитектура

adc-stack
├── adc-appkit     # Ядро: компоненты, DI, lifecycle
│   ├── PG         # Встроенный компонент для PostgreSQL
│   ├── S3         # Встроенный компонент для S3
│   └── HTTP       # Встроенный компонент для HTTP-клиента
├── adc-webkit     # Web: эндпоинты, роутинг, auth, OpenAPI
├── adc-aiopg      # PostgreSQL: пул, запросы, DAO, миграции
├── adc-aios3      # S3: upload/download, streaming, presigned URL
└── adc-logger     # Logging: JSON/color форматтеры, конфигурация

adc-appkit выступает центральным элементом: он управляет жизненным циклом всех компонентов (БД, S3, HTTP-клиенты) и предоставляет DI для связывания их с бизнес-логикой. adc-webkit отвечает за HTTP-слой. Остальные библиотеки можно использовать как вместе, так и по отдельности.

Требования

• Python >= 3.11
• PostgreSQL (для adc-aiopg)
• S3-совместимое хранилище (для adc-aios3) -- AWS S3, MinIO и др.

Лицензия

MIT