plesty-lib 0.2.2__tar.gz → 0.2.3__tar.gz

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/.gitlab-ci.yml

@@ -1,9 +1,9 @@
 stages:
   - check
+  - deploy
   - test
   - build
   - release
-  - deploy
 
 variables:
   # Required for versioningit: the runner must fetch full Git history and tags.
@@ -14,24 +14,31 @@ include:
   - component: $CI_SERVER_FQDN/plesty/plesty-ci/check-compliance@main
     inputs:
       stage: check
+  
+    # Deploy documentation to dedicated documentation branch
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/deploy-docs@main
+    inputs:
+      stage: deploy
+      access_token: $CI_BOT_TOKEN
+
+  # Run tests
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/run-tests@main
+    inputs:
+      stage: test
+      job_name: run-tests
 
   # Build Python package and expose dist/ as an artifact
-  - component: $CI_SERVER_FQDN/plesty/plesty-ci/build-pkg@feature/release_tag
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/build-pkg@main
     inputs:
       stage: build
       job_name: build-pkg
 
   # Publish package to PyPI on release tags
-  - component: $CI_SERVER_FQDN/plesty/plesty-ci/publish-pypi@feature/release_tag
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/publish-pypi@main
     inputs:
       stage: release
       pypi_token: $PYPI_TOKEN
       build_job_name: build-pkg
 
-  # Deploy documentation to dedicated documentation branch
-  - component: $CI_SERVER_FQDN/plesty/plesty-ci/deploy-docs@main
-    inputs:
-      stage: deploy
-      access_token: $CI_BOT_TOKEN
 
 

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plesty-lib
-Version: 0.2.2
+Version: 0.2.3
 Summary: A library for the Plesty ecosystem.
 Author-email: Yunshuang Yuan <yunshuang.yuan@fkp.uni-hannover.de>
 Maintainer-email: Plesty Development Team <yunshuang.yuan@fkp.uni-hannover.de>
@@ -57,7 +57,7 @@ pip install plesty-sdk
 ### 1. Create a device class from a base device
 
 ```python
-from plestylib.device.base_visa_scpi_device import BaseVisaScpiDevice
+from plesty.lib.device.base_visa_scpi_device import BaseVisaScpiDevice
 
 
 class PowermeterDevice(BaseVisaScpiDevice):

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/README.md

@@ -39,7 +39,7 @@ pip install plesty-sdk
 ### 1. Create a device class from a base device
 
 ```python
-from plestylib.device.base_visa_scpi_device import BaseVisaScpiDevice
+from plesty.lib.device.base_visa_scpi_device import BaseVisaScpiDevice
 
 
 class PowermeterDevice(BaseVisaScpiDevice):

plesty_lib-0.2.3/conftest.py

@@ -0,0 +1,64 @@
+"""Development import hook for editable installs.
+
+Maps ``plesty`` → synthetic namespace package and ``plesty.lib.*`` → ``lib.*``
+so that tests can use the canonical ``plesty.lib`` import path without
+requiring a built wheel or extra directories in the project tree.
+
+This file is loaded automatically by pytest and has no effect on installed
+packages (the wheel's sources mapping handles that path).
+"""
+
+import sys
+import types
+import importlib
+import importlib.abc
+import importlib.machinery
+import importlib.util
+
+
+class _Loader(importlib.abc.Loader):
+    """Return an already-imported module so Python uses it under the aliased name."""
+
+    def __init__(self, module):
+        self._module = module
+
+    def create_module(self, spec):
+        return self._module
+
+    def exec_module(self, module):
+        pass
+
+
+class _PlestyLibDevFinder(importlib.abc.MetaPathFinder):
+    """Redirect ``plesty.lib.*`` imports to ``lib.*`` for editable installs."""
+
+    def find_spec(self, fullname, path, target=None):
+        # Synthesize the ``plesty`` namespace package on demand.
+        if fullname == "plesty":
+            if "plesty" in sys.modules:
+                return sys.modules["plesty"].__spec__
+            ns = types.ModuleType("plesty")
+            ns.__path__ = []
+            ns.__package__ = "plesty"
+            spec = importlib.machinery.ModuleSpec("plesty", loader=None, is_package=True)
+            ns.__spec__ = spec
+            sys.modules["plesty"] = ns
+            return spec
+
+        if fullname == "plesty.lib" or fullname.startswith("plesty.lib."):
+            target_name = "lib" + fullname[len("plesty.lib"):]
+            if target_name in sys.modules:
+                sys.modules[fullname] = sys.modules[target_name]
+                return sys.modules[target_name].__spec__
+            try:
+                mod = importlib.import_module(target_name)
+            except ImportError:
+                return None
+            sys.modules[fullname] = mod
+            return importlib.util.spec_from_loader(fullname, _Loader(mod))
+
+        return None
+
+
+if not any(isinstance(f, _PlestyLibDevFinder) for f in sys.meta_path):
+    sys.meta_path.insert(0, _PlestyLibDevFinder())

plesty_lib-0.2.3/docs/api_reference.md

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

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/docs/device/base_device.md

@@ -19,6 +19,7 @@ When your device class inherits from `BaseDeviceSyncModel`, you get:
 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.
+6. Per-instance resource locking (`_locked_resources`, `_clients`) for multi-client access control.
 
 ## Typical Layering
 
@@ -73,9 +74,9 @@ with MyDevice("dev-id") as dev:
 ```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
+from plesty.lib.device.base_device_sync import BaseDeviceSyncModel
+from plesty.lib.traffic.serial import SerialTrafficManager
+from plesty.lib.solver.scpi import SCPISolver
 
 
 class MyScpiSerialDevice(BaseDeviceSyncModel):
@@ -145,7 +146,7 @@ Example with `AsyncWrapperSafe`:
 
 ```python
 import asyncio
-from plestylib.device.async_wrapper import AsyncWrapperSafe
+from plesty.lib.device.async_wrapper import AsyncWrapperSafe
 
 
 async def main():
@@ -157,6 +158,35 @@ async def main():
 asyncio.run(main())
 ```
 
+## Multi-Client Resource Control
+
+`BaseDeviceSyncModel` carries three resource-tracking attributes that support exclusive access
+control when a device is shared by multiple clients (for example, over a TCP/IP service):
+
+| Attribute | Type | Purpose |
+|---|---|---|
+| `_resources` | `list` | Hardware resources registered for automatic release on disconnect |
+| `_locked_resources` | `set` | Resources that are currently allocated to any client |
+| `_clients` | `dict` | Maps `client_id → [allocated resources]` |
+
+These attributes mirror the `ResourceManager` pattern from `plesty.lib.service.resource_manager`.
+You can compose a `ResourceManager` inside your device subclass and delegate to its methods, or
+override `_user_permission_check` to enforce access rules based on the per-instance state.
+
+The default `_user_permission_check` always returns `True` (no restriction). Override it to
+implement real guard logic:
+
+```python
+def _user_permission_check(self, user_resources: list, key: str) -> bool:
+    if not user_resources:
+        return True
+    return any(r in self._locked_resources for r in user_resources)
+```
+
+Both `write` and `query` pass a `resources` kwarg through to `_user_permission_check` when the
+caller supplies it, so access control integrates transparently with the standard operation
+interface.
+
 ## Best Practices
 
 1. Keep transport logic in traffic managers, not in device classes.

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/docs/device/cmd_solver.md

@@ -21,7 +21,7 @@ A command solver typically handles:
 
 ## Solver Types in PlestyLib
 
-The base interfaces are in `plestylib.solver`:
+The base interfaces are in `plesty.lib.solver`:
 
 1. `CmdSolver`: parameter-centric command generation.
 2. `OpSolver`: operation/message-centric translation.
@@ -45,7 +45,7 @@ Use this for protocol layers that operate on operation messages rather than dire
 
 ## Built-in Example: SCPISolver
 
-`SCPISolver` (in `plestylib.solver.scpi`) is a `CmdSolver` implementation used by SCPI devices.
+`SCPISolver` (in `plesty.lib.solver.scpi`) is a `CmdSolver` implementation used by SCPI devices.
 
 Behavior highlights:
 
@@ -66,8 +66,8 @@ This means your concrete device class usually only needs to register parameters
 ## Demo 1: Use SCPISolver Directly
 
 ```python
-from plestylib.solver.scpi import SCPISolver
-from plestylib.device.params import ConfigParameter
+from plesty.lib.solver.scpi import SCPISolver
+from plesty.lib.device.params import ConfigParameter
 
 solver = SCPISolver()
 
@@ -95,8 +95,8 @@ Use a custom solver when your protocol syntax is not SCPI-compatible.
 ```python
 from typing import Any
 
-from plestylib.solver import CmdSolver
-from plestylib.device.params import ConfigParameter
+from plesty.lib.solver import CmdSolver
+from plesty.lib.device.params import ConfigParameter
 
 
 class KVTextSolver(CmdSolver):
@@ -118,7 +118,7 @@ class KVTextSolver(CmdSolver):
 `ICEBLOCKSolver` is an operation-style solver that builds compact JSON messages with transmission IDs and includes helpers for response decoding and status checks.
 
 ```python
-from plestylib.solver.iceblock import ICEBLOCKSolver
+from plesty.lib.solver.iceblock import ICEBLOCKSolver
 
 solver = ICEBLOCKSolver()
 msg = solver.get_startLink_cmd("192.168.1.20")

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/docs/device/error_handling.md

@@ -1,6 +1,6 @@
 # Error Handling
 
-PlestyLib centralizes most runtime error behavior through `handle_error` in `plestylib.utils.error_utils`.
+PlestyLib centralizes most runtime error behavior through `handle_error` in `plesty.lib.utils.error_utils`.
 
 This utility standardizes logging and exception raising across device, traffic, and solver layers.
 
@@ -56,17 +56,17 @@ This project uses `handle_error` to:
 
 You can see usage in:
 
-1. Traffic managers (`plestylib/traffic`).
-2. Base device classes (`plestylib/device/base_*`).
-3. Solvers (`plestylib/solver`).
-4. Parameter system (`plestylib/device/params.py`).
+1. Traffic managers (`plesty/lib/traffic`).
+2. Base device classes (`plesty/lib/device/base_*`).
+3. Solvers (`plesty/lib/solver`).
+4. Parameter system (`plesty/lib/device/params.py`).
 
 ## Usage Examples
 
 ### Re-raise the original exception
 
 ```python
-from plestylib.utils.error_utils import handle_error
+from plesty.lib.utils.error_utils import handle_error
 
 try:
 	risky_call()
@@ -77,7 +77,7 @@ except Exception as e:
 ### Raise a contextual runtime error with chained cause
 
 ```python
-from plestylib.utils.error_utils import handle_error
+from plesty.lib.utils.error_utils import handle_error
 
 try:
 	device.connect()
@@ -88,7 +88,7 @@ except Exception as e:
 ### Warning-only mode (rare)
 
 ```python
-from plestylib.utils.error_utils import handle_error
+from plesty.lib.utils.error_utils import handle_error
 
 try:
 	optional_background_task()

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/docs/device/func_system.md

@@ -4,7 +4,7 @@ The function system is the operation layer used by device APIs in PlestyLib.
 
 It lets you define operation signatures with structured input and output metadata, then automatically exposes callable methods with validation, casting, and optional response parsing.
 
-Core implementation: `FunctionSystem` in `plestylib.device.funcs`.
+Core implementation: `FunctionSystem` in `plesty.lib.device.funcs`.
 
 ## What It Does
 
@@ -82,7 +82,7 @@ Registered operation methods support all three styles:
 ## Register Operations Programmatically
 
 ```python
-from plestylib.device.funcs import FunctionSystem, FuncParam, FuncOutput
+from plesty.lib.device.funcs import FunctionSystem, FuncParam, FuncOutput
 
 
 def fake_solver(request: dict) -> dict:
@@ -138,7 +138,7 @@ Example schema:
 Load from file:
 
 ```python
-from plestylib.device.funcs import FunctionSystem
+from plesty.lib.device.funcs import FunctionSystem
 
 fs = FunctionSystem(solver=my_solver)
 registered = fs.register_from_op_schema("op_schema.json")
@@ -156,7 +156,7 @@ Notes:
 Bind a parser when raw solver responses need custom transformation:
 
 ```python
-from plestylib.device.device_utils import ResponseParser
+from plesty.lib.device.device_utils import ResponseParser
 
 
 class MyParser(ResponseParser):
@@ -206,7 +206,7 @@ fs.func_summary(style="md", filename="ops.md")
 Example:
 
 ```python
-from plestylib.device.base_device_sync import BaseDeviceSyncModel
+from plesty.lib.device.base_device_sync import BaseDeviceSyncModel
 
 
 class MyDevice(BaseDeviceSyncModel):

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/docs/device/index.md

@@ -9,7 +9,7 @@ If you are building a new device API, read in this order:
 5. [Traffic Manager](traffic_manager.md)
 6. [Error Handling](error_handling.md)
 7. [Logging System](logging_system.md)
-8. [Auto Test](auto_test.md)
+8. [Test Helpers](test_helper.md)
 
 ## Topic Guide
 
@@ -28,5 +28,5 @@ If you are building a new device API, read in this order:
 
 1. [Error Handling](error_handling.md): Standard error propagation and contextual wrapping.
 2. [Logging System](logging_system.md): Process-level logging setup and usage patterns.
-3. [Auto Test](auto_test.md): Automated smoke tests for configuration and operation workflows.
+3. [Test Helpers](test_helper.md): Auto-test utilities for config parameters, operations, resource contention, and schema refresh.
 

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/docs/device/logging_system.md

@@ -2,7 +2,7 @@
 
 PlestyLib uses Python built-in logging throughout device, traffic, service, and utility layers.
 
-Central setup helper: `setup_logging` in `plestylib.utils.logger`.
+Central setup helper: `setup_logging` in `plesty.lib.utils.logger`.
 
 ## Purpose
 
@@ -16,7 +16,7 @@ The logging system is used to:
 ## Setup API
 
 ```python
-from plestylib.utils.logger import setup_logging
+from plesty.lib.utils.logger import setup_logging
 
 setup_logging(app_name="powermeter", level="INFO", console_print=True)
 ```
@@ -46,7 +46,7 @@ When `setup_logging` runs:
 ## Minimal Example
 
 ```python
-from plestylib.utils.logger import setup_logging
+from plesty.lib.utils.logger import setup_logging
 
 setup_logging(app_name="pm100d", level="DEBUG", console_print=True)
 
@@ -59,7 +59,7 @@ Call setup once at process startup, before creating device instances:
 
 ```python
 import logging
-from plestylib.utils.logger import setup_logging
+from plesty.lib.utils.logger import setup_logging
 from powermeter_device import PowermeterDevice
 
 setup_logging(app_name="powermeter_service", level="INFO", console_print=True)
@@ -76,7 +76,7 @@ Use this pattern when building or debugging a new device API implementation.
 
 ```python
 import logging
-from plestylib.device.base_tcp_scpi_device import BaseTCPScpiDevice
+from plesty.lib.device.base_tcp_scpi_device import BaseTCPScpiDevice
 
 
 class DemoScpiDevice(BaseTCPScpiDevice):
@@ -107,7 +107,7 @@ Use this pattern in production-like scripts where operators mainly need status a
 ```python
 import logging
 
-from plestylib.utils.logger import setup_logging
+from plesty.lib.utils.logger import setup_logging
 from powermeter_device import PowermeterDevice
 
 

{plesty_lib-0.2.2 → plesty_lib-0.2.3}/docs/device/param_system.md

@@ -4,7 +4,7 @@ The parameter system is the metadata and validation layer used by device classes
 
 It defines what can be queried or written, validates user input, stores cached values, and supports typed parsing of device responses.
 
-Core implementation: `ConfigSystem` in `plestylib.device.params`.
+Core implementation: `ConfigSystem` in `plesty.lib.device.params`.
 
 ## What It Does
 
@@ -59,7 +59,7 @@ Command metadata object used in grouped schemas:
 ## Register Parameters in Code
 
 ```python
-from plestylib.device.base_visa_scpi_device import BaseVisaScpiDevice
+from plesty.lib.device.base_visa_scpi_device import BaseVisaScpiDevice
 
 
 class PowermeterDevice(BaseVisaScpiDevice):
@@ -95,7 +95,7 @@ class PowermeterDevice(BaseVisaScpiDevice):
 Load schema from file path or dictionary:
 
 ```python
-from plestylib.device.params import ConfigSystem
+from plesty.lib.device.params import ConfigSystem
 
 cfg = ConfigSystem(param_schema="param_schema.json")
 # or
@@ -105,7 +105,7 @@ cfg = ConfigSystem(param_schema="param_schema.json")
 Load schema directly in a base-device constructor (`BaseDeviceSyncModel`):
 
 ```python
-from plestylib.device.base_device_sync import BaseDeviceSyncModel
+from plesty.lib.device.base_device_sync import BaseDeviceSyncModel
 
 
 class MyDevice(BaseDeviceSyncModel):
@@ -197,7 +197,7 @@ If needed, provide a custom parser in parameter metadata via `parser`.
 ## Minimal End-to-End Example
 
 ```python
-from plestylib.device.params import ConfigSystem
+from plesty.lib.device.params import ConfigSystem
 
 system = ConfigSystem()