plesty-lib 0.1.0__tar.gz

plesty_lib-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Custom 
+.deprecated/
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions and shared libraries
+*.so
+*.pyd
+*.dll
+
+# Packaging and build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test and coverage outputs
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Logs and runtime files
+*.log
+*.pid
+
+# IDE/editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db

plesty_lib-0.1.0/.gitlab-ci.yaml

@@ -0,0 +1,4 @@
+include:
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/deploy-docs@main
+    inputs:
+      access_token: $CI_BOT_TOKEN

plesty_lib-0.1.0/.plesty/.gitignore

@@ -0,0 +1 @@
+*

plesty_lib-0.1.0/.plesty/.sdk-version

@@ -0,0 +1 @@
+0.1.0.dev76+5b01a5a

plesty_lib-0.1.0/.plesty/docs-build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: ab3635e821c2cb92234785467f242b10
+tags: 645f666f9bcd5a90fca523b33c5a78b7

plesty_lib-0.1.0/.plesty/docs-build/_sources/api_reference.md.txt

@@ -0,0 +1,15 @@
+# API Reference
+Entry page for [Full API](reference/index) documentation.
+
+## Core Packages
+
+| Package | Description | 
+| --- | --- | 
+| [`plestylib.data`](reference/plestylib/data/index) | Data containers, units, and type helpers 
+| [`plestylib.device`](reference/plestylib/device/index) | Base device model, parameter/function systems, async wrappers |
+| [`plestylib.traffic`](reference/plestylib/traffic/index) | Transport backends (TCP/IP, VISA, Serial) |
+| [`plestylib.solver`](reference/plestylib/solver/index) | Command and operation solvers |
+| [`plestylib.service`](reference/plestylib/service/index) | TCP/IP server/client and service builders |
+| [`plestylib.sim`](reference/plestylib/sim/index) | Synthetic data generation for testing |
+| [`plestylib.utils`](reference/plestylib/utils/index) | Shared utilities (logging, errors, registry, DLL helpers) |
+

plesty_lib-0.1.0/.plesty/docs-build/_sources/device/auto_test.md.txt

@@ -0,0 +1,168 @@
+# Auto Test
+
+PlestyLib includes lightweight auto-test helpers to quickly validate a device API implementation.
+
+These helpers are intended for development-time smoke testing, not full regression testing.
+
+## Available Auto Tests
+
+There are two utilities:
+
+1. Config auto test: validates registered config parameters (read-only, write-only, read-write).
+2. Function auto test: validates registered operations in the function system.
+
+## 1) Config Auto Test (Synchronous Device API)
+
+Utility location:
+
+`plestylib.test.auto_test_sync_device.auto_test`
+
+What it does:
+
+1. Opens the device with context manager.
+2. Prints identity.
+3. Queries all read-only configs.
+4. Writes all write-only configs using defaults or dtype-based fallback values.
+5. Writes and re-queries read-write configs.
+
+Example:
+
+```python
+from plestylib.test.auto_test_sync_device import auto_test
+from powermeter_device import PowermeterDevice
+
+
+auto_test(
+	 PowermeterDevice,
+	 "USB0::0x1313::0x8078::P0000001::INSTR",
+	 sensor_type="S155C",
+)
+```
+
+Notes:
+
+1. For read-write parameters without default value, current queried value is written back.
+2. This avoids guessing unsupported values when device constraints are incomplete.
+
+## 2) Function Auto Test (Operation/Func System)
+
+Utility location:
+
+`plestylib.test.auto_test_func_system.auto_test`
+
+What it does:
+
+1. Opens the device and optionally queries identity.
+2. Enumerates registered operations from `device._functions`.
+3. Generates valid payloads from `FuncParam` metadata.
+4. Calls each operation and checks response shape.
+5. Prints pass/fail summary.
+
+By default it can use a mock operation solver so operation validation can run without real backend behavior.
+
+Example (mock solver mode):
+
+```python
+from plestylib.test.auto_test_func_system import auto_test
+from my_device import MyDevice
+
+
+auto_test(
+	 MyDevice,
+	 "device-id-or-address",
+	 use_mock_solver=True,
+	 seed=123,
+)
+```
+
+Example (real solver mode):
+
+```python
+from plestylib.test.auto_test_func_system import auto_test
+from my_device import MyDevice
+
+
+auto_test(
+	 MyDevice,
+	 "device-id-or-address",
+	 use_mock_solver=False,
+	 ignore_ops=["dangerous_operation"],
+)
+```
+
+## Important Parameters (Function Auto Test)
+
+1. `use_mock_solver`:
+	When true, binds an internal mock solver that generates output-shaped responses from metadata.
+2. `ignore_ops`:
+	List of operation names to skip.
+3. `seed`:
+	Seed for deterministic test payload generation.
+4. `sleep_time`:
+	Delay between operation calls.
+
+## Output Interpretation
+
+Function auto test prints one line per operation:
+
+1. `[PASS] op_name payload=... response=...`
+2. `[FAIL] op_name payload=... error=...`
+
+Then a summary:
+
+1. Passed count
+2. Failed count
+3. Passed operation list
+
+## Recommended Workflow
+
+1. Start with config auto test after registering parameters.
+2. Add function auto test after registering operations.
+3. Run function auto test first with `use_mock_solver=True` to validate schemas.
+4. Then switch to `use_mock_solver=False` for end-to-end backend checks.
+5. Add operation names to `ignore_ops` for stateful or destructive actions.
+
+## Limitations
+
+1. These helpers are print-based and not pytest assertions by default.
+2. They do not replace integration tests for timing, hardware state transitions, or long-running sequences.
+3. Mock mode validates interface contracts, not real protocol/device behavior.
+
+## Using with pytest
+
+You can leverage auto-test utilities inside `pytest` suites in two ways.
+
+### 1. Smoke-test style (no exception means pass)
+
+```python
+from plestylib.test.auto_test_sync_device import auto_test as auto_test_sync
+from plestylib.test.auto_test_func_system import auto_test as auto_test_func
+from my_device import MyDevice
+
+
+def test_config_auto():
+    auto_test_sync(MyDevice, "device-id-or-address")
+
+
+def test_function_auto_mock():
+    auto_test_func(MyDevice, "device-id-or-address", use_mock_solver=True, seed=123)
+```
+
+### 2. Assertion style with pytest output capture
+
+Because these helpers currently print summary lines, use pytest `capsys` to capture stdout and assert summary text.
+
+```python
+from plestylib.test.auto_test_func_system import auto_test
+from my_device import MyDevice
+
+
+def test_no_failed_operations(capsys):
+    auto_test(MyDevice, "device-id-or-address", use_mock_solver=True, seed=123)
+    captured = capsys.readouterr()
+    assert "Failed: 0" in captured.out, captured.out
+```
+
+### Recommendation
+
+For stronger tests, consider extending auto-test helpers to return a summary dictionary (for example passed/failed counts) in addition to printing. Then `pytest` assertions can be done directly without parsing text output.

plesty_lib-0.1.0/.plesty/docs-build/_sources/device/base_device.md.txt

@@ -0,0 +1,167 @@
+# Base Device
+
+`BaseDeviceSyncModel` is the core abstraction for building a synchronized device API in PlestyLib.
+
+It combines:
+
+1. Device lifecycle (`init`, `connect`, `disconnect`)
+2. Parameter system (`ConfigSystem`)
+3. Function system (`FunctionSystem`)
+4. Standardized read/write/query workflow
+5. Resource ownership and context-manager cleanup
+
+## What It Provides
+
+When your device class inherits from `BaseDeviceSyncModel`, you get:
+
+1. Parameter registration, validation, and typed parsing through `ConfigSystem`.
+2. Function registration and invocation metadata through `FunctionSystem`.
+3. Built-in high-level methods such as `write`, `query`, `state`, and `summary`.
+4. Context manager support (`with device:`) that calls `init`, `connect`, and `disconnect`.
+5. Resource tracking through `ResourceRegistry` to avoid duplicate ownership.
+
+## Typical Layering
+
+A concrete device class usually composes three parts:
+
+1. Device class (inherits `BaseDeviceSyncModel`)
+2. Traffic manager (transport I/O)
+3. Command/operation solver (protocol translation)
+
+Data flow:
+
+1. `write("KEY", value)` validates input against parameter metadata.
+2. Device `_write_` builds protocol command and sends it via traffic manager.
+3. `query("KEY")` sends protocol query and converts response to target dtype.
+
+## Required Methods to Implement
+
+Your subclass must implement these methods:
+
+1. `connect(self)`
+2. `disconnect(self)`
+3. `_write_(self, key, value)`
+4. `_query_(self, key)`
+5. `check_errors(self)`
+6. `check_operatability(self)`
+
+Commonly overridden methods:
+
+1. `init(self, main=None)` to create traffic manager and solver objects.
+2. `identity(self)` for model/vendor identification command.
+3. `query_param_range(self, key)` if device can report runtime min/max.
+4. `query_param_options(self, key)` if categorical options are queryable.
+
+## Lifecycle
+
+Recommended lifecycle:
+
+1. Instantiate device object.
+2. Enter context (`with device:`) or call `init()` and `connect()` manually.
+3. Perform `query`/`write` operations.
+4. Call `disconnect()` (automatic when using context manager).
+
+Using context manager is recommended because cleanup is guaranteed:
+
+```python
+with MyDevice("dev-id") as dev:
+	print(dev.query("POWER"))
+```
+
+## Minimal Implementation Example
+
+```python
+from typing import Any
+
+from plestylib.device.base_device_sync import BaseDeviceSyncModel
+from plestylib.traffic.serial import SerialTrafficManager
+from plestylib.solver.scpi import SCPISolver
+
+
+class MyScpiSerialDevice(BaseDeviceSyncModel):
+	def __init__(self, port: str):
+		super().__init__(id=port)
+		self.port = port
+
+		# Register parameters for validation + parsing.
+		self.register_config("POWER", dtype=float, read_only=True, command="MEAS:POW")
+		self.register_config("WAVELENGTH", dtype=int, command="SENS:WAV")
+
+	def init(self, main=None):
+		self.traffic_manager = SerialTrafficManager(
+			port=self.port,
+			baudrate=9600,
+			timeout=5,
+			write_termination="\r",
+			read_termination="\r\n",
+		)
+		self.cmd_solver = SCPISolver()
+
+	def connect(self):
+		return self.traffic_manager.open(parity="none", stopbits="one", bytesize=8)
+
+	def disconnect(self):
+		self.traffic_manager.close()
+
+	def _write_(self, key: str, value: str | float | int | bool) -> bool:
+		cfg = self.get_config(key)
+		command = self.cmd_solver.get_write_cmd(cfg, value)
+		return bool(self.traffic_manager.send_command(command))
+
+	def _query_(self, key: str) -> str:
+		cfg = self.get_config(key)
+		command = self.cmd_solver.get_query_cmd(cfg)
+		return self.traffic_manager.send_command(command)
+
+	def check_errors(self) -> list[str]:
+		# Replace with device-specific error query if available.
+		return []
+
+	def check_operatability(self) -> bool:
+		return self.traffic_manager is not None and self.traffic_manager.is_open
+```
+
+## State and Synchronization Helpers
+
+Useful built-in helpers:
+
+1. `state` / `get_state()`: query all registered parameters and return a dictionary.
+2. `synchronize_param_from_device(keys=None, sync_constraints=False)`: pull current values from hardware into the model.
+3. `summary()`: generate a textual API overview.
+
+If your device supports querying dynamic constraints, implement:
+
+1. `query_param_range` for numeric parameters.
+2. `query_param_options` for categorical parameters.
+
+## Sync vs Async Use
+
+`BaseDeviceSyncModel` is synchronous by design. To use it in async applications, wrap it with one of the provided wrappers.
+
+1. `AsyncWrapperSafe`: thread-offloaded calls protected by an async lock (simple, safe default).
+2. `AsyncDeviceThread`: dedicated worker thread with queued calls (better for high-frequency workflows).
+
+Example with `AsyncWrapperSafe`:
+
+```python
+import asyncio
+from plestylib.device.async_wrapper import AsyncWrapperSafe
+
+
+async def main():
+	async with AsyncWrapperSafe(MyScpiSerialDevice("/dev/ttyUSB0")) as dev:
+		power = await dev.query("POWER")
+		print(power)
+
+
+asyncio.run(main())
+```
+
+## Best Practices
+
+1. Keep transport logic in traffic managers, not in device classes.
+2. Keep protocol formatting/parsing in solvers.
+3. Register all parameters with correct dtype/range/options for safe validation.
+4. Prefer `with device:` for guaranteed cleanup.
+5. Implement `check_operatability` using a real device health query when possible.
+6. Avoid mixing direct synchronous access and async wrapper access on the same device instance.