Skip to main content

DaMIA SDK

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

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

Установка

Требуется Python 3.11 или новее:

pip install damia-sdk
damia --help

SDK и CLI выполняют запросы к API DaMIA; для работы нужны настройки и ключи соответствующих сервисов. Вызовы могут быть платными или изменять состояние. Спецификации носят исследовательский характер, совместимость с реальным API не подтверждена.

Лицензия

MIT.

Разработка

Требуются 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 и диапазонов зависимостей ещё не проверен.

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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for damia-sdk 1.1.1
File Size Uploaded Provenance Actions
damia_sdk-1.1.1.tar.gz 26.8 kB Without provenance Details for damia_sdk-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for damia-sdk 1.1.1
File Interpreter ABI Platform Actions
damia_sdk-1.1.1-py3-none-any.whl Python 3 none any Details for damia_sdk-1.1.1-py3-none-any.whl

Total release size: 66.0 kB

Release files / damia_sdk-1.1.1.tar.gz

Download URL damia_sdk-1.1.1.tar.gz
Size 26.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c70bbf734a5c37cff487423127f61d3d2474c48a101735b25626fdfbb8ce6036
BLAKE2b-256 checksum
How to use checksums
6327eea21734bfe57e19363cf86b4ac0fea1e5fc79c42b910592c4bc61cb520a
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.1-py3-none-any.whl

Download URL damia_sdk-1.1.1-py3-none-any.whl
Size 39.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b4b47cda55ef0aaa7e6460b4c73220550012ff58c9bf14f8f6f7a566302a668f
BLAKE2b-256 checksum
How to use checksums
bc65ac35fd8098c014d90f0780b4e779864f2792072dce1e42c38a3feef90ed2
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.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page