thzdaqapi 0.1.0__tar.gz

thzdaqapi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Format check
+        run: uv run ruff format --check src tests
+
+      - name: Run tests
+        run: uv run pytest -q

thzdaqapi-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,42 @@
+name: Publish PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install build tools
+        run: uv sync --extra dev
+
+      - name: Build package
+        run: uv run python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true

thzdaqapi-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+.idea/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.pre-commit-cache/
+.env
+.env.*

thzdaqapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thzdaqapi-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+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 и маршрутизацию.
+
+### Ответ парсится с ошибкой
+- Убедитесь, что модель прибора совпадает с драйвером.
+- Проверьте версию прошивки.
+- Снимите сырые ответы и сравните с ожидаемым форматом.
+
+### Нестабильные измерения
+- Увеличьте таймауты/паузы.
+- Добавьте повторные запросы и медиану по нескольким чтениям.

thzdaqapi-0.1.0/README.md

@@ -0,0 +1,217 @@
+# 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 и маршрутизацию.
+
+### Ответ парсится с ошибкой
+- Убедитесь, что модель прибора совпадает с драйвером.
+- Проверьте версию прошивки.
+- Снимите сырые ответы и сравните с ожидаемым форматом.
+
+### Нестабильные измерения
+- Увеличьте таймауты/паузы.
+- Добавьте повторные запросы и медиану по нескольким чтениям.