thzdaqapi 0.1.0

Python API for THzDAQ laboratory instruments

thzdaqapi

Профессиональная Python-библиотека для управления лабораторными THzDAQ-устройствами.

Репозиторий содержит:

• runtime API (src/thzdaqapi),
• документацию по каждому девайсу,
• тесты,
• CI/CD,
• pre-commit конфигурацию для автопроверки и автоформатирования.

Что внутри

• Полное API-референс-описание сигнатур: docs/api-reference.md
• Подробные device guides:
  • Agilent
  • Arduino Grid
  • Chopper
  • Keithley
  • LakeShore
  • National Instruments
  • Pfeiffer
  • Rigol
  • Rohde & Schwarz
  • SRS
  • Scontel SIS Block
  • Sumitomo

Установка

Runtime

uv pip install thzdaqapi

Разработка

uv sync --extra dev

Быстрый старт (правильный порядок)

from thzdaqapi.RohdeSchwarz.vna import VNABlock

# 1) Инициализация
vna = VNABlock(host="169.254.106.189", port=5025)

# 2) Проверка связи
print(vna.idn())
assert vna.test()

# 3) Настройка
vna.set_sweep(801)
vna.set_start_frequency(2e9)
vna.set_stop_frequency(12e9)

# 4) Получение данных
payload = vna.get_data()
print(payload.keys())

Рекомендуемый шаблон для любого девайса:

1. Создать экземпляр класса с правильными host/port/gpib/adapter.
2. Выполнить idn() и/или test().
3. Применить set_* параметры.
4. Считать get_* / measure_* / fetch().
5. Явно закрыть соединение (close() / disconnect()), если метод доступен.

Архитектура и адаптеры

Транспортный слой

Большинство устройств работают через базовый инструментальный слой и адаптеры из thzdaqapi.adapters.

Поддерживаемые типы адаптеров в thzdaqapi.settings:

• SOCKET
• SOCKET_SINGLE
• PROLOGIX_ETHERNET
• PROLOGIX_USB
• HTTP
• SERIAL

Сопоставление тип -> класс задаётся в ADAPTERS.

Конфигурация

• Общие константы/транспорты: thzdaqapi.settings
• Дефолты IP/портов задаются прямо в __init__ конкретных классов устройств
• Параметры Pfeiffer: thzdaqapi.Pfeiffer.parameters (PFEIFFER_PARAMETERS)

Инициализация устройств: что важно

1) Проверяйте параметры подключения

• host: IP прибора или Prologix.
• port: TCP-порт прибора (или COM-порт для serial-классов).
• gpib: адрес прибора на GPIB-шине (если нужен).
• adapter: транспорт (SOCKET, PROLOGIX_ETHERNET, HTTP и т.д.).

2) Запускайте в безопасной последовательности

Для источников/генераторов:

1. Отключённый output.
2. Установка диапазонов/лимитов.
3. Установка целевых значений.
4. Включение output.

3) Всегда валидируйте ответ

• Для методов, возвращающих числа/словарь, проверяйте диапазон и тип.
• Для сетевых/serial нестабильностей используйте retry-логику уровня сценария.

Паттерны работы с методами

Группа set_*

• Изменяют состояние прибора.
• Часто не возвращают значение (None) или возвращают сырую строку статуса.

Группа get_*

• Возвращают текущее значение с устройства.
• Тип зависит от конкретного метода (float, int, str, dict, tuple).

Группа measure_* / fetch()

• Возвращают результат измерения.
• Для плавающих интерфейсов рекомендуется повторная валидация значения.

Очень важные best practices

• Не делайте резких шагов напряжения/тока/мощности.
• На старте работайте с минимальными уровнями.
• Для моторов/чоппера сначала проверяйте нулевую/опорную позицию (set_origin(), align*()).
• Для vacuum/pump устройств учитывайте задержки между командами.
• Логируйте все команды в критических экспериментах.

Подробные документы по девайсам

Каждый файл в docs/devices/*.md включает:

• сигнатуру __init__,
• параметры и defaults,
• таблицу публичных методов,
• сценарий эксплуатации,
• рабочие примеры,
• рекомендации по диагностике.

Если нужна вся поверхность API в одном месте — используйте docs/api-reference.md.

Типизация и IDE-подсказки

Типы указаны прямо в исходниках (.py) — без *.pyi.

Это означает:

• IDE автодополнение читает фактические сигнатуры из runtime-кода,
• меньше риска рассинхрона между реализацией и документацией,
• легче поддерживать при рефакторинге.

Локальная проверка качества

uv sync --extra dev
uv run ruff check src tests
uv run ruff format src tests
uv run pytest -q

Pre-commit (автоформат и проверки перед commit)

uv sync --extra dev
uv run pre-commit install
uv run pre-commit run --all-files

Что запускается:

• check-merge-conflict
• end-of-file-fixer
• trailing-whitespace
• check-yaml
• check-toml
• ruff --fix
• ruff format

CI/CD

Workflow-файлы:

• .github/workflows/ci.yml — линт + тесты на push/PR
• .github/workflows/publish-pypi.yml — публикация в PyPI (release/manual)

Публикация в PyPI

Рекомендуемый сценарий:

1. Настроить Trusted Publishing (OIDC) в PyPI.
2. Создать GitHub Release.
3. Workflow соберёт и опубликует пакет.

Альтернатива: токен через PYPI_API_TOKEN (секрет репозитория).

Частые проблемы и решения

Прибор не отвечает

• Проверьте кабель/порт/IP.
• Проверьте, что порт не занят другим процессом.
• Проверьте firewall и маршрутизацию.

Ответ парсится с ошибкой

• Убедитесь, что модель прибора совпадает с драйвером.
• Проверьте версию прошивки.
• Снимите сырые ответы и сравните с ожидаемым форматом.

Нестабильные измерения

• Увеличьте таймауты/паузы.
• Добавьте повторные запросы и медиану по нескольким чтениям.