Metadata-Version: 2.3
Name: damia-sdk
Version: 0.1.0
Summary: Async Python SDK for DaMIA APIs
Requires-Dist: aiocache
Requires-Dist: httpx
Requires-Dist: loguru
Requires-Dist: pydantic
Requires-Dist: pydantic-settings>=2.16.2
Requires-Dist: tenacity
Requires-Dist: typer
Requires-Dist: sentry-sdk ; extra == 'sentry'
Requires-Python: >=3.11
Provides-Extra: sentry
Description-Content-Type: text/markdown

# DaMIA SDK

Асинхронный Python SDK и CLI для сервисов DaMIA. Реализованы 61 GET-метод восьми сервисов и общий HTTP-транспорт; CLI вызывает методы SDK.

Проектный дизайн, настройки, HTTP-клиент, CLI и план разработки описаны в [docs/PROJECT.md](docs/PROJECT.md).

## Разработка

Требуются Python 3.11+, [uv](https://docs.astral.sh/uv/) и Make:

```bash
make sync
uv run damia --help
uv run damia version-info
make check
```

Зависимости и настройки находятся в `pyproject.toml`, зафиксированные версии — в `uv.lock`. Sentry доступен как необязательная зависимость: `uv sync --extra sentry`; интеграция и логирование SDK ещё не реализованы.

Настройки загружаются из окружения только явно, через `DamiaSettings.from_env()`. Например, `DAMIA_FNS_KEY`, `DAMIA_BASE_URLS__FNS` и `DAMIA_TIMEOUT__READ`. Сервисные методы выполняют GET-запросы через общий транспорт и возвращают `HttpResponse` с `status_code`, `data`, `body` и `json()`. **Вызовы SDK могут быть платными или изменять состояние**, несмотря на использование GET. Повторы и кеширование на уровне сервисных методов не включаются автоматически, даже если они разрешены в настройках транспорта. Низкоуровневому транспорту нужны явные флаги `allow_retry` и `allow_cache`; для кеша также обязателен `cache_validator`. Подробности — в [дизайне проекта](docs/PROJECT.md#http-транспорт).

## CLI

В CLI доступны группы `fns`, `rosstat`, `banks`, `scoring`, `procurement`, `arbitration`, `fssp` и `spk` и команды для 61 метода SDK:

```bash
uv run damia fns --help
uv run damia fns egr --help
uv run damia rosstat multbalance --help
```

Имена методов и параметров соответствуют SDK; подчёркивания заменяются дефисами (например, `nalogbi_file` → `nalogbi-file`). Опции списков повторяются для каждого значения, порядок сохраняется. Для полей баланса повторяйте `--balance-field NAME=INTEGER`; имена полей не должны повторяться. Команды выполняют реальные запросы, которые могут тарифицироваться; `fns mon`, `procurement zmon` и `arbitration delopro` могут менять состояние. `--help` и `version-info` не создают клиент. CLI явно вызывает `DamiaSettings.from_env()` и не читает `.env` автоматически. Ключи: `DAMIA_FNS_KEY`, `DAMIA_BANKS_KEY`, `DAMIA_API_KEY` и сервисные overrides; адреса: `DAMIA_BASE_URLS__SERVICE` (имя сервиса заглавными буквами). Не указывайте ключи в аргументах.

Чувствительные параметры передавайте через `--params-file PATH` или `--params-file -` (stdin): UTF-8 JSON-объект с именами и типами параметров SDK. Неизвестные поля, дубликаты ключей и конфликт с явно заданной CLI-опцией запрещены. Аргументы команд могут оставаться в истории shell и списке процессов; файл параметров и stdin также требуют защиты.

JSON выводится корректным JSON; `text/*` — текстом без добавления перевода строки. В TTY управляющие C0 (кроме LF и TAB), DEL и C1 экранируются как `\uXXXX`; JSON остаётся корректным. При перенаправлении текст не изменяется: последующий просмотр файла в терминале может быть опасен. Ответы также могут содержать конфиденциальные данные. Бинарный ответ обычной команды отклоняется. Для `fns nalogbi-file`, `vyp`, `mspinfo-file`, `bo-file` обязателен `--output PATH`: записываются точные байты, stdout пуст. Существующие файлы и симлинки не перезаписываются; POSIX создание использует режим не шире 0600 с учётом umask. На других платформах приватность ACL не гарантируется. При ошибке частичная запись удаляется, если путь ещё указывает на созданный файл; при сбое `fstat` может остаться пустой файл; защита удаления от гонки замены пути платформенно ограничена. Ошибки параметров возвращают 2, прочие ошибки 1; диагностика идёт в stderr без значений.

## Контрактный gate

Исследовательские спецификации и SDK сопоставлены в [инвентаре](docs/contracts/inventory.md); наблюдаемое поведение ответов и ошибок описано в [контракте ответов](docs/contracts/response-errors.md). Процедура ревью и обновления снимка — в [контроле изменений](docs/contracts/change-control.md).

Локальные контрактные проверки без Prism и реального API:

```bash
PYTHONDONTWRITEBYTECODE=1 uv run --locked pytest -p no:cacheprovider -q tests/test_contract_inventory.py tests/test_service_contract.py tests/test_response_error_contract.py tests/test_e2e_inventory.py
```

Этот gate не заменяет полный `make check` и не разрешает выпуск: полный набор должен пройти перед выпуском.

## Тестирование с Prism

В одном терминале запустите Prism для ФНС (нужны Node.js и `npx`):

```bash
make prism-fns
```

В другом запустите локальный тест с Hypothesis:

```bash
RUN_PRISM_TESTS=1 uv run --locked pytest -m prism
```

Этот первоначальный тест обращается только к `127.0.0.1`, использует синтетические данные и проверяет HTTP-интерфейс Prism, а не SDK. По умолчанию он пропускается. Если Prism запущен на другом порту, передайте его в `PRISM_TEST_PORT`, например `RUN_PRISM_TESTS=1 PRISM_TEST_PORT=4011 uv run --locked pytest -m prism`. Подробнее о mock-сервере: [docs/swagger/README.md](docs/swagger/README.md).

### E2E-тесты SDK и CLI

```bash
make test-e2e-sdk  # все 61 метода SDK
make test-e2e-cli  # все 61 команды CLI
make test-e2e      # оба набора
make test-unit     # прочие тесты, без e2e
```

Тесты самостоятельно запускают восемь локальных Prism 5.5.0 через `npx --yes @stoplight/prism-cli@5.5.0` на свободных портах и завершают процессы после тестирования; нужны Node.js и `npx`, при отсутствии пакета в кеше возможна загрузка из npm. Отсутствие `npx` или ошибка запуска приводят к ошибке тестов, не к пропуску. Используются только синтетические значения. Для Python-процесса тестов и дочернего процесса CLI включён запрет внешних сетевых адресов; настройки и реальные ключи `DAMIA_*` из окружения CLI не наследуются. Это тестовая защита на уровне Python, не распространяющаяся на Prism и другие subprocess; это не замена сетевой песочнице ОС.

E2E-наборы проверяют адрес и параметры через локальный прокси, ответ Prism и результат SDK или CLI. Методы SDK возвращают `HttpResponse`, содержащий `data` и `status_code`. Для файлов CLI-тесты используют `--output`. Hypothesis генерирует синтетические параметры и ключи; сокращение примеров при ошибках отключено для скорости. Сценарии охватывают каждый метод, но не все комбинации его параметров.

Временные тестовые копии спецификаций содержат искусственные ответы для `procurement/zmon`, `spk/report` и `spk/proverki`: без них Prism возвращает 500 из-за неопределённых схем. Исходный Swagger не изменяется, фикстуры не доказывают реальное поведение DaMIA.

Успех SDK e2e с локальным Prism не подтверждает совместимость с реальным DaMIA: спецификации исследовательские и не подтверждены поставщиком. CLI E2E не помечены `xfail`. E2E входят в обычные `make test` и `make check`; при ошибке запуска Prism полный gate не проходит.

## Сборка и публикация

Метаданные пакета заявляют Python 3.11+, но полный набор поддерживаемых версий Python и диапазонов зависимостей ещё не проверен. Локально wheel и sdist версии 0.1.0 собраны и их состав и метаданные просмотрены на Python 3.13.14; установка с зависимостями в чистые окружения пока не подтверждена: в локальном offline-кеше отсутствует `aiocache`. Диапазоны зависимостей и необходимость `aiocache` требуют отдельной проверки до выпуска.

```bash
make build       # собрать wheel и sdist в dist/
make push        # проверить проект, собрать заново и опубликовать на PyPI
```

**`make push` действительно публикует пакет в публичный PyPI.** Перед запуском проверьте имя пакета `damia-sdk`, его доступность и права, версию в `pyproject.toml`, содержимое сборки и возможность публичного распространения. Имя выбрано для каркаса; его доступность и права на него не проверялись. PyPI не позволяет повторно загрузить уже опубликованный файл той же версии; при частичной неудаче проверьте состояние проекта на PyPI перед повторной попыткой.

Для локальной публикации настройте токен PyPI в переменной окружения `POETRY_PYPI_TOKEN_PYPI` или `UV_PUBLISH_TOKEN` либо используйте поддерживаемую uv доверенную публикацию. Непустая `POETRY_PYPI_TOKEN_PYPI` имеет приоритет над `UV_PUBLISH_TOKEN`; если она не задана или пуста, uv использует обычный механизм авторизации, включая `UV_PUBLISH_TOKEN` и доверенную публикацию. Не записывайте токен в файлы проекта, команду или логи. `make push` собирает артефакты во временный каталог и не отправляет старые файлы из `dist/`. Команда отправляет wheel и sdist, а не весь репозиторий; состав пакета следует проверять перед публикацией.
