micropython-stubber 1.17.5__py3-none-any.whl → 1.19.0__py3-none-any.whl

mpflash/mpflash/ask_input.py

@@ -0,0 +1,234 @@
+"""
+Interactive input for mpflash.
+
+Note: The prompts can use "{version}" and "{action}" to insert the version and action in the prompt without needing an f-string.
+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 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]
+
+
+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.
+    """
+    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):
+        if not params.serial or "?" in params.serial:
+            ask_serialport(questions, action=action)
+        else:
+            answers["serial"] = params.serial
+
+    if not params.versions or "?" in params.versions:
+        ask_versions(questions, 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)
+    if not answers:
+        # input cancelled by user
+        return []  # type: ignore
+    # print(repr(answers))
+    if isinstance(params, FlashParams) and "serial" in answers:
+        params.serial = answers["serial"]
+    if "port" in answers:
+        params.ports = [answers["port"]]
+    if "boards" in answers:
+        params.boards = answers["boards"] if isinstance(answers["boards"], list) else [answers["boards"]]
+    if "versions" in answers:
+        # make sure it is a list
+        params.versions = answers["versions"] if isinstance(answers["versions"], list) else [answers["versions"]]
+
+    log.debug(repr(params))
+
+    return params
+
+
+def filter_matching_boards(answers: dict) -> Sequence[Tuple[str, str]]:
+    """
+    Filters the known boards based on the selected versions and returns the filtered boards.
+
+    Args:
+        answers (dict): The user's answers.
+
+    Returns:
+        Sequence[Tuple[str, str]]: The filtered boards.
+    """
+    # 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"])
+
+    if some_boards:
+        # Create a dictionary where the keys are the second elements of the tuples
+        # This will automatically remove duplicates because dictionaries cannot have duplicate keys
+        unique_dict = {item[1]: item for item in some_boards}
+        # 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", "")]
+    return some_boards
+
+
+def ask_port_board(questions: list, *, action: str):
+    """
+    Asks the user for the port and board selection.
+
+    Args:
+        questions (list): The list of questions to be asked.
+        action (str): The action to be performed.
+
+    Returns:
+        None
+    """
+    # 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
+            ),
+        )
+    )
+
+
+def ask_versions(questions: list, *, action: str):
+    """
+    Asks the user for the version selection.
+
+    Args:
+        questions (list): The list of questions to be asked.
+        action (str): The action to be performed.
+
+    Returns:
+        None
+    """
+    # import only when needed to reduce load time
+    import inquirer
+
+    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
+        )
+    )
+
+
+def ask_serialport(questions: list, *, action: str):
+    """
+    Asks the user for the serial port selection.
+
+    Args:
+        questions (list): The list of questions to be asked.
+        action (str): The action to be performed.
+
+    Returns:
+        None
+    """
+    # 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
+        )
+    )
+
+    return questions

mpflash/mpflash/cli_download.py

@@ -0,0 +1,107 @@
+"""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.vendor.versions import clean_version
+
+from .ask_input import DownloadParams, ask_missing_params
+from .cli_group import cli
+from .cli_list import list_mcus
+from .config import config
+from .download import download
+
+
+@cli.command(
+    "download",
+    help="Download MicroPython firmware for specific ports, boards and versions.",
+)
+@click.option(
+    "--destination",
+    "-d",
+    "fw_folder",
+    type=click.Path(file_okay=False, dir_okay=True, path_type=Path),
+    default=config.firmware_folder,
+    show_default=True,
+    help="The folder to download the firmware to.",
+)
+@click.option(
+    "--version",
+    "-v",
+    "versions",
+    default=["stable"],
+    multiple=True,
+    show_default=True,
+    help="The version of MicroPython to to download.",
+    metavar="SEMVER, 'stable', 'preview' or '?'",
+)
+@click.option(
+    "--board",
+    "-b",
+    "boards",
+    multiple=True,
+    default=[],
+    show_default=True,
+    help="The board(s) to download the firmware for.",
+    metavar="BOARD_ID or ?",
+)
+@click.option(
+    "--clean/--no-clean",
+    default=True,
+    show_default=True,
+    help="""Remove dates and hashes from the downloaded firmware filenames.""",
+)
+@click.option(
+    "--force",
+    default=False,
+    is_flag=True,
+    show_default=True,
+    help="""Force download of firmware even if it already exists.""",
+)
+def cli_download(
+    **kwargs,
+):
+    params = DownloadParams(**kwargs)
+    params.versions = list(params.versions)
+    params.boards = list(params.boards)
+    if params.boards:
+        pass
+        # TODO Clean board - same as in cli_flash.py
+    else:
+        # no boards specified - detect connected boards
+        params.ports, params.boards = connected_ports_boards()
+
+    params = ask_missing_params(params, action="download")
+    if not params:  # Cancelled by user
+        exit(1)
+    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

mpflash/mpflash/cli_flash.py

@@ -0,0 +1,165 @@
+from pathlib import Path
+
+import rich_click as click
+from loguru import logger as log
+
+from mpflash.errors import MPFlashError
+from mpflash.mpboard_id import find_stored_board
+from mpflash.vendor.versions import clean_version
+
+from .ask_input import FlashParams, ask_missing_params
+from .cli_download import connected_ports_boards
+from .cli_group import cli
+from .cli_list import show_mcus
+from .config import config
+from .flash import flash_list
+from .worklist import WorkList, full_auto_worklist, manual_worklist, single_auto_worklist
+
+# #########################################################################################################
+# CLI
+# #########################################################################################################
+
+
+@cli.command(
+    "flash",
+    short_help="Flash one or all connected MicroPython boards with a specific firmware and version.",
+)
+@click.option(
+    "--firmware",
+    "-f",
+    "fw_folder",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    default=config.firmware_folder,
+    show_default=True,
+    help="The folder to retrieve the firmware from.",
+)
+@click.option(
+    "--version",
+    "-v",
+    "version",  # single version
+    default="stable",
+    multiple=False,
+    show_default=True,
+    help="The version of MicroPython to flash.",
+    metavar="SEMVER, 'stable', 'preview' or '?'",
+)
+@click.option(
+    "--serial",
+    "--serial-port",
+    "-s",
+    "serial",
+    default="auto",
+    show_default=True,
+    help="Which serial port(s) to flash",
+    metavar="SERIAL_PORT",
+)
+@click.option(
+    "--port",
+    "-p",
+    "ports",
+    help="The MicroPython port to flash",
+    metavar="PORT",
+    default=[],
+    multiple=True,
+)
+@click.option(
+    "--board",
+    "-b",
+    "board",  # single board
+    multiple=False,
+    help="The MicroPython board ID to flash. If not specified will try to read the BOARD_ID from the connected MCU.",
+    metavar="BOARD_ID or ?",
+)
+@click.option(
+    "--cpu",
+    "--chip",
+    "-c",
+    "cpu",
+    help="The CPU type to flash. If not specified will try to read the CPU from the connected MCU.",
+    metavar="CPU",
+)
+@click.option(
+    "--erase/--no-erase",
+    default=True,
+    show_default=True,
+    help="""Erase flash before writing new firmware. (Not supported on UF2 boards)""",
+)
+@click.option(
+    "--bootloader/--no-bootloader",
+    default=True,
+    is_flag=True,
+    show_default=True,
+    help="""Enter micropython bootloader mode before flashing.""",
+)
+def cli_flash_board(**kwargs):
+    # version to versions, board to boards
+    kwargs["versions"] = [kwargs.pop("version")] if kwargs["version"] != None else []
+    if kwargs["board"] is None:
+        kwargs["boards"] = []
+        kwargs.pop("board")
+    else:
+        kwargs["boards"] = [kwargs.pop("board")]
+
+    params = FlashParams(**kwargs)
+    if not params.boards or params.boards == []:
+        # nothing specified - detect connected boards
+        params.ports, params.boards = connected_ports_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}")
+
+    # Ask for missing input if needed
+    params = ask_missing_params(params, action="flash")
+    if not params:  # Cancelled by user
+        exit(1)
+    # TODO: Just in time Download of firmware
+
+    assert isinstance(params, FlashParams)
+
+    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)
+    elif params.versions[0] and params.boards[0] and params.serial:
+        # A single serial port including the board / variant
+        worklist = manual_worklist(
+            params.versions[0],
+            params.fw_folder,
+            params.serial,
+            params.boards[0],
+        )
+    else:
+        # just this serial port on auto
+        worklist = single_auto_worklist(
+            serial_port=params.serial,
+            version=params.versions[0],
+            fw_folder=params.fw_folder,
+        )
+
+    if flashed := flash_list(
+        worklist,
+        params.fw_folder,
+        params.erase,
+        params.bootloader,
+    ):
+        log.info(f"Flashed {len(flashed)} boards")
+        show_mcus(flashed, title="Updated boards after flashing")

mpflash/mpflash/cli_group.py

@@ -3,54 +3,87 @@ Main entry point for the CLI group.
 Additional comands are added in the submodules.
 """
 
-from typing import List
-
 import rich_click as click
 
 from .config import config
-from .logger import set_loglevel
+from .logger import make_quiet, set_loglevel
 
 
 def cb_verbose(ctx, param, value):
     """Callback to set the log level to DEBUG if verbose is set"""
     if value:
         set_loglevel("DEBUG")
+        config.verbose = True
     else:
         set_loglevel("INFO")
+        config.verbose = False
     return value
 
 
 def cb_ignore(ctx, param, value):
     if value:
         config.ignore_ports = list(value)
-        print(repr(config.ignore_ports))
+    return value
+
+
+def cb_interactive(ctx, param, value):
+    if value:
+        config.interactive = value
+    return value
+
+
+def cb_quiet(ctx, param, value):
+    if value:
+        make_quiet()
     return value
 
 
 @click.group()
+@click.version_option(package_name="mpflash")
+@click.option(
+    "--quiet",
+    "-q",
+    is_eager=True,
+    is_flag=True,
+    help="Suppresses all output.",
+    callback=cb_quiet,
+    envvar="MPFLASH_QUIET",
+    show_default=True,
+)
+@click.option(
+    "--interactive/--no-interactive",
+    "-i/-x",
+    is_eager=True,
+    help="Suppresses all request for Input.",
+    callback=cb_interactive,
+    # envvar="MPFLASH_QUIET",
+    default=True,
+    show_default=True,
+)
 @click.option(
     "-V",
     "--verbose",
+    is_eager=True,
     is_flag=True,
     help="Enables verbose mode.",
-    is_eager=True,
     callback=cb_verbose,
 )
 @click.option(
     "--ignore",
     "-i",
     is_eager=True,
-    help="Serial port(s) to ignore. Defaults to MPTOOL_IGNORE.",
+    help="Serial port(s) to ignore. Defaults to MPFLASH_IGNORE.",
     callback=cb_ignore,
     multiple=True,
     default=[],
-    envvar="MPTOOL_IGNORE",
+    envvar="MPFLASH_IGNORE",
     show_default=True,
     metavar="SERIALPORT",
 )
-def cli(verbose: bool, ignore: List[str], **kwargs):
+def cli(**kwargs):
     """mpflash - MicroPython Tool.
 
     A CLI to download and flash MicroPython firmware to different ports and boards.
     """
+    # all functionality is added in the submodules
     pass

mpflash/mpflash/cli_list.py

@@ -0,0 +1,41 @@
+import json
+
+import rich_click as click
+from rich import print
+
+from .cli_group import cli
+from .list import list_mcus, show_mcus
+from .logger import make_quiet
+
+
+@cli.command("list", help="List the connected MCU boards.")
+@click.option(
+    "--json",
+    "-j",
+    "as_json",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="""Output in json format""",
+)
+@click.option(
+    "--progress/--no-progress",
+    "progress",
+    is_flag=True,
+    default=True,
+    show_default=True,
+    help="""Show progress""",
+)
+def cli_list_mcus(as_json: bool, progress: bool = True):
+    """List the connected MCU boards, and output in a nice table or json."""
+    if as_json:
+        # avoid noise in json output
+        make_quiet()
+
+    conn_mcus = list_mcus()
+    if as_json:
+        print(json.dumps([mcu.__dict__ for mcu in conn_mcus], indent=4))
+        progress = False
+    if progress:
+        show_mcus(conn_mcus, refresh=False)
+    return conn_mcus

mpflash/mpflash/cli_main.py

@@ -1,20 +1,25 @@
 """mpflash is a CLI to download and flash MicroPython firmware to various boards."""
 
-import rich_click as click
+# import rich_click as click
 
+from .cli_download import cli_download
+from .cli_flash import cli_flash_board
 from .cli_group import cli
-from .downloader import download
-from .flasher import flash_board
-from .list import list_boards
+from .cli_list import cli_list_mcus
 
 # from loguru import logger as log
 
 
 def mpflash():
-    # cli.add_command(flash_board)
-    # cli.add_command(list_boards)
-    # cli.add_command(download)
-    cli()  # auto_envvar_prefix='MPTOOL')
+    cli.add_command(cli_flash_board)
+    cli.add_command(cli_list_mcus)
+    cli.add_command(cli_download)
+    # cli(auto_envvar_prefix="MPFLASH")
+    try:
+        exit(cli())
+    except AttributeError as e:
+        print(f"Error: {e}")
+        exit(-1)
 
 
 if __name__ == "__main__":