Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
218 lines (154 loc) · 8.21 KB

CONTRIBUTING.md

File metadata and controls

218 lines (154 loc) · 8.21 KB

Руководство для контрибьюторов

Спасибо за интерес к проекту! Ниже описано, как внести вклад.

Содержание

Требования

  • Python 3.11+
  • git

Установка для разработки

git clone https://github.com/stemirkhan/suz-sdk-python.git
cd suz-sdk-python

python -m venv .venv
source .venv/bin/activate          # Linux / macOS
# .venv\Scripts\activate           # Windows

pip install -e ".[dev]"

Структура проекта

src/suz_sdk/
├── __init__.py          # публичный API — что экспортируется наружу
├── client.py            # SuzClient — точка входа
├── config.py            # SuzConfig + Environment
├── exceptions.py        # иерархия исключений
├── signing/             # абстракция подписи X-Signature
├── transport/           # HTTP-слой (httpx)
└── api/                 # высокоуровневые методы по группам

tests/                   # pytest-тесты (зеркалируют структуру src/)
docs/                    # исходный PDF и техническое задание

Каждый слой имеет чёткую ответственность — не смешивайте бизнес-логику с HTTP-механикой или подписью.

Правила разработки

Источник истины

Документ docs/API_СУЗ_3.0.pdf и docs/technical_specification.md — единственные авторитетные источники для:

  • URL эндпоинтов и HTTP-методов
  • полей запросов и ответов
  • заголовков и их обязательности
  • логики авторизации и подписи

Не выдумывайте поля, эндпоинты или поведение — только то, что подтверждено документами. Если что-то неясно, оставьте TODO с объяснением.

Что делать, прежде чем писать код

  1. Прочитайте соответствующий раздел PDF.
  2. Изучите существующую структуру — не дублируйте.
  3. Напишите тест до или сразу после реализации.

Чего не делать

  • Не смешивайте HTTP-механику, бизнес-логику и подпись в одном файле.
  • Не хардкодите конкретную крипто-библиотеку — только через BaseSigner.
  • Не логируйте токены, подписи и ключи.
  • Не добавляйте зависимости без явной необходимости.

Тесты

Запуск всех тестов:

pytest

Запуск конкретного файла:

pytest tests/test_health.py -v

Что покрывать тестами

  • Валидацию конфигурации
  • Маппинг HTTP-ошибок в исключения SDK
  • Заголовки запросов (clientToken, X-Signature, Accept)
  • Query-параметры
  • Парсинг ответов
  • Поведение при сетевых ошибках и таймаутах

Для юнит-тестов используйте StubTransport (см. tests/test_health.py). Для тестов транспортного слоя используйте pytest-httpx.

Стиль кода

Проект использует ruff для линтинга и форматирования:

ruff check src/ tests/          # проверка
ruff check --fix src/ tests/    # автоисправление
ruff format src/ tests/         # форматирование

Проверка типов через mypy:

mypy src/

Соглашения

  • Строгая типизация везде (аннотации обязательны).
  • Docstring на английском языке — на всех публичных классах и методах.
  • Комментарии в коде можно писать на русском или английском.
  • Длина строки — 100 символов.

Как отправить изменения

  1. Форкните репозиторий.
  2. Создайте ветку от main: 
    git checkout -b feat/my-feature
  3. Внесите изменения, напишите тесты.
  4. Убедитесь, что всё работает: 
    pytest && ruff check src/ tests/ && mypy src/
  5. Сделайте коммит (см. формат ниже).
  6. Откройте Pull Request в main.

Сообщения о коммитах

Используйте формат Conventional Commits:

<тип>: краткое описание (до 72 символов)

Дополнительный контекст, если нужен.

Типы:

Тип Когда использовать
feat Новая функциональность
fix Исправление ошибки
docs Только документация
test Добавление или исправление тестов
refactor Рефакторинг без изменения поведения
chore Зависимости, конфиги, утилиты

Примеры:

feat: add client.integration.register_connection()
fix: handle empty globalErrors list in transport error mapping
docs: add example for NoopSigner in README
test: cover SuzApiError.raw_body in test_exceptions.py

Открытые задачи

Приоритетные направления для вклада (Итерации 2–5):

Итерация 2 — Авторизация

  • TokenManager с автообновлением, учётом TTL, потокобезопасностью
  • client.integration.register_connection() (POST /api/v3/integration/connection)
  • client.auth.authenticate() — True API (ГИС МТ) и ИС МДЛП

Итерация 3 — Заказы

  • client.orders.create() — создание заказа на эмиссию КМ
  • client.orders.get_status() — статус массива КМ
  • client.orders.get_codes() — получение кодов маркировки
  • client.orders.close() — закрытие заказа

Итерация 4 — Отчёты и квитирование

  • client.reports.send_utilisation() — отчёт об использовании КМ
  • client.reports.get_status() — статус обработки отчёта
  • client.receipts.get() — получение квитанции

Итерация 5 — Полировка

  • Асинхронный клиент (AsyncSuzClient)
  • Адаптер для КриптоПро (CryptoProSigner)
  • Интеграционные тесты против демо-стенда

Прежде чем браться за задачу, откройте issue или уточните в PR, чтобы избежать дублирования работы.