capva 0.1.0__py3-none-any.whl

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/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/constants.py

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

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/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/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/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/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"]

capva/providers/ca_pv.py

@@ -0,0 +1,158 @@
+"""EPICS Channel Access (CA) PV implementation using pyepics"""
+
+from typing import Any, Callable
+
+import epics
+from epics.ca import ChannelAccessGetFailure, ChannelAccessException
+from ..constants import DEFAULT_IO_TIMEOUT
+from ..pv_data import PVData
+from ..pv_parser import parse_ca, parse_ca_update, ca_metadata
+from ..monitor_handle import MonitorHandle
+from ..exceptions import EPICSTimeoutError, EPICSConnectionError, EPICSGetError, EPICSPutError
+
+
+class CAPV:
+    def __init__(self, pvname: str):
+        self.pvname = pvname
+        self._pv = epics.PV(pvname)
+        self._monitor_cbs: dict[int, Callable[[PVData], None]] = {}
+
+    def get(self, *, timeout: float = DEFAULT_IO_TIMEOUT) -> PVData:
+        if not self._pv.wait_for_connection(timeout=timeout):
+            raise EPICSConnectionError(f"PV {self.pvname} not connected")
+
+        try:
+            ca_dict = self._pv.get_with_metadata(
+                with_ctrlvars=True,
+                use_monitor=False,
+                timeout=timeout,
+            )
+        except ChannelAccessGetFailure as e:
+            raise EPICSGetError(
+                f"Get failed for {self.pvname}: {e}"
+            )
+        if ca_dict is None:
+            raise EPICSTimeoutError(
+                f"Get operation timed out after {timeout}s for {self.pvname}"
+            )
+        return parse_ca(ca_dict, self.pvname)
+
+    def put(self, value, *, timeout: float = DEFAULT_IO_TIMEOUT, wait: bool = False) -> None:
+        if not self._pv.wait_for_connection(timeout=timeout):
+            raise EPICSConnectionError(f"PV {self.pvname} not connected")
+
+        try:
+            result = self._pv.put(value, wait=wait, timeout=timeout)
+        except ChannelAccessException as e:
+            raise EPICSPutError(f"Put failed for {self.pvname}: {e}")
+
+        if result is None:
+            raise EPICSConnectionError(f"PV {self.pvname} not connected")
+        elif result == 1:
+            pass
+        elif result == -1:
+            if wait:
+                raise EPICSTimeoutError(
+                    f"Put timed out after {timeout}s for {self.pvname}"
+                )
+            raise EPICSPutError(
+                f"Put failed for {self.pvname}: unexpected result {result}"
+            )
+        else:
+            raise EPICSPutError(
+                f"Put failed for {self.pvname}: unexpected result {result}"
+            )
+
+    def info(self, *, timeout: float = DEFAULT_IO_TIMEOUT) -> dict[str, Any]:
+        if not self._pv.wait_for_connection(timeout=timeout):
+            raise EPICSConnectionError(f"PV {self.pvname} not connected")
+
+        try:
+            ca_dict = self._pv.get_with_metadata(
+                with_ctrlvars=True,
+                use_monitor=False,
+                timeout=timeout,
+            )
+        except ChannelAccessGetFailure as e:
+            raise EPICSGetError(
+                f"Get failed for {self.pvname}: {e}"
+            )
+        if ca_dict is None:
+            raise EPICSTimeoutError(
+                f"Get operation timed out after {timeout}s for {self.pvname}"
+            )
+
+        base_type = self._pv.type
+        type_str = f"{base_type}[]" if self._pv.nelm > 1 else base_type
+        info: dict[str, Any] = {
+            "pvName": self.pvname,
+            "protocol": "ca",
+            "state": "CONNECTED",
+            "host": self._pv.host or "",
+            "type": type_str,
+        }
+        info.update(ca_metadata(ca_dict))
+        return info
+
+    def _on_connection_change(self, *, conn=None, **kw):
+        if conn:
+            return
+        disconnected = PVData.create_disconnected(self.pvname)
+        for cb in self._monitor_cbs.values():
+            cb(disconnected)
+
+    def monitor(
+        self,
+        callback: Callable[[PVData], None],
+    ) -> MonitorHandle:
+        if not self._monitor_cbs:
+            self._pv.connection_callbacks.append(self._on_connection_change)
+
+        def wrapped_callback(**ca_kwargs):
+            callback(parse_ca_update(ca_kwargs, self.pvname))
+
+        # run_now=False: CA monitor delivers an initial update on subscribe;
+        # True would duplicate it via run_callback.
+        index = self._pv.add_callback(
+            wrapped_callback,
+            with_ctrlvars=True,
+            run_now=False,
+        )
+        self._monitor_cbs[index] = callback
+
+        if not self._pv.connected:
+            callback(PVData.create_disconnected(self.pvname))
+
+        return MonitorHandle(self, index)
+
+    def clear_monitor(self, handle: MonitorHandle) -> None:
+        if handle._owner is not self:
+            raise ValueError(
+                f"MonitorHandle does not belong to PV {self.pvname!r}"
+            )
+        self._monitor_cbs.pop(handle._handle, None)
+        self._pv.remove_callback(handle._handle)
+        if not self._monitor_cbs:
+            try:
+                self._pv.connection_callbacks.remove(self._on_connection_change)
+            except ValueError:
+                pass
+
+    def disconnect(self) -> None:
+        self._monitor_cbs.clear()
+        try:
+            self._pv.connection_callbacks.remove(self._on_connection_change)
+        except ValueError:
+            pass
+        # Clears monitor callbacks and the shared CA subscription;
+        # explicit remove_callback is unnecessary.
+        self._pv.disconnect()
+
+    def close(self) -> None:
+        chid = self._pv.chid
+        self.disconnect()
+        if chid is not None:
+            try:
+                epics.ca.clear_channel(chid)
+            except Exception:
+                pass

capva/providers/pva_pv.py

@@ -0,0 +1,127 @@
+"""EPICS PVAccess (PVA) PV implementation using p4p"""
+
+from typing import Any, Callable
+
+from p4p.client.thread import Context, Disconnected, TimeoutError
+from ..constants import DEFAULT_IO_TIMEOUT
+from ..pv_data import PVData
+from ..pv_parser import parse_pva, parse_pva_update, pva_metadata
+from ..monitor_handle import MonitorHandle
+from ..exceptions import EPICSTimeoutError, EPICSConnectionError, EPICSGetError, EPICSPutError
+
+_pva_context = Context("pva", nt=False)
+
+
+class PVAPV:
+    def __init__(self, pvname: str):
+        self.pvname = pvname
+        self._subscriptions: list = []
+
+    def get(self, *, timeout: float = DEFAULT_IO_TIMEOUT) -> PVData:
+        pva_value = _pva_context.get(
+            self.pvname, timeout=timeout, throw=False
+        )
+        if isinstance(pva_value, Exception):
+            if isinstance(pva_value, TimeoutError):
+                raise EPICSTimeoutError(
+                    f"Get operation timed out after {timeout}s for {self.pvname}"
+                )
+            if isinstance(pva_value, Disconnected):
+                raise EPICSConnectionError(
+                    f"PV {self.pvname} not connected: {pva_value}"
+                )
+            raise EPICSGetError(
+                f"Failed to get {self.pvname}: "
+                f"{type(pva_value).__name__}: {pva_value}"
+            )
+        return parse_pva(pva_value, self.pvname)
+
+    def put(self, value, *, timeout: float = DEFAULT_IO_TIMEOUT, wait: bool = False) -> None:
+        result = _pva_context.put(
+            self.pvname,
+            value,
+            timeout=timeout,
+            wait=wait,
+            throw=False,
+        )
+        if result is not None:
+            if isinstance(result, TimeoutError):
+                raise EPICSTimeoutError(
+                    f"Put operation timed out after {timeout}s for {self.pvname}"
+                )
+            if isinstance(result, Disconnected):
+                raise EPICSConnectionError(
+                    f"PV {self.pvname} not connected: {result}"
+                )
+            raise EPICSPutError(
+                f"Failed to put {self.pvname}: "
+                f"{type(result).__name__}: {result}"
+            )
+
+    def info(self, *, timeout: float = DEFAULT_IO_TIMEOUT) -> dict[str, Any]:
+        pva_value = _pva_context.get(
+            self.pvname, timeout=timeout, throw=False
+        )
+        if isinstance(pva_value, Exception):
+            if isinstance(pva_value, TimeoutError):
+                raise EPICSTimeoutError(
+                    f"Get operation timed out after {timeout}s for {self.pvname}"
+                )
+            if isinstance(pva_value, Disconnected):
+                raise EPICSConnectionError(
+                    f"PV {self.pvname} not connected: {pva_value}"
+                )
+            raise EPICSGetError(
+                f"Failed to get {self.pvname}: "
+                f"{type(pva_value).__name__}: {pva_value}"
+            )
+
+        info: dict[str, Any] = {
+            "pvName": self.pvname,
+            "protocol": "pva",
+            "state": "CONNECTED",
+            "host": "",
+            "type": pva_value.getID(),
+        }
+        info.update(pva_metadata(pva_value))
+        return info
+
+    def monitor(
+        self,
+        callback: Callable[[PVData], None],
+    ) -> MonitorHandle:
+        def wrapped_callback(pva_update):
+            if isinstance(pva_update, Disconnected):
+                callback(PVData.create_disconnected(self.pvname))
+                return
+            if isinstance(pva_update, Exception):
+                return
+            callback(parse_pva_update(pva_update, self.pvname))
+
+        subscription = _pva_context.monitor(
+            self.pvname, wrapped_callback, notify_disconnect=True
+        )
+        self._subscriptions.append(subscription)
+        return MonitorHandle(self, subscription)
+
+    def clear_monitor(self, handle: MonitorHandle) -> None:
+        if handle._owner is not self:
+            raise ValueError(
+                f"MonitorHandle does not belong to PV {self.pvname!r}"
+            )
+        subscription = handle._handle
+        subscription.close()
+        try:
+            self._subscriptions.remove(subscription)
+        except ValueError:
+            pass
+
+    def disconnect(self) -> None:
+        for subscription in list(self._subscriptions):
+            subscription.close()
+        self._subscriptions.clear()
+        # This call is optional in p4p; unused channels are removed from the context cache after ~20 seconds.
+        # _pva_context.disconnect(self.pvname)
+
+    def close(self) -> None:
+        self.disconnect()

capva/pv.py

@@ -0,0 +1,68 @@
+"""Unified PV client interface for EPICS CA and PVA"""
+
+from typing import Any, Callable
+
+from .constants import DEFAULT_IO_TIMEOUT
+from .pv_data import PVData
+from .monitor_handle import MonitorHandle
+from .protocol import parse_protocol, CA, PVA
+from .providers.ca_pv import CAPV
+from .providers.pva_pv import PVAPV
+from .exceptions import (
+    EPICSProtocolError,
+    EPICSConnectionError,
+    EPICSGetError,
+    EPICSPutError,
+    EPICSTimeoutError,
+)
+
+
+class PV:
+    def __init__(self, pvname: str):
+        protocol, clean_name = parse_protocol(pvname)
+        self.protocol = protocol
+        self.pvname = clean_name
+
+        if protocol == CA:
+            self._pv = CAPV(clean_name)
+        elif protocol == PVA:
+            self._pv = PVAPV(clean_name)
+        else:
+            raise EPICSProtocolError(f"Unsupported protocol: {protocol}")
+
+    def get(self, *, timeout: float = DEFAULT_IO_TIMEOUT) -> PVData:
+        return self._pv.get(timeout=timeout)
+
+    def get_or_none(self, *, timeout: float = DEFAULT_IO_TIMEOUT) -> PVData | None:
+        try:
+            return self.get(timeout=timeout)
+        except (EPICSTimeoutError, EPICSConnectionError):
+            return None
+
+    def put(self, value, *, timeout: float = DEFAULT_IO_TIMEOUT, wait: bool = False) -> None:
+        self._pv.put(value, timeout=timeout, wait=wait)
+
+    def put_or_false(self, value, *, timeout: float = DEFAULT_IO_TIMEOUT, wait: bool = False) -> bool:
+        try:
+            self.put(value, timeout=timeout, wait=wait)
+            return True
+        except (EPICSTimeoutError, EPICSConnectionError, EPICSPutError):
+            return False
+
+    def info(self, *, timeout: float = DEFAULT_IO_TIMEOUT) -> dict[str, Any]:
+        return self._pv.info(timeout=timeout)
+
+    def monitor(
+        self,
+        callback: Callable[[PVData], None],
+    ) -> MonitorHandle:
+        return self._pv.monitor(callback)
+
+    def clear_monitor(self, handle: MonitorHandle) -> None:
+        self._pv.clear_monitor(handle)
+
+    def disconnect(self) -> None:
+        self._pv.disconnect()
+
+    def close(self) -> None:
+        self._pv.close()

capva/pv_data.py

@@ -0,0 +1,152 @@
+"""Data models for EPICS PV client"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from typing import Any, List, Literal, Optional, Union
+
+import numpy as np
+
+from .array_b64 import encode_array
+
+
+# NormativeType data definitions
+# See: https://docs.epics-controls.org/en/latest/pv-access/Normative-Types-Specification.html
+@dataclass
+class Alarm:
+    severity: int = 0
+    status: int = 0
+    message: str = "NO_ALARM"
+
+
+@dataclass
+class TimeStamp:
+    secondsPastEpoch: int = 0
+    nanoseconds: int = 0
+    userTag: int = 0
+
+
+@dataclass
+class Display:
+    limitLow: Optional[float] = None
+    limitHigh: Optional[float] = None
+    description: Optional[str] = None
+    units: Optional[str] = None
+    precision: Optional[int] = None
+    form: Optional[int] = None
+    choices: Optional[List[str]] = None
+
+
+@dataclass
+class Control:
+    limitLow: Optional[float] = None
+    limitHigh: Optional[float] = None
+    minStep: Optional[float] = None
+
+
+@dataclass
+class ValueAlarm:
+    active: Optional[bool] = None
+    lowAlarmLimit: Optional[float] = None
+    lowWarningLimit: Optional[float] = None
+    highWarningLimit: Optional[float] = None
+    highAlarmLimit: Optional[float] = None
+    lowAlarmSeverity: Optional[int] = None
+    lowWarningSeverity: Optional[int] = None
+    highWarningSeverity: Optional[int] = None
+    highAlarmSeverity: Optional[int] = None
+    hysteresis: Optional[float] = None
+
+
+@dataclass
+class PVData:
+    pvName: Optional[str] = None
+    value: Optional[Union[float, int, str, List[float], List[int], List[str]]] = None
+    enumChoices: Optional[List[str]] = None
+    alarm: Optional[Alarm] = None
+    timeStamp: Optional[TimeStamp] = None
+    display: Optional[Display] = None
+    control: Optional[Control] = None
+    valueAlarm: Optional[ValueAlarm] = None
+
+    @classmethod
+    def create_disconnected(cls, pvname: str) -> "PVData":
+        # Alarm shape aligned with org.epics.vtype.Alarm.disconnected():
+        # INVALID(3), CLIENT(7), "Disconnected"
+        return cls(
+            pvName=pvname,
+            alarm=Alarm(severity=3, status=7, message="Disconnected"),
+        )
+
+    def is_disconnected(self) -> bool:
+        alarm = self.alarm
+        return (
+            alarm is not None
+            and alarm.severity == 3
+            and alarm.status == 7
+            and alarm.message == "Disconnected"
+        )
+
+    def to_dict(
+        self,
+        *,
+        mode: Literal["full", "update", "metadata"] = "full",
+        base64_encode: bool = False,
+    ) -> dict[str, Any]:
+        if mode == "full":
+            d = {k: v for k, v in asdict(self).items() if v is not None}
+            if base64_encode and isinstance(self.value, (list, np.ndarray)):
+                b64, dtype = encode_array(self.value)
+                if b64 is not None:
+                    d.pop("value", None)
+                    d["b64arr"] = b64
+                    d["b64dtype"] = dtype
+            return d
+
+        if mode == "update":
+            d: dict[str, Any] = {}
+            if self.pvName is not None:
+                d["pvName"] = self.pvName
+            if base64_encode and isinstance(self.value, (list, np.ndarray)):
+                b64, dtype = encode_array(self.value)
+                if b64 is not None:
+                    d["b64arr"] = b64
+                    d["b64dtype"] = dtype
+                elif self.value is not None:
+                    d["value"] = self.value
+            elif self.value is not None:
+                d["value"] = self.value
+            if self.enumChoices is not None:
+                d["enumChoices"] = self.enumChoices
+            if self.alarm is not None:
+                d["alarm"] = asdict(self.alarm)
+            if self.timeStamp is not None:
+                d["timeStamp"] = asdict(self.timeStamp)
+            return d
+
+        if mode == "metadata":
+            d = {}
+            if self.display is not None:
+                d["display"] = asdict(self.display)
+            if self.control is not None:
+                d["control"] = asdict(self.control)
+            if self.valueAlarm is not None:
+                d["valueAlarm"] = asdict(self.valueAlarm)
+            return d
+
+        raise ValueError(
+            f"mode must be 'full', 'update', or 'metadata', got {mode!r}"
+        )
+
+    def to_json(
+        self,
+        *,
+        mode: Literal["full", "update", "metadata"] = "full",
+        base64_encode: bool = False,
+        **kwargs: Any,
+    ) -> str:
+        return json.dumps(
+            self.to_dict(mode=mode, base64_encode=base64_encode),
+            **kwargs,
+        )

capva/pv_parser.py

@@ -0,0 +1,255 @@
+"""Parsing utilities for EPICS PV client"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, List, Optional, Union
+
+import math
+
+import numpy as np
+from epics import dbr
+from p4p.wrapper import Value as p4pValue
+
+from .pv_data import PVData, Alarm, TimeStamp, Display, Control, ValueAlarm
+
+
+def get_none_if_nan(obj, k: str):
+    v = obj.get(k)
+    return None if isinstance(v, float) and math.isnan(v) else v
+
+
+def ca_alarm_message(status) -> str:
+    try:
+        return dbr.AlarmStatus(int(status)).name
+    except (ValueError, TypeError):
+        return "UNKNOWN"
+
+
+# ---------------------------------------------------------------------------
+# CA helpers
+# ---------------------------------------------------------------------------
+
+
+def _ca_normalize(v):
+    """Converts numpy types and arrays to JSON-serializable Python types."""
+    if isinstance(v, np.generic):
+        return v.item()
+    if isinstance(v, np.ndarray):
+        return v.tolist()
+    return v
+
+
+def _ca_parse_value(pv_obj: dict) -> tuple[Any, Optional[List[str]]]:
+    value_field = pv_obj.get("value")
+    enumChoices = pv_obj.get("enum_strs")
+    value = _ca_normalize(value_field)
+    return value, enumChoices
+
+
+def _ca_parse_alarm_ts(pv_obj: dict) -> tuple[Alarm, TimeStamp]:
+    status = _ca_normalize(pv_obj.get("status", 0))
+    alarm = Alarm(
+        severity = _ca_normalize(pv_obj.get("severity", 0)),
+        status = status,
+        message = ca_alarm_message(status),
+    )
+    ts = _ca_normalize(pv_obj.get("timestamp", 0.0)) or 0.0
+    sec = int(ts)
+    nsec = int((ts - sec) * 1e9)
+    timestamp = TimeStamp(
+        secondsPastEpoch = sec,
+        nanoseconds = nsec,
+    )
+    return alarm, timestamp
+
+
+def _ca_parse_metadata_fields(
+    pv_obj: dict,
+) -> tuple[Display, Control, ValueAlarm]:
+    display = Display(
+        limitLow = _ca_normalize(get_none_if_nan(pv_obj, "lower_disp_limit")),
+        limitHigh = _ca_normalize(get_none_if_nan(pv_obj, "upper_disp_limit")),
+        units = pv_obj.get("units"),
+        precision = _ca_normalize(get_none_if_nan(pv_obj, "precision")),
+    )
+    control = Control(
+        limitLow = _ca_normalize(get_none_if_nan(pv_obj, "lower_ctrl_limit")),
+        limitHigh = _ca_normalize(get_none_if_nan(pv_obj, "upper_ctrl_limit")),
+    )
+    value_alarm = ValueAlarm(
+        lowAlarmLimit = _ca_normalize(get_none_if_nan(pv_obj, "lower_alarm_limit")),
+        highAlarmLimit = _ca_normalize(get_none_if_nan(pv_obj, "upper_alarm_limit")),
+        lowWarningLimit = _ca_normalize(get_none_if_nan(pv_obj, "lower_warning_limit")),
+        highWarningLimit = _ca_normalize(get_none_if_nan(pv_obj, "upper_warning_limit")),
+
+        # pyepics CA metadata has no hysteresis/HYST
+        hysteresis = None,
+    )
+    return display, control, value_alarm
+
+
+def ca_metadata(pv_obj: dict) -> dict[str, Any]:
+    display, control, value_alarm = _ca_parse_metadata_fields(pv_obj)
+    return {
+        "display": asdict(display),
+        "control": asdict(control),
+        "valueAlarm": asdict(value_alarm),
+    }
+
+
+def _ca_to_pvdata(
+    pv_obj: dict,
+    pv_name: str,
+    *,
+    with_metadata: bool,
+) -> PVData:
+    value, enumChoices = _ca_parse_value(pv_obj)
+    alarm, timestamp = _ca_parse_alarm_ts(pv_obj)
+    display = control = value_alarm = None
+    if with_metadata:
+        display, control, value_alarm = _ca_parse_metadata_fields(pv_obj)
+    return PVData(
+        pvName = pv_name,
+        value = value,
+        enumChoices = enumChoices,
+        alarm = alarm,
+        timeStamp = timestamp,
+        display = display,
+        control = control,
+        valueAlarm = value_alarm,
+    )
+
+
+def parse_ca(pv_obj: dict, pv_name: str) -> PVData:
+    """Full CA snapshot: value, alarm, timeStamp, and metadata."""
+    return _ca_to_pvdata(pv_obj, pv_name, with_metadata=True)
+
+
+def parse_ca_update(pv_obj: dict, pv_name: str) -> PVData:
+    """Fast CA monitor path: value, alarm, timeStamp only (no metadata)."""
+    return _ca_to_pvdata(pv_obj, pv_name, with_metadata=False)
+
+
+# ---------------------------------------------------------------------------
+# PVA helpers
+# ---------------------------------------------------------------------------
+
+
+def _pva_parse_value(pv_obj) -> tuple[Any, Optional[List[str]]]:
+    enumChoices: Optional[List[str]] = None
+    value: Any = None
+
+    value_field = pv_obj.get("value")
+
+    if isinstance(value_field, (int, float, str)):
+        value = value_field
+    elif (
+        isinstance(value_field, p4pValue)
+        and value_field.has("index")
+        and value_field.has("choices")
+    ):
+        value = value_field.get("index")
+        enumChoices = value_field.get("choices")
+    elif isinstance(value_field, (list, np.ndarray)):
+        value = (
+            value_field.tolist()
+            if isinstance(value_field, np.ndarray)
+            else list(value_field)
+        )
+
+    return value, enumChoices
+
+
+def _pva_parse_alarm_ts(pv_obj) -> tuple[Alarm, TimeStamp]:
+    a = pv_obj.get("alarm") or {}
+    alarm = Alarm(
+        severity = a.get("severity", 0),
+        status = a.get("status", 0),
+        message = a.get("message", "NO_ALARM"),
+    )
+    ts = pv_obj.get("timeStamp") or {}
+    timestamp = TimeStamp(
+        secondsPastEpoch = ts.get("secondsPastEpoch", 0),
+        nanoseconds = ts.get("nanoseconds", 0),
+        userTag = ts.get("userTag", 0),
+    )
+    return alarm, timestamp
+
+
+def _pva_parse_metadata_fields(
+    pv_obj,
+) -> tuple[Display, Control, ValueAlarm]:
+    d = pv_obj.get("display") or {}
+    form = d.get("form") or {}
+    display = Display(
+        limitLow = get_none_if_nan(d, "limitLow"),
+        limitHigh = get_none_if_nan(d, "limitHigh"),
+        description = d.get("description"),
+        units = d.get("units"),
+        precision = d.get("precision"),
+        form = form.get("index"),
+        choices = form.get("choices"),
+    )
+    c = pv_obj.get("control") or {}
+    control = Control(
+        limitLow = get_none_if_nan(c, "limitLow"),
+        limitHigh = get_none_if_nan(c, "limitHigh"),
+        minStep = c.get("minStep"),
+    )
+    va = pv_obj.get("valueAlarm") or {}
+    value_alarm = ValueAlarm(
+        active = va.get("active"),
+        lowAlarmLimit = get_none_if_nan(va, "lowAlarmLimit"),
+        lowWarningLimit = get_none_if_nan(va, "lowWarningLimit"),
+        highWarningLimit = get_none_if_nan(va, "highWarningLimit"),
+        highAlarmLimit = get_none_if_nan(va, "highAlarmLimit"),
+        lowAlarmSeverity = va.get("lowAlarmSeverity"),
+        lowWarningSeverity = va.get("lowWarningSeverity"),
+        highWarningSeverity = va.get("highWarningSeverity"),
+        highAlarmSeverity = va.get("highAlarmSeverity"),
+        hysteresis = get_none_if_nan(va, "hysteresis"),
+    )
+    return display, control, value_alarm
+
+
+def pva_metadata(pv_obj) -> dict[str, Any]:
+    display, control, value_alarm = _pva_parse_metadata_fields(pv_obj)
+    return {
+        "display": asdict(display),
+        "control": asdict(control),
+        "valueAlarm": asdict(value_alarm),
+    }
+
+
+def _pva_to_pvdata(
+    pv_obj,
+    pv_name: Optional[str],
+    *,
+    with_metadata: bool,
+) -> PVData:
+    value, enumChoices = _pva_parse_value(pv_obj)
+    alarm, timestamp = _pva_parse_alarm_ts(pv_obj)
+    display = control = value_alarm = None
+    if with_metadata:
+        display, control, value_alarm = _pva_parse_metadata_fields(pv_obj)
+    return PVData(
+        pvName = pv_name,
+        value = value,
+        enumChoices = enumChoices,
+        alarm = alarm,
+        timeStamp = timestamp,
+        display = display,
+        control = control,
+        valueAlarm = value_alarm,
+    )
+
+
+def parse_pva(pv_obj, pv_name: Optional[str] = None) -> PVData:
+    """Full PVA snapshot: value, alarm, timeStamp, and metadata."""
+    return _pva_to_pvdata(pv_obj, pv_name, with_metadata=True)
+
+
+def parse_pva_update(pv_obj, pv_name: Optional[str] = None) -> PVData:
+    """Fast PVA monitor path: value, alarm, timeStamp only (no metadata)."""
+    return _pva_to_pvdata(pv_obj, pv_name, with_metadata=False)

capva/tools.py

@@ -0,0 +1,71 @@
+"""Procedural API aligned with EPICS pvget, pvput, pvinfo, and pvmonitor."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .constants import DEFAULT_IO_TIMEOUT
+from .monitor_handle import MonitorHandle
+from .pv import PV
+from .pv_data import PVData
+
+
+class MonitorSession:
+    def __init__(self, pv: PV, handle: MonitorHandle) -> None:
+        self._pv = pv
+        self._handle = handle
+
+    def close(self) -> None:
+        pv = self._pv
+        if pv is None:
+            return
+        self._pv = None
+        pv.clear_monitor(self._handle)
+        pv.close()
+
+
+def pvget(
+    pvname: str,
+    *,
+    timeout: float = DEFAULT_IO_TIMEOUT,
+) -> PVData:
+    pv = PV(pvname)
+    try:
+        return pv.get(timeout=timeout)
+    finally:
+        pv.close()
+
+
+def pvput(
+    pvname: str,
+    value,
+    *,
+    timeout: float = DEFAULT_IO_TIMEOUT,
+    wait: bool = False,
+) -> None:
+    pv = PV(pvname)
+    try:
+        pv.put(value, timeout=timeout, wait=wait)
+    finally:
+        pv.close()
+
+
+def pvinfo(
+    pvname: str,
+    *,
+    timeout: float = DEFAULT_IO_TIMEOUT,
+) -> dict[str, Any]:
+    pv = PV(pvname)
+    try:
+        return pv.info(timeout=timeout)
+    finally:
+        pv.close()
+
+
+def pvmonitor(
+    pvname: str,
+    callback: Callable[[PVData], None],
+) -> MonitorSession:
+    pv = PV(pvname)
+    handle = pv.monitor(callback)
+    return MonitorSession(pv, handle)

capva-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,19 @@
+capva/__init__.py,sha256=HEpccjuAfUUYqPJpOV0095gWYV6LQ8gWxjlGrhudSew,898
+capva/array_b64.py,sha256=ewz68YjK0ge-cHe6lRCFRNfVoiVftvBqHu6rNjHAeGs,1218
+capva/constants.py,sha256=I2k46Nww6cZYsk4kcTLF7FOF8T2WVvjOn-RmhMIhQvM,70
+capva/exceptions.py,sha256=TYby8R7DeMysrIVn0FoiOF5NYF857ZifkPthJz6A0Oo,587
+capva/monitor_handle.py,sha256=i-cQvel6vWyu9JjvyLsjY_-nG7lsjeeObSXje5vuKB4,406
+capva/pool.py,sha256=EiyGq7oW_OEbTmvmMB9pkXEaPzDU4CarzdgzQJYN1bw,1783
+capva/protocol.py,sha256=Iewl-RVUGmzZve24Vrb6UgAA5ZQ-XpAUSNUOg73oWWw,507
+capva/pv.py,sha256=gGePw6pcZZOHa0-RSEx0Dxe_MJsS1PfcwynH86fy5Mk,2194
+capva/pv_data.py,sha256=NAGfYcsOFRcboYTQIM-z0Ll75hx_4cvzOaSQi5h5N_A,4772
+capva/pv_parser.py,sha256=6DqDQ5Ie1LU7IRyo3rkpXnLCh9hSjgs3oszBziQUeFo,8329
+capva/tools.py,sha256=UtmjHxdcBxppII9BbyjD2svSCoeaoPL0rZZvaEGsQxU,1479
+capva/providers/__init__.py,sha256=vkDWwiq63aNykp737HTGotp9kCP5a0ftk9fI739lf7s,137
+capva/providers/ca_pv.py,sha256=_fmq3XtE0BFeT-R5Ra-MW0pd0u2KmBSpnts0yJgqwzk,5704
+capva/providers/pva_pv.py,sha256=pOsgdWvk6W9Z05Tz1GzzDPRiCs9tpiEQaBAcGDU6fsk,4752
+capva-0.1.0.dist-info/licenses/LICENSE,sha256=z_o60cadUCm8yPNB17ZF_Mrub-qqv4re8OyD2lkkC14,1086
+capva-0.1.0.dist-info/METADATA,sha256=tNsE814Y9BqVrhHDU9I20ux9pvPcn0D53-TvwSur_MU,5999
+capva-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+capva-0.1.0.dist-info/top_level.txt,sha256=dfcUKLML0iSTuvTLOYLEs6jTGbi8qdHkrW9u4FC2R1E,6
+capva-0.1.0.dist-info/RECORD,,

capva-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

capva-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+capva