rocket-welder-sdk 1.0.5__py3-none-any.whl → 1.1.25__py3-none-any.whl

rocket_welder_sdk/__init__.py

@@ -1,8 +1,56 @@
 """
-Rocket Welder SDK - Python client library for RocketWelder video streaming services.
+RocketWelder SDK - Enterprise-grade Python client library for video streaming services.
+
+High-performance video streaming using shared memory (ZeroBuffer) for zero-copy operations.
 """
 
-from .client import Client
+import logging
+import os
+
+from .bytes_size import BytesSize
+from .connection_string import ConnectionMode, ConnectionString, Protocol
+from .controllers import DuplexShmController, IController, OneWayShmController
+from .gst_metadata import GstCaps, GstMetadata
+from .rocket_welder_client import RocketWelderClient
+
+# Alias for backward compatibility
+Client = RocketWelderClient
+
+__version__ = "1.1.0"
+
+# Configure library logger with NullHandler (best practice for libraries)
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+# Configure from environment variable and propagate to zerobuffer
+_log_level = os.environ.get("ROCKET_WELDER_LOG_LEVEL")
+if _log_level:
+    try:
+        # Set rocket-welder-sdk log level
+        logging.getLogger(__name__).setLevel(getattr(logging, _log_level.upper()))
+
+        # Propagate to zerobuffer if not already set
+        if not os.environ.get("ZEROBUFFER_LOG_LEVEL"):
+            os.environ["ZEROBUFFER_LOG_LEVEL"] = _log_level
+            # Also configure zerobuffer logger if already imported
+            zerobuffer_logger = logging.getLogger("zerobuffer")
+            zerobuffer_logger.setLevel(getattr(logging, _log_level.upper()))
+    except AttributeError:
+        pass  # Invalid log level, ignore
 
-__version__ = "1.0.0"
-__all__ = ["Client"]
+__all__ = [
+    # Core types
+    "BytesSize",
+    "Client",  # Backward compatibility
+    "ConnectionMode",
+    "ConnectionString",
+    "DuplexShmController",
+    # GStreamer metadata
+    "GstCaps",
+    "GstMetadata",
+    # Controllers
+    "IController",
+    "OneWayShmController",
+    "Protocol",
+    # Main client
+    "RocketWelderClient",
+]

rocket_welder_sdk/bytes_size.py

@@ -0,0 +1,234 @@
+"""
+Enterprise-grade Bytes size representation with parsing support.
+Matches C# Bytes struct functionality.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import ClassVar
+
+
+@dataclass(frozen=True)
+class BytesSize:
+    """
+    Immutable representation of byte sizes with human-readable formatting.
+
+    Supports parsing from strings like "256MB", "4KB", "1.5GB" etc.
+    """
+
+    _value: int
+    _precision: int = 0
+
+    def __init__(self, value: int, precision: int = 0) -> None:
+        """Initialize BytesSize with value and optional precision."""
+        object.__setattr__(self, "_value", value)
+        object.__setattr__(self, "_precision", precision)
+
+    # Size multipliers
+    _SUFFIXES: ClassVar[dict[str, int]] = {
+        "B": 1,
+        "K": 1024,
+        "KB": 1024,
+        "M": 1024 * 1024,
+        "MB": 1024 * 1024,
+        "G": 1024 * 1024 * 1024,
+        "GB": 1024 * 1024 * 1024,
+        "T": 1024 * 1024 * 1024 * 1024,
+        "TB": 1024 * 1024 * 1024 * 1024,
+        "P": 1024 * 1024 * 1024 * 1024 * 1024,
+        "PB": 1024 * 1024 * 1024 * 1024 * 1024,
+        "E": 1024 * 1024 * 1024 * 1024 * 1024 * 1024,
+        "EB": 1024 * 1024 * 1024 * 1024 * 1024 * 1024,
+    }
+
+    # Pattern for parsing size strings
+    _PATTERN: ClassVar[re.Pattern[str]] = re.compile(r"^([\d.,]+)\s*([KMGTPE]?B?)$", re.IGNORECASE)
+
+    @property
+    def value(self) -> int:
+        """Get the raw byte value."""
+        return self._value
+
+    def __int__(self) -> int:
+        """Convert to integer."""
+        return self._value
+
+    def __float__(self) -> float:
+        """Convert to float."""
+        return float(self._value)
+
+    def __str__(self) -> str:
+        """Format as human-readable string."""
+        return self._format_size(self._value, self._precision)
+
+    def __repr__(self) -> str:
+        """Developer-friendly representation."""
+        return f"BytesSize({self._value}, precision={self._precision})"
+
+    def __eq__(self, other: object) -> bool:
+        """Equality comparison."""
+        if isinstance(other, BytesSize):
+            return self._value == other._value
+        if isinstance(other, (int, float)):
+            return self._value == other
+        return False
+
+    def __lt__(self, other: BytesSize | int | float) -> bool:
+        """Less than comparison."""
+        if isinstance(other, BytesSize):
+            return self._value < other._value
+        if isinstance(other, (int, float)):
+            return self._value < other
+        return NotImplemented
+
+    def __le__(self, other: BytesSize | int | float) -> bool:
+        """Less than or equal comparison."""
+        if isinstance(other, BytesSize):
+            return self._value <= other._value
+        if isinstance(other, (int, float)):
+            return self._value <= other
+        return NotImplemented
+
+    def __gt__(self, other: BytesSize | int | float) -> bool:
+        """Greater than comparison."""
+        if isinstance(other, BytesSize):
+            return self._value > other._value
+        if isinstance(other, (int, float)):
+            return self._value > other
+        return NotImplemented
+
+    def __ge__(self, other: BytesSize | int | float) -> bool:
+        """Greater than or equal comparison."""
+        if isinstance(other, BytesSize):
+            return self._value >= other._value
+        if isinstance(other, (int, float)):
+            return self._value >= other
+        return NotImplemented
+
+    def __add__(self, other: BytesSize | int) -> BytesSize:
+        """Add byte sizes."""
+        if isinstance(other, BytesSize):
+            return BytesSize(self._value + other._value, self._precision)
+        if isinstance(other, int):
+            return BytesSize(self._value + other, self._precision)
+        return NotImplemented
+
+    def __sub__(self, other: BytesSize | int) -> BytesSize:
+        """Subtract byte sizes."""
+        if isinstance(other, BytesSize):
+            return BytesSize(self._value - other._value, self._precision)
+        if isinstance(other, int):
+            return BytesSize(self._value - other, self._precision)
+        return NotImplemented
+
+    @classmethod
+    def parse(cls, value: str | int | float | BytesSize) -> BytesSize:
+        """
+        Parse a string, number, or BytesSize into a BytesSize object.
+
+        Args:
+            value: Value to parse (e.g., "256MB", 1024, "4.5GB")
+
+        Returns:
+            BytesSize instance
+
+        Raises:
+            ValueError: If the value cannot be parsed
+        """
+        if isinstance(value, BytesSize):
+            return value
+
+        if isinstance(value, (int, float)):
+            return cls(int(value))
+
+        if not isinstance(value, str):
+            raise ValueError(f"Cannot parse {type(value).__name__} as BytesSize")
+
+        # Clean the string
+        value = value.strip()
+        if not value:
+            raise ValueError("Cannot parse empty string as BytesSize")
+
+        # Try to match the pattern
+        match = cls._PATTERN.match(value)
+        if not match:
+            raise ValueError(f"Invalid byte size format: '{value}'")
+
+        number_str, suffix = match.groups()
+
+        # Parse the number part (handle different locales)
+        number_str = number_str.replace(",", "")  # Remove thousands separators
+        try:
+            number = float(number_str)
+        except ValueError as e:
+            raise ValueError(f"Invalid number in byte size: '{number_str}'") from e
+
+        # Get the multiplier
+        suffix = suffix.upper() if suffix else "B"
+        multiplier = cls._SUFFIXES.get(suffix, 0)
+
+        if multiplier == 0:
+            raise ValueError(f"Unknown size suffix: '{suffix}'")
+
+        # Calculate the bytes
+        bytes_value = int(number * multiplier)
+        return cls(bytes_value)
+
+    @classmethod
+    def try_parse(cls, value: str | int | float | BytesSize) -> BytesSize | None:
+        """
+        Try to parse a value into BytesSize, returning None on failure.
+
+        Args:
+            value: Value to parse
+
+        Returns:
+            BytesSize instance or None if parsing failed
+        """
+        try:
+            return cls.parse(value)
+        except (ValueError, TypeError):
+            return None
+
+    @staticmethod
+    def _format_size(bytes_value: int, precision: int = 0) -> str:
+        """
+        Format bytes as human-readable string.
+
+        Args:
+            bytes_value: Number of bytes
+            precision: Decimal precision for formatting
+
+        Returns:
+            Formatted string (e.g., "256MB", "1.5GB")
+        """
+        if bytes_value == 0:
+            return "0B"
+
+        # Determine the appropriate unit
+        units = ["B", "KB", "MB", "GB", "TB", "PB", "EB"]
+        unit_index = 0
+        size = float(bytes_value)
+
+        while size >= 1024 and unit_index < len(units) - 1:
+            size /= 1024
+            unit_index += 1
+
+        # Format based on precision
+        if precision > 0:
+            return f"{size:.{precision}f}{units[unit_index]}"
+        elif size == int(size):
+            return f"{int(size)}{units[unit_index]}"
+        else:
+            # Auto precision (up to 2 decimal places, remove trailing zeros)
+            return f"{size:.2f}".rstrip("0").rstrip(".") + units[unit_index]
+
+
+# Convenience constants
+ZERO = BytesSize(0)
+KB = BytesSize(1024)
+MB = BytesSize(1024 * 1024)
+GB = BytesSize(1024 * 1024 * 1024)
+TB = BytesSize(1024 * 1024 * 1024 * 1024)

rocket_welder_sdk/connection_string.py

@@ -0,0 +1,232 @@
+"""
+Enterprise-grade Connection String implementation for RocketWelder SDK.
+Matches C# ConnectionString struct functionality.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass, field
+from enum import Enum, Flag, auto
+from typing import Any
+
+from .bytes_size import BytesSize
+
+
+class Protocol(Flag):
+    """Protocol flags for connection types."""
+
+    NONE = 0
+    SHM = auto()  # Shared memory
+    MJPEG = auto()  # Motion JPEG
+    HTTP = auto()  # HTTP protocol
+    TCP = auto()  # TCP protocol
+
+
+class ConnectionMode(Enum):
+    """Connection mode for duplex/one-way communication."""
+
+    ONE_WAY = "OneWay"
+    DUPLEX = "Duplex"
+
+    def __str__(self) -> str:
+        """String representation."""
+        return self.value
+
+
+@dataclass(frozen=True)
+class ConnectionString:
+    """
+    Immutable connection string representation for RocketWelder SDK.
+
+    Supports parsing connection strings like:
+    - shm://buffer_name?size=256MB&metadata=4KB&mode=Duplex
+    - mjpeg://192.168.1.100:8080
+    - mjpeg+http://camera.local:80
+    """
+
+    protocol: Protocol
+    host: str | None = None
+    port: int | None = None
+    buffer_name: str | None = None
+    buffer_size: BytesSize = field(default_factory=lambda: BytesSize.parse("256MB"))
+    metadata_size: BytesSize = field(default_factory=lambda: BytesSize.parse("4KB"))
+    connection_mode: ConnectionMode = ConnectionMode.ONE_WAY
+    timeout_ms: int = 5000
+
+    @classmethod
+    def parse(cls, connection_string: str) -> ConnectionString:
+        """
+        Parse a connection string into a ConnectionString object.
+
+        Args:
+            connection_string: Connection string to parse
+
+        Returns:
+            ConnectionString instance
+
+        Raises:
+            ValueError: If the connection string format is invalid
+        """
+        if not connection_string:
+            raise ValueError("Connection string cannot be empty")
+
+        # Handle special protocols
+        if "://" not in connection_string:
+            raise ValueError(f"Invalid connection string format: {connection_string}")
+
+        # Split protocol and remainder
+        protocol_str, remainder = connection_string.split("://", 1)
+        protocol = cls._parse_protocol(protocol_str)
+
+        # Parse based on protocol type
+        if protocol == Protocol.SHM:
+            return cls._parse_shm(protocol, remainder)
+        elif bool(protocol & Protocol.MJPEG):  # type: ignore[operator]
+            return cls._parse_mjpeg(protocol, remainder)
+        else:
+            raise ValueError(f"Unsupported protocol: {protocol_str}")
+
+    @classmethod
+    def _parse_protocol(cls, protocol_str: str) -> Protocol:
+        """Parse protocol string into Protocol flags."""
+        protocol_str = protocol_str.lower()
+
+        # Handle combined protocols (e.g., mjpeg+http)
+        if "+" in protocol_str:
+            parts = protocol_str.split("+")
+            result = Protocol.NONE
+            for part in parts:
+                result |= cls._get_single_protocol(part)
+            return result
+        else:
+            return cls._get_single_protocol(protocol_str)
+
+    @classmethod
+    def _get_single_protocol(cls, protocol_str: str) -> Protocol:
+        """Get a single protocol from string."""
+        protocol_map = {
+            "shm": Protocol.SHM,
+            "mjpeg": Protocol.MJPEG,
+            "http": Protocol.HTTP,
+            "tcp": Protocol.TCP,
+        }
+
+        protocol = protocol_map.get(protocol_str, Protocol.NONE)
+        if protocol == Protocol.NONE:
+            raise ValueError(f"Unknown protocol: {protocol_str}")
+        return protocol
+
+    @classmethod
+    def _parse_shm(cls, protocol: Protocol, remainder: str) -> ConnectionString:
+        """Parse shared memory connection string."""
+        # Split buffer name and query parameters
+        if "?" in remainder:
+            buffer_name, query_string = remainder.split("?", 1)
+            params = cls._parse_query_params(query_string)
+        else:
+            buffer_name = remainder
+            params = {}
+
+        # Parse parameters
+        buffer_size = BytesSize.parse("256MB")
+        metadata_size = BytesSize.parse("4KB")
+        connection_mode = ConnectionMode.ONE_WAY
+        timeout_ms = 5000
+
+        if "size" in params:
+            buffer_size = BytesSize.parse(params["size"])
+        if "metadata" in params:
+            metadata_size = BytesSize.parse(params["metadata"])
+        if "mode" in params:
+            mode_str = params["mode"].upper()
+            if mode_str == "DUPLEX":
+                connection_mode = ConnectionMode.DUPLEX
+            elif mode_str == "ONEWAY" or mode_str == "ONE_WAY":
+                connection_mode = ConnectionMode.ONE_WAY
+        if "timeout" in params:
+            with contextlib.suppress(ValueError):
+                timeout_ms = int(params["timeout"])
+
+        return cls(
+            protocol=protocol,
+            buffer_name=buffer_name,
+            buffer_size=buffer_size,
+            metadata_size=metadata_size,
+            connection_mode=connection_mode,
+            timeout_ms=timeout_ms,
+        )
+
+    @classmethod
+    def _parse_mjpeg(cls, protocol: Protocol, remainder: str) -> ConnectionString:
+        """Parse MJPEG connection string."""
+        # Parse host:port format
+        if ":" in remainder:
+            host, port_str = remainder.rsplit(":", 1)
+            try:
+                port = int(port_str)
+            except ValueError as e:
+                raise ValueError(f"Invalid port number: {port_str}") from e
+        else:
+            host = remainder
+            # Default ports based on protocol
+            port = 80 if Protocol.HTTP in protocol else 8080
+
+        return cls(protocol=protocol, host=host, port=port)
+
+    @classmethod
+    def _parse_query_params(cls, query_string: str) -> dict[str, str]:
+        """Parse query parameters from string."""
+        params: dict[str, str] = {}
+        if not query_string:
+            return params
+
+        pairs = query_string.split("&")
+        for pair in pairs:
+            if "=" in pair:
+                key, value = pair.split("=", 1)
+                params[key.lower()] = value
+
+        return params
+
+    def __str__(self) -> str:
+        """Convert to connection string format."""
+        # Format protocol
+        protocol_parts = []
+        if self.protocol & Protocol.SHM:
+            protocol_parts.append("shm")
+        if self.protocol & Protocol.MJPEG:
+            protocol_parts.append("mjpeg")
+        if self.protocol & Protocol.HTTP:
+            protocol_parts.append("http")
+        if self.protocol & Protocol.TCP:
+            protocol_parts.append("tcp")
+
+        protocol_str = "+".join(protocol_parts)
+
+        # Format based on protocol type
+        if self.protocol == Protocol.SHM:
+            params = [
+                f"size={self.buffer_size}",
+                f"metadata={self.metadata_size}",
+                f"mode={self.connection_mode.value}",
+            ]
+            if self.timeout_ms != 5000:
+                params.append(f"timeout={self.timeout_ms}")
+
+            return f"{protocol_str}://{self.buffer_name}?{'&'.join(params)}"
+        else:
+            return f"{protocol_str}://{self.host}:{self.port}"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "protocol": str(self.protocol),
+            "host": self.host,
+            "port": self.port,
+            "buffer_name": self.buffer_name,
+            "buffer_size": str(self.buffer_size),
+            "metadata_size": str(self.metadata_size),
+            "connection_mode": self.connection_mode.value,
+            "timeout_ms": self.timeout_ms,
+        }