conson-xp 1.18.0__py3-none-any.whl

xp/utils/serialization.py

@@ -0,0 +1,205 @@
+"""Binary serialization utility functions.
+
+This module provides common binary manipulation functions used across
+the XP protocol serializers for consistent data encoding/decoding.
+"""
+
+from typing import List
+
+# BCD and bit manipulation constants
+UPPER4 = 240  # 0xF0
+LOWER4 = 15  # 0x0F
+LOWER3 = 7  # 0x07
+UPPER5 = 248  # 0xF8
+
+
+def de_bcd(byte_val: int) -> int:
+    """Convert BCD byte to decimal.
+
+    Args:
+        byte_val: BCD encoded byte
+
+    Returns:
+        Decimal value
+    """
+    return ((UPPER4 & byte_val) >> 4) * 10 + (LOWER4 & byte_val)
+
+
+def to_bcd(decimal_val: int) -> int:
+    """Convert decimal to BCD byte.
+
+    Args:
+        decimal_val: Decimal value to convert
+
+    Returns:
+        BCD encoded byte
+    """
+    tens = (decimal_val // 10) % 10
+    ones = decimal_val % 10
+    return (tens << 4) | ones
+
+
+def lower3(byte_val: int) -> int:
+    """Extract lower 3 bits from byte.
+
+    Args:
+        byte_val: Input byte
+
+    Returns:
+        Lower 3 bits as integer
+    """
+    return byte_val & LOWER3
+
+
+def upper5(byte_val: int) -> int:
+    """Extract upper 5 bits from byte.
+
+    Args:
+        byte_val: Input byte
+
+    Returns:
+        Upper 5 bits as integer
+    """
+    return (byte_val & UPPER5) >> 3
+
+
+def byte_to_bits(byte_value: int) -> List[bool]:
+    """Convert a byte value to 8-bit boolean array.
+
+    Args:
+        byte_value: Byte value to convert
+
+    Returns:
+        List of 8 boolean values representing the bits
+    """
+    return [(byte_value & (1 << n)) != 0 for n in range(8)]
+
+
+def bits_to_byte(bits: List[bool]) -> int:
+    """Convert boolean array to byte value.
+
+    Args:
+        bits: List of boolean values representing bits
+
+    Returns:
+        Byte value
+    """
+    byte_val = 0
+    for i, bit in enumerate(bits[:8]):  # Limit to 8 bits
+        if bit:
+            byte_val |= 1 << i
+    return byte_val
+
+
+def highest_bit_set(value: int) -> int:
+    """Remove the high bit (0x80) from a byte value.
+
+    Args:
+        value: Byte value to process
+
+    Returns:
+        Value with high bit cleared (XOR with 0x80 if high bit was set)
+    """
+    return (value & 0x80) == 128
+
+
+def remove_highest_bit(value: int) -> int:
+    """Remove the high bit (0x80) from a byte value.
+
+    Args:
+        value: Byte value to process
+
+    Returns:
+        Value with high bit cleared (XOR with 0x80 if high bit was set)
+    """
+    return value ^ 0x80 if (value & 0x80) == 128 else value
+
+
+def byte_to_unsigned(byte_val: int) -> int:
+    """Convert signed byte to unsigned integer.
+
+    Args:
+        byte_val: Byte value (can be negative)
+
+    Returns:
+        Unsigned integer (0-255)
+    """
+    if byte_val < 0:
+        return byte_val + 256
+    return byte_val
+
+
+def nibble(byte_val: int) -> str:
+    """Convert byte value to two-character nibble representation.
+
+    Args:
+        byte_val: Byte value (0-255)
+
+    Returns:
+        Two-character string representing the nibble
+    """
+    low_cc = ((byte_val & 0xF0) >> 4) + 65
+    high_cc = (byte_val & 0xF) + 65
+    return chr(low_cc) + chr(high_cc)
+
+
+def de_nibble(nibble_str: str) -> int:
+    """Convert two-character nibble string to byte value.
+
+    Based on pseudocode: A=0, B=1, C=2, ..., P=15
+
+    Args:
+        nibble_str: Two-character string with A-P encoding
+
+    Returns:
+        Byte value (0-255)
+
+    Raises:
+        ValueError: If nibble string is not exactly 2 characters
+    """
+    if len(nibble_str) != 2:
+        raise ValueError("Nibble string must be exactly 2 characters")
+
+    high_char = nibble_str[0]
+    low_char = nibble_str[1]
+
+    # Convert A-P to 0-15 (A=65 in ASCII, so A-65=0)
+    high_nibble = (ord(high_char) - 65) << 4
+    low_nibble = ord(low_char) - 65
+
+    return high_nibble + low_nibble
+
+
+def de_nibbles(str_val: str) -> bytearray:
+    """Convert hex string with A-P encoding to list of integers.
+
+    Based on pseudocode: A=0, B=1, C=2, ..., P=15
+
+    Args:
+        str_val: Hex string with A-P encoding
+
+    Returns:
+        List of integers representing the decoded bytes
+
+    Raises:
+        ValueError: If string length is not even for nibble conversion
+    """
+    if len(str_val) % 2 != 0:
+        raise ValueError("String length must be even for nibble conversion")
+
+    result = bytearray()
+    for i in range(0, len(str_val), 2):
+        result.append(de_nibble(str_val[i : i + 2]))
+    return result
+
+
+def nibbles(data: bytes) -> str:
+    """Convert bytes data to nibble string representation.
+
+    Args:
+        data: Bytes data to convert
+
+    Returns:
+        String representation using A-P encoding
+    """
+    return "".join(nibble(byte) for byte in data)

xp/utils/time_utils.py

@@ -0,0 +1,134 @@
+"""Time parsing utilities for console bus logs."""
+
+import re
+from datetime import datetime, time
+from typing import Optional
+
+
+class TimeParsingError(Exception):
+    """Raised when time parsing fails."""
+
+    pass
+
+
+def parse_log_timestamp(
+    timestamp_str: str, base_date: Optional[datetime] = None
+) -> datetime:
+    """Parse timestamp from console bus log format: HH:MM:SS,mmm.
+
+    Args:
+        timestamp_str: Timestamp string (e.g., "22:44:20,352")
+        base_date: Base date to use (defaults to today)
+
+    Returns:
+        datetime object with parsed time
+
+    Raises:
+        TimeParsingError: If timestamp format is invalid
+    """
+    # Pattern: HH:MM:SS,mmm
+    pattern = r"^(\d{2}):(\d{2}):(\d{2}),(\d{3})$"
+    match = re.match(pattern, timestamp_str.strip())
+
+    if not match:
+        raise TimeParsingError(f"Invalid timestamp format: {timestamp_str}")
+
+    try:
+        hour = int(match.group(1))
+        minute = int(match.group(2))
+        second = int(match.group(3))
+        millisecond = int(match.group(4))
+
+        # Validate ranges
+        if not (0 <= hour <= 23):
+            raise TimeParsingError(f"Invalid hour: {hour}")
+        if not (0 <= minute <= 59):
+            raise TimeParsingError(f"Invalid minute: {minute}")
+        if not (0 <= second <= 59):
+            raise TimeParsingError(f"Invalid second: {second}")
+        if not (0 <= millisecond <= 999):
+            raise TimeParsingError(f"Invalid millisecond: {millisecond}")
+
+        # Create time object
+        time_obj = time(hour, minute, second, millisecond * 1000)  # microseconds
+
+        # Use base date or today
+        if base_date is None:
+            date_part = datetime.now().date()
+        else:
+            date_part = base_date.date()
+
+        return datetime.combine(date_part, time_obj)
+
+    except ValueError as e:
+        raise TimeParsingError(f"Error parsing timestamp {timestamp_str}: {e}")
+
+
+def format_log_timestamp(dt: datetime) -> str:
+    """Format datetime to console bus log timestamp format: HH:MM:SS,mmm.
+
+    Args:
+        dt: datetime object to format
+
+    Returns:
+        Formatted timestamp string
+    """
+    return dt.strftime("%H:%M:%S,%f")[:-3]  # Remove last 3 digits of microseconds
+
+
+def parse_time_range(
+    time_range_str: str, base_date: Optional[datetime] = None
+) -> tuple[datetime, datetime]:
+    """Parse time range string like "22:44:20,352-22:44:25,500".
+
+    Args:
+        time_range_str: Time range string
+        base_date: Base date to use
+
+    Returns:
+        Tuple of (start_time, end_time)
+
+    Raises:
+        TimeParsingError: If format is invalid
+    """
+    parts = time_range_str.split("-")
+    if len(parts) != 2:
+        raise TimeParsingError(f"Invalid time range format: {time_range_str}")
+
+    start_time = parse_log_timestamp(parts[0].strip(), base_date)
+    end_time = parse_log_timestamp(parts[1].strip(), base_date)
+
+    if start_time > end_time:
+        raise TimeParsingError(f"Start time {parts[0]} is after end time {parts[1]}")
+
+    return start_time, end_time
+
+
+def calculate_duration_ms(start_time: datetime, end_time: datetime) -> int:
+    """Calculate duration between two timestamps in milliseconds.
+
+    Args:
+        start_time: Start timestamp
+        end_time: End timestamp
+
+    Returns:
+        Duration in milliseconds
+    """
+    duration = end_time - start_time
+    return int(duration.total_seconds() * 1000)
+
+
+def is_valid_log_timestamp(timestamp_str: str) -> bool:
+    """Check if timestamp string is valid console bus log format.
+
+    Args:
+        timestamp_str: Timestamp string to validate
+
+    Returns:
+        True if valid format, False otherwise
+    """
+    try:
+        parse_log_timestamp(timestamp_str)
+        return True
+    except TimeParsingError:
+        return False