mpflash 1.26.2__py3-none-any.whl → 1.26.4__py3-none-any.whl

mpflash/flash/worklist.py

@@ -1,5 +1,30 @@
-"""Worklist for updating boards"""
+"""Worklist for updating boards.
 
+This module provides functionality for creating worklists - collections of board-firmware
+pairs that need to be flashed.
+
+The API provides a clean, maintainable interface:
+
+```python
+from mpflash.flash.worklist import create_worklist, WorklistConfig
+
+# Simple auto-detection
+config = WorklistConfig.for_auto_detection("1.22.0")
+tasks = create_auto_worklist(connected_comports, config)
+
+# Or use the high-level function
+tasks = create_worklist("1.22.0", connected_comports=boards)
+
+# Manual board specification
+tasks = create_worklist("1.22.0", serial_ports=["COM1"], board_id="ESP32_GENERIC")
+
+# Filtered boards
+tasks = create_worklist("1.22.0", connected_comports=all_boards, include_ports=["COM*"])
+```
+
+"""
+
+from dataclasses import dataclass
 from typing import List, Optional, Tuple
 
 from loguru import logger as log
@@ -15,170 +40,312 @@ from mpflash.mpboard_id import find_known_board
 from mpflash.mpremoteboard import MPRemoteBoard
 
 # #########################################################################################################
-FlashItem: TypeAlias = Tuple[MPRemoteBoard, Optional[Firmware]]
-WorkList: TypeAlias = List[FlashItem]
+
+
+@dataclass
+class FlashTask:
+    """Represents a single board-firmware flashing task."""
+
+    board: MPRemoteBoard
+    firmware: Optional[Firmware]
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if the task has both board and firmware."""
+        return self.firmware is not None
+
+    @property
+    def board_id(self) -> str:
+        """Get the board ID for this task."""
+        return self.board.board_id
+
+    @property
+    def firmware_version(self) -> str:
+        """Get the firmware version for this task."""
+        return self.firmware.version if self.firmware else "unknown"
+
+
+@dataclass
+class WorklistConfig:
+    """Configuration for creating worklists."""
+
+    version: str
+    include_ports: Optional[List[str]] = None
+    ignore_ports: Optional[List[str]] = None
+    board_id: Optional[str] = None
+    custom_firmware: bool = False
+
+    def __post_init__(self):
+        if self.include_ports is None:
+            self.include_ports = []
+        if self.ignore_ports is None:
+            self.ignore_ports = []
+
+    @classmethod
+    def for_auto_detection(cls, version: str) -> "WorklistConfig":
+        """Create config for automatic board detection."""
+        return cls(version=version)
+
+    @classmethod
+    def for_manual_boards(cls, version: str, board_id: str, custom_firmware: bool = False) -> "WorklistConfig":
+        """Create config for manually specified boards."""
+        return cls(version=version, board_id=board_id, custom_firmware=custom_firmware)
+
+    @classmethod
+    def for_filtered_boards(
+        cls, version: str, include_ports: Optional[List[str]] = None, ignore_ports: Optional[List[str]] = None
+    ) -> "WorklistConfig":
+        """Create config for filtered board selection."""
+        return cls(version=version, include_ports=include_ports or [], ignore_ports=ignore_ports or [])
+
+
+FlashTaskList: TypeAlias = List[FlashTask]
+
 # #########################################################################################################
 
 
-def auto_update_worklist(
-    conn_boards: List[MPRemoteBoard],
-    target_version: str,
-) -> WorkList:
-    """Builds a list of boards to update based on the connected boards and the firmwares available locally in the firmware folder.
+def _create_flash_task(board: MPRemoteBoard, firmware: Optional[Firmware]) -> FlashTask:
+    """Create a FlashTask from board and firmware."""
+    return FlashTask(board=board, firmware=firmware)
 
-    Args:
-        conn_boards (List[MPRemoteBoard]): List of connected boards
-        target_version (str): Target firmware version
-        selector (Optional[Dict[str, str]], optional): Selector for filtering firmware. Defaults to None.
 
-    Returns:
-        WorkList: List of boards and firmware information to update
-    """
-    log.debug(f"auto_update_worklist: {len(conn_boards)} boards, target version: {target_version}")
-    wl: WorkList = []
-    for mcu in conn_boards:
-        if mcu.family not in ("micropython", "unknown"):
-            log.warning(f"Skipping flashing {mcu.family} {mcu.port} {mcu.board} on {mcu.serialport} as it is not a MicroPython firmware")
-            continue
-        board_firmwares = find_downloaded_firmware(
-            board_id=f"{mcu.board}-{mcu.variant}" if mcu.variant else mcu.board,
-            version=target_version,
-            port=mcu.port,
-        )
-
-        if not board_firmwares:
-            log.warning(f"No {target_version} firmware found for {mcu.board} on {mcu.serialport}.")
-            wl.append((mcu, None))
-            continue
+def _find_firmware_for_board(board: MPRemoteBoard, version: str, custom: bool = False) -> Optional[Firmware]:
+    """Find appropriate firmware for a board."""
+    board_id = f"{board.board}-{board.variant}" if board.variant else board.board
+    firmwares = find_downloaded_firmware(board_id=board_id, version=version, port=board.port, custom=custom)
 
-        if len(board_firmwares) > 1:
-            log.warning(f"Multiple {target_version} firmwares found for {mcu.board} on {mcu.serialport}.")
+    if not firmwares:
+        log.warning(f"No {version} firmware found for {board.board} on {board.serialport}.")
+        return None
 
-        # just use the last firmware
-        fw_info = board_firmwares[-1]
-        log.info(f"Found {target_version} firmware {fw_info.firmware_file} for {mcu.board} on {mcu.serialport}.")
-        wl.append((mcu, fw_info))
-    return wl
+    if len(firmwares) > 1:
+        log.warning(f"Multiple {version} firmwares found for {board.board} on {board.serialport}.")
 
+    # Use the most recent matching firmware
+    firmware = firmwares[-1]
+    log.info(f"Found {version} firmware {firmware.firmware_file} for {board.board} on {board.serialport}.")
+    return firmware
 
-def manual_worklist(
-    serial: List[str],
-    *,
-    board_id: str,
-    version: str,
-    custom: bool = False,
-) -> WorkList:
-    """Create a worklist for manually specified boards."""
-    log.debug(f"manual_worklist: {len(serial)} serial ports, board_id: {board_id}, version: {version}")
-    wl: WorkList = []
-    for comport in serial:
-        log.trace(f"Manual updating {comport} to {board_id} {version}")
-        wl.append(manual_board(comport, board_id=board_id, version=version, custom=custom))
-    return wl
-
-
-def manual_board(
-    serial: str,
-    *,
-    board_id: str,
-    version: str,
-    custom: bool = False,
-) -> FlashItem:
-    """Create a Flash work item for a single board specified manually.
 
-    Args:
-        serial (str): Serial port of the board
-        board (str): Board_ID
-        version (str): Firmware version
+def _create_manual_board(serial_port: str, board_id: str, version: str, custom: bool = False) -> FlashTask:
+    """Create a FlashTask for manually specified board parameters."""
+    log.debug(f"Creating manual board task: {serial_port} {board_id} {version}")
 
-    Returns:
-        FlashItem: Board and firmware information to update
-    """
-    log.debug(f"manual_board: {serial} {board_id} {version}")
-    mcu = MPRemoteBoard(serial)
-    # Lookup the matching port and cpu in board_info based in the board name
+    board = MPRemoteBoard(serial_port)
+
+    # Look up board information
     try:
         info = find_known_board(board_id)
-        mcu.port = info.port
-        # need the CPU type for the esptool
-        mcu.cpu = info.mcu
+        board.port = info.port
+        board.cpu = info.mcu  # Need CPU type for esptool
     except (LookupError, MPFlashError) as e:
         log.error(f"Board {board_id} not found in board database")
         log.exception(e)
-        return (mcu, None)
-    mcu.board = board_id
-    firmwares = find_downloaded_firmware(board_id=board_id, version=version, port=mcu.port, custom=custom)
-    if not firmwares:
-        log.trace(f"No firmware found for {mcu.port} {board_id} version {version}")
-        return (mcu, None)
-    # use the most recent matching firmware
-    return (mcu, firmwares[-1])  # type: ignore
+        return _create_flash_task(board, None)
 
+    board.board = board_id
+    firmware = _find_firmware_for_board(board, version, custom)
+    return _create_flash_task(board, firmware)
 
-def single_auto_worklist(
-    serial: str,
-    *,
+
+def _filter_connected_comports(
+    all_boards: List[MPRemoteBoard],
+    include: List[str],
+    ignore: List[str],
+) -> List[MPRemoteBoard]:
+    """Filter connected boards based on include/ignore patterns."""
+    try:
+        allowed_ports = [
+            p.device
+            for p in filtered_portinfos(
+                ignore=ignore,
+                include=include,
+                bluetooth=False,
+            )
+        ]
+        return [board for board in all_boards if board.serialport in allowed_ports]
+    except ConnectionError as e:
+        log.error(f"Error connecting to boards: {e}")
+        return []
+
+
+# #########################################################################################################
+
+
+# High-level API functions
+# #########################################################################################################
+
+
+def create_worklist(
     version: str,
-) -> WorkList:
-    """Create a worklist for a single serial-port.
+    *,
+    connected_comports: Optional[List[MPRemoteBoard]] = None,
+    serial_ports: Optional[List[str]] = None,
+    board_id: Optional[str] = None,
+    include_ports: Optional[List[str]] = None,
+    ignore_ports: Optional[List[str]] = None,
+    custom_firmware: bool = False,
+) -> FlashTaskList:
+    """High-level function to create a worklist based on different scenarios.
+
+    This function automatically determines the appropriate worklist creation method
+    based on the provided parameters.
 
     Args:
-        serial_port (str): Serial port of the board
-        version (str): Firmware version
+        version: Target firmware version
+        connected_comports: Pre-detected connected boards (for auto mode)
+        serial_ports: Specific serial ports to use (for manual mode)
+        board_id: Board ID to use with serial_ports (required for manual mode)
+        include_ports: Port patterns to include (for filtered mode)
+        ignore_ports: Port patterns to ignore (for filtered mode)
+        custom_firmware: Whether to use custom firmware
 
     Returns:
-        WorkList: List of boards and firmware information to update
+        List of FlashTask objects
+
+    Raises:
+        ValueError: If parameters are inconsistent or missing required values
+
+    Examples:
+        # Auto-detect firmware for connected boards
+        tasks = create_worklist("1.22.0", connected_comports=boards)
+
+        # Manual specification
+        tasks = create_worklist("1.22.0", serial_ports=["COM1"], board_id="ESP32_GENERIC")
+
+        # Filtered boards
+        tasks = create_worklist("1.22.0", connected_comports=all_boards, include_ports=["COM*"])
     """
-    log.debug(f"single_auto_worklist: {serial} version: {version}")
-    log.trace(f"Auto updating {serial} to {version}")
-    conn_boards = [MPRemoteBoard(serial)]
-    todo = auto_update_worklist(conn_boards, version)  # type: ignore # List / list
-    show_mcus(conn_boards)
-    return todo
+    # Manual mode: specific serial ports with board_id
+    if serial_ports and board_id:
+        config = WorklistConfig.for_manual_boards(version, board_id, custom_firmware)
+        return create_manual_worklist(serial_ports, config)
 
+    # Auto mode with filtering
+    if connected_comports and (include_ports or ignore_ports):
+        config = WorklistConfig.for_filtered_boards(version, include_ports, ignore_ports)
+        return create_filtered_worklist(connected_comports, config)
 
-def full_auto_worklist(
-    all_boards: List[MPRemoteBoard],
-    *,
-    include: List[str],
-    ignore: List[str],
-    version: str,
-) -> WorkList:
+    # Simple auto mode
+    if connected_comports:
+        config = WorklistConfig.for_auto_detection(version)
+        return create_auto_worklist(connected_comports, config)
+
+    # Error cases
+    if serial_ports and not board_id:
+        raise ValueError("board_id is required when specifying serial_ports for manual mode")
+
+    if not connected_comports and not serial_ports:
+        raise ValueError("Either connected_comports or serial_ports must be provided")
+
+    raise ValueError("Invalid combination of parameters")
+
+
+# New, simplified API functions
+# #########################################################################################################
+
+
+def create_auto_worklist(
+    connected_comports: List[MPRemoteBoard],
+    config: WorklistConfig,
+) -> FlashTaskList:
+    """Create a worklist by automatically detecting firmware for connected boards.
+
+    Args:
+        connected_comports: List of connected MicroPython boards
+        config: Configuration for the worklist creation
+
+    Returns:
+        List of FlashTask objects
     """
-    Create a worklist for all connected micropython boards based on the information retrieved from the board.
-    This allows the firmware version of one or more boards to be changed without needing to specify the port or board_id manually.
+    log.debug(f"Creating auto worklist for {len(connected_comports)} boards, target version: {config.version}")
+
+    tasks: FlashTaskList = []
+    for board in connected_comports:
+        if board.family not in ("micropython", "unknown"):
+            log.warning(
+                f"Skipping flashing {board.family} {board.port} {board.board} on {board.serialport} as it is not a MicroPython firmware"
+            )
+            continue
+
+        firmware = _find_firmware_for_board(board, config.version, config.custom_firmware)
+        tasks.append(_create_flash_task(board, firmware))
+
+    return tasks
+
+
+def create_manual_worklist(
+    serial_ports: List[str],
+    config: WorklistConfig,
+) -> FlashTaskList:
+    """Create a worklist for manually specified boards and firmware.
 
     Args:
-        version (str): Firmware version
+        serial_ports: List of serial port identifiers
+        config: Configuration including board_id and version
 
     Returns:
-        WorkList: List of boards and firmware information to update
+        List of FlashTask objects
     """
-    log.debug(f"full_auto_worklist: {len(all_boards)} boards, include: {include}, ignore: {ignore}, version: {version}")
-    if selected_boards := filter_boards(all_boards, include=include, ignore=ignore):
-        return auto_update_worklist(selected_boards, version)
-    else:
-        return []
+    if not config.board_id:
+        raise ValueError("board_id must be specified for manual worklist creation")
+
+    log.debug(f"Creating manual worklist for {len(serial_ports)} ports, board_id: {config.board_id}, version: {config.version}")
+
+    tasks: FlashTaskList = []
+    for port in serial_ports:
+        log.trace(f"Manual updating {port} to {config.board_id} {config.version}")
+        task = _create_manual_board(port, config.board_id, config.version, config.custom_firmware)
+        tasks.append(task)
 
+    return tasks
 
-def filter_boards(
+
+def create_filtered_worklist(
     all_boards: List[MPRemoteBoard],
-    *,
-    include: List[str],
-    ignore: List[str],
-):
-    try:
-        comports = [
-            p.device
-            for p in filtered_portinfos(
-                ignore=ignore,
-                include=include,
-                bluetooth=False,
-            )
-        ]
-        selected_boards = [b for b in all_boards if b.serialport in comports]
-        # [MPRemoteBoard(port.device, update=True) for port in comports]
-    except ConnectionError as e:
-        log.error(f"Error connecting to boards: {e}")
+    config: WorklistConfig,
+) -> FlashTaskList:
+    """Create a worklist for filtered connected boards.
+
+    Args:
+        all_boards: All available connected boards
+        config: Configuration including include/ignore patterns and version
+
+    Returns:
+        List of FlashTask objects
+    """
+    log.debug(
+        f"Creating filtered worklist from {len(all_boards)} boards, include: {config.include_ports}, ignore: {config.ignore_ports}, version: {config.version}"
+    )
+
+    filtered_boards = _filter_connected_comports(all_boards, config.include_ports or [], config.ignore_ports or [])
+    if not filtered_boards:
+        log.warning("No boards match the filtering criteria")
         return []
-    return selected_boards  # type: ignore
+
+    return create_auto_worklist(filtered_boards, config)
+
+
+def create_single_board_worklist(
+    serial_port: str,
+    config: WorklistConfig,
+) -> FlashTaskList:
+    """Create a worklist for a single serial port with automatic detection.
+
+    Args:
+        serial_port: Serial port identifier
+        config: Configuration with version information
+
+    Returns:
+        List of FlashTask objects (typically containing one item)
+    """
+    log.debug(f"Creating single board worklist: {serial_port} version: {config.version}")
+    log.trace(f"Auto updating {serial_port} to {config.version}")
+
+    connected_comports = [MPRemoteBoard(serial_port)]
+    tasks = create_auto_worklist(connected_comports, config)
+    show_mcus(connected_comports)
+    return tasks
+
+
+# End of worklist.py module

mpflash/logger.py

@@ -3,6 +3,14 @@ Logger setup for CLI tools with Unicode-safe output.
 
 Ensures log messages are compatible with the current console encoding.
 Removes or replaces Unicode icons if the encoding is not UTF-8.
+Prevents Loguru colorization errors with angle bracket notation.
+
+Usage for external packages:
+    from mpflash.logger import setup_external_logger_safety
+    setup_external_logger_safety()
+
+This is particularly important when using packages like micropython-stubber
+that may log messages containing angle bracket notation like <board_default>.
 """
 
 import functools
@@ -28,12 +36,23 @@ def _is_utf8_encoding() -> bool:
         return False
 
 
-def _log_formatter(record: dict) -> str:
+def _sanitize_message(message: str) -> str:
+    """
+    Sanitize log messages to prevent Loguru colorization issues.
+
+    Escapes angle brackets that could be interpreted as color tags.
+    This prevents errors when logging documentation with placeholders like <board_default>.
+    """
+    # Escape angle brackets to prevent them from being interpreted as color tags
+    return message.replace("<", "\\<").replace(">", "\\>")
+
+
+def _log_formatter(record) -> str:
     """
     Log message formatter for loguru and rich.
 
     Removes Unicode icons if console encoding is not UTF-8.
-    Handles messages containing curly braces safely.
+    Handles messages containing curly braces and angle brackets safely.
     """
     color_map = {
         "TRACE": "cyan",
@@ -50,8 +69,12 @@ def _log_formatter(record: dict) -> str:
         icon = record["level"].icon
     else:
         icon = record["level"].name  # fallback to text
-    # Escape curly braces in the message to prevent format conflicts
-    safe_message = record["message"].replace("{", "{{").replace("}", "}}")
+
+    # Sanitize the message to prevent format conflicts and colorization errors
+    safe_message = _sanitize_message(record["message"])
+    # Escape curly braces to prevent format conflicts
+    safe_message = safe_message.replace("{", "{{").replace("}", "}}")
+
     # Use string concatenation to avoid f-string format conflicts
     time_part = "[not bold green]{time:HH:mm:ss}[/not bold green]"
     message_part = f"[{lvl_color}]{safe_message}[/{lvl_color}]"
@@ -63,6 +86,7 @@ def set_loglevel(loglevel: str) -> None:
     Set the log level for the logger.
 
     Ensures Unicode safety for log output and handles format errors.
+    Disables colorization to prevent angle bracket interpretation issues.
     """
     try:
         log.remove()
@@ -77,7 +101,57 @@ def set_loglevel(loglevel: str) -> None:
             # Fallback to simple text output if formatting fails
             console.print(f"[LOG FORMAT ERROR] {message} (Error: {e})")
 
-    log.add(safe_format_wrapper, level=loglevel.upper(), colorize=False, format=_log_formatter)  # type: ignore
+    # Disable colorization completely to prevent angle bracket interpretation as color tags
+    log.add(
+        safe_format_wrapper,
+        level=loglevel.upper(),
+        colorize=False,  # This prevents Loguru from parsing angle brackets as color tags
+        format=_log_formatter,
+    )  # type: ignore
+
+
+# def configure_safe_logging() -> None:
+#     """
+#     Configure logging to be safe from colorization errors.
+
+#     This function helps prevent issues when external packages
+#     (like micropython-stubber) log messages with angle brackets
+#     that could be misinterpreted as color tags.
+#     """
+#     # Remove all existing handlers to start fresh
+#     try:
+#         log.remove()
+#     except ValueError:
+#         pass
+
+#     # Add a completely safe handler with no colorization
+#     log.add(
+#         sys.stderr,
+#         level="TRACE",
+#         colorize=False,  # Completely disable colorization
+#         format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name}:{function}:{line} - {message}",
+#     )
+
+
+# def setup_external_logger_safety() -> None:
+#     """
+#     Setup safe logging configuration for external packages.
+
+#     Call this function before running tools that might log messages
+#     with angle bracket notation (like micropython-stubber) to prevent
+#     Loguru colorization errors.
+#     """
+#     import logging
+
+#     # Configure the root logger to be safe
+#     logging.basicConfig(
+#         level=logging.DEBUG,
+#         format="%(asctime)s | %(levelname)s | %(name)s:%(funcName)s:%(lineno)d - %(message)s",
+#         handlers=[logging.StreamHandler(sys.stderr)],
+#     )
+
+#     # Also configure loguru for safety
+#     configure_safe_logging()
 
 
 def make_quiet() -> None:

mpflash/mpremoteboard/__init__.py

@@ -10,13 +10,12 @@ from pathlib import Path
 from typing import List, Optional, Union
 
 import serial.tools.list_ports
-from rich.progress import track
-from tenacity import retry, stop_after_attempt, wait_fixed
-
 from mpflash.errors import MPFlashError
 from mpflash.logger import log
 from mpflash.mpboard_id.board_id import find_board_id_by_description
 from mpflash.mpremoteboard.runner import run
+from rich.progress import track
+from tenacity import retry, stop_after_attempt, wait_fixed
 
 if sys.version_info >= (3, 11):
     import tomllib  # type: ignore
@@ -64,13 +63,17 @@ class MPRemoteBoard:
         self.build = ""
         self.location = location  # USB location
         self.toml = {}
-        portinfo = list(serial.tools.list_ports.grep(serialport))  # type: ignore
+        portinfo = list(serial.tools.list_ports.grep(serialport)) 
         if not portinfo or len(portinfo) != 1:
             self.vid = 0x00
             self.pid = 0x00
         else:
-            self.vid = portinfo[0].vid
-            self.pid = portinfo[0].pid
+            try:
+                self.vid = portinfo[0].vid  # type: ignore
+                self.pid = portinfo[0].pid  # type: ignore
+            except Exception:
+                self.vid = 0x00
+                self.pid = 0x00
         if update:
             self.get_mcu_info()
 
@@ -125,7 +128,7 @@ class MPRemoteBoard:
         return f"MPRemoteBoard({self.serialport}, {self.family} {self.port}, {self.board}{f'-{self.variant}' if self.variant else ''}, {self.version})"
 
     @staticmethod
-    def connected_boards(
+    def connected_comports(
         bluetooth: bool = False, description: bool = False
     ) -> List[str]:
         # TODO: rename to connected_comports
@@ -206,7 +209,6 @@ class MPRemoteBoard:
                     descr, short_descr, version=self.version
                 )
                 self.board_id = board_name or "UNKNOWN_BOARD"
-                # TODO: Get the variant as well
             # get the board_info.toml
             self.get_board_info_toml()
             # TODO: get board_id from the toml file if it exists