Explanations¶
Explanations описывают причины архитектурных решений SDK: границы слоёв, retry-поведение, модель ошибок, безопасность диагностики и правила обратной совместимости.
| Статья | Что объясняет |
|---|---|
| Архитектура CLI | Почему CLI является тонкой оболочкой над AvitoClient, как работают registry, coverage linter, exclusions, redaction и пагинация |
| Архитектура SDK | Как AvitoClient, домены, OperationSpec, executor, transport, auth и модели разделяют ответственность |
| Целевая структура доменов | Как API-домены используют dataclass-модели для сериализации, десериализации, нормализации и enum-ов |
| OAuth и токены | Почему token-flow скрыт за AuthProvider |
| Transport и retry | Почему retry живёт в transport-слое и как учитываются 429/5xx |
| Модель ошибок | Как HTTP-коды превращаются в typed exceptions |
| Семантика пагинации | Почему PaginatedList ленивый и когда загружаются страницы |
| Dry-run и идемпотентность | Как write-операции проверяются без сетевого вызова |
| Стратегия тестирования | Как FakeTransport, contract-тесты и docs-harness проверяют SDK |
| Шаблон async-домена | Как портировать доменный объект в async_domain.py без нарушения Swagger bindings |
| Покрытие API и deprecation | Как specs, reference и runtime warnings связаны между собой |
| Swagger binding subsystem | Как Swagger specs, bindings, strict lint, JSON report и contract runner сохраняют coverage-контекст |
| Resolution конфигурации | Как env, .env и defaults превращаются в AvitoSettings |
| Security и redaction | Какие секреты SDK не раскрывает в диагностике и ошибках |
Для практических сценариев используйте how-to рецепты, а для полного API-контракта — reference.