DaMIA SDK
Асинхронный Python SDK и CLI для сервисов DaMIA. Реализованы 61 GET-метод восьми сервисов и общий HTTP-транспорт; CLI вызывает методы SDK.
Проектный дизайн, настройки, HTTP-клиент, CLI и план разработки описаны в docs/PROJECT.md.
Разработка
Требуются Python 3.11+, uv и Make:
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. Подробности — в дизайне проекта.
CLI
В CLI доступны группы fns, rosstat, banks, scoring, procurement, arbitration, fssp и spk и команды для 61 метода SDK:
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 сопоставлены в инвентаре; наблюдаемое поведение ответов и ошибок описано в контракте ответов. Процедура ревью и обновления снимка — в контроле изменений.
Локальные контрактные проверки без Prism и реального API:
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):
make prism-fns
В другом запустите локальный тест с Hypothesis:
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.
E2E-тесты SDK и CLI
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 требуют отдельной проверки до выпуска.
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, а не весь репозиторий; состав пакета следует проверять перед публикацией.
Metadata
Release files for damia-sdk 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| damia_sdk-1.1.0.tar.gz | 25.9 kB | Without provenance | Details for damia_sdk-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| damia_sdk-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for damia_sdk-1.1.0-py3-none-any.whl |
Total release size: 64.0 kB
Release files / damia_sdk-1.1.0.tar.gz
| Download URL | damia_sdk-1.1.0.tar.gz |
|---|---|
| Size | 25.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7ff681f3deda923d9d11e44f7b300359d731d39263c980680e7fa9a3f7b04dcb
|
|
BLAKE2b-256 checksum How to use checksums |
2df8a0c867d9a1b8fd18d8dcdb3a9ccb0fa6f726a2f2820562c49c5322bfa0e1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / damia_sdk-1.1.0-py3-none-any.whl
| Download URL | damia_sdk-1.1.0-py3-none-any.whl |
|---|---|
| Size | 38.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
859cd75f82f029f018d96430b9ebc278e819012863359091dfc6adba8805659e
|
|
BLAKE2b-256 checksum How to use checksums |
ba31c9cf721c8c6e584f6da3d5b8a330bd9b7a2f6ad08745b41aff990fbb0956
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for damia-sdk 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.