mpflash 1.24.6__py3-none-any.whl → 1.24.8__py3-none-any.whl

mpflash/mpboard_id/known.py

@@ -0,0 +1,94 @@
+"""
+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.errors import MPFlashError
+from mpflash.versions import clean_version
+
+from .board import Board
+from .store import read_known_boardinfo
+
+
+def get_known_ports() -> List[str]:
+    # TODO: Filter for Version
+    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")
+    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]
+
+    # filter for the port
+    if port:
+        mp_boards = [board for board in mp_boards if board.port == port]
+    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) -> 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
+    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

@@ -19,7 +19,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
@@ -34,7 +33,6 @@ def write_boardinfo_json(board_list: List[Board], *, folder: Optional[Path] = No
 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
 
     if not board_info:
         board_info = HERE / "board_info.zip"

mpflash/mpremoteboard/__init__.py

@@ -2,6 +2,8 @@
 Module to run mpremote commands, and retry on failure or timeout
 """
 
+
+import contextlib
 import sys
 import time
 from pathlib import Path
@@ -51,6 +53,7 @@ class MPRemoteBoard:
         self.version = ""
         self.port = ""
         self.board = ""
+        self.variant= ""
         self.cpu = ""
         self.arch = ""
         self.mpy = ""
@@ -65,9 +68,9 @@ class MPRemoteBoard:
         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]:
@@ -137,9 +140,12 @@ 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
-            ):
+            if info["_build"]: 
+                self.board = info["_build"].split('-')[0]
+                self.variant = info["_build"].split('-')[1] if '-' in info["_build"] else ""
+            elif board_name := find_board_id_by_description(
+                    descr, short_descr, version=self.version
+                ):
                 self.board = board_name
             else:
                 self.board = "UNKNOWN_BOARD"
@@ -168,7 +174,7 @@ 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 +270,6 @@ class MPRemoteBoard:
             total=timeout,
         ):
             time.sleep(1)
-            try:
+            with contextlib.suppress(ConnectionError, MPFlashError):
                 self.get_mcu_info()
                 break
-            except (ConnectionError, MPFlashError):
-                pass

mpflash/mpremoteboard/mpy_fw_info.py

@@ -1,4 +1,4 @@
-# %%micropython
+# pragma: no cover
 import os
 import sys
 
@@ -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,17 +49,16 @@ def _info():  # type:() -> dict[str, str]
     except AttributeError:
         pass
     try:
-        machine = (
-            sys.implementation._machine
-            if "_machine" in dir(sys.implementation)
-            else os.uname().machine
-        )
+        machine = sys.implementation._machine if "_machine" in dir(sys.implementation) else os.uname().machine  # type: ignore
         info["board"] = machine.strip()
+        info["_build"] = sys.implementation._build if "_build" in dir(sys.implementation) else ""
         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
@@ -69,10 +67,10 @@ def _info():  # type:() -> dict[str, str]
         if hasattr(sys, "version"):
             info["build"] = _build(sys.version)
         elif hasattr(os, "uname"):
-            info["build"] = _build(os.uname()[3])
+            info["build"] = _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"] = _build(os.uname()[2])  # type: ignore
     except (AttributeError, IndexError):
         pass
     # avoid  build hashes
@@ -81,7 +79,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 +104,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

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:

mpflash/vendor/dfu.py

@@ -46,10 +46,7 @@ def parse(file, dump_images=False):
             tprefix["name"] = cstring(tprefix["name"])
         else:
             tprefix["name"] = ""
-        print(
-            '%(signature)s %(num)d, alt setting: %(altsetting)s, name: "%(name)s", size: %(size)d, elements: %(elements)d'
-            % tprefix
-        )
+        print('%(signature)s %(num)d, alt setting: %(altsetting)s, name: "%(name)s", size: %(size)d, elements: %(elements)d' % tprefix)
         tsize = tprefix["size"]
         target, data = data[:tsize], data[tsize:]
         for e in range(tprefix["elements"]):
@@ -65,10 +62,7 @@ def parse(file, dump_images=False):
         if len(target):
             print("target %d: PARSE ERROR" % t)
     suffix = named(struct.unpack("<4H3sBI", data[:16]), "device product vendor dfu ufd len crc")
-    print(
-        "usb: %(vendor)04x:%(product)04x, device: 0x%(device)04x, dfu: 0x%(dfu)04x, %(ufd)s, %(len)d, 0x%(crc)08x"
-        % suffix
-    )
+    print("usb: %(vendor)04x:%(product)04x, device: 0x%(device)04x, dfu: 0x%(dfu)04x, %(ufd)s, %(len)d, 0x%(crc)08x" % suffix)
     if crc != suffix["crc"]:
         print("CRC ERROR: computed crc32 is 0x%08x" % crc)
     data = data[16:]

mpflash/vendor/pico-universal-flash-nuke/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright 2024 Phil Howard
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+   disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+   disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mpflash/vendor/pydfu.py

@@ -395,10 +395,7 @@ def read_dfu_file(filename):
     #   B   uint8_t     len         16
     #   I   uint32_t    crc32       Checksum
     dfu_suffix = named(struct.unpack("<4H3sBI", data[:16]), "device product vendor dfu ufd len crc")
-    print(
-        "    usb: %(vendor)04x:%(product)04x, device: 0x%(device)04x, "
-        "dfu: 0x%(dfu)04x, %(ufd)s, %(len)d, 0x%(crc)08x" % dfu_suffix
-    )
+    print("    usb: %(vendor)04x:%(product)04x, device: 0x%(device)04x, " "dfu: 0x%(dfu)04x, %(ufd)s, %(len)d, 0x%(crc)08x" % dfu_suffix)
     if crc != dfu_suffix["crc"]:
         print("CRC ERROR: computed crc32 is 0x%08x" % crc)
         return
@@ -477,19 +474,11 @@ def list_dfu_devices(*args, **kwargs):
     if not devices:
         raise SystemExit("No DFU capable devices found")
     for device in devices:
-        print(
-            "Bus {} Device {:03d}: ID {:04x}:{:04x}".format(
-                device.bus, device.address, device.idVendor, device.idProduct
-            )
-        )
+        print("Bus {} Device {:03d}: ID {:04x}:{:04x}".format(device.bus, device.address, device.idVendor, device.idProduct))
         layout = get_memory_layout(device)
         print("Memory Layout")
         for entry in layout:
-            print(
-                "    0x{:x} {:2d} pages of {:3d}K bytes".format(
-                    entry["addr"], entry["num_pages"], entry["page_size"] // 1024
-                )
-            )
+            print("    0x{:x} {:2d} pages of {:3d}K bytes".format(entry["addr"], entry["num_pages"], entry["page_size"] // 1024))
 
 
 def write_elements(elements, mass_erase_used, progress=None):

mpflash/vendor/readme.md

@@ -10,3 +10,5 @@ These modules are vendored from the following repositories:
 - https://github.com/click-contrib/click-aliases  (Public Domain)
   - click_aliases.py (Robbin Bonthond)
 
+- https://github.com/Gadgetoid/pico-universal-flash-nuke
+    - universal_flash_nuke.uf2

mpflash/versions.py

@@ -6,10 +6,8 @@ from pathlib import Path
 
 from cache_to_disk import NoCacheCondition, cache_to_disk
 from loguru import logger as log
-from packaging.version import Version, parse
 
-import mpflash.basicgit as git
-from mpflash.common import GH_CLIENT
+from mpflash.config import config
 
 OLDEST_VERSION = "1.16"
 "This is the oldest MicroPython version to build the stubs on"
@@ -71,15 +69,18 @@ def clean_version(
 
 def is_version(version: str):
     """Check if the version is a valid version string"""
+    # Just in time import
+    from packaging.version import Version
     return Version._regex.search(version) is not None
 
 
 @cache_to_disk(n_days_to_cache=1)
 def micropython_versions(minver: str = "v1.20", reverse: bool = False, cache_it=True):
     """Get the list of micropython versions from github tags"""
-
+    # Just in time import
+    from packaging.version import parse
     try:
-        gh_client = GH_CLIENT
+        gh_client = config.gh_client
         repo = gh_client.get_repo("micropython/micropython")
         tags = [tag.name for tag in repo.get_tags() if parse(tag.name) >= parse(minver)]
         versions = [v for v in tags if not v.endswith(V_PREVIEW)]
@@ -90,7 +91,7 @@ def micropython_versions(minver: str = "v1.20", reverse: bool = False, cache_it=
         log.error(e)
         versions = []
         # returns - but does not cache
-        raise NoCacheCondition(function_value=versions)
+        raise NoCacheCondition(function_value=versions) from e
     # remove any duplicates and sort
     versions = sorted(list(set(versions)), reverse=reverse, key=lambda s: (not is_version(s), s))
     if cache_it:
@@ -116,6 +117,8 @@ def get_preview_mp_version(cache_it=True) -> str:
 # Do not cache , same path will have different versions checked out
 def checkedout_version(path: Path, flat: bool = False) -> str:
     """Get the checked-out version of the repo"""
+    # Just in time import
+    import mpflash.basicgit as git
     version = git.get_local_tag(path.as_posix())
     if not version:
         raise ValueError("No valid Tag found")