Metadata-Version: 2.4
Name: thzdaqapi
Version: 0.1.0
Summary: Python API for THzDAQ laboratory instruments
Project-URL: Homepage, https://github.com/yarvod/thzdaqapi
Project-URL: Repository, https://github.com/yarvod/thzdaqapi
Project-URL: Issues, https://github.com/yarvod/thzdaqapi/issues
Author: THzDAQ Team
License: MIT
License-File: LICENSE
Keywords: gpib,instrument-control,lab-automation,modbus,thz
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: pymodbus>=3.8
Requires-Dist: pyserial>=3.5
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# thzdaqapi

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

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

## Что внутри

- Полное API-референс-описание сигнатур: [docs/api-reference.md](docs/api-reference.md)
- Подробные device guides:
  - [Agilent](docs/devices/agilent.md)
  - [Arduino Grid](docs/devices/arduino.md)
  - [Chopper](docs/devices/chopper.md)
  - [Keithley](docs/devices/keithley.md)
  - [LakeShore](docs/devices/lakeshore.md)
  - [National Instruments](docs/devices/national-instruments.md)
  - [Pfeiffer](docs/devices/pfeiffer.md)
  - [Rigol](docs/devices/rigol.md)
  - [Rohde & Schwarz](docs/devices/rohde-schwarz.md)
  - [SRS](docs/devices/srs.md)
  - [Scontel SIS Block](docs/devices/scontel.md)
  - [Sumitomo](docs/devices/sumitomo.md)

## Установка

### Runtime

```bash
uv pip install thzdaqapi
```

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

```bash
uv sync --extra dev
```

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

```python
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](docs/api-reference.md).

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

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

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

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

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

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

```bash
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 и маршрутизацию.

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

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