micropython-stubber 1.20.0__py3-none-any.whl → 1.20.2__py3-none-any.whl

mpflash/mpflash/ask_input.py

@@ -5,97 +5,85 @@ Note: The prompts can use "{version}" and "{action}" to insert the version and a
 The values are provided from the answers dictionary.
 """
 
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Dict, List, Sequence, Tuple, Union
+from typing import List, Sequence, Tuple, Union
 
 from loguru import logger as log
 
-from mpflash.config import config
-from mpflash.mpboard_id import known_stored_boards, local_mp_ports
-from mpflash.mpremoteboard import MPRemoteBoard
-from mpflash.vendor.versions import micropython_versions
-
-
-@dataclass
-class Params:
-    ports: List[str] = field(default_factory=list)
-    boards: List[str] = field(default_factory=list)
-    versions: List[str] = field(default_factory=list)
-    fw_folder: Path = Path()
-
-
-@dataclass
-class DownloadParams(Params):
-    clean: bool = False
-    force: bool = False
-
-
-@dataclass
-class FlashParams(Params):
-    # TODO: Should Serial port be a list?
-    serial: str = ""
-    erase: bool = True
-    bootloader: bool = True
-    cpu: str = ""
-
-
-ParamType = Union[DownloadParams, FlashParams]
+from .common import DownloadParams, FlashParams, ParamType
+from .config import config
+from .mpboard_id import get_known_boards_for_port, get_known_ports, known_stored_boards
+from .mpremoteboard import MPRemoteBoard
+from .vendor.versions import micropython_versions
 
 
 def ask_missing_params(
     params: ParamType,
-    action: str = "download",
 ) -> ParamType:
     """
     Asks the user for parameters that have not been supplied on the commandline and returns the updated params.
 
     Args:
         params (ParamType): The parameters to be updated.
-        action (str, optional): The action to be performed. Defaults to "download".
 
     Returns:
         ParamType: The updated parameters.
     """
+    import inquirer
+
+    log.trace(f"ask_missing_params: {params}")
+
+    # if action flash,  single input
+    # if action download, multiple input
+    multi_select = isinstance(params, DownloadParams)
+    action = "download" if isinstance(params, DownloadParams) else "flash"
     if not config.interactive:
         # no interactivity allowed
         return params
-    # import only when needed to reduce load time
-    import inquirer
 
     questions = []
-    answers = {"action": action}
-    if isinstance(params, FlashParams):
+    answers: dict[str, Union[str, List]] = {"action": action}
+    if not multi_select:
         if not params.serial or "?" in params.serial:
-            ask_serialport(questions, action=action)
+            questions.append(ask_serialport(multi_select=False, bluetooth=False))
         else:
             answers["serial"] = params.serial
 
-    if not params.versions or "?" in params.versions:
-        ask_versions(questions, action=action)
+    if params.versions == [] or "?" in params.versions:
+        questions.append(ask_mp_version(multi_select=multi_select, action=action))
     else:
         # versions is used to show only the boards for the selected versions
         answers["versions"] = params.versions  # type: ignore
 
     if not params.boards or "?" in params.boards:
-        ask_port_board(questions, action=action)
-
-    answers = inquirer.prompt(questions, answers=answers)
+        questions.extend(ask_port_board(multi_select=multi_select, action=action))
+    if questions:
+        answers = inquirer.prompt(questions, answers=answers)  # type: ignore
     if not answers:
         # input cancelled by user
         return []  # type: ignore
-    # print(repr(answers))
+    log.trace(f"answers: {answers}")
     if isinstance(params, FlashParams) and "serial" in answers:
-        params.serial = answers["serial"]
+        if isinstance(answers["serial"], str):
+            answers["serial"] = [answers["serial"]]
+        params.serial = [s.split()[0] for s in answers["serial"]]  # split to remove the description
     if "port" in answers:
-        params.ports = [answers["port"]]
+        params.ports = [p for p in params.ports if p != "?"]  # remove the "?" if present
+        params.ports.extend(answers["port"])
     if "boards" in answers:
-        params.boards = answers["boards"] if isinstance(answers["boards"], list) else [answers["boards"]]
+        params.boards = [b for b in params.boards if b != "?"]  # remove the "?" if present
+        params.boards.extend(answers["boards"] if isinstance(answers["boards"], list) else [answers["boards"]])
     if "versions" in answers:
+        params.versions = [v for v in params.versions if v != "?"]  # remove the "?" if present
         # make sure it is a list
-        params.versions = answers["versions"] if isinstance(answers["versions"], list) else [answers["versions"]]
-
-    log.debug(repr(params))
+        if isinstance(answers["versions"], (list, tuple)):
+            params.versions.extend(answers["versions"])
+        else:
+            params.versions.append(answers["versions"])
+    # remove duplicates
+    params.ports = list(set(params.ports))
+    params.boards = list(set(params.boards))
+    params.versions = list(set(params.versions))
+    log.trace(f"ask_missing_params returns: {params}")
 
     return params
 
@@ -110,19 +98,18 @@ def filter_matching_boards(answers: dict) -> Sequence[Tuple[str, str]]:
     Returns:
         Sequence[Tuple[str, str]]: The filtered boards.
     """
+    versions = None
     # if version is not asked ; then need to get the version from the inputs
     if "versions" in answers:
-        _versions = list(answers["versions"])
-        if "stable" in _versions:
-            _versions.remove("stable")
-            _versions.append(micropython_versions()[-2])  # latest stable
-        if "preview" in _versions:
-            _versions.remove("preview")
-            _versions.extend((micropython_versions()[-1], micropython_versions()[-2]))  # latest preview and stable
-
-        some_boards = known_stored_boards(answers["port"], _versions)  #    or known_mp_boards(answers["port"])
-    else:
-        some_boards = known_stored_boards(answers["port"])
+        versions = list(answers["versions"])
+        if "stable" in versions:
+            versions.remove("stable")
+            versions.append(micropython_versions()[-2])  # latest stable
+        elif "preview" in versions:
+            versions.remove("preview")
+            versions.extend((micropython_versions()[-1], micropython_versions()[-2]))  # latest preview and stable
+
+    some_boards = known_stored_boards(answers["port"], versions)  #    or known_mp_boards(answers["port"])
 
     if some_boards:
         # Create a dictionary where the keys are the second elements of the tuples
@@ -131,11 +118,11 @@ def filter_matching_boards(answers: dict) -> Sequence[Tuple[str, str]]:
         # Get the values of the dictionary, which are the unique items from the original list
         some_boards = list(unique_dict.values())
     else:
-        some_boards = [("No boards found", "")]
+        some_boards = [(f"No {answers['port']} boards found for version(s) {versions}", "")]
     return some_boards
 
 
-def ask_port_board(questions: list, *, action: str):
+def ask_port_board(*, multi_select: bool, action: str):
     """
     Asks the user for the port and board selection.
 
@@ -149,31 +136,28 @@ def ask_port_board(questions: list, *, action: str):
     # import only when needed to reduce load time
     import inquirer
 
-    # TODO: if action = flash, Use Inquirer.List for boards
-    inquirer_ux = inquirer.Checkbox if action == "download" else inquirer.List
-    questions.extend(
-        (
-            inquirer.List(
-                "port",
-                message="Which port do you want to {action} " + "to {serial} ?" if action == "flash" else "?",
-                choices=local_mp_ports(),
-                autocomplete=True,
-            ),
-            inquirer_ux(
-                "boards",
-                message=(
-                    "Which {port} board firmware do you want to {action} " + "to {serial} ?"
-                    if action == "flash"
-                    else "?"
-                ),
-                choices=filter_matching_boards,
-                validate=lambda _, x: True if x else "Please select at least one board",  # type: ignore
+    # if action flash,  single input
+    # if action download, multiple input
+    inquirer_ux = inquirer.Checkbox if multi_select else inquirer.List
+    return [
+        inquirer.List(
+            "port",
+            message="Which port do you want to {action} " + "to {serial} ?" if action == "flash" else "?",
+            choices=get_known_ports(),
+            # autocomplete=True,
+        ),
+        inquirer_ux(
+            "boards",
+            message=(
+                "Which {port} board firmware do you want to {action} " + "to {serial} ?" if action == "flash" else "?"
             ),
-        )
-    )
+            choices=filter_matching_boards,
+            validate=lambda _, x: True if x else "Please select at least one board",  # type: ignore
+        ),
+    ]
 
 
-def ask_versions(questions: list, *, action: str):
+def ask_mp_version(multi_select: bool, action: str):
     """
     Asks the user for the version selection.
 
@@ -182,31 +166,43 @@ def ask_versions(questions: list, *, action: str):
         action (str): The action to be performed.
 
     Returns:
-        None
+
     """
     # import only when needed to reduce load time
     import inquirer
+    import inquirer.errors
+
+    input_ux = inquirer.Checkbox if multi_select else inquirer.List
 
-    input_ux = inquirer.Checkbox if action == "download" else inquirer.List
     mp_versions: List[str] = micropython_versions()
-    mp_versions = [v for v in mp_versions if "preview" not in v]
-    mp_versions.append("preview")
     mp_versions.reverse()  # newest first
-    questions.append(
-        input_ux(
-            # inquirer.List(
-            "versions",
-            message="Which version(s) do you want to {action} " + ("to {serial} ?" if action == "flash" else "?"),
-            # Hints would be nice , but needs a hint for each and every option
-            # hints=["Use space to select multiple options"],
-            choices=mp_versions,
-            autocomplete=True,
-            validate=lambda _, x: True if x else "Please select at least one version",  # type: ignore
-        )
+
+    # remove the versions for which there are no known boards in the board_info.json
+    # todo: this may be a little slow
+    mp_versions = [v for v in mp_versions if "preview" in v or get_known_boards_for_port("stm32", [v])]
+
+    def at_least_one_validation(answers, current) -> bool:
+        if not current:
+            raise inquirer.errors.ValidationError("", reason="Please select at least one version")
+        if isinstance(current, list) and not any(current):
+            raise inquirer.errors.ValidationError("", reason="Please select at least one version")
+        return True
+
+    message = "Which version(s) do you want to {action} " + ("to {serial} ?" if action == "flash" else "?")
+    q = input_ux(
+        # inquirer.List(
+        "versions",
+        message=message,
+        # Hints would be nice , but needs a hint for each and every option
+        # hints=["Use space to select multiple options"],
+        choices=mp_versions,
+        autocomplete=True,
+        validate=at_least_one_validation,  # type: ignore
     )
+    return q
 
 
-def ask_serialport(questions: list, *, action: str):
+def ask_serialport(*, multi_select: bool = False, bluetooth: bool = False):
     """
     Asks the user for the serial port selection.
 
@@ -220,15 +216,11 @@ def ask_serialport(questions: list, *, action: str):
     # import only when needed to reduce load time
     import inquirer
 
-    serialports = MPRemoteBoard.connected_boards()
-    questions.append(
-        inquirer.List(
-            "serial",
-            message="Which serial port do you want to {action} ?",
-            choices=serialports,
-            other=True,
-            validate=lambda _, x: True if x else "Please select or enter a serial port",  # type: ignore
-        )
+    comports = MPRemoteBoard.connected_boards(bluetooth=bluetooth, description=True)
+    return inquirer.List(
+        "serial",
+        message="Which serial port do you want to {action} ?",
+        choices=comports,
+        other=True,
+        validate=lambda _, x: True if x else "Please select or enter a serial port",  # type: ignore
     )
-
-    return questions

mpflash/mpflash/cli_download.py

@@ -1,17 +1,18 @@
 """CLI to Download MicroPython firmware for specific ports, boards and versions."""
 
 from pathlib import Path
-from typing import List, Tuple
 
 import rich_click as click
 from loguru import logger as log
 
-from mpflash.mpboard_id import find_stored_board
+from mpflash.connected import connected_ports_boards
+from mpflash.errors import MPFlashError
+from mpflash.mpboard_id import find_known_board
 from mpflash.vendor.versions import clean_version
 
-from .ask_input import DownloadParams, ask_missing_params
+from .ask_input import ask_missing_params
 from .cli_group import cli
-from .cli_list import list_mcus
+from .common import DownloadParams
 from .config import config
 from .download import download
 
@@ -49,6 +50,28 @@ from .download import download
     help="The board(s) to download the firmware for.",
     metavar="BOARD_ID or ?",
 )
+@click.option(
+    "--serial",
+    "--serial-port",
+    "-s",
+    "serial",
+    default=["*"],
+    show_default=True,
+    multiple=True,
+    help="Which serial port(s) to flash",
+    metavar="SERIALPORT",
+)
+@click.option(
+    "--ignore",
+    "-i",
+    is_eager=True,
+    help="Serial port(s) to ignore. Defaults to MPFLASH_IGNORE.",
+    multiple=True,
+    default=[],
+    envvar="MPFLASH_IGNORE",
+    show_default=True,
+    metavar="SERIALPORT",
+)
 @click.option(
     "--clean/--no-clean",
     default=True,
@@ -62,46 +85,44 @@ from .download import download
     show_default=True,
     help="""Force download of firmware even if it already exists.""",
 )
-def cli_download(
-    **kwargs,
-):
+def cli_download(**kwargs) -> int:
     params = DownloadParams(**kwargs)
     params.versions = list(params.versions)
     params.boards = list(params.boards)
+    params.serial = list(params.serial)
+    params.ignore = list(params.ignore)
+
+    # all_boards: List[MPRemoteBoard] = []
     if params.boards:
-        pass
-        # TODO Clean board - same as in cli_flash.py
+        if not params.ports:
+            # no ports specified - resolve ports from specified boards by resolving board IDs
+            for board in params.boards:
+                if board != "?":
+                    try:
+                        board_ = find_known_board(board)
+                        params.ports.append(board_.port)
+                    except MPFlashError as e:
+                        log.error(f"{e}")
     else:
-        # no boards specified - detect connected boards
-        params.ports, params.boards = connected_ports_boards()
+        # no boards specified - detect connected ports and boards
+        params.ports, params.boards, _ = connected_ports_boards(include=params.serial, ignore=params.ignore)
 
-    params = ask_missing_params(params, action="download")
+    params = ask_missing_params(params)
     if not params:  # Cancelled by user
-        exit(1)
+        return 2
     params.versions = [clean_version(v, drop_v=True) for v in params.versions]
     assert isinstance(params, DownloadParams)
 
-    download(
-        params.fw_folder,
-        params.ports,
-        params.boards,
-        params.versions,
-        params.force,
-        params.clean,
-    )
-
-
-def connected_ports_boards() -> Tuple[List[str], List[str]]:
-    """
-    Returns a tuple containing lists of unique ports and boards from the connected MCUs.
-    Boards that are physically connected, but give no tangible response are ignored.
-
-    Returns:
-        A tuple containing two lists:
-            - A list of unique ports where MCUs are connected.
-            - A list of unique board names of the connected MCUs.
-    """
-    mpr_boards = [b for b in list_mcus() if b.connected]
-    ports = list({b.port for b in mpr_boards})
-    boards = list({b.board for b in mpr_boards})
-    return ports, boards
+    try:
+        download(
+            params.fw_folder,
+            params.ports,
+            params.boards,
+            params.versions,
+            params.force,
+            params.clean,
+        )
+        return 0
+    except MPFlashError as e:
+        log.error(f"{e}")
+        return 1

mpflash/mpflash/cli_flash.py

@@ -1,19 +1,23 @@
 from pathlib import Path
+from typing import List
 
 import rich_click as click
 from loguru import logger as log
 
+# from mpflash.common import filtered_comports
 from mpflash.errors import MPFlashError
-from mpflash.mpboard_id import find_stored_board
+from mpflash.mpboard_id import find_known_board
+from mpflash.mpremoteboard import MPRemoteBoard
 from mpflash.vendor.versions import clean_version
 
-from .ask_input import FlashParams, ask_missing_params
+from .ask_input import ask_missing_params
 from .cli_download import connected_ports_boards
 from .cli_group import cli
 from .cli_list import show_mcus
+from .common import FlashParams
 from .config import config
 from .flash import flash_list
-from .worklist import MPRemoteBoard, WorkList, full_auto_worklist, manual_worklist, single_auto_worklist
+from .worklist import WorkList, full_auto_worklist, manual_worklist, single_auto_worklist
 
 # #########################################################################################################
 # CLI
@@ -28,7 +32,7 @@ from .worklist import MPRemoteBoard, WorkList, full_auto_worklist, manual_workli
     "--firmware",
     "-f",
     "fw_folder",
-    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    type=click.Path(file_okay=False, dir_okay=True, path_type=Path),
     default=config.firmware_folder,
     show_default=True,
     help="The folder to retrieve the firmware from.",
@@ -48,10 +52,22 @@ from .worklist import MPRemoteBoard, WorkList, full_auto_worklist, manual_workli
     "--serial-port",
     "-s",
     "serial",
-    default="auto",
+    default=["*"],
+    multiple=True,
     show_default=True,
     help="Which serial port(s) to flash",
-    metavar="SERIAL_PORT",
+    metavar="SERIALPORT",
+)
+@click.option(
+    "--ignore",
+    "-i",
+    is_eager=True,
+    help="Serial port(s) to ignore. Defaults to MPFLASH_IGNORE.",
+    multiple=True,
+    default=[],
+    envvar="MPFLASH_IGNORE",
+    show_default=True,
+    metavar="SERIALPORT",
 )
 @click.option(
     "--port",
@@ -91,7 +107,7 @@ from .worklist import MPRemoteBoard, WorkList, full_auto_worklist, manual_workli
     show_default=True,
     help="""Enter micropython bootloader mode before flashing.""",
 )
-def cli_flash_board(**kwargs):
+def cli_flash_board(**kwargs) -> int:
     # version to versions, board to boards
     kwargs["versions"] = [kwargs.pop("version")] if kwargs["version"] != None else []
     if kwargs["board"] is None:
@@ -101,33 +117,33 @@ def cli_flash_board(**kwargs):
         kwargs["boards"] = [kwargs.pop("board")]
 
     params = FlashParams(**kwargs)
+    params.versions = list(params.versions)
+    params.boards = list(params.boards)
+    params.serial = list(params.serial)
+    params.ignore = list(params.ignore)
+
+    # make it simple for the user to flash one board by asking for the serial port if not specified
+    if params.boards == ["?"] and params.serial == "*":
+        params.serial = ["?"]
+
+    # Detect connected boards if not specified,
+    # and ask for input if boards cannot be detected
+    all_boards: List[MPRemoteBoard] = []
     if not params.boards or params.boards == []:
         # nothing specified - detect connected boards
-        params.ports, params.boards = connected_ports_boards()
+        params.ports, params.boards, all_boards = connected_ports_boards(include=params.ports, ignore=params.ignore)
         if params.boards == []:
             # No MicroPython boards detected, but it could be unflashed or not in bootloader mode
             # Ask for serial port and board_id to flash
-            params.serial = "?"
+            params.serial = ["?"]
             params.boards = ["?"]
     else:
-        for board_id in params.boards:
-            if board_id == "":
-                params.boards.remove(board_id)
-                continue
-            if " " in board_id:
-                try:
-                    info = find_stored_board(board_id)
-                    if info:
-                        log.info(f"Resolved board description: {info['board']}")
-                        params.boards.remove(board_id)
-                        params.boards.append(info["board"])
-                except Exception as e:
-                    log.warning(f"unable to resolve board description: {e}")
+        resolve_board_ids(params)
 
     # Ask for missing input if needed
-    params = ask_missing_params(params, action="flash")
+    params = ask_missing_params(params)
     if not params:  # Cancelled by user
-        exit(1)
+        return 2
     # TODO: Just in time Download of firmware
 
     assert isinstance(params, FlashParams)
@@ -135,27 +151,33 @@ def cli_flash_board(**kwargs):
     if len(params.versions) > 1:
         log.error(f"Only one version can be flashed at a time, not {params.versions}")
         raise MPFlashError("Only one version can be flashed at a time")
-    # if len(params.boards) > 1:
-    #     log.error(f"Only one board can be flashed at a time, not {params.boards}")
-    #     raise MPFlashError("Only one board can be flashed at a time")
 
     params.versions = [clean_version(v) for v in params.versions]
     worklist: WorkList = []
     # if serial port == auto and there are one or more specified/detected boards
-    if params.serial == "auto" and params.boards:
-        worklist = full_auto_worklist(version=params.versions[0], fw_folder=params.fw_folder)
+    if params.serial == ["*"] and params.boards:
+        if not all_boards:
+            log.trace("No boards detected yet, scanning for connected boards")
+            _, _, all_boards = connected_ports_boards(include=params.ports, ignore=params.ignore)
+        worklist = full_auto_worklist(
+            all_boards=all_boards,
+            version=params.versions[0],
+            fw_folder=params.fw_folder,
+            include=params.serial,
+            ignore=params.ignore,
+        )
     elif params.versions[0] and params.boards[0] and params.serial:
-        # A single serial port including the board / variant
+        # A one or more  serial port including the board / variant
         worklist = manual_worklist(
-            params.versions[0],
-            params.fw_folder,
-            params.serial,
-            params.boards[0],
+            params.serial[0],
+            board_id=params.boards[0],
+            version=params.versions[0],
+            fw_folder=params.fw_folder,
         )
     else:
         # just this serial port on auto
         worklist = single_auto_worklist(
-            serial_port=params.serial,
+            serial=params.serial[0],
             version=params.versions[0],
             fw_folder=params.fw_folder,
         )
@@ -168,3 +190,23 @@ def cli_flash_board(**kwargs):
     ):
         log.info(f"Flashed {len(flashed)} boards")
         show_mcus(flashed, title="Updated boards after flashing")
+        return 0
+    else:
+        log.error("No boards were flashed")
+        return 1
+
+
+def resolve_board_ids(params):
+    """Resolve board descriptions to board_id, and remove empty strings from list of boards"""
+    for board_id in params.boards:
+        if board_id == "":
+            params.boards.remove(board_id)
+            continue
+        if " " in board_id:
+            try:
+                if info := find_known_board(board_id):
+                    log.info(f"Resolved board description: {info.board_id}")
+                    params.boards.remove(board_id)
+                    params.boards.append(info.board_id)
+            except Exception as e:
+                log.warning(f"Unable to resolve board description: {e}")