oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/automotive/loaders/csv_can.py

@@ -17,6 +17,142 @@ from oscura.automotive.can.models import CANMessage, CANMessageList
 __all__ = ["load_csv_can"]
 
 
+def _detect_csv_columns(fieldnames: list[str] | None) -> dict[str, str]:
+    """Detect required column names from CSV header.
+
+    Args:
+        fieldnames: List of column names from CSV header.
+
+    Returns:
+        Dictionary mapping logical names to actual column names.
+
+    Raises:
+        ValueError: If CSV has no header or missing required columns.
+    """
+    if not fieldnames:
+        raise ValueError("CSV file has no header row")
+
+    # Normalize column names to lowercase
+    fieldnames_lower = [name.lower().strip() for name in fieldnames]
+
+    # Find required columns
+    timestamp_col = None
+    id_col = None
+    data_col = None
+
+    for col in fieldnames_lower:
+        if "timestamp" in col or col == "time" or col == "t":
+            timestamp_col = col
+        elif "id" in col or col == "can_id" or col == "arbitration_id":
+            id_col = col
+        elif "data" in col or col == "payload" or col == "bytes":
+            data_col = col
+
+    if not all([timestamp_col is not None, id_col is not None, data_col is not None]):
+        raise ValueError(
+            f"CSV file missing required columns. "
+            f"Found: {fieldnames_lower}. "
+            f"Need: timestamp, id, data"
+        )
+
+    # All columns are guaranteed non-None here due to validation above
+    return {
+        "timestamp": str(timestamp_col),
+        "id": str(id_col),
+        "data": str(data_col),
+    }
+
+
+def _parse_csv_row(
+    row_dict: dict[str, str],
+    column_mapping: dict[str, str],
+    messages: CANMessageList,
+) -> None:
+    """Parse a single CSV row into a CAN message.
+
+    Args:
+        row_dict: Dictionary of row data from CSV.
+        column_mapping: Mapping of logical names to column names.
+        messages: Message list to append to.
+    """
+    # Create lowercase dict for case-insensitive access
+    row = {k.lower().strip(): v for k, v in row_dict.items()}
+
+    try:
+        # Parse timestamp
+        timestamp = float(row[column_mapping["timestamp"]])
+
+        # Parse ID (handle hex or decimal)
+        arb_id = _parse_can_id(row[column_mapping["id"]])
+
+        # Parse data bytes
+        data_bytes = _parse_data_bytes(row[column_mapping["data"]])
+
+        # Determine if extended (>11 bits = 0x7FF)
+        is_extended = arb_id > 0x7FF
+
+        # Create and append message
+        can_msg = CANMessage(
+            arbitration_id=arb_id,
+            timestamp=timestamp,
+            data=data_bytes,
+            is_extended=is_extended,
+            is_fd=False,
+            channel=0,
+        )
+        messages.append(can_msg)
+
+    except (ValueError, KeyError):
+        # Skip malformed rows silently
+        pass
+
+
+def _parse_can_id(id_str: str) -> int:
+    """Parse CAN ID from string (hex or decimal).
+
+    Args:
+        id_str: CAN ID string.
+
+    Returns:
+        CAN ID as integer.
+
+    Raises:
+        ValueError: If ID cannot be parsed.
+    """
+    id_str = id_str.strip()
+
+    if id_str.startswith("0x") or id_str.startswith("0X"):
+        return int(id_str, 16)
+
+    # Try as int first, then hex
+    try:
+        return int(id_str)
+    except ValueError:
+        return int(id_str, 16)
+
+
+def _parse_data_bytes(data_str: str) -> bytes:
+    """Parse data bytes from hex string.
+
+    Args:
+        data_str: Data bytes as hex string.
+
+    Returns:
+        Parsed bytes.
+
+    Raises:
+        ValueError: If data cannot be parsed.
+    """
+    # Remove common separators and spaces
+    data_str = data_str.strip().replace(" ", "").replace(":", "").replace("-", "")
+
+    # Remove 0x prefix if present
+    if data_str.startswith("0x") or data_str.startswith("0X"):
+        data_str = data_str[2:]
+
+    return bytes.fromhex(data_str)
+
+
 def load_csv_can(file_path: Path | str, delimiter: str = ",") -> CANMessageList:
     """Load CAN messages from a CSV file.
 
@@ -54,79 +190,14 @@ def load_csv_can(file_path: Path | str, delimiter: str = ",") -> CANMessageList:
         with open(path, encoding="utf-8") as f:
             reader = csv.DictReader(f, delimiter=delimiter)
 
-            # Try to detect column names
-            if not reader.fieldnames:
-                raise ValueError("CSV file has no header row")
-
-            # Normalize column names to lowercase for easier matching
-            fieldnames = [name.lower().strip() for name in reader.fieldnames]
-
-            # Find required columns
-            timestamp_col = None
-            id_col = None
-            data_col = None
-
-            for col in fieldnames:
-                if "timestamp" in col or col == "time" or col == "t":
-                    timestamp_col = col
-                elif "id" in col or col == "can_id" or col == "arbitration_id":
-                    id_col = col
-                elif "data" in col or col == "payload" or col == "bytes":
-                    data_col = col
-
-            if not all([timestamp_col, id_col, data_col]):
-                raise ValueError(
-                    f"CSV file missing required columns. "
-                    f"Found: {fieldnames}. "
-                    f"Need: timestamp, id, data"
-                )
-
-            # Parse messages
+            # Detect and validate column layout
+            column_mapping = _detect_csv_columns(
+                list(reader.fieldnames) if reader.fieldnames else None
+            )
+
+            # Parse all message rows
             for row_dict in reader:
-                # Create lowercase dict for case-insensitive access
-                row = {k.lower().strip(): v for k, v in row_dict.items()}
-
-                try:
-                    # Parse timestamp
-                    timestamp = float(row[timestamp_col])
-
-                    # Parse ID (handle hex or decimal)
-                    id_str = row[id_col].strip()
-                    if id_str.startswith("0x") or id_str.startswith("0X"):
-                        arb_id = int(id_str, 16)
-                    else:
-                        # Try as int first, then hex
-                        try:
-                            arb_id = int(id_str)
-                        except ValueError:
-                            arb_id = int(id_str, 16)
-
-                    # Parse data bytes
-                    data_str = row[data_col].strip()
-                    # Remove common separators and spaces
-                    data_str = data_str.replace(" ", "").replace(":", "").replace("-", "")
-                    # Remove 0x prefix if present
-                    if data_str.startswith("0x") or data_str.startswith("0X"):
-                        data_str = data_str[2:]
-                    data_bytes = bytes.fromhex(data_str)
-
-                    # Determine if extended (>11 bits = 0x7FF)
-                    is_extended = arb_id > 0x7FF
-
-                    # Create message
-                    can_msg = CANMessage(
-                        arbitration_id=arb_id,
-                        timestamp=timestamp,
-                        data=data_bytes,
-                        is_extended=is_extended,
-                        is_fd=False,
-                        channel=0,
-                    )
-                    messages.append(can_msg)
-
-                except (ValueError, KeyError):
-                    # Skip malformed rows
-                    continue
+                _parse_csv_row(row_dict, column_mapping, messages)
 
     except Exception as e:
         raise ValueError(f"Failed to parse CSV file {path}: {e}") from e

oscura/automotive/loaders/dispatcher.py

@@ -27,6 +27,32 @@ def detect_format(file_path: Path | str) -> str:
     path = Path(file_path)
 
     # Check extension first
+    ext_format = _detect_by_extension(path)
+    if ext_format != "unknown":
+        return ext_format
+
+    # Check binary file contents
+    binary_format = _detect_by_binary_header(path)
+    if binary_format != "unknown":
+        return binary_format
+
+    # Check text file contents
+    text_format = _detect_by_text_content(path)
+    if text_format != "unknown":
+        return text_format
+
+    return "unknown"
+
+
+def _detect_by_extension(path: Path) -> str:
+    """Detect format by file extension.
+
+    Args:
+        path: Path to the file.
+
+    Returns:
+        Format name or 'unknown'.
+    """
     ext = path.suffix.lower()
 
     if ext == ".blf":
@@ -40,7 +66,18 @@ def detect_format(file_path: Path | str) -> str:
     elif ext in [".pcap", ".pcapng"]:
         return "pcap"
 
-    # If extension is ambiguous, check file contents
+    return "unknown"
+
+
+def _detect_by_binary_header(path: Path) -> str:
+    """Detect format by binary file header.
+
+    Args:
+        path: Path to the file.
+
+    Returns:
+        Format name or 'unknown'.
+    """
     try:
         with open(path, "rb") as f:
             header = f.read(16)
@@ -60,7 +97,18 @@ def detect_format(file_path: Path | str) -> str:
     except Exception:
         pass
 
-    # Try as text file
+    return "unknown"
+
+
+def _detect_by_text_content(path: Path) -> str:
+    """Detect format by text file content.
+
+    Args:
+        path: Path to the file.
+
+    Returns:
+        Format name or 'unknown'.
+    """
     try:
         with open(path, encoding="utf-8") as f:
             first_line = f.readline().strip()

oscura/automotive/loaders/mdf.py

@@ -47,7 +47,7 @@ def load_mdf(file_path: Path | str) -> CANMessageList:
         >>> print(f"Unique IDs: {len(messages.unique_ids())}")
     """
     try:
-        from asammdf import MDF  # type: ignore[import-untyped]
+        from asammdf import MDF
     except ImportError as e:
         raise ImportError(
             "asammdf is required for MDF/MF4 file support. "
@@ -142,63 +142,104 @@ def _extract_structured_can_frames(
         timestamps: Array of timestamps.
         messages: CANMessageList to append to.
     """
-    # Common field names in structured CAN logging
-    id_fields = ["ID", "id", "BusID", "Identifier", "ArbitrationID"]
-    data_fields = ["Data", "data", "DataBytes", "Payload"]
-    dlc_fields = ["DLC", "dlc", "DataLength"]
-
-    # Find which fields are present
     field_names = samples.dtype.names
     if not field_names:
         return
 
-    id_field = next((f for f in id_fields if f in field_names), None)
-    data_field = next((f for f in data_fields if f in field_names), None)
-    dlc_field = next((f for f in dlc_fields if f in field_names), None)
-
-    if not id_field:
+    field_map = _find_can_field_mapping(field_names)
+    if not field_map["id_field"]:
         return
 
     for i in range(len(samples)):
         try:
-            # Extract CAN ID
-            arb_id = int(samples[id_field][i])
-
-            # Extract data bytes
-            if data_field:
-                data_bytes = samples[data_field][i]
-                if isinstance(data_bytes, bytes):
-                    data = data_bytes
-                else:
-                    # Convert array to bytes
-                    data = bytes(data_bytes)
-            else:
-                data = b""
-
-            # Extract DLC if available
-            if dlc_field:
-                dlc = int(samples[dlc_field][i])
-                data = data[:dlc]
-
-            # Determine if extended ID
-            is_extended = arb_id > 0x7FF
-
-            # Create message
-            can_msg = CANMessage(
-                arbitration_id=arb_id,
-                timestamp=float(timestamps[i]),
-                data=data,
-                is_extended=is_extended,
-                is_fd=False,  # MDF doesn't typically indicate CAN-FD
-                channel=0,  # Channel info not always available in MDF
-            )
+            can_msg = _extract_can_message_from_sample(samples, timestamps, i, field_map)
             messages.append(can_msg)
-
         except (IndexError, ValueError, TypeError):
-            # Skip malformed frames
             continue
 
 
+def _find_can_field_mapping(field_names: tuple[str, ...]) -> dict[str, str | None]:
+    """Find mapping of CAN field names in structured array.
+
+    Args:
+        field_names: Field names from structured array.
+
+    Returns:
+        Dictionary mapping field types to actual field names.
+    """
+    id_fields = ["ID", "id", "BusID", "Identifier", "ArbitrationID"]
+    data_fields = ["Data", "data", "DataBytes", "Payload"]
+    dlc_fields = ["DLC", "dlc", "DataLength"]
+
+    return {
+        "id_field": next((f for f in id_fields if f in field_names), None),
+        "data_field": next((f for f in data_fields if f in field_names), None),
+        "dlc_field": next((f for f in dlc_fields if f in field_names), None),
+    }
+
+
+def _extract_can_message_from_sample(
+    samples: npt.NDArray[Any],
+    timestamps: npt.NDArray[Any],
+    index: int,
+    field_map: dict[str, str | None],
+) -> CANMessage:
+    """Extract single CAN message from sample.
+
+    Args:
+        samples: Structured array.
+        timestamps: Timestamp array.
+        index: Sample index.
+        field_map: Field name mapping.
+
+    Returns:
+        CANMessage instance.
+    """
+    arb_id = int(samples[field_map["id_field"]][index])
+    data = _extract_can_data_field(samples, index, field_map)
+    is_extended = arb_id > 0x7FF
+
+    return CANMessage(
+        arbitration_id=arb_id,
+        timestamp=float(timestamps[index]),
+        data=data,
+        is_extended=is_extended,
+        is_fd=False,
+        channel=0,
+    )
+
+
+def _extract_can_data_field(
+    samples: npt.NDArray[Any], index: int, field_map: dict[str, str | None]
+) -> bytes:
+    """Extract data bytes from sample.
+
+    Args:
+        samples: Structured array.
+        index: Sample index.
+        field_map: Field name mapping.
+
+    Returns:
+        Data bytes.
+    """
+    data_field = field_map["data_field"]
+    if not data_field:
+        return b""
+
+    data_bytes = samples[data_field][index]
+    if isinstance(data_bytes, bytes):
+        data = data_bytes
+    else:
+        data = bytes(data_bytes)
+
+    dlc_field = field_map["dlc_field"]
+    if dlc_field:
+        dlc = int(samples[dlc_field][index])
+        data = data[:dlc]
+
+    return data
+
+
 def _extract_raw_can_frames(
     samples: npt.NDArray[Any], timestamps: npt.NDArray[Any], messages: CANMessageList
 ) -> None:

oscura/automotive/loaders/pcap.py

@@ -15,13 +15,9 @@ Requirements:
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING
 
 from oscura.automotive.can.models import CANMessage, CANMessageList
 
-if TYPE_CHECKING:
-    from scapy.packet import Packet  # type: ignore[import-not-found]
-
 __all__ = ["load_pcap"]
 
 
@@ -58,67 +54,12 @@ def load_pcap(file_path: Path | str) -> CANMessageList:
     if not path.exists():
         raise FileNotFoundError(f"PCAP file not found: {path}")
 
-    try:
-        from scapy.all import rdpcap  # type: ignore[import-not-found]
-        from scapy.layers.can import CAN  # type: ignore[import-not-found]
-    except ImportError as e:
-        msg = "scapy library is required for PCAP loading. Install with: uv pip install scapy"
-        raise ImportError(msg) from e
-
+    rdpcap, CAN = _import_scapy_modules()
     messages = CANMessageList()
 
     try:
-        # Read PCAP file
         packets = rdpcap(str(path))
-
-        # Extract CAN frames
-        first_timestamp: float | None = None
-        for packet in packets:
-            # Check if packet contains CAN layer
-            if CAN in packet:
-                can_frame: Packet = packet[CAN]
-
-                # Get timestamp
-                if hasattr(packet, "time"):
-                    if first_timestamp is None:
-                        first_timestamp = float(packet.time)
-                    timestamp = float(packet.time) - first_timestamp
-                else:
-                    timestamp = 0.0
-
-                # Extract CAN ID and data
-                arb_id = int(can_frame.identifier)
-
-                # Get data bytes (scapy stores CAN data as bytes)
-                if hasattr(can_frame, "data"):
-                    data = bytes(can_frame.data)
-                else:
-                    data = b""
-
-                # Determine if extended ID (bit 31 indicates extended format)
-                # SocketCAN uses bit 31 for extended frame flag
-                is_extended = bool(arb_id & 0x80000000)
-                if is_extended:
-                    arb_id = arb_id & 0x1FFFFFFF  # Mask to get 29-bit ID
-
-                # Determine if CAN-FD (scapy may have an FD flag)
-                is_fd = hasattr(can_frame, "flags") and (can_frame.flags & 0x01)
-
-                # Extract channel if available
-                channel = 0
-                if hasattr(can_frame, "channel"):
-                    channel = int(can_frame.channel)
-
-                # Create CANMessage
-                can_msg = CANMessage(
-                    arbitration_id=arb_id,
-                    timestamp=timestamp,
-                    data=data,
-                    is_extended=is_extended,
-                    is_fd=is_fd,
-                    channel=channel,
-                )
-                messages.append(can_msg)
+        _extract_can_messages(packets, CAN, messages)
 
     except Exception as e:
         raise ValueError(f"Failed to parse PCAP file {path}: {e}") from e
@@ -130,3 +71,112 @@ def load_pcap(file_path: Path | str) -> CANMessageList:
         )
 
     return messages
+
+
+def _import_scapy_modules() -> tuple[type, type]:
+    """Import and return required scapy modules.
+
+    Returns:
+        Tuple of (rdpcap function, CAN class).
+
+    Raises:
+        ImportError: If scapy is not installed.
+    """
+    try:
+        from scapy.all import rdpcap
+        from scapy.layers.can import CAN
+
+        return rdpcap, CAN  # type: ignore[return-value]
+    except ImportError as e:
+        msg = "scapy library is required for PCAP loading. Install with: uv pip install scapy"
+        raise ImportError(msg) from e
+
+
+def _extract_can_messages(
+    packets: list[object], CAN: type, messages: CANMessageList
+) -> float | None:
+    """Extract CAN messages from PCAP packets.
+
+    Args:
+        packets: List of scapy packets.
+        CAN: CAN layer class from scapy.
+        messages: CANMessageList to populate.
+
+    Returns:
+        First timestamp value for reference.
+    """
+    first_timestamp: float | None = None
+
+    for packet in packets:
+        if CAN in packet:  # type: ignore[operator]
+            can_frame = packet[CAN]  # type: ignore[index]
+            timestamp = _extract_timestamp(packet, first_timestamp)
+
+            if first_timestamp is None and hasattr(packet, "time"):
+                first_timestamp = float(packet.time)
+
+            can_msg = _create_can_message(can_frame, timestamp)
+            messages.append(can_msg)
+
+    return first_timestamp
+
+
+def _extract_timestamp(packet: object, first_timestamp: float | None) -> float:
+    """Extract and normalize timestamp from packet.
+
+    Args:
+        packet: Scapy packet with time attribute.
+        first_timestamp: Reference timestamp for normalization.
+
+    Returns:
+        Normalized timestamp in seconds.
+    """
+    if hasattr(packet, "time"):
+        if first_timestamp is None:
+            return 0.0
+        return float(packet.time) - first_timestamp
+    return 0.0
+
+
+def _create_can_message(can_frame: object, timestamp: float) -> CANMessage:
+    """Create CANMessage from scapy CAN frame.
+
+    Args:
+        can_frame: Scapy CAN frame object.
+        timestamp: Message timestamp.
+
+    Returns:
+        CANMessage object.
+    """
+    arb_id: int = int(can_frame.identifier)  # type: ignore[attr-defined]
+    # Check if data attribute exists before accessing
+    if hasattr(can_frame, "data"):
+        data: bytes = bytes(can_frame.data)
+    else:
+        data = b""
+
+    # Determine if extended ID (bit 31 indicates extended format)
+    is_extended = bool(arb_id & 0x80000000)
+    if is_extended:
+        arb_id = arb_id & 0x1FFFFFFF  # Mask to get 29-bit ID
+
+    # Determine if CAN-FD
+    if hasattr(can_frame, "flags"):
+        is_fd: bool = bool(can_frame.flags & 0x01)
+    else:
+        is_fd = False
+
+    # Extract channel if available
+    if hasattr(can_frame, "channel"):
+        channel: int = int(can_frame.channel)
+    else:
+        channel = 0
+
+    return CANMessage(
+        arbitration_id=arb_id,
+        timestamp=timestamp,
+        data=data,
+        is_extended=is_extended,
+        is_fd=is_fd,
+        channel=channel,
+    )

oscura/automotive/uds/__init__.py

@@ -37,10 +37,14 @@ Example:
 """
 
 __all__ = [
+    "UDSECU",
+    "UDSAnalyzer",
     "UDSDecoder",
+    "UDSMessage",
     "UDSNegativeResponse",
     "UDSService",
 ]
 
+from oscura.automotive.uds.analyzer import UDSECU, UDSAnalyzer, UDSMessage
 from oscura.automotive.uds.decoder import UDSDecoder
 from oscura.automotive.uds.models import UDSNegativeResponse, UDSService