hid-usb-relay 25.0.0__py3-none-any.whl → 26.0.0__py3-none-any.whl

hid_usb_relay/usb_relay.py

@@ -1,197 +1,582 @@
 """
-This module provides functions to interact with a USB relay device using command-line commands.
-It allows users to get and set the state of the relay device, as well as retrieve information about the relay device's status.
+HID USB Relay Controller Module
+
+Provides an object-oriented interface for controlling HID USB relay devices
+via command-line executable. Supports multiple relay devices with proper
+error handling, validation, and reusability.
+
+Example:
+    >>> relay = USBRelayDevice()  # Default device
+    >>> relay.turn_on(1)
+    >>> relay.get_state()
+    {'R1': 'ON', 'R2': 'OFF'}
+
+    >>> specific = USBRelayDevice(device_id='HURTM')
+    >>> specific.turn_on_all()
+
+    >>> # Context manager pattern
+    >>> with USBRelayDevice('HURTM') as relay:
+    ...     relay.turn_on_all()
 """
 
+import logging
 import os
 import platform
+import re
 import subprocess
-from typing import Optional, Tuple, List
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
+from pathlib import Path
+from typing import Dict, List, Optional, Union
 
-def get_platform_and_architecture() -> Tuple[str, str]:
-    """
-    Get the current system platform and architecture.
+__all__ = [
+    'USBRelayDevice',
+    'enumerate_devices',
+    'RelayState',
+    'RelayError',
+    'RelayCommandError',
+    'RelayValidationError',
+]
 
-    Returns:
-        tuple: (system, architecture), both lowercase strings.
-    """
-    return platform.system().lower(), platform.architecture()[0].lower()
+# Configure module logger
+logger = logging.getLogger(__name__)
 
-def get_bin_path() -> str:
-    """
-    Get the absolute path to the package's binary folder.
+# Constants
+DEFAULT_TIMEOUT = 5.0
+MAX_RELAY_COUNT = 8
 
-    Returns:
-        str: Path to the binary folder.
-    """
-    return os.path.join(os.path.dirname(os.path.abspath(__file__)), 'hid_usb_relay_bin')
 
-def get_relay_path(file_name: str) -> str:
-    """
-    Build the path to a relay binary/library for the current platform and architecture.
+class RelayState(Enum):
+    """Relay state enumeration."""
+    ON = "on"
+    OFF = "off"
 
-    Args:
-        file_name (str): Name of the binary/library file.
 
-    Returns:
-        str: Full path to the file.
+class RelayCommand(Enum):
+    """Available relay commands."""
+    STATE = "state"
+    ENUM = "enum"
 
-    Raises:
-        OSError: If the system platform is unsupported.
-    """
-    bin_dir = get_bin_path()
-    system, arch = get_platform_and_architecture()
-    if system not in ['windows', 'linux']:
-        raise OSError(f'Unsupported system platform: {system}')
-    return os.path.join(bin_dir, system, arch, file_name)
 
-def get_relay_executable() -> str:
-    """
-    Get the path to the relay command-line executable for the current platform.
+class RelayError(Exception):
+    """Base exception for relay operations."""
+    pass
 
-    Returns:
-        str: Full path to the relay executable.
-    """
-    exe_name = "hidusb-relay-cmd.exe" if platform.system().lower() == 'windows' else "hidusb-relay-cmd"
-    return get_relay_path(exe_name)
 
-def get_relay_library() -> str:
+class RelayCommandError(RelayError):
+    """Raised when relay command execution fails."""
+    pass
+
+
+class RelayValidationError(RelayError):
+    """Raised when input validation fails."""
+    pass
+
+
+@dataclass(frozen=True)
+class PlatformInfo:
+    """Platform and architecture information."""
+    system: str
+    architecture: str
+
+    @property
+    def is_windows(self) -> bool:
+        return self.system == 'windows'
+
+    @property
+    def is_linux(self) -> bool:
+        return self.system == 'linux'
+
+    @property
+    def arch_bits(self) -> str:
+        """Get architecture as bit string (32bit/64bit)."""
+        return '64bit' if '64' in self.architecture else '32bit'
+
+
+@lru_cache(maxsize=1)
+def get_platform_info() -> PlatformInfo:
     """
-    Get the path to the relay library for the current platform.
+    Get cached platform information.
 
     Returns:
-        str: Full path to the relay library.
+        PlatformInfo: Platform and architecture details.
     """
-    lib_name = "USB_RELAY_DEVICE.dll" if platform.system().lower() == 'windows' else "usb_relay_device.so"
-    return get_relay_path(lib_name)
+    return PlatformInfo(
+        system=platform.system().lower(),
+        architecture=platform.architecture()[0].lower()
+    )
+
 
-def run_command(command: List[str]) -> Optional[str]:
+def _get_module_bin_directory() -> Path:
+    """Get the default binaries folder in module directory."""
+    return Path(__file__).parent / 'hid_usb_relay_bin'
+
+
+def get_bin_directory(base_path: Optional[Union[str, Path]] = None) -> Path:
     """
-    Run a command using subprocess and return its output.
+    Get the absolute path to the binaries folder.
 
     Args:
-        command (List[str]): Command and arguments as a list.
+        base_path: Optional custom base path. If None, uses module directory.
 
     Returns:
-        Optional[str]: Output string if successful, None otherwise.
+        Path: Path to the binary folder.
     """
-    process = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
-    if process.returncode == 0:
-        return process.stdout.strip()
-    print(f"Error executing command: {process.stderr}")
-    return None
+    if base_path is None:
+        return _get_module_bin_directory()
+    return Path(base_path) / 'hid_usb_relay_bin'
 
-def get_default_relay_device_state() -> Optional[List[str]]:
-    """
-    Get the status of the default relay device.
 
-    Returns:
-        Optional[List[str]]: List of relay states, or None on error.
-    """
-    output = run_command([get_relay_executable(), "STATUS"])
-    return output.split(':')[-1].strip().split(' ') if output else None
+@lru_cache(maxsize=1)
+def _get_default_executable_path() -> Path:
+    """Get cached default executable path."""
+    plat = get_platform_info()
 
-def set_default_relay_device_state(relay_state: str) -> bool:
+    if not (plat.is_windows or plat.is_linux):
+        raise RelayError(f'Unsupported platform: {plat.system}')
+
+    bin_dir = _get_module_bin_directory()
+    exe_name = "hidusb-relay-cmd.exe" if plat.is_windows else "hidusb-relay-cmd"
+    exe_path = bin_dir / plat.system / plat.arch_bits / exe_name
+
+    if not exe_path.exists():
+        raise RelayError(f'Executable not found: {exe_path}')
+
+    return exe_path
+
+
+def get_executable_path(base_path: Optional[Union[str, Path]] = None) -> Path:
     """
-    Set all relays on the default device to a given state.
+    Get the path to the relay command-line executable.
 
     Args:
-        relay_state (str): "ON" or "OFF".
+        base_path: Optional custom base path for binaries. If None, uses cached default.
 
     Returns:
-        bool: True if successful, False otherwise.
+        Path: Full path to the relay executable.
+
+    Raises:
+        RelayError: If platform is unsupported or executable not found.
     """
-    return run_command([get_relay_executable(), relay_state, "ALL"]) is not None
+    if base_path is None:
+        return _get_default_executable_path()
 
-def get_relay_device_state(relay_id: str) -> Optional[List[str]]:
+    plat = get_platform_info()
+
+    if not (plat.is_windows or plat.is_linux):
+        raise RelayError(f'Unsupported platform: {plat.system}')
+
+    bin_dir = get_bin_directory(base_path)
+    exe_name = "hidusb-relay-cmd.exe" if plat.is_windows else "hidusb-relay-cmd"
+    exe_path = bin_dir / plat.system / plat.arch_bits / exe_name
+
+    if not exe_path.exists():
+        raise RelayError(f'Executable not found: {exe_path}')
+
+    return exe_path
+
+
+def _execute_command(command: List[str], timeout: float = DEFAULT_TIMEOUT) -> str:
     """
-    Get the status of a specific relay device by ID.
+    Execute a relay command and return output.
 
     Args:
-        relay_id (str): Relay device ID.
+        command: Command and arguments as list.
+        timeout: Command timeout in seconds.
 
     Returns:
-        Optional[List[str]]: List of relay states, or None on error.
-    """
-    output = run_command([get_relay_executable(), f"id={relay_id}", "STATUS"])
-    return output.split(':')[-1].strip().split(' ') if output else None
+        str: Command output (empty string if no output).
 
-def set_relay_device_state(relay_id: str, relay_state: str) -> bool:
+    Raises:
+        RelayCommandError: If command execution fails.
+    """
+    # Convert Path objects to strings for subprocess
+    cmd_str = [str(c) for c in command]
+    logger.debug(f"Executing: {' '.join(cmd_str)}")
+
+    try:
+        result = subprocess.run(
+            cmd_str,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=True,
+            timeout=timeout
+        )
+        output = result.stdout.strip() if result.stdout else ""
+        if output:
+            logger.debug(f"Output: {output}")
+        return output
+
+    except subprocess.CalledProcessError as e:
+        error_msg = f"Command failed (exit {e.returncode}): {e.stderr.strip() if e.stderr else 'Unknown error'}"
+        logger.error(error_msg)
+        raise RelayCommandError(error_msg) from e
+    except subprocess.TimeoutExpired as e:
+        error_msg = f"Command timed out after {timeout}s"
+        logger.error(error_msg)
+        raise RelayCommandError(error_msg) from e
+    except FileNotFoundError as e:
+        error_msg = f"Executable not found: {command[0]}"
+        logger.error(error_msg)
+        raise RelayCommandError(error_msg) from e
+    except OSError as e:
+        error_msg = f"OS error executing command: {e}"
+        logger.error(error_msg)
+        raise RelayCommandError(error_msg) from e
+
+
+def _parse_relay_states(output: str) -> Dict[str, str]:
     """
-    Set all relays on a specific device to a given state.
+    Parse relay state output into a dictionary.
 
     Args:
-        relay_id (str): Relay device ID.
-        relay_state (str): "ON" or "OFF".
+        output: Raw command output (e.g., "Board ID=[BITFT] State: R1=OFF R2=OFF").
 
     Returns:
-        bool: True if successful, False otherwise.
-    """
-    return run_command([get_relay_executable(), f"id={relay_id}", relay_state, "ALL"]) is not None
+        Dict mapping relay names to states (e.g., {'R1': 'OFF', 'R2': 'OFF'}).
 
-def get_all_relay_device_state() -> Optional[str]:
+    Raises:
+        RelayError: If output format is invalid.
     """
-    Get the status of all connected relay devices.
+    if not output or 'State:' not in output:
+        raise RelayError(f"Invalid state format: {output}")
 
-    Returns:
-        Optional[str]: Status string, or None on error.
-    """
-    return run_command([get_relay_executable(), "ENUM"])
+    # Extract state portion after "State:"
+    state_str = output.split('State:', 1)[-1].strip()
 
-def get_relay_device_relay_state(relay_id: str, relay_number: str) -> Optional[str]:
-    """
-    Get the state of a specific relay on a specific device.
+    # Parse relay states using regex for robustness
+    # Matches patterns like R1=OFF, R2=ON
+    pattern = re.compile(r'(R\d+)=(ON|OFF)', re.IGNORECASE)
+    matches = pattern.findall(state_str)
 
-    Args:
-        relay_id (str): Relay device ID.
-        relay_number (str): Relay number as string (e.g., "1").
+    if not matches:
+        raise RelayError(f"No relay states found in: {output}")
 
-    Returns:
-        Optional[str]: State ("ON"/"OFF") or None on error.
-    """
-    states = get_relay_device_state(relay_id)
-    if states:
-        return states[int(relay_number) - 1].split('=')[-1]
-    return None
+    return {relay: state.upper() for relay, state in matches}
 
-def set_relay_device_relay_state(relay_id: str, relay_number: str, relay_state: str) -> bool:
+
+def _validate_relay_number(relay_num: Union[int, str], max_relays: int = MAX_RELAY_COUNT) -> int:
     """
-    Set the state of a specific relay on a specific device.
+    Validate and convert relay number.
 
     Args:
-        relay_id (str): Relay device ID.
-        relay_number (str): Relay number as string (e.g., "1").
-        relay_state (str): "ON" or "OFF".
+        relay_num: Relay number as int or string.
+        max_relays: Maximum valid relay number.
 
     Returns:
-        bool: True if successful, False otherwise.
-    """
-    return run_command([get_relay_executable(), f"id={relay_id}", relay_state, relay_number]) is not None
+        int: Validated relay number.
 
-def get_default_relay_device_relay_state(relay_number: str) -> Optional[str]:
+    Raises:
+        RelayValidationError: If relay number is invalid.
     """
-    Get the state of a specific relay on the default device.
+    try:
+        num = int(relay_num)
+    except (ValueError, TypeError) as e:
+        raise RelayValidationError(
+            f"Invalid relay number format: {relay_num!r}"
+        ) from e
 
-    Args:
-        relay_number (str): Relay number as string (e.g., "1").
+    if not 1 <= num <= max_relays:
+        raise RelayValidationError(
+            f"Relay number must be between 1 and {max_relays}, got {num}"
+        )
 
-    Returns:
-        Optional[str]: State ("ON"/"OFF") or None on error.
+    return num
+
+
+class USBRelayDevice:
     """
-    states = get_default_relay_device_state()
-    if states:
-        return states[int(relay_number) - 1].split('=')[-1]
-    return None
+    Interface for controlling a USB relay device.
 
-def set_default_relay_device_relay_state(relay_number: str, relay_state: str) -> bool:
+    Supports context manager protocol for resource management patterns.
+
+    Attributes:
+        device_id: Optional device ID. If None, uses default device.
+
+    Example:
+        >>> relay = USBRelayDevice(device_id='HURTM')
+        >>> relay.turn_on(1)
+        >>> relay.get_state()
+        {'R1': 'ON', 'R2': 'OFF'}
+
+        >>> with USBRelayDevice('HURTM') as relay:
+        ...     relay.turn_on_all()
     """
-    Set the state of a specific relay on the default device.
 
-    Args:
-        relay_number (str): Relay number as string (e.g., "1").
-        relay_state (str): "ON" or "OFF".
+    def __init__(
+        self,
+        device_id: Optional[str] = None,
+        executable_path: Optional[Union[str, Path]] = None,
+        timeout: float = DEFAULT_TIMEOUT
+    ):
+        """
+        Initialize relay device controller.
+
+        Args:
+            device_id: Device ID. If None, controls the default device.
+            executable_path: Custom path to relay executable. If None, auto-detects.
+            timeout: Command timeout in seconds.
+        """
+        self.device_id = device_id
+        self._timeout = timeout
+        self._exe_path = Path(executable_path) if executable_path else get_executable_path()
+        logger.info(f"Initialized USB relay: {device_id or 'default'}")
+
+    def __enter__(self) -> 'USBRelayDevice':
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        # Could add cleanup logic here if needed
+        pass
+
+    def __repr__(self) -> str:
+        return f"USBRelayDevice(device_id={self.device_id!r})"
+
+    def _build_command(
+        self,
+        action: str,
+        target: Optional[str] = None
+    ) -> List[Union[Path, str]]:
+        """
+        Build command list for execution.
+
+        Args:
+            action: Action to perform (on/off/state/enum).
+            target: Target relay number or "all".
+
+        Returns:
+            List of command arguments.
+        """
+        cmd: List[Union[Path, str]] = [self._exe_path]
+
+        if self.device_id:
+            cmd.append(f"id={self.device_id}")
+
+        cmd.append(action)
+
+        if target is not None:
+            cmd.append(target)
+
+        return cmd
+
+    def _execute(self, action: str, target: Optional[str] = None) -> str:
+        """Execute command with device-specific timeout."""
+        cmd = self._build_command(action, target)
+        return _execute_command(cmd, timeout=self._timeout)
+
+    def get_state(self) -> Dict[str, str]:
+        """
+        Get current state of all relays on this device.
+
+        Returns:
+            Dict mapping relay names to states (e.g., {'R1': 'ON', 'R2': 'OFF'}).
+
+        Raises:
+            RelayCommandError: If command fails.
+        """
+        output = self._execute(RelayCommand.STATE.value)
+        return _parse_relay_states(output)
+
+    def get_relay_state(self, relay_num: Union[int, str]) -> str:
+        """
+        Get state of a specific relay.
+
+        Args:
+            relay_num: Relay number (1-based).
+
+        Returns:
+            str: "ON" or "OFF".
+
+        Raises:
+            RelayValidationError: If relay number is invalid.
+            RelayCommandError: If command fails.
+            RelayError: If relay not found.
+        """
+        num = _validate_relay_number(relay_num)
+        states = self.get_state()
+        relay_key = f"R{num}"
+
+        if relay_key not in states:
+            raise RelayError(
+                f"Relay {num} not found. Available: {', '.join(states.keys())}"
+            )
+
+        return states[relay_key]
+
+    def set_state(
+        self,
+        state: Union[RelayState, str],
+        relay_num: Optional[Union[int, str]] = None
+    ) -> None:
+        """
+        Set relay state.
+
+        Args:
+            state: RelayState.ON/OFF or "on"/"off"/"ON"/"OFF" string.
+            relay_num: Optional relay number. If None, sets all relays.
+
+        Raises:
+            RelayValidationError: If inputs are invalid.
+            RelayCommandError: If command fails.
+        """
+        # Normalize state
+        if isinstance(state, RelayState):
+            state_str = state.value
+        elif isinstance(state, str):
+            state_str = state.lower()
+            if state_str not in ('on', 'off'):
+                raise RelayValidationError(
+                    f"Invalid state: {state!r}. Must be 'on' or 'off'"
+                )
+        else:
+            raise RelayValidationError(
+                f"State must be RelayState or str, got {type(state).__name__}"
+            )
+
+        # Determine target
+        if relay_num is None:
+            target = "all"
+        else:
+            num = _validate_relay_number(relay_num)
+            target = str(num)
+
+        self._execute(state_str, target)
+        logger.info(f"Set {self.device_id or 'default'} relay {target} to {state_str.upper()}")
+
+    def turn_on(self, relay_num: Union[int, str]) -> None:
+        """Turn on a specific relay."""
+        self.set_state(RelayState.ON, relay_num)
+
+    def turn_off(self, relay_num: Union[int, str]) -> None:
+        """Turn off a specific relay."""
+        self.set_state(RelayState.OFF, relay_num)
+
+    def turn_on_all(self) -> None:
+        """Turn on all relays."""
+        self.set_state(RelayState.ON)
+
+    def turn_off_all(self) -> None:
+        """Turn off all relays."""
+        self.set_state(RelayState.OFF)
+
+
+def enumerate_devices() -> List[Dict[str, str]]:
+    """
+    Enumerate all connected relay devices.
 
     Returns:
-        bool: True if successful, False otherwise.
+        List of dicts containing device info and states.
+        Example: [
+            {'device_id': 'BITFT', 'R1': 'OFF', 'R2': 'OFF'},
+            {'device_id': 'HURTM', 'R1': 'ON', 'R2': 'ON'}
+        ]
+
+    Raises:
+        RelayCommandError: If enumeration fails.
     """
-    return run_command([get_relay_executable(), relay_state, relay_number]) is not None
+    exe_path = _get_default_executable_path()
+    output = _execute_command([exe_path, RelayCommand.ENUM.value])
+
+    # Regex to extract device ID more robustly
+    device_pattern = re.compile(r'Board ID=\[([^\]]+)\]', re.IGNORECASE)
+
+    devices = []
+    for line in output.split('\n'):
+        if not line.strip():
+            continue
+
+        match = device_pattern.search(line)
+        if match:
+            device_id = match.group(1)
+            try:
+                states = _parse_relay_states(line)
+                devices.append({'device_id': device_id, **states})
+            except RelayError as e:
+                logger.warning(f"Failed to parse device {device_id}: {e}")
+
+    logger.info(f"Found {len(devices)} relay device(s)")
+    return devices
+
+
+# Backward compatibility functions (delegating to class-based API)
+def get_default_relay_device_state() -> Optional[List[str]]:
+    """DEPRECATED: Use USBRelayDevice().get_state() instead."""
+    try:
+        states = USBRelayDevice().get_state()
+        return [f"{k}={v}" for k, v in states.items()]
+    except RelayError:
+        return None
+
+
+def set_default_relay_device_state(relay_state: str) -> bool:
+    """DEPRECATED: Use USBRelayDevice().set_state() instead."""
+    try:
+        USBRelayDevice().set_state(relay_state)
+        return True
+    except RelayError:
+        return False
+
+
+def get_relay_device_state(relay_id: str) -> Optional[List[str]]:
+    """DEPRECATED: Use USBRelayDevice(device_id).get_state() instead."""
+    try:
+        states = USBRelayDevice(device_id=relay_id).get_state()
+        return [f"{k}={v}" for k, v in states.items()]
+    except RelayError:
+        return None
+
+
+def set_relay_device_state(relay_id: str, relay_state: str) -> bool:
+    """DEPRECATED: Use USBRelayDevice(device_id).set_state() instead."""
+    try:
+        USBRelayDevice(device_id=relay_id).set_state(relay_state)
+        return True
+    except RelayError:
+        return False
+
+
+def get_all_relay_device_state() -> Optional[str]:
+    """DEPRECATED: Use enumerate_devices() instead."""
+    try:
+        exe_path = get_executable_path()
+        return _execute_command([exe_path, RelayCommand.ENUM.value])
+    except RelayError:
+        return None
+
+
+def get_relay_device_relay_state(relay_id: str, relay_number: str) -> Optional[str]:
+    """DEPRECATED: Use USBRelayDevice(device_id).get_relay_state() instead."""
+    try:
+        return USBRelayDevice(device_id=relay_id).get_relay_state(relay_number)
+    except RelayError:
+        return None
+
+
+def set_relay_device_relay_state(relay_id: str, relay_number: str, relay_state: str) -> bool:
+    """DEPRECATED: Use USBRelayDevice(device_id).set_state() instead."""
+    try:
+        USBRelayDevice(device_id=relay_id).set_state(relay_state, relay_number)
+        return True
+    except RelayError:
+        return False
+
+
+def get_default_relay_device_relay_state(relay_number: str) -> Optional[str]:
+    """DEPRECATED: Use USBRelayDevice().get_relay_state() instead."""
+    try:
+        return USBRelayDevice().get_relay_state(relay_number)
+    except RelayError:
+        return None
+
+
+def set_default_relay_device_relay_state(relay_number: str, relay_state: str) -> bool:
+    """DEPRECATED: Use USBRelayDevice().set_state() instead."""
+    try:
+        USBRelayDevice().set_state(relay_state, relay_number)
+        return True
+    except RelayError:
+        return False