Документация всего

.claude/settings.local.json

@@ -25,7 +25,17 @@
       "Bash(grep -E '\\(def |\"\"\"$\\)')",
       "Bash(\" /Users/n.baryshnikov/Projects/avito_python_api/avito/client.py)",
       "Bash(rg \"```\" /Users/n.baryshnikov/Projects/avito_python_api/avito/client.py)",
-      "Bash(grep ``` *)"
+      "Bash(grep ``` *)",
+      "Bash(poetry install *)",
+      "Bash(poetry lock *)",
+      "Bash(awk -F'|' '{print $4}')",
+      "Bash(grep -v \"^$\")",
+      "Bash(grep -n \"^\\\\`\\\\`\\\\`\" /Users/n.baryshnikov/Projects/avito_python_api/docs/site/how-to/idempotency.md)",
+      "Bash(grep -n \"^\\\\`\\\\`\\\\`\" /Users/n.baryshnikov/Projects/avito_python_api/docs/site/how-to/per-operation-overrides.md)",
+      "Bash(grep -n \"^\\\\`\\\\`\\\\`\" /Users/n.baryshnikov/Projects/avito_python_api/docs/site/how-to/security-practices.md)",
+      "Bash(pip show *)",
+      "Bash(awk -F'|' '{gsub\\(/^ +| +$/,\"\",$2\\); gsub\\(/^ +| +$/,\"\",$6\\); print $2 \":\" $6}')",
+      "Bash(make qa-docs *)"
     ]
   }
 }

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## Проверки
+
+- [ ] `make check` проходит локально или в CI.
+- [ ] `make docs-strict` проходит, если изменены README, docs, публичные сигнатуры или inventory.
+- [ ] README/tutorials/how-to примеры соответствуют актуальным публичным сигнатурам SDK.
+- [ ] Новая публичная операция добавлена в `docs/avito/inventory.md` и покрыта reference.
+- [ ] Публичное переименование: alias сохранён, `DeprecationWarning` добавлен, `CHANGELOG.md` обновлён в секции `Deprecated`.

.github/workflows/ci.yml

@@ -14,6 +14,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set up Python 3.14
         uses: actions/setup-python@v5
@@ -27,11 +29,20 @@ jobs:
           virtualenvs-in-project: true
 
       - name: Install dependencies
-        run: poetry install --no-interaction
+        run: poetry install --no-interaction --with docs
 
       - name: Run quality gate
         run: make check
 
+      - name: Run docs strict gate
+        run: make docs-strict
+
+      - name: Run qa-docs (pydocstyle + interrogate)
+        run: make qa-docs
+
+      - name: Interrogate diff gate (changed modules vs baseline)
+        run: poetry run python scripts/check_interrogate_gate.py --base-ref origin/main
+
       - name: Collect coverage report
         run: |
           poetry run coverage run -m pytest

.github/workflows/docs.yml

@@ -35,7 +35,42 @@ jobs:
         run: poetry install --no-interaction --with docs
 
       - name: Build docs (strict)
-        run: poetry run mkdocs build --strict
+        run: make docs-strict
+
+      - name: Build docs reports
+        run: |
+          poetry run python scripts/check_inventory_coverage.py --output inventory-coverage-report.json
+          poetry run python scripts/check_spec_inventory_sync.py --output spec-inventory-report.json
+          poetry run python scripts/check_reference_public_surface.py --output reference-public-report.json
+          poetry run python scripts/check_public_docstrings.py --output docstring-contract-report.json
+          poetry run python scripts/check_changelog_sections.py --output changelog-sections-report.json
+          poetry run bandit -r avito -lll -f json -o bandit-report.json
+          poetry run python scripts/build_docs_quality_report.py \
+            --inventory-report inventory-coverage-report.json \
+            --spec-report spec-inventory-report.json \
+            --reference-report reference-public-report.json \
+            --docstring-report docstring-contract-report.json \
+            --changelog-report changelog-sections-report.json \
+            --bandit-report bandit-report.json \
+            --output docs-quality-report.json
+
+      - name: Upload docs reports
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-contract-reports
+          path: |
+            inventory-coverage-report.json
+            spec-inventory-report.json
+            reference-public-report.json
+            docstring-contract-report.json
+            changelog-sections-report.json
+            bandit-report.json
+            docs-quality-report.json
+
+      - name: Check links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --exclude "avito\.ru" --retry-wait-time 5 --max-retries 3 --timeout 30 site/
 
   deploy:
     runs-on: ubuntu-latest
@@ -67,4 +102,12 @@ jobs:
 
       - name: Deploy latest (push to main)
         if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
-        run: poetry run mike deploy --push --update-aliases main latest
+        run: |
+          poetry run mike deploy --push --update-aliases main latest
+          poetry run mike set-default --push latest
+
+      - name: Deploy stable (push tag)
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          poetry run mike deploy --push --update-aliases "$VERSION" stable

.gitignore

@@ -127,6 +127,14 @@ venv.bak/
 
 # mkdocs documentation
 /site
+inventory-coverage-report.json
+spec-inventory-report.json
+reference-public-report.json
+docstring-contract-report.json
+changelog-sections-report.json
+bandit-report.json
+docs-quality-report.json
+ttfc-minutes.txt
 
 # mypy
 .mypy_cache/
@@ -140,4 +148,4 @@ dmypy.json
 .pytype/
 
 # Cython debug symbols
-cython_debug/
+cython_debug/

.interrogate-baseline

@@ -0,0 +1,98 @@
+{
+  "modules": {
+    "avito/__init__.py": 100.0,
+    "avito/__main__.py": 100.0,
+    "avito/_env.py": 88.0,
+    "avito/client.py": 92.0,
+    "avito/config.py": 83.0,
+    "avito/settings.py": 100.0,
+    "avito/accounts/__init__.py": 100.0,
+    "avito/accounts/client.py": 85.0,
+    "avito/accounts/domain.py": 92.0,
+    "avito/accounts/enums.py": 100.0,
+    "avito/accounts/mappers.py": 56.0,
+    "avito/accounts/models.py": 100.0,
+    "avito/ads/__init__.py": 100.0,
+    "avito/ads/client.py": 94.0,
+    "avito/ads/domain.py": 78.0,
+    "avito/ads/enums.py": 100.0,
+    "avito/ads/mappers.py": 68.0,
+    "avito/ads/models.py": 100.0,
+    "avito/auth/__init__.py": 100.0,
+    "avito/auth/enums.py": 100.0,
+    "avito/auth/mappers.py": 100.0,
+    "avito/auth/models.py": 100.0,
+    "avito/auth/provider.py": 60.0,
+    "avito/auth/settings.py": 100.0,
+    "avito/autoteka/__init__.py": 100.0,
+    "avito/autoteka/client.py": 26.0,
+    "avito/autoteka/domain.py": 91.0,
+    "avito/autoteka/enums.py": 100.0,
+    "avito/autoteka/mappers.py": 62.0,
+    "avito/autoteka/models.py": 100.0,
+    "avito/core/__init__.py": 100.0,
+    "avito/core/deprecation.py": 0.0,
+    "avito/core/domain.py": 100.0,
+    "avito/core/enums.py": 100.0,
+    "avito/core/exceptions.py": 84.0,
+    "avito/core/mapping.py": 100.0,
+    "avito/core/pagination.py": 41.0,
+    "avito/core/retries.py": 100.0,
+    "avito/core/serialization.py": 50.0,
+    "avito/core/transport.py": 37.0,
+    "avito/core/types.py": 100.0,
+    "avito/core/validation.py": 100.0,
+    "avito/cpa/__init__.py": 100.0,
+    "avito/cpa/client.py": 30.0,
+    "avito/cpa/domain.py": 86.0,
+    "avito/cpa/enums.py": 100.0,
+    "avito/cpa/mappers.py": 52.0,
+    "avito/cpa/models.py": 76.0,
+    "avito/jobs/__init__.py": 100.0,
+    "avito/jobs/client.py": 19.0,
+    "avito/jobs/domain.py": 90.0,
+    "avito/jobs/enums.py": 100.0,
+    "avito/jobs/mappers.py": 60.0,
+    "avito/jobs/models.py": 100.0,
+    "avito/messenger/__init__.py": 100.0,
+    "avito/messenger/client.py": 100.0,
+    "avito/messenger/domain.py": 77.0,
+    "avito/messenger/enums.py": 100.0,
+    "avito/messenger/mappers.py": 67.0,
+    "avito/messenger/models.py": 100.0,
+    "avito/orders/__init__.py": 100.0,
+    "avito/orders/client.py": 12.0,
+    "avito/orders/domain.py": 96.0,
+    "avito/orders/enums.py": 100.0,
+    "avito/orders/mappers.py": 59.0,
+    "avito/orders/models.py": 56.0,
+    "avito/promotion/__init__.py": 100.0,
+    "avito/promotion/client.py": 100.0,
+    "avito/promotion/domain.py": 84.0,
+    "avito/promotion/enums.py": 100.0,
+    "avito/promotion/mappers.py": 41.0,
+    "avito/promotion/models.py": 100.0,
+    "avito/ratings/__init__.py": 100.0,
+    "avito/ratings/client.py": 33.0,
+    "avito/ratings/domain.py": 89.0,
+    "avito/ratings/enums.py": 100.0,
+    "avito/ratings/mappers.py": 36.0,
+    "avito/ratings/models.py": 100.0,
+    "avito/realty/__init__.py": 100.0,
+    "avito/realty/client.py": 30.0,
+    "avito/realty/domain.py": 67.0,
+    "avito/realty/enums.py": 100.0,
+    "avito/realty/mappers.py": 50.0,
+    "avito/realty/models.py": 100.0,
+    "avito/tariffs/__init__.py": 100.0,
+    "avito/tariffs/client.py": 67.0,
+    "avito/tariffs/domain.py": 100.0,
+    "avito/tariffs/enums.py": 100.0,
+    "avito/tariffs/mappers.py": 22.0,
+    "avito/tariffs/models.py": 100.0,
+    "avito/testing/__init__.py": 100.0,
+    "avito/testing/fake_transport.py": 79.0
+  },
+  "generated_at": "2026-04-24T09:02:16.576057+00:00",
+  "interrogate_version": "1.7.0"
+}

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to Semantic Versioning.
 
 ## [Unreleased]
 
+### Added
+- Нет изменений.
+
+### Deprecated
+- Архивные CPA-методы `CpaArchive.get_call`, `CpaArchive.get_balance_info`, `CpaArchive.get_call_by_id` и режим `CpaChat.list(version=1)` теперь эмитируют `DeprecationWarning` при первом вызове; используйте `call_tracking_call().download`, `cpa_lead().get_balance_info`, `call_tracking_call().get` и `cpa_chat().list(version=2)`.
+- Архивные методы автозагрузки `AutoloadArchive.get_profile`, `AutoloadArchive.save_profile`, `AutoloadArchive.get_last_completed_report`, `AutoloadArchive.get_report` теперь эмитируют `DeprecationWarning` при первом вызове; используйте `autoload_profile().get`, `autoload_profile().save`, `autoload_report().get_last_completed` и `autoload_report().get`.
+
 ### Changed
 - Централизовано выполнение схемы `request + map` через `Transport.request_public_model`.
 - Убраны прямые обращения доменных клиентов к `request_json` и приватному `Transport._auth_provider`.
@@ -16,6 +23,12 @@ and this project adheres to Semantic Versioning.
 - Transport получил поддержку `Idempotency-Key`; публичные write-методы во всех доменах принимают `idempotency_key`, а dry-run/write-контракт promotion покрыт тестами.
 - Во всех доменных пакетах добавлены `enums.py`; `accounts`, `ads`, `autoteka`, `jobs`, `messenger`, `orders`, `promotion`, `ratings`, `realty` и `tariffs` переведены на typed enums с fallback на `UNKNOWN` и warning-логом ровно один раз на неизвестное upstream-значение.
 
+### Removed
+- Нет изменений.
+
+### Fixed
+- Нет изменений.
+
 ## [1.0.2] - 2026-04-21
 
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+## Проверки документации
+
+Перед PR, который меняет публичный API, README или `docs/site/`, выполните:
+
+```bash
+make docs-strict
+make docs-report
+```
+
+Для полной локальной проверки ссылок установите `lychee`:
+
+```bash
+brew install lychee
+```
+
+или на Linux:
+
+```bash
+cargo binstall lychee
+```
+
+После установки доступна проверка:
+
+```bash
+make docs-check
+```
+
+## TTFC measurement
+
+TTFC показывает, за сколько минут новый пользователь проходит путь от чистого
+окружения до первого реального `get_self()` из `docs/site/tutorials/getting-started.md`.
+Цель документации: не больше 15 минут.
+
+Процедура перед релизом:
+
+1. Создайте новый временный каталог и виртуальное окружение.
+2. Установите опубликованный пакет: `pip install avito-py`.
+3. Установите реальные `AVITO_CLIENT_ID` и `AVITO_CLIENT_SECRET`.
+4. Запустите секундомер.
+5. Выполните tutorial `getting-started.md` до успешного `get_self()`.
+6. Остановите секундомер и запишите результат в минутах.
+7. Перед сборкой отчёта передайте значение одним из способов:
+
+```bash
+TTFC_MINUTES=8.5 make docs-report
+```
+
+или:
+
+```bash
+printf "8.5\n" > ttfc-minutes.txt
+make docs-report
+```
+
+`ttfc-minutes.txt` не коммитится. В CI релизного прогона можно передать
+`--ttfc-minutes <value>` в `scripts/build_docs_quality_report.py`.

Makefile

@@ -44,5 +44,30 @@ release:
 docs-serve:
 	poetry run mkdocs serve
 
-docs-build:
+docs-strict:
 	poetry run mkdocs build --strict
+	poetry run python scripts/check_readme_domain_coverage.py
+	poetry run pytest tests/docs/
+
+docs-build: docs-strict
+
+docs-report:
+	poetry run python scripts/check_inventory_coverage.py --output inventory-coverage-report.json
+	poetry run python scripts/check_spec_inventory_sync.py --output spec-inventory-report.json
+	poetry run python scripts/check_reference_public_surface.py --output reference-public-report.json
+	poetry run python scripts/check_public_docstrings.py --output docstring-contract-report.json
+	poetry run python scripts/check_changelog_sections.py --output changelog-sections-report.json
+	poetry run python scripts/check_docs_examples.py --output reference-explanation-examples-report.json
+	poetry run bandit -r avito -lll -f json -o bandit-report.json
+	poetry run python scripts/build_docs_quality_report.py
+
+docs-check: docs-strict
+	lychee --exclude "avito\.ru" --retry-wait-time 5 --max-retries 3 --timeout 30 site/
+
+qa-docs:
+	poetry run pydocstyle \
+		avito/client.py avito/config.py \
+		avito/core/exceptions.py avito/core/pagination.py \
+		avito/*/domain.py \
+		avito/testing/fake_transport.py
+	poetry run interrogate avito/ --fail-under=0 --quiet