Metadata-Version: 2.4
Name: avito-python-sdk
Version: 0.2.3
Summary: Async Python SDK for Avito OpenAPI (full endpoint coverage)
Project-URL: Repository, https://github.com/kozandlov/avito-python-sdk
Project-URL: Issues, https://github.com/kozandlov/avito-python-sdk/issues
Author: kozandlov
License: MIT
License-File: LICENSE
Keywords: async,avito,httpx,openapi,sdk
Classifier: Development Status :: 3 - Alpha
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: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# pyAvitoApi

Асинхронная Python SDK-библиотека для Avito API с полным покрытием операций на основе официальных OpenAPI-снимков.

## Что входит

- Покрытие всех API-групп из `https://developers.avito.ru/web/1/openapi/list`.
- Генерация per-slug API-классов из нормализованных (`patched`) OpenAPI-спецификаций.
- Typed response models на Pydantic для всех сгенерированных методов.
- Детерминированный pipeline снимков и генерации.

## Структура проекта

- `specs/raw` — сырой snapshot OpenAPI.
- `specs/patched` — нормализованные спеки для генерации.
- `tools/fetch_specs.py` — загрузка snapshot + manifest.
- `tools/patch_specs.py` — нормализация известных дефектов OpenAPI.
- `tools/generate_clients.py` — генерация async API-модулей.
- `tools/build_coverage_report.py` — сборка отчета покрытия.
- `src/pyavitoapi/generated` — сгенерированные API-модули по slug.
- `src/pyavitoapi/generated_models` — сгенерированные typed response models.
- `src/pyavitoapi/client.py` — фасад `AvitoAsyncClient`.

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

```python
from pyavitoapi import AvitoAsyncClient

async def main() -> None:
    async with AvitoAsyncClient(client_id="...", client_secret="...") as client:
        token = await client.auth.get_client_credentials_token()
        me = await client.user.get_user_info_self(path_params={}, query=None)
        print(token.access_token[:8], me.model_dump(exclude_none=True))
```

## Установка из пакетного менеджера

```bash
pip install pyAvitoApi
```

Для фиксации версии в `requirements.txt`:

```text
pyAvitoApi==0.2.0
```

## Перегенерация

```bash
python tools/fetch_specs.py
python tools/patch_specs.py
python tools/generate_clients.py
python tools/build_coverage_report.py
```

## Релиз и публикация в PyPI

Пайплайн релиза автоматизирован через GitHub Actions:

1. Запустите workflow `Release Bump And Tag`.
2. Workflow увеличит patch-версию в `pyproject.toml`, создаст commit и тег `vX.Y.Z`.
3. По тегу автоматически запускается `Publish To PyPI`, который собирает и публикует пакет.

Публикация использует Trusted Publishing (OIDC) без API-токенов в GitHub Secrets.

## Тесты

```bash
pytest -q
```

## Примечания

- Метрика покрытия считается относительно `specs/patched` (нормализованные уникальные операции).
- Raw-спеки могут содержать дубликаты token-операций из-за известных upstream-особенностей.
- Сгенерированные методы валидируют ответы по typed-моделям и бросают
  `AvitoValidationError`, если payload не соответствует схеме.

## Документация

- Руководство по использованию: `docs/USAGE.md`
- Матрица endpoint-ов: `docs/endpoint-matrix.md`
- Известные особенности OpenAPI: `docs/known-quirks.md`
- Отчет покрытия: `docs/final-compliance-report.md`
- Карта typed-ответов: `docs/typed-response-map.json`
- История релизов: `RELEASE_NOTES.md`
