Metadata-Version: 2.4
Name: adc-stack
Version: 0.1.2
Summary: Backend toolkit: async web, PostgreSQL, S3, logging, and component lifecycle management
Project-URL: Homepage, https://github.com/ascet-dev/adc-stack
Project-URL: Repository, https://github.com/ascet-dev/adc-stack.git
Project-URL: Issues, https://github.com/ascet-dev/adc-stack/issues
Author: ascet.dev
License-Expression: MIT
License-File: LICENSE
Keywords: async,backend,framework,logging,postgresql,s3,web
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: adc-aiopg>=1.0.0
Requires-Dist: adc-aios3>=0.1.0
Requires-Dist: adc-appkit>=0.2.0
Requires-Dist: adc-logger>=0.1.0
Requires-Dist: adc-webkit>=0.2.0
Description-Content-Type: text/markdown

# adc-stack

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

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

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

## Установка

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

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

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

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

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

```python
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
