capva 0.1.0__tar.gz

capva-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lin Wang
+
+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.

capva-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: capva
+Version: 0.1.0
+Summary: EPICS PV client supporting both Channel Access and PV Access
+Author: Lin Wang
+License: MIT
+Project-URL: Homepage, https://github.com/wanglin86769/capva
+Keywords: epics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyepics>=3.5.10
+Requires-Dist: p4p>=4.2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# capva
+
+Unified Python client for EPICS PVs over **Channel Access (CA)** and **PV Access (PVA)**.
+
+capva wraps [pyepics](https://github.com/pyepics/pyepics) and [p4p](https://github.com/epics-base/p4p) behind one API. Reads and monitors return a structured **`PVData`** model; JSON/Web payloads are built with **`PVData.to_dict()`** (optional base64 array encoding).
+
+**Developed from the [weiss](https://github.com/weiss-controls/weiss) project** — capva builds on that codebase and refactors the PV client layer into a standalone Python library with a unified CA/PVA API and structured `PVData`.
+
+```mermaid
+flowchart TB
+  subgraph capva["capva — standalone PV client library"]
+    api["PV, PVPool, tools"]
+    prov["CA_PV, PVA_PV"]
+    data["pv_parser, PVData"]
+  end
+
+  subgraph drivers["protocol drivers"]
+    direction LR
+    pyepics["pyepics (CA)"]
+    p4p["p4p (PVA)"]
+  end
+
+  epics["EPICS IOC"]
+
+  prov --> pyepics
+  prov --> p4p
+  pyepics --> epics
+  p4p --> epics
+```
+
+## Features
+
+- **Single API for CA and PVA** — One client for Channel Access and PV Access; capva picks the backend from the PV name so application code does not split into separate CA/PVA paths.
+- **Unified `PVData` model** — Every read and monitor callback returns the same structured snapshot (value, alarm, timeStamp, display, control, …), regardless of protocol.
+- **Public interfaces: `PV`, `PVPool`, and procedural tools** — Use the object API for multi-step work on one connection, `PVPool` when several callers share a PV, or one-shot `pvget` / `pvput` / `pvinfo` / `pvmonitor` when a script only needs a single operation.
+- **Reference-counted `PVPool`** — `getPV` / `releasePV` reuse one connection per PV name; the channel closes when the last reference is released.
+- **Protocol prefixes** — `ca://…` for Channel Access, `pva://…` for PV Access, or no prefix to default to CA.
+
+## Requirements
+
+- Python ≥ 3.10
+
+## Installation
+
+From [PyPI](https://pypi.org/project/capva/):
+
+```bash
+pip install capva
+```
+
+From a checkout (development):
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+Examples use `pva://calcExample`; switch to `ca://…` or a bare name (CA default) as needed.
+
+### Procedural API
+
+```python
+import time
+
+from capva import PVData, pvget, pvmonitor
+
+PV_NAME = "pva://calcExample"
+
+data = pvget(PV_NAME)
+print(data.value)
+
+def on_update(data: PVData) -> None:
+    if data.is_disconnected():
+        print(f"{data.pvName} disconnected")
+    else:
+        print(data.value)
+
+session = pvmonitor(PV_NAME, on_update)
+try:
+    time.sleep(30)
+finally:
+    session.close()
+```
+
+### Object API
+
+```python
+import time
+
+from capva import PV, PVData
+
+PV_NAME = "pva://calcExample"
+
+pv = PV(PV_NAME)
+handle = None
+try:
+    data = pv.get()
+    print(data.value)
+
+    def on_update(data: PVData) -> None:
+        if data.is_disconnected():
+            print(f"{data.pvName} disconnected")
+        else:
+            print(data.value)
+
+    handle = pv.monitor(on_update)
+    time.sleep(30)
+finally:
+    if handle is not None:
+        pv.clear_monitor(handle)
+    pv.close()
+```
+
+### PVPool
+
+```python
+from capva import PVPool
+
+PV_NAME = "pva://calcExample"
+
+pv1 = PVPool.getPV(PV_NAME)
+pv2 = PVPool.getPV(PV_NAME)
+try:
+    print(pv1 is pv2)  # same pooled instance
+    print(pv1.get().value)
+finally:
+    PVPool.releasePV(pv1)
+    PVPool.releasePV(pv2)
+```
+
+### `PVData.to_dict` modes
+
+| `mode` | Use case |
+|--------|----------|
+| `"full"` | Complete snapshot (value, alarm, timeStamp, display, control, …) |
+| `"update"` | Monitor/Web push (no metadata fields) |
+| `"metadata"` | display / control / valueAlarm only |
+
+Set `base64_encode=True` on `"full"` or `"update"` to emit `b64arr` / `b64dtype` instead of a numeric array `value`.
+
+## Project layout
+
+```
+src/capva/
+  pv.py, pv_data.py      # Public PV + PVData model
+  pv_parser.py           # CA/PVA → PVData
+  tools.py               # pvget, pvput, pvinfo, pvmonitor
+  pool.py                # PVPool
+  providers/             # ca_pv, pva_pv
+examples/
+  tool_*.py              # Procedural tools (one-shot)
+  pv_*.py                # PV class API
+  pool_*.py              # PVPool (shared connections)
+tests/                   # Unit tests (mocked; no IOC required)
+```
+
+## Examples
+
+Edit `PV_NAME` at the top of each script, then run against a real IOC:
+
+```bash
+# Procedural tools
+python examples/tool_get.py
+python examples/tool_info.py
+python examples/tool_put.py
+python examples/tool_monitor.py
+
+# PV class
+python examples/pv_get.py
+python examples/pv_info.py
+python examples/pv_put.py
+python examples/pv_monitor.py
+
+# PVPool
+python examples/pool_get.py
+python examples/pool_info.py
+python examples/pool_put.py
+python examples/pool_monitor.py
+
+# Web JSON payload (wfExample waveform PV + Node.js)
+python examples/encode_array.py
+node examples/decode_array.js
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

capva-0.1.0/README.md

@@ -0,0 +1,188 @@
+# capva
+
+Unified Python client for EPICS PVs over **Channel Access (CA)** and **PV Access (PVA)**.
+
+capva wraps [pyepics](https://github.com/pyepics/pyepics) and [p4p](https://github.com/epics-base/p4p) behind one API. Reads and monitors return a structured **`PVData`** model; JSON/Web payloads are built with **`PVData.to_dict()`** (optional base64 array encoding).
+
+**Developed from the [weiss](https://github.com/weiss-controls/weiss) project** — capva builds on that codebase and refactors the PV client layer into a standalone Python library with a unified CA/PVA API and structured `PVData`.
+
+```mermaid
+flowchart TB
+  subgraph capva["capva — standalone PV client library"]
+    api["PV, PVPool, tools"]
+    prov["CA_PV, PVA_PV"]
+    data["pv_parser, PVData"]
+  end
+
+  subgraph drivers["protocol drivers"]
+    direction LR
+    pyepics["pyepics (CA)"]
+    p4p["p4p (PVA)"]
+  end
+
+  epics["EPICS IOC"]
+
+  prov --> pyepics
+  prov --> p4p
+  pyepics --> epics
+  p4p --> epics
+```
+
+## Features
+
+- **Single API for CA and PVA** — One client for Channel Access and PV Access; capva picks the backend from the PV name so application code does not split into separate CA/PVA paths.
+- **Unified `PVData` model** — Every read and monitor callback returns the same structured snapshot (value, alarm, timeStamp, display, control, …), regardless of protocol.
+- **Public interfaces: `PV`, `PVPool`, and procedural tools** — Use the object API for multi-step work on one connection, `PVPool` when several callers share a PV, or one-shot `pvget` / `pvput` / `pvinfo` / `pvmonitor` when a script only needs a single operation.
+- **Reference-counted `PVPool`** — `getPV` / `releasePV` reuse one connection per PV name; the channel closes when the last reference is released.
+- **Protocol prefixes** — `ca://…` for Channel Access, `pva://…` for PV Access, or no prefix to default to CA.
+
+## Requirements
+
+- Python ≥ 3.10
+
+## Installation
+
+From [PyPI](https://pypi.org/project/capva/):
+
+```bash
+pip install capva
+```
+
+From a checkout (development):
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+Examples use `pva://calcExample`; switch to `ca://…` or a bare name (CA default) as needed.
+
+### Procedural API
+
+```python
+import time
+
+from capva import PVData, pvget, pvmonitor
+
+PV_NAME = "pva://calcExample"
+
+data = pvget(PV_NAME)
+print(data.value)
+
+def on_update(data: PVData) -> None:
+    if data.is_disconnected():
+        print(f"{data.pvName} disconnected")
+    else:
+        print(data.value)
+
+session = pvmonitor(PV_NAME, on_update)
+try:
+    time.sleep(30)
+finally:
+    session.close()
+```
+
+### Object API
+
+```python
+import time
+
+from capva import PV, PVData
+
+PV_NAME = "pva://calcExample"
+
+pv = PV(PV_NAME)
+handle = None
+try:
+    data = pv.get()
+    print(data.value)
+
+    def on_update(data: PVData) -> None:
+        if data.is_disconnected():
+            print(f"{data.pvName} disconnected")
+        else:
+            print(data.value)
+
+    handle = pv.monitor(on_update)
+    time.sleep(30)
+finally:
+    if handle is not None:
+        pv.clear_monitor(handle)
+    pv.close()
+```
+
+### PVPool
+
+```python
+from capva import PVPool
+
+PV_NAME = "pva://calcExample"
+
+pv1 = PVPool.getPV(PV_NAME)
+pv2 = PVPool.getPV(PV_NAME)
+try:
+    print(pv1 is pv2)  # same pooled instance
+    print(pv1.get().value)
+finally:
+    PVPool.releasePV(pv1)
+    PVPool.releasePV(pv2)
+```
+
+### `PVData.to_dict` modes
+
+| `mode` | Use case |
+|--------|----------|
+| `"full"` | Complete snapshot (value, alarm, timeStamp, display, control, …) |
+| `"update"` | Monitor/Web push (no metadata fields) |
+| `"metadata"` | display / control / valueAlarm only |
+
+Set `base64_encode=True` on `"full"` or `"update"` to emit `b64arr` / `b64dtype` instead of a numeric array `value`.
+
+## Project layout
+
+```
+src/capva/
+  pv.py, pv_data.py      # Public PV + PVData model
+  pv_parser.py           # CA/PVA → PVData
+  tools.py               # pvget, pvput, pvinfo, pvmonitor
+  pool.py                # PVPool
+  providers/             # ca_pv, pva_pv
+examples/
+  tool_*.py              # Procedural tools (one-shot)
+  pv_*.py                # PV class API
+  pool_*.py              # PVPool (shared connections)
+tests/                   # Unit tests (mocked; no IOC required)
+```
+
+## Examples
+
+Edit `PV_NAME` at the top of each script, then run against a real IOC:
+
+```bash
+# Procedural tools
+python examples/tool_get.py
+python examples/tool_info.py
+python examples/tool_put.py
+python examples/tool_monitor.py
+
+# PV class
+python examples/pv_get.py
+python examples/pv_info.py
+python examples/pv_put.py
+python examples/pv_monitor.py
+
+# PVPool
+python examples/pool_get.py
+python examples/pool_info.py
+python examples/pool_put.py
+python examples/pool_monitor.py
+
+# Web JSON payload (wfExample waveform PV + Node.js)
+python examples/encode_array.py
+node examples/decode_array.js
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

capva-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "capva"
+version = "0.1.0"
+description = "EPICS PV client supporting both Channel Access and PV Access"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Lin Wang"},
+]
+keywords = ["epics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "pyepics>=3.5.10",
+    "p4p>=4.2.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/wanglin86769/capva"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

capva-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

capva-0.1.0/src/capva/__init__.py

@@ -0,0 +1,37 @@
+"""
+capva - Unified EPICS Process Variable client (CA + PVA).
+
+Supports both Channel Access (CA) and PV Access (PVA) with a single, consistent API.
+Automatically selects the optimal backend: p4p for PVA, pyepics for CA.
+"""
+
+from .constants import DEFAULT_IO_TIMEOUT
+from .pv import PV
+from .pv_data import PVData
+from .pool import PVPool
+from .monitor_handle import MonitorHandle
+from .tools import MonitorSession, pvget, pvinfo, pvmonitor, pvput
+from .exceptions import (
+    EPICSProtocolError,
+    EPICSConnectionError,
+    EPICSGetError,
+    EPICSPutError,
+    EPICSTimeoutError,
+)
+
+__all__ = [
+    "PV",
+    "PVData",
+    "PVPool",
+    "MonitorHandle",
+    "pvget",
+    "pvput",
+    "pvinfo",
+    "MonitorSession",
+    "pvmonitor",
+    "EPICSProtocolError",
+    "EPICSConnectionError",
+    "EPICSGetError",
+    "EPICSPutError",
+    "EPICSTimeoutError",
+]

capva-0.1.0/src/capva/array_b64.py

@@ -0,0 +1,40 @@
+"""Numeric array base64 encoding for PV value."""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, List, Optional, Union
+
+import numpy as np
+
+
+def _numeric_array_to_base64(array: Union[List, np.ndarray], dtype: str) -> str:
+    arr = np.asarray(array, dtype=dtype)
+    if arr.dtype.byteorder not in ("<", "="):
+        arr = arr.astype("<" + arr.dtype.str[1:])
+    return base64.b64encode(arr.tobytes()).decode("ascii")
+
+
+def encode_array(arr: Any) -> tuple[Optional[str], Optional[str]]:
+    """Returns (b64arr, b64dtype) for numeric arrays."""
+    if arr is None:
+        return None, None
+
+    arr = np.asarray(arr)
+    if arr.size == 0:
+        return None, None
+
+    if np.issubdtype(arr.dtype, np.floating):
+        return _numeric_array_to_base64(arr, "float64"), "float64"
+
+    if np.issubdtype(arr.dtype, np.integer):
+        min_val, max_val = arr.min(), arr.max()
+        if -128 <= min_val <= max_val <= 127:
+            dtype = "int8"
+        elif -32768 <= min_val <= max_val <= 32767:
+            dtype = "int16"
+        else:
+            dtype = "int32"
+        return _numeric_array_to_base64(arr, dtype), dtype
+
+    return None, None

capva-0.1.0/src/capva/constants.py

@@ -0,0 +1,3 @@
+"""Shared constants for capva."""
+
+DEFAULT_IO_TIMEOUT: float = 5.0

capva-0.1.0/src/capva/exceptions.py

@@ -0,0 +1,26 @@
+"""Custom exceptions for capva."""
+
+
+class EPICSProtocolError(Exception):
+    """Raised when protocol detection or selection fails."""
+    pass
+
+
+class EPICSConnectionError(Exception):
+    """Raised when connection to PV fails."""
+    pass
+
+
+class EPICSGetError(Exception):
+    """Raised when a get operation fails after the PV is reachable."""
+    pass
+
+
+class EPICSPutError(Exception):
+    """Raised when a put operation fails after the PV is reachable."""
+    pass
+
+
+class EPICSTimeoutError(Exception):
+    """Raised when PV operation times out."""
+    pass

capva-0.1.0/src/capva/monitor_handle.py

@@ -0,0 +1,13 @@
+"""Opaque handle for PV monitor subscriptions.
+
+MonitorHandle stores two values returned from provider ``monitor()`` calls:
+
+- owner: the CAPV or PVAPV instance that created this subscription
+- handle: CA callback index (int) or p4p Subscription, depending on protocol
+"""
+
+
+class MonitorHandle:
+    def __init__(self, owner, handle):
+        self._owner = owner
+        self._handle = handle

capva-0.1.0/src/capva/pool.py

@@ -0,0 +1,66 @@
+"""Reference-counted pool of PV instances keyed by protocol and name."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import threading
+from typing import Dict, List, Tuple
+
+from .protocol import pvname_key
+from .pv import PV
+
+
+def _pool_key_from_pv(pv: PV) -> str:
+    return f"{pv.protocol}:{pv.pvname}"
+
+
+@dataclass
+class _PoolEntry:
+    pv: PV
+    refs: int = 0
+
+
+class PVPool:
+    _lock = threading.Lock()
+    _entries: Dict[str, _PoolEntry] = {}
+
+    @classmethod
+    def getPV(cls, pvname: str) -> PV:
+        if not pvname or not pvname.strip():
+            raise ValueError("pvname must be a non-empty string")
+
+        key = pvname_key(pvname)
+        with cls._lock:
+            entry = cls._entries.get(key)
+            if entry is None:
+                entry = _PoolEntry(pv=PV(pvname))
+                cls._entries[key] = entry
+            entry.refs += 1
+            return entry.pv
+
+    @classmethod
+    def releasePV(cls, pv: PV) -> None:
+        key = _pool_key_from_pv(pv)
+        with cls._lock:
+            entry = cls._entries.get(key)
+            if entry is None:
+                return
+            entry.refs -= 1
+            if entry.refs <= 0:
+                entry.pv.close()
+                del cls._entries[key]
+
+    @classmethod
+    def getReferenceCount(cls, pvname: str) -> int:
+        key = pvname_key(pvname)
+        with cls._lock:
+            entry = cls._entries.get(key)
+            return entry.refs if entry else 0
+
+    @classmethod
+    def getPVReferences(cls) -> List[Tuple[str, PV, int]]:
+        with cls._lock:
+            return [
+                (key, entry.pv, entry.refs)
+                for key, entry in cls._entries.items()
+            ]

capva-0.1.0/src/capva/protocol.py

@@ -0,0 +1,20 @@
+"""Protocol detection and constants for EPICS PV client."""
+
+from typing import Tuple
+
+CA = "ca"
+PVA = "pva"
+DEFAULT_PROTOCOL = CA
+
+
+def parse_protocol(pv_name: str) -> Tuple[str, str]:
+    if pv_name.startswith("pva://"):
+        return PVA, pv_name[6:]
+    elif pv_name.startswith("ca://"):
+        return CA, pv_name[5:]
+    return DEFAULT_PROTOCOL, pv_name
+
+
+def pvname_key(pvname: str) -> str:
+    protocol, clean_name = parse_protocol(pvname)
+    return f"{protocol}:{clean_name}"

capva-0.1.0/src/capva/providers/__init__.py

@@ -0,0 +1,6 @@
+"""PV implementations for CA and PVA protocols."""
+
+from .ca_pv import CAPV
+from .pva_pv import PVAPV
+
+__all__ = ["CAPV", "PVAPV"]