mpflash 1.24.7__py3-none-any.whl → 1.25.0__py3-none-any.whl

mpflash/mpboard_id/known.py

@@ -0,0 +1,108 @@
+"""
+KNOWN ports and boards are sourced from the micropython repo,
+this info is stored in the board_info.json file
+and is used to identify the board and port for flashing.
+This module provides access to the board info and the known ports and boards."""
+
+from functools import lru_cache
+from typing import List, Optional, Tuple
+
+from mpflash.db.boards import find_board_id, find_board_info
+from mpflash.errors import MPFlashError
+from mpflash.versions import clean_version
+from mpflash.logger import log
+
+from .board import Board
+from .store import read_known_boardinfo
+
+
+def get_known_ports() -> List[str]:
+    # TODO: Filter for Version
+    log.warning("get_known_ports() is deprecated")
+    mp_boards = read_known_boardinfo()
+    # select the unique ports from info
+    ports = set({board.port for board in mp_boards if board.port})
+    return sorted(list(ports))
+
+
+def get_known_boards_for_port(port: Optional[str] = "", versions: Optional[List[str]] = None) -> List[Board]:
+    """
+    Returns a list of boards for the given port and version(s)
+
+    port: The Micropython port to filter for
+    versions:  Optional, The Micropython versions to filter for (actual versions required)
+    """
+    mp_boards = read_known_boardinfo()
+    if versions:
+        preview_or_stable = "preview" in versions or "stable" in versions
+    else:
+        preview_or_stable = False
+
+    # filter for 'preview' as they are not in the board_info.json
+    # instead use stable version
+    versions = versions or []
+    if "preview" in versions:
+        versions.remove("preview")
+        versions.append("stable")
+    # filter for the port
+    if port:
+        mp_boards = [board for board in mp_boards if board.port == port]
+    if versions:
+        # make sure of the v prefix
+        versions = [clean_version(v) for v in versions]
+        # filter for the version(s)
+        mp_boards = [board for board in mp_boards if board.version in versions]
+        if not mp_boards and preview_or_stable:
+            # nothing found - perhaps there is a newer version for which we do not have the board info yet
+            # use the latest known version from the board info
+            mp_boards = read_known_boardinfo()
+            last_known_version = sorted({b.version for b in mp_boards})[-1]
+            mp_boards = [board for board in mp_boards if board.version == last_known_version]
+
+    return mp_boards
+
+
+def known_stored_boards(port: str, versions: Optional[List[str]] = None) -> List[Tuple[str, str]]:
+    """
+    Returns a list of tuples with the description and board name for the given port and version
+
+    port : str : The Micropython port to filter for
+    versions : List[str] : The Micropython versions to filter for (actual versions required)
+    """
+    mp_boards = get_known_boards_for_port(port, versions)
+
+    boards = set({(f"{board.version} {board.description}", board.board_id) for board in mp_boards})
+    return sorted(list(boards))
+
+
+@lru_cache(maxsize=20)
+def find_known_board(board_id: str, version ="") -> Board:
+    """Find the board for the given BOARD_ID or 'board description' and return the board info as a Board object"""
+    # Some functional overlap with:
+    # mpboard_id\board_id.py _find_board_id_by_description
+    # TODO: Refactor to search the SQLite DB instead of the JSON file
+    board_ids = find_board_id(board_id = board_id, version = version or "%")
+    boards = []
+    for board_id in board_ids:
+        # if we have a board_id, use it to find the board info
+        boards += [Board.from_dict(dict(r)) for r in find_board_info(board_id = board_id)]
+  
+
+    # if board_ids:
+    #     # if we have a board_id, use it to find the board info
+    #     board_id = board_ids[0]
+    # info = read_known_boardinfo()
+    # for board_info in info:
+    #     if board_id in (
+    #         board_info.board_id,
+    #         board_info.description,
+    #     ) or board_info.description.startswith(board_id):
+    #         if not board_info.cpu:
+    #             # failsafe for older board_info.json files
+    #             print(f"Board {board_id} has no CPU info, using port as CPU")
+    #             if " with " in board_info.description:
+    #                 board_info.cpu = board_info.description.split(" with ")[-1]
+    #             else:
+    #                 board_info.cpu = board_info.port
+    #         return board_info
+    raise MPFlashError(f"Board {board_id} not found")

mpflash/mpboard_id/store.py

@@ -2,6 +2,7 @@ import functools
 import zipfile
 from pathlib import Path
 from typing import Final, List, Optional
+from mpflash.logger import log
 
 import jsons
 
@@ -19,7 +20,6 @@ def write_boardinfo_json(board_list: List[Board], *, folder: Optional[Path] = No
         board_list (List[Board]): The list of Board objects.
         folder (Path): The folder where the compressed JSON file will be saved.
     """
-    import zipfile
 
     if not folder:
         folder = HERE
@@ -33,8 +33,7 @@ def write_boardinfo_json(board_list: List[Board], *, folder: Optional[Path] = No
 @functools.lru_cache(maxsize=20)
 def read_known_boardinfo(board_info: Optional[Path] = None) -> List[Board]:
     """Reads the board information from a JSON file in a zip file."""
-
-    import zipfile
+    log.warning("read_known_boardinfo() is deprecated")
 
     if not board_info:
         board_info = HERE / "board_info.zip"

mpflash/mpremoteboard/__init__.py

@@ -2,6 +2,7 @@
 Module to run mpremote commands, and retry on failure or timeout
 """
 
+import contextlib
 import sys
 import time
 from pathlib import Path
@@ -33,7 +34,9 @@ RETRIES = 3
 class MPRemoteBoard:
     """Class to run mpremote commands"""
 
-    def __init__(self, serialport: str = "", update: bool = False, *, location: str = ""):
+    def __init__(
+        self, serialport: str = "", update: bool = False, *, location: str = ""
+    ):
         """
         Initialize MPRemoteBoard object.
 
@@ -41,6 +44,8 @@ class MPRemoteBoard:
         - serialport (str): The serial port to connect to. Default is an empty string.
         - update (bool): Whether to update the MCU information. Default is False.
         """
+        self._board_id = ""
+
         self.serialport: str = serialport
         self.firmware = {}
 
@@ -50,7 +55,6 @@ class MPRemoteBoard:
         self.description = ""
         self.version = ""
         self.port = ""
-        self.board = ""
         self.cpu = ""
         self.arch = ""
         self.mpy = ""
@@ -60,17 +64,46 @@ class MPRemoteBoard:
         if update:
             self.get_mcu_info()
 
+    ###################################
+    # board_id := board[-variant]
+    @property
+    def board_id(self) -> str:
+        return self._board_id
+
+    @board_id.setter
+    def board_id(self, value: str) -> None:
+        self._board_id = value.rstrip("-")
+
+    @property
+    def board(self) -> str:
+        return self._board_id.split("-")[0]
+
+    @board.setter
+    def board(self, value: str) -> None:
+        self.board_id = f"{value}-{self.variant}" if self.variant else value
+
+    @property
+    def variant(self) -> str:
+        return self._board_id.split("-")[1] if "-" in self._board_id else ""
+
+    @variant.setter
+    def variant(self, value: str) -> None:
+        self.board_id = f"{self.board}-{value}"
+
+    ###################################
     def __str__(self):
         """
         Return a string representation of the MPRemoteBoard object.
 
         Returns:
-        - str: The string representation of the object.
+        - str: A human readable representation of the MCU.
         """
-        return f"MPRemoteBoard({self.serialport}, {self.family} {self.port}, {self.board}, {self.version})"
+        return f"MPRemoteBoard({self.serialport}, {self.family} {self.port}, {self.board}{f'-{self.variant}' if self.variant else ''}, {self.version})"
 
     @staticmethod
-    def connected_boards(bluetooth: bool = False, description: bool = False) -> List[str]:
+    def connected_boards(
+        bluetooth: bool = False, description: bool = False
+    ) -> List[str]:
         # TODO: rename to connected_comports
         """
         Get a list of connected comports.
@@ -98,7 +131,10 @@ class MPRemoteBoard:
         if sys.platform == "win32":
             # Windows sort of comports by number - but fallback to device name
             return sorted(
-                output, key=lambda x: int(x.split()[0][3:]) if x.split()[0][3:].isdigit() else x
+                output,
+                key=lambda x: int(x.split()[0][3:])
+                if x.split()[0][3:].isdigit()
+                else x,
             )
         # sort by device name
         return sorted(output)
@@ -120,11 +156,11 @@ class MPRemoteBoard:
             timeout=timeout,
             resume=False,  # Avoid restarts
         )
-        if rc:
+        if rc not in (0, 1):  ## WORKAROUND - SUDDEN RETURN OF 1 on success
             log.debug(f"rc: {rc}, result: {result}")
             raise ConnectionError(f"Failed to get mcu_info for {self.serialport}")
         # Ok we have the info, now parse it
-        raw_info = result[0].strip()
+        raw_info = result[0].strip() if result else ""
         if raw_info.startswith("{") and raw_info.endswith("}"):
             info = eval(raw_info)
             self.family = info["family"]
@@ -137,14 +173,19 @@ class MPRemoteBoard:
             self.description = descr = info["board"]
             pos = descr.rfind(" with")
             short_descr = descr[:pos].strip() if pos != -1 else ""
-            if board_name := find_board_id_by_description(
-                descr, short_descr, version=self.version
-            ):
-                self.board = board_name
+            if info.get("board_id", None):
+                # we have a board_id - so use that to get the board name
+                self.board_id = info["board_id"]
             else:
-                self.board = "UNKNOWN_BOARD"
+                self.board_id = f"{info['board']}-{info.get('variant', '')}"
+                board_name = find_board_id_by_description(
+                    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
         # now we know the board is connected
         self.connected = True
 
@@ -168,7 +209,9 @@ class MPRemoteBoard:
                 log_errors=False,
             )
         except Exception as e:
-            raise ConnectionError(f"Failed to get board_info.toml for {self.serialport}: {e}")
+            raise ConnectionError(
+                f"Failed to get board_info.toml for {self.serialport}:"
+            ) from e
         # this is optional - so only parse if we got the file
         self.toml = {}
         if rc in [OK]:  # sometimes we get an -9 ???
@@ -264,8 +307,33 @@ class MPRemoteBoard:
             total=timeout,
         ):
             time.sleep(1)
-            try:
+            with contextlib.suppress(ConnectionError, MPFlashError):
                 self.get_mcu_info()
                 break
-            except (ConnectionError, MPFlashError):
-                pass
+
+    def to_dict(self) -> dict:
+        """
+        Serialize the MPRemoteBoard object to JSON, including all attributes and readable properties.
+
+        Returns:
+        - str: A JSON string representation of the object.
+        """
+
+        def get_properties(obj):
+            """Helper function to get all readable properties."""
+            return {
+                name: getattr(obj, name)
+                for name in dir(obj.__class__)
+                if isinstance(getattr(obj.__class__, name, None), property)
+            }
+
+        # Combine instance attributes, readable properties, and private attributes
+        data = {**self.__dict__, **get_properties(self)}
+
+        # remove the path and firmware attibutes from the json output as they are always empty
+        del data["_board_id"]  # dup of board_id
+        del data["connected"]
+        del data["path"]
+        del data["firmware"]
+
+        return data

mpflash/mpremoteboard/mpy_fw_info.py

@@ -1,9 +1,9 @@
-# %%micropython
+# pragma: no cover
 import os
 import sys
 
 
-def _build(s):
+def get_build(s):
     # extract build from sys.version or os.uname().version if available
     # sys.version: 'MicroPython v1.23.0-preview.6.g3d0b6276f'
     # sys.implementation.version: 'v1.13-103-gb137d064e'
@@ -11,11 +11,11 @@ def _build(s):
         return ""
     s = s.split(" on ", 1)[0] if " on " in s else s
     if s.startswith("v"):
-        if not "-" in s:
+        if "-" not in s:
             return ""
         b = s.split("-")[1]
         return b
-    if not "-preview" in s:
+    if "-preview" not in s:
         return ""
     b = s.split("-preview")[1].split(".")[1]
     return b
@@ -36,10 +36,9 @@ def _info():  # type:() -> dict[str, str]
             "version": "",
             "build": "",
             "ver": "",
-            "port": (
-                "stm32" if sys.platform.startswith("pyb") else sys.platform
-            ),  # port: esp32 / win32 / linux / stm32
+            "port": ("stm32" if sys.platform.startswith("pyb") else sys.platform),  # port: esp32 / win32 / linux / stm32
             "board": "GENERIC",
+            "_build": "",
             "cpu": "",
             "mpy": "",
             "arch": "",
@@ -50,29 +49,32 @@ def _info():  # type:() -> dict[str, str]
     except AttributeError:
         pass
     try:
-        machine = (
-            sys.implementation._machine
-            if "_machine" in dir(sys.implementation)
-            else os.uname().machine
-        )
-        info["board"] = machine.strip()
-        info["cpu"] = machine.split("with")[-1].strip() if "with" in machine else ""
+        _machine = sys.implementation._machine if "_machine" in dir(sys.implementation) else os.uname().machine  # type: ignore
+        info["board"] = _machine.strip()
+        si_build = sys.implementation._build if "_build" in dir(sys.implementation) else ""
+        if si_build:
+            info["board"] = si_build.split("-")[0]
+            info["variant"] = si_build.split("-")[1] if "-" in si_build else ""
+        info["board_id"] = si_build
+        info["cpu"] = _machine.split("with")[-1].strip() if "with" in _machine else ""
         info["mpy"] = (
             sys.implementation._mpy
             if "_mpy" in dir(sys.implementation)
-            else sys.implementation.mpy if "mpy" in dir(sys.implementation) else ""
+            else sys.implementation.mpy
+            if "mpy" in dir(sys.implementation)
+            else ""
         )
     except (AttributeError, IndexError):
         pass
 
     try:
         if hasattr(sys, "version"):
-            info["build"] = _build(sys.version)
+            info["build"] = get_build(sys.version)
         elif hasattr(os, "uname"):
-            info["build"] = _build(os.uname()[3])
+            info["build"] = get_build(os.uname()[3])  # type: ignore
             if not info["build"]:
                 # extract build from uname().release if available
-                info["build"] = _build(os.uname()[2])
+                info["build"] = get_build(os.uname()[2])  # type: ignore
     except (AttributeError, IndexError):
         pass
     # avoid  build hashes
@@ -81,7 +83,7 @@ def _info():  # type:() -> dict[str, str]
 
     if info["version"] == "" and sys.platform not in ("unix", "win32"):
         try:
-            u = os.uname()
+            u = os.uname()  # type: ignore
             info["version"] = u.release
         except (IndexError, AttributeError, TypeError):
             pass
@@ -106,8 +108,7 @@ def _info():  # type:() -> dict[str, str]
         if (
             info["version"]
             and info["version"].endswith(".0")
-            and info["version"]
-            >= "1.10.0"  # versions from 1.10.0 to 1.20.0 do not have a micro .0
+            and info["version"] >= "1.10.0"  # versions from 1.10.0 to 1.20.0 do not have a micro .0
             and info["version"] <= "1.19.9"
         ):
             # drop the .0 for newer releases
@@ -149,4 +150,4 @@ def _info():  # type:() -> dict[str, str]
 
 
 print(_info())
-del _info, _build, _version_str
+del _info, get_build, _version_str

mpflash/vendor/board_database.py

@@ -37,7 +37,9 @@ from __future__ import annotations
 import json
 from dataclasses import dataclass, field
 from glob import glob
+from os import path
 from pathlib import Path
+import re
 
 
 @dataclass(order=True)
@@ -52,6 +54,15 @@ class Variant:
     """
     board: Board = field(repr=False)
 
+    @property
+    def description(self) -> str:
+        """
+        Description of the board, if available.
+        Example: "Pyboard v1.1 with STM32F4"
+        """
+        return description_from_source(self.board.path, self.name) or self.board.description
+        # f"{self.board.description}-{self.name}"
+
 
 @dataclass(order=True)
 class Board:
@@ -93,6 +104,12 @@ class Board:
     """
     port: Port | None = field(default=None, compare=False)
 
+    path: str = ""
+    """
+    the relative path to the boards files.
+    Example: "ports/stm32/boards/PYBV11"
+    """
+
     @staticmethod
     def factory(filename_json: Path) -> Board:
         with filename_json.open() as f:
@@ -101,18 +118,27 @@ class Board:
         board = Board(
             name=filename_json.parent.name,
             variants=[],
-            url=board_json["url"],
+            url=board_json["url"] if "url" in board_json else "",  # fix missing url
             mcu=board_json["mcu"],
             product=board_json["product"],
             vendor=board_json["vendor"],
             images=board_json["images"],
             deploy=board_json["deploy"],
+            path=filename_json.parent.as_posix(),
         )
         board.variants.extend(
             sorted([Variant(*v, board) for v in board_json.get("variants", {}).items()])  # type: ignore
         )
         return board
 
+    @property
+    def description(self) -> str:
+        """
+        Description of the board, if available.
+        Example: "Pyboard v1.1 with STM32F4"
+        """
+        return description_from_source(self.path, "") or self.name
+
 
 @dataclass(order=True)
 class Port:
@@ -140,6 +166,8 @@ class Database:
 
     def __post_init__(self) -> None:
         mpy_dir = self.mpy_root_directory
+        if not mpy_dir.is_dir():
+            raise ValueError(f"Invalid path to micropython directory: {mpy_dir}")
         # Take care to avoid using Path.glob! Performance was 15x slower.
         for p in glob(f"{mpy_dir}/ports/**/boards/**/board.json"):
             filename_json = Path(p)
@@ -176,6 +204,7 @@ class Database:
                 "",
                 [],
                 [],
+                path=path.as_posix(),
             )
             board.variants = [Variant(v, "", board) for v in variant_names]
             port = Port(special_port_name, {special_port_name: board})
@@ -183,3 +212,59 @@ class Database:
 
             self.ports[special_port_name] = port
             self.boards[board.name] = board
+
+
+# look for all mpconfigboard.h files and extract the board name
+# from the #define MICROPY_HW_BOARD_NAME "PYBD_SF6"
+# and the #define MICROPY_HW_MCU_NAME "STM32F767xx"
+RE_H_MICROPY_HW_BOARD_NAME = re.compile(r"#define\s+MICROPY_HW_BOARD_NAME\s+\"(.+)\"")
+RE_H_MICROPY_HW_MCU_NAME = re.compile(r"#define\s+MICROPY_HW_MCU_NAME\s+\"(.+)\"")
+# find boards and variants in the mpconfigboard*.cmake files
+RE_CMAKE_MICROPY_HW_BOARD_NAME = re.compile(r"MICROPY_HW_BOARD_NAME\s?=\s?\"(?P<variant>[\w\s\S]*)\"")
+RE_CMAKE_MICROPY_HW_MCU_NAME = re.compile(r"MICROPY_HW_MCU_NAME\s?=\s?\"(?P<variant>[\w\s\S]*)\"")
+
+
+def description_from_source(board_path: str | Path, variant: str = "") -> str:
+    """Get the board's description from the header or make files."""
+    return description_from_header(board_path, variant) or description_from_cmake(board_path, variant)
+
+
+def description_from_header(board_path: str | Path, variant: str = "") -> str:
+    """Get the board's description from the mpconfigboard.h file."""
+
+    mpconfig_path = path.join(board_path, f"mpconfigboard_{variant}.h" if variant else "mpconfigboard.h")
+    if not path.exists(mpconfig_path):
+        return f""
+
+    with open(mpconfig_path, "r") as f:
+        board_name = mcu_name = "-"
+        found = 0
+        for line in f:
+            if match := RE_H_MICROPY_HW_BOARD_NAME.match(line):
+                board_name = match[1]
+                found += 1
+            elif match := RE_H_MICROPY_HW_MCU_NAME.match(line):
+                mcu_name = match[1]
+                found += 1
+            if found == 2:
+                return f"{board_name} with {mcu_name}" if mcu_name != "-" else board_name
+    return board_name if found == 1 else ""
+
+
+def description_from_cmake(board_path: str | Path, variant: str = "") -> str:
+    """Get the board's description from the mpconfig[board|variant].cmake file."""
+
+    cmake_path = path.join(board_path, f"mpconfigvariant_{variant}.cmake" if variant else "mpconfigboard.cmake")
+    if not path.exists(cmake_path):
+        return f""
+    with open(cmake_path, "r") as f:
+        board_name = mcu_name = "-"
+        for line in f:
+            line = line.strip()
+            if match := RE_CMAKE_MICROPY_HW_BOARD_NAME.match(line):
+                description = match["variant"]
+                return description
+            elif match := RE_CMAKE_MICROPY_HW_MCU_NAME.match(line):
+                description = match["variant"]
+                return description
+    return ""

mpflash/vendor/click_aliases.py

@@ -10,6 +10,7 @@
 # The above copyright notice and this permission notice shall be included in all
 # copies or substantial portions of the Software.
 # ------------------------------------------------------------------------------------
+# Jos Verlinde - 2024
 # modified to avoid conflcts with rich_click
 
 # sourcery skip: assign-if-exp, use-named-expression
@@ -20,12 +21,36 @@ _click7 = click.__version__[0] >= "7"
 
 
 class ClickAliasedGroup(click.RichGroup):
+    """
+    A subclass of click.RichGroup that adds support for command aliases.
+
+    This class allows defining aliases for commands and groups, enabling users
+    to invoke commands using alternative names.
+    """
+
     def __init__(self, *args, **kwargs):
+        """
+        Initialize the ClickAliasedGroup instance.
+
+        Args:
+            *args: Positional arguments passed to the superclass.
+            **kwargs: Keyword arguments passed to the superclass.
+        """
         super().__init__(*args, **kwargs)
         self._commands = {}
         self._aliases = {}
 
     def add_command(self, *args, **kwargs):
+        """
+        Add a command to the group, optionally with aliases.
+
+        Args:
+            *args: Positional arguments, typically the command instance and optionally its name.
+            **kwargs: Keyword arguments, may include 'aliases' as a list of alternative names.
+
+        Raises:
+            TypeError: If the command has no name.
+        """
         aliases = kwargs.pop("aliases", [])
         super().add_command(*args, **kwargs)
         if aliases:
@@ -40,6 +65,16 @@ class ClickAliasedGroup(click.RichGroup):
                 self._aliases[alias] = cmd.name
 
     def command(self, *args, **kwargs):
+        """
+        Decorator to define a new command with optional aliases.
+
+        Args:
+            *args: Positional arguments passed to the superclass decorator.
+            **kwargs: Keyword arguments, may include 'aliases' as a list of alternative names.
+
+        Returns:
+            Callable: A decorator function that registers the command and its aliases.
+        """
         aliases = kwargs.pop("aliases", [])
         decorator = super().command(*args, **kwargs)
         if not aliases:
@@ -56,6 +91,16 @@ class ClickAliasedGroup(click.RichGroup):
         return _decorator
 
     def group(self, *args, **kwargs):
+        """
+        Decorator to define a new command group with optional aliases.
+
+        Args:
+            *args: Positional arguments passed to the superclass decorator.
+            **kwargs: Keyword arguments, may include 'aliases' as a list of alternative names.
+
+        Returns:
+            Callable: A decorator function that registers the group and its aliases.
+        """
         aliases = kwargs.pop("aliases", [])
         decorator = super().group(*args, **kwargs)
         if not aliases:
@@ -72,11 +117,30 @@ class ClickAliasedGroup(click.RichGroup):
         return _decorator
 
     def resolve_alias(self, cmd_name):
+        """
+        Resolve a command alias to its original command name.
+
+        Args:
+            cmd_name (str): The command name or alias to resolve.
+
+        Returns:
+            str: The original command name if an alias is provided; otherwise, the input name.
+        """
         if cmd_name in self._aliases:
             return self._aliases[cmd_name]
         return cmd_name
 
     def get_command(self, ctx, cmd_name):
+        """
+        Retrieve a command by name or alias.
+
+        Args:
+            ctx (click.Context): The Click context object.
+            cmd_name (str): The command name or alias to retrieve.
+
+        Returns:
+            click.Command or None: The command object if found; otherwise, None.
+        """
         cmd_name = self.resolve_alias(cmd_name)
         command = super().get_command(ctx, cmd_name)
         if command: