cgse-common 0.17.2__py3-none-any.whl → 0.17.3__py3-none-any.whl

egse/ratelimit.py

@@ -1,275 +0,0 @@
-"""
-Rate limiting utilities for controlling execution frequency of functions and code blocks.
-
-This module provides decorators, context managers, and utility functions to limit how
-often code executes, which is particularly useful for:
-
-- Reducing noisy output in loops (print statements, logging)
-- Throttling expensive operations
-- Controlling debug message frequency
-- Implementing backpressure in data processing pipelines
-
-The rate limiting tracks execution counts per unique key and shows suppressed message
-counts similar to system loggers (e.g., "... 5 more similar messages suppressed").
-
-Basic Usage:
-    # Decorator - limit function execution
-    @rate_limit(every_n=10)
-    def debug_function():
-        print("Debug info")
-
-    # Context manager - limit code block execution
-    for i in range(100):
-        with rate_limited(every_n=10, key="progress") as should_execute:
-            if should_execute:
-                print(f"Progress: {i}")
-
-    # Convenience functions
-    for i in range(100):
-        rate_limited_print(f"Processing item {i}", every_n=10)
-
-Advanced Usage:
-    # Custom rate limiter instances for isolation
-    debug_limiter = RateLimiter()
-
-    @rate_limit(every_n=5, limiter=debug_limiter)
-    def isolated_debug():
-        print("This uses a separate counter")
-
-    # Rate-limited logging with suppression tracking
-    import logging
-    logger = logging.getLogger(__name__)
-
-    for i in range(50):
-        rate_limited_log(logger, logging.WARNING,
-                        "High CPU usage", every_n=10)
-
-Classes:
-    RateLimiter: Core rate limiting logic with per-key counters
-
-Functions:
-    rate_limit: Decorator for rate-limiting function calls
-    rate_limited: Context manager for rate-limiting code blocks
-    rate_limited_print: Convenience function for rate-limited printing
-    rate_limited_log: Convenience function for rate-limited logging
-
-Author: Generated by Claude
-License: MIT
-"""
-
-import time
-import logging
-from functools import wraps
-from collections import defaultdict
-from contextlib import contextmanager
-from typing import Dict, Any, Optional, Callable
-
-
-class RateLimiter:
-    """A rate limiter that tracks execution counts and provides rate limiting functionality."""
-
-    def __init__(self):
-        self.counters: Dict[str, int] = defaultdict(int)
-        self.last_executed: Dict[str, int] = defaultdict(int)
-        self.suppressed_count: Dict[str, int] = defaultdict(int)
-
-    def should_execute(self, key: str, every_n: int) -> tuple[bool, int]:
-        """
-        Check if an operation should be executed based on rate limiting.
-
-        Returns:
-            tuple: (should_execute: bool, suppressed_count: int)
-        """
-        self.counters[key] += 1
-
-        # Execute on 1st call, then every every_n calls after that
-        if self.counters[key] == 1 or (self.counters[key] - 1) % every_n == 0:
-            # For the first call, no suppressed count to return
-            if self.counters[key] == 1:
-                return True, 0
-            else:
-                # For subsequent executions, return the suppressed count and reset it
-                suppressed = self.suppressed_count[key]
-                self.suppressed_count[key] = 0
-                return True, suppressed
-        else:
-            self.suppressed_count[key] += 1
-            return False, 0
-
-    def reset(self, key: Optional[str] = None):
-        """Reset counters for a specific key or all keys."""
-        if key:
-            self.counters[key] = 0
-            self.last_executed[key] = 0
-            self.suppressed_count[key] = 0
-        else:
-            self.counters.clear()
-            self.last_executed.clear()
-            self.suppressed_count.clear()
-
-
-# Global rate limiter instance
-_global_limiter = RateLimiter()
-
-
-def rate_limit(
-    every_n: int = 10, key: Optional[str] = None, show_suppressed: bool = True, limiter: Optional[RateLimiter] = None
-):
-    """
-    Decorator that limits function execution to every N calls.
-
-    Args:
-        every_n: Execute only every N calls
-        key: Unique identifier for this rate limiter (auto-generated if None)
-        show_suppressed: Whether to show "... N more suppressed" message
-        limiter: Custom RateLimiter instance (uses global one if None)
-    """
-
-    def decorator(func: Callable) -> Callable:
-        nonlocal key
-        if key is None:
-            key = f"{func.__module__}.{func.__qualname__}"
-
-        rate_limiter = limiter or _global_limiter
-
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            should_execute, suppressed = rate_limiter.should_execute(key, every_n)
-
-            if should_execute:
-                # Show suppressed count BEFORE executing (except for first execution)
-                if show_suppressed and suppressed > 0:
-                    print(f"... {suppressed} more similar messages suppressed")
-
-                result = func(*args, **kwargs)
-                return result
-
-            return None  # Suppressed execution
-
-        # Add utility methods to the wrapper
-        wrapper.reset = lambda: rate_limiter.reset(key)
-        wrapper.get_count = lambda: rate_limiter.counters[key]
-
-        return wrapper
-
-    return decorator
-
-
-@contextmanager
-def rate_limited(
-    every_n: int = 10, key: Optional[str] = None, show_suppressed: bool = True, limiter: Optional[RateLimiter] = None
-):
-    """
-    Context manager that limits execution of code block to every N calls.
-
-    Args:
-        every_n: Execute only every N calls
-        key: Unique identifier for this rate limiter (required for context manager)
-        show_suppressed: Whether to show "... N more suppressed" message
-        limiter: Custom RateLimiter instance (uses global one if None)
-
-    Yields:
-        bool: True if code should execute, False if suppressed
-    """
-    if key is None:
-        raise ValueError("Context manager requires a unique 'key' parameter")
-
-    rate_limiter = limiter or _global_limiter
-    should_execute, suppressed = rate_limiter.should_execute(key, every_n)
-
-    if should_execute:
-        # Show suppressed count BEFORE yielding (except for first execution)
-        if show_suppressed and suppressed > 0:
-            print(f"... {suppressed} more similar operations suppressed")
-
-    try:
-        yield should_execute
-    finally:
-        pass  # Nothing to do in finally
-
-
-# Convenience functions for common use cases
-def rate_limited_print(message: str, every_n: int = 10, key: Optional[str] = None):
-    """Print a message only every N calls."""
-    if key is None:
-        key = f"print_{hash(message) % 10000}"
-
-    with rate_limited(every_n, key=key) as should_execute:
-        if should_execute:
-            print(message)
-
-
-def rate_limited_log(
-    logger: logging.Logger, level: int, message: str, every_n: int = 10, key: Optional[str] = None, *args
-):
-    """Log a message only every N calls."""
-    if key is None:
-        key = f"log_{hash(message) % 10000}"
-
-    with rate_limited(every_n, key=key, show_suppressed=False) as should_execute:
-        if should_execute:
-            suppressed = _global_limiter.suppressed_count[key]
-            if suppressed > 0:
-                message += f" (... {suppressed} more similar messages suppressed)"
-            logger.log(level, message, *args)
-
-
-# Example usage and demonstrations
-if __name__ == "__main__":
-    print("=== Decorator Example ===")
-
-    @rate_limit(every_n=3, show_suppressed=True)
-    def noisy_function(i):
-        print(f"Processing item {i}")
-        return f"result_{i}"
-
-    # This will only print every 3rd call
-    for i in range(10):
-        noisy_function(i)
-
-    print(f"\nTotal calls to noisy_function: {noisy_function.get_count()}")
-
-    print("\n=== Context Manager Example ===")
-
-    # Using context manager in a loop
-    for i in range(15):
-        with rate_limited(every_n=5, key="loop_progress") as should_execute:
-            if should_execute:
-                print(f"Progress update: processed {i + 1} items")
-
-    print("\n=== Convenience Functions Example ===")
-
-    # Using convenience functions
-    for i in range(8):
-        rate_limited_print(f"Item {i} processed", every_n=3, key="item_processing")
-
-    print("\n=== Logging Example ===")
-
-    # Setup logging
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-    logger = logging.getLogger(__name__)
-
-    # Rate-limited logging
-    for i in range(12):
-        rate_limited_log(
-            logger, logging.WARNING, f"High memory usage detected: {i * 10}%", every_n=4, key="memory_warning"
-        )
-
-    print("\n=== Multiple Rate Limiters Example ===")
-
-    # Using separate rate limiter instances for different purposes
-    debug_limiter = RateLimiter()
-    error_limiter = RateLimiter()
-
-    @rate_limit(every_n=2, key="debug_messages", limiter=debug_limiter)
-    def debug_message(msg):
-        print(f"DEBUG: {msg}")
-
-    @rate_limit(every_n=4, key="error_messages", limiter=error_limiter)
-    def error_message(msg):
-        print(f"ERROR: {msg}")
-
-    for i in range(10):
-        debug_message(f"Debug info {i}")
-        if i % 2 == 0:
-            error_message(f"Error condition {i}")

egse/socketdevice.py

@@ -1,379 +0,0 @@
-"""
-This module defines base classes and generic functions to work with sockets.
-"""
-
-import asyncio
-import select
-import socket
-import time
-from typing import Optional
-
-from egse.device import AsyncDeviceInterface
-from egse.device import AsyncDeviceTransport
-from egse.device import DeviceConnectionError
-from egse.device import DeviceConnectionInterface
-from egse.device import DeviceTimeoutError
-from egse.device import DeviceTransport
-from egse.log import logger
-from egse.system import type_name
-
-
-class SocketDevice(DeviceConnectionInterface, DeviceTransport):
-    """Base class that implements the socket interface."""
-
-    # We set a default connect timeout of 3.0 sec before connecting and reset
-    # to None (=blocking) after connecting. The reason for this is that when no
-    # device is available, e.g. during testing, the timeout will take about
-    # two minutes which is way too long. It needs to be evaluated if this
-    # approach is acceptable and not causing problems during production.
-
-    def __init__(
-        self,
-        hostname: str,
-        port: int,
-        connect_timeout: float = 3.0,
-        read_timeout: float | None = 1.0,
-        separator: str = b"\x03",
-    ):
-        super().__init__()
-        self.is_connection_open = False
-        self.hostname = hostname
-        self.port = port
-        self.connect_timeout = connect_timeout
-        self.read_timeout = read_timeout
-        self.separator = separator
-        self.socket = None
-
-    @property
-    def device_name(self):
-        """The name of the device that this interface connects to."""
-        return f"SocketDevice({self.hostname}:{self.port})"
-
-    def connect(self):
-        """
-        Connect the device.
-
-        Raises:
-            ConnectionError: When the connection could not be established. Check the logging
-                messages for more detail.
-            TimeoutError: When the connection timed out.
-            ValueError: When hostname or port number are not provided.
-        """
-
-        # Sanity checks
-
-        if self.is_connection_open:
-            logger.warning(f"{self.device_name}: trying to connect to an already connected socket.")
-            return
-
-        if self.hostname in (None, ""):
-            raise ValueError(f"{self.device_name}: hostname is not initialized.")
-
-        if self.port in (None, 0):
-            raise ValueError(f"{self.device_name}: port number is not initialized.")
-
-        # Create a new socket instance
-
-        try:
-            self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        except socket.error as exc:
-            raise ConnectionError(f"{self.device_name}: Failed to create socket.") from exc
-
-        try:
-            logger.debug(f'Connecting a socket to host "{self.hostname}" using port {self.port}')
-            self.socket.settimeout(self.connect_timeout)
-            self.socket.connect((self.hostname, self.port))
-            self.socket.settimeout(None)
-        except ConnectionRefusedError as exc:
-            raise ConnectionError(f"{self.device_name}: Connection refused to {self.hostname}:{self.port}.") from exc
-        except TimeoutError as exc:
-            raise TimeoutError(f"{self.device_name}: Connection to {self.hostname}:{self.port} timed out.") from exc
-        except socket.gaierror as exc:
-            raise ConnectionError(f"{self.device_name}: socket address info error for {self.hostname}") from exc
-        except socket.herror as exc:
-            raise ConnectionError(f"{self.device_name}: socket host address error for {self.hostname}") from exc
-        except socket.timeout as exc:
-            raise TimeoutError(f"{self.device_name}: socket timeout error for {self.hostname}:{self.port}") from exc
-        except OSError as exc:
-            raise ConnectionError(f"{self.device_name}: OSError caught ({exc}).") from exc
-
-        self.is_connection_open = True
-
-    def disconnect(self):
-        """
-        Disconnect from the Ethernet connection.
-
-        Raises:
-            ConnectionError when the socket could not be closed.
-        """
-
-        try:
-            if self.is_connection_open:
-                logger.debug(f"Disconnecting from {self.hostname}")
-                self.socket.close()
-                self.is_connection_open = False
-        except Exception as e_exc:
-            raise ConnectionError(f"{self.device_name}: Could not close socket to {self.hostname}") from e_exc
-
-    def is_connected(self) -> bool:
-        """
-        Check if the device is connected.
-
-        Returns:
-             True is the device is connected, False otherwise.
-        """
-
-        return bool(self.is_connection_open)
-
-    def reconnect(self):
-        """
-        Reconnect to the device. If the connection is open, this function will first disconnect
-        and then connect again.
-        """
-
-        if self.is_connection_open:
-            self.disconnect()
-        self.connect()
-
-    def read(self) -> bytes:
-        """
-        Read until ETX (b'\x03') or until `self.read_timeout` elapses.
-        Uses `select` to avoid blocking indefinitely when no data is available.
-        If `self.read_timeout` was set to None in the constructor, this will block anyway.
-        """
-        if not self.socket:
-            raise DeviceConnectionError(self.device_name, "Not connected")
-
-        buf_size = 1024 * 4
-        response = bytearray()
-
-        # If read_timeout is None we preserve blocking behaviour; otherwise enforce overall timeout.
-        if self.read_timeout is None:
-            end_time = None
-        else:
-            end_time = time.monotonic() + self.read_timeout
-
-        try:
-            while True:
-                # compute the remaining timeout for select, this is needed because we read in different parts
-                # until ETX is received, and we want to receive the complete messages including ETX within
-                # the read timeout.
-                if end_time is None:
-                    timeout = None
-                else:
-                    remaining = end_time - time.monotonic()
-                    if remaining <= 0.0:
-                        raise DeviceTimeoutError(self.device_name, "Socket read timed out")
-                    timeout = remaining
-
-                ready, _, _ = select.select([self.socket], [], [], timeout)
-
-                if not ready:
-                    # no socket ready within timeout
-                    raise DeviceTimeoutError(self.device_name, "Socket read timed out")
-
-                try:
-                    data = self.socket.recv(buf_size)
-                except OSError as exc:
-                    raise DeviceConnectionError(self.device_name, f"Caught {type_name(exc)}: {exc}") from exc
-
-                if not data:
-                    # remote closed connection (EOF)
-                    raise DeviceConnectionError(self.device_name, "Connection closed by peer")
-
-                response.extend(data)
-
-                if self.separator in response:
-                    break
-
-        except DeviceTimeoutError:
-            raise
-        except DeviceConnectionError:
-            raise
-        except Exception as exc:
-            # unexpected errors - translate to DeviceConnectionError
-            raise DeviceConnectionError(self.device_name, "Socket read error") from exc
-
-        return bytes(response)
-
-    def write(self, command: str):
-        """
-        Send a command to the device.
-
-        No processing is done on the command string, except for the encoding into a bytes object.
-
-        Args:
-            command: the command string including terminators.
-
-        Raises:
-            A DeviceTimeoutError when the send timed out, and a DeviceConnectionError if
-            there was a socket related error.
-        """
-
-        try:
-            self.socket.sendall(command.encode())
-        except socket.timeout as exc:
-            raise DeviceTimeoutError(self.device_name, "Socket timeout error") from exc
-        except socket.error as exc:
-            # Interpret any socket-related error as an I/O error
-            raise DeviceConnectionError(self.device_name, "Socket communication error.") from exc
-
-    def trans(self, command: str) -> bytes:
-        """
-        Send a command to the device and wait for the response.
-
-        No processing is done on the command string, except for the encoding into a bytes object.
-
-        Args:
-            command: the command string including terminators.
-
-        Returns:
-            A bytes object containing the response from the device. No processing is done
-            on the response.
-
-        Raises:
-            A DeviceTimeoutError when the send timed out, and a DeviceConnectionError if
-            there was a socket related error.
-        """
-
-        try:
-            # Attempt to send the complete command
-
-            self.socket.sendall(command.encode())
-
-            # wait for, read and return the response (will be at most TBD chars)
-
-            return_string = self.read()
-
-            return return_string
-
-        except socket.timeout as exc:
-            raise DeviceTimeoutError(self.device_name, "Socket timeout error") from exc
-        except socket.error as exc:
-            # Interpret any socket-related error as an I/O error
-            raise DeviceConnectionError(self.device_name, "Socket communication error.") from exc
-
-
-class AsyncSocketDevice(AsyncDeviceInterface, AsyncDeviceTransport):
-    """
-    Async socket-backed device using asyncio streams.
-
-    - async connect() / disconnect()
-    - async read() reads until ETX (b'\\x03') or timeout
-    - async write() and async trans()
-    """
-
-    def __init__(
-        self,
-        hostname: str,
-        port: int,
-        connect_timeout: float = 3.0,
-        read_timeout: float | None = 1.0,
-        separator: str = b"\x03",
-    ):
-        super().__init__()
-        self.hostname = hostname
-        self.port = port
-        self.connect_timeout = connect_timeout
-        self.read_timeout = read_timeout
-        self.separator = separator
-        self.reader: Optional[asyncio.StreamReader] = None
-        self.writer: Optional[asyncio.StreamWriter] = None
-        self.is_connection_open = False
-
-    @property
-    def device_name(self) -> str:
-        # Override this property for a decent name
-        return f"AsyncSocketDevice({self.hostname}:{self.port})"
-
-    async def connect(self) -> None:
-        if self.is_connection_open:
-            logger.debug(f"{self.device_name}: already connected")
-            return
-
-        if not self.hostname:
-            raise ValueError(f"{self.device_name}: hostname is not initialized.")
-        if not self.port:
-            raise ValueError(f"{self.device_name}: port is not initialized.")
-
-        try:
-            logger.debug(f"{self.device_name}: connect() called; is_connection_open={self.is_connection_open}")
-            coro = asyncio.open_connection(self.hostname, self.port)
-            self.reader, self.writer = await asyncio.wait_for(coro, timeout=self.connect_timeout)
-            self.is_connection_open = True
-            logger.debug(f"{self.device_name}: connected -> peer={self.writer.get_extra_info('peername')}")
-
-        except asyncio.TimeoutError as exc:
-            await self._cleanup()
-            logger.warning(f"{self.device_name}: connect timed out")
-            raise DeviceTimeoutError(self.device_name, f"Connection to {self.hostname}:{self.port} timed out.") from exc
-        except Exception as exc:
-            await self._cleanup()
-            logger.warning(f"{self.device_name}: connect failed: {type_name(exc)} – {exc}")
-            raise DeviceConnectionError(self.device_name, f"Failed to connect to {self.hostname}:{self.port}") from exc
-
-    async def disconnect(self) -> None:
-        logger.debug(f"{self.device_name}: disconnect() called; writer_exists={bool(self.writer)}")
-        peer = None
-        try:
-            if self.writer and not self.writer.is_closing():
-                peer = self.writer.get_extra_info("peername")
-                self.writer.close()
-                # wait for close, but don't hang forever
-                try:
-                    await asyncio.wait_for(self.writer.wait_closed(), timeout=1.0)
-                except asyncio.TimeoutError:
-                    logger.debug(f"{self.device_name}: wait_closed() timed out for peer={peer}")
-
-        finally:
-            await self._cleanup()
-            logger.debug(f"{self.device_name}: disconnected ({peer=})")
-
-    def is_connected(self) -> bool:
-        return bool(self.is_connection_open and self.writer and not self.writer.is_closing())
-
-    async def _cleanup(self) -> None:
-        self.reader = None
-        self.writer = None
-        self.is_connection_open = False
-
-    async def read(self) -> bytes:
-        if not self.reader:
-            raise DeviceConnectionError(self.device_name, "Not connected")
-        try:
-            # readuntil includes the separator; we keep it for parity with existing code
-            data = await asyncio.wait_for(self.reader.readuntil(separator=self.separator), timeout=self.read_timeout)
-            return data
-        except asyncio.IncompleteReadError as exc:
-            # EOF before separator
-            await self._cleanup()
-            raise DeviceConnectionError(self.device_name, "Connection closed while reading") from exc
-        except asyncio.TimeoutError as exc:
-            raise DeviceTimeoutError(self.device_name, "Socket read timed out") from exc
-        except Exception as exc:
-            await self._cleanup()
-            raise DeviceConnectionError(self.device_name, "Socket read error") from exc
-
-    async def write(self, command: str) -> None:
-        if not self.writer:
-            raise DeviceConnectionError(self.device_name, "Not connected")
-        try:
-            self.writer.write(command.encode())
-            await asyncio.wait_for(self.writer.drain(), timeout=self.read_timeout)
-        except asyncio.TimeoutError as exc:
-            raise DeviceTimeoutError(self.device_name, "Socket write timed out") from exc
-        except Exception as exc:
-            await self._cleanup()
-            raise DeviceConnectionError(self.device_name, "Socket write error") from exc
-
-    async def trans(self, command: str) -> bytes:
-        if not self.writer or not self.reader:
-            raise DeviceConnectionError(self.device_name, "Not connected")
-        try:
-            await self.write(command)
-            return await self.read()
-        except (DeviceTimeoutError, DeviceConnectionError):
-            raise
-        except Exception as exc:
-            await self._cleanup()
-            raise DeviceConnectionError(self.device_name, "Socket trans error") from exc