micropython-stubber 1.20.1__py3-none-any.whl → 1.20.4__py3-none-any.whl

mpflash/mpflash/mpboard_id/board_id.py

@@ -3,64 +3,84 @@ Translate board description to board designator
 """
 
 import functools
-import json
 from pathlib import Path
 from typing import Optional
 
 from mpflash.errors import MPFlashError
-from mpflash.vendor.versions import clean_version
+from mpflash.logger import log
+from mpflash.mpboard_id.store import read_known_boardinfo
+from mpflash.vendor.versions import clean_version, get_stable_mp_version
 
-###############################################################################################
-HERE = Path(__file__).parent
-###############################################################################################
 
-
-def find_board_id(
-    descr: str, short_descr: str, board_info: Optional[Path] = None, version: str = "stable"
+def find_board_id_by_description(
+    descr: str,
+    short_descr: str,
+    *,
+    version: str,
+    board_info: Optional[Path] = None,
 ) -> Optional[str]:
     """Find the MicroPython BOARD_ID based on the description in the firmware"""
+
     try:
-        boards = find_board_id_by_description(
+        boards = _find_board_id_by_description(
             descr=descr,
             short_descr=short_descr,
             board_info=board_info,
-            version=clean_version(version),
+            version=clean_version(version) if version else None,
         )
-        return boards[-1]["board"]
+        return boards[-1].board_id
     except MPFlashError:
         return "UNKNOWN_BOARD"
 
 
 @functools.lru_cache(maxsize=20)
-def find_board_id_by_description(*, descr: str, short_descr: str, version="v1.21.0", board_info: Optional[Path] = None):
+def _find_board_id_by_description(
+    *,
+    descr: str,
+    short_descr: str,
+    version: Optional[str] = None,
+    board_info: Optional[Path] = None,
+):
     """
     Find the MicroPython BOARD_ID based on the description in the firmware
     using the pre-built board_info.json file
+
+    Parameters:
+    descr: str
+        Description of the board
+    short_descr: str
+        Short description of the board (optional)
+    version: str
+        Version of the MicroPython firmware
+    board_info: Path
+        Path to the board_info.json file (optional)
+
     """
-    if not board_info:
-        board_info = HERE / "board_info.json"
-    if not board_info.exists():
-        raise FileNotFoundError(f"Board info file not found: {board_info}")
+    # FIXME: functional overlap with
+    # src\mpflash\mpflash\mpboard_id\__init__.py find_known_board
 
-    info = _read_board_info(board_info)
+    if not short_descr and " with " in descr:
+        short_descr = descr.split(" with ")[0]
 
-    # filter for matching version
-    if version == "preview":
-        # TODO: match last stable
-        version = "v1.22.2"
-    version_matches = [b for b in info if b["version"].startswith(version)]
-    if not version_matches:
-        raise MPFlashError(f"No board info found for version {version}")
-    matches = [b for b in version_matches if b["description"] == descr]
+    candidate_boards = read_known_boardinfo(board_info)
+
+    if version:
+        # filter for matching version
+        if version in ("preview", "stable"):
+            # match last stable
+            version = get_stable_mp_version()
+        known_versions = sorted({b.version for b in candidate_boards})
+        if version not in known_versions:
+            # FIXME if latest stable is newer than the last version in the boardlist this will fail
+            log.trace(f"Version {version} not found in board info, using latest known version {known_versions[-1]}")
+            version = known_versions[-1]
+        if version_matches := [b for b in candidate_boards if b.version.startswith(version)]:
+            candidate_boards = version_matches
+        else:
+            raise MPFlashError(f"No board info found for version {version}")
+    matches = [b for b in candidate_boards if b.description == descr]
     if not matches and short_descr:
-        matches = [b for b in version_matches if b["description"] == short_descr]
+        matches = [b for b in candidate_boards if b.description == short_descr]
     if not matches:
         raise MPFlashError(f"No board info found for description '{descr}' or '{short_descr}'")
-    return sorted(matches, key=lambda x: x["version"])
-
-
-@functools.lru_cache(maxsize=20)
-def _read_board_info(board_info):
-    with open(board_info, "r") as file:
-        info = json.load(file)
-    return info
+    return sorted(matches, key=lambda x: x.version)

mpflash/mpflash/mpboard_id/store.py

@@ -0,0 +1,43 @@
+import functools
+import zipfile
+from pathlib import Path
+from typing import List, Optional
+
+import jsons
+
+from mpflash.mpboard_id.board import Board
+
+###############################################################################################
+HERE = Path(__file__).parent
+###############################################################################################
+
+
+def write_boardinfo_json(board_list: List[Board], *, folder: Path):
+    """Writes the board information to a JSON file.
+
+    Args:
+        board_list (List[Board]): The list of Board objects.
+        folder (Path): The folder where the compressed JSON file will be saved.
+    """
+    import zipfile
+
+    # create a zip file with the json file
+    with zipfile.ZipFile(folder / "board_info.zip", "w", compression=zipfile.ZIP_DEFLATED) as zipf:
+        # write the list to json file inside the zip
+        with zipf.open("board_info.json", "w") as fp:
+            fp.write(jsons.dumps(board_list, jdkwargs={"indent": 4}).encode())
+
+
+@functools.lru_cache(maxsize=20)
+def read_known_boardinfo(board_info: Optional[Path] = None) -> List[Board]:
+
+    if not board_info:
+        board_info = HERE / "board_info.zip"
+    if not board_info.exists():
+        raise FileNotFoundError(f"Board info file not found: {board_info}")
+
+    with zipfile.ZipFile(board_info, "r") as zf:
+        with zf.open("board_info.json", "r") as file:
+            info = jsons.loads(file.read().decode(encoding="utf-8"), List[Board])
+
+    return info

mpflash/mpflash/mpremoteboard/__init__.py

@@ -13,7 +13,7 @@ from rich.progress import track
 from tenacity import retry, stop_after_attempt, wait_fixed
 
 from mpflash.errors import MPFlashError
-from mpflash.mpboard_id.board_id import find_board_id
+from mpflash.mpboard_id.board_id import find_board_id_by_description
 from mpflash.mpremoteboard.runner import run
 
 ###############################################################################################
@@ -64,7 +64,7 @@ class MPRemoteBoard:
         return f"MPRemoteBoard({self.serialport}, {self.family} {self.port}, {self.board}, {self.version})"
 
     @staticmethod
-    def connected_boards(bluetooth: 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.
@@ -81,8 +81,19 @@ class MPRemoteBoard:
             # filter out bluetooth ports
             comports = [p for p in comports if "bluetooth" not in p.description.lower()]
             comports = [p for p in comports if "BTHENUM" not in p.hwid]
-
-        return sorted([p.device for p in comports])
+        if description:
+            output = [
+                f"{p.device} {(p.manufacturer + ' ') if p.manufacturer and not p.description.startswith(p.manufacturer) else ''}{p.description}"
+                for p in comports
+            ]
+        else:
+            output = [p.device for p in comports]
+
+        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)
+        # sort by device name
+        return sorted(output)
 
     @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(1), reraise=True)  # type: ignore ## retry_error_cls=ConnectionError,
     def get_mcu_info(self, timeout: int = 2):
@@ -116,10 +127,10 @@ 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(descr, short_descr):
+            if board_name := find_board_id_by_description(descr, short_descr, version=self.version):
                 self.board = board_name
             else:
-                self.board = "UNKNOWN"
+                self.board = "UNKNOWN_BOARD"
 
     def disconnect(self) -> bool:
         """
@@ -200,6 +211,7 @@ class MPRemoteBoard:
             transient=True,
             get_time=lambda: time.time(),
             show_speed=False,
+            refresh_per_second=1,
         ):
             time.sleep(1)
             try:

mpflash/mpflash/uf2disk.py

@@ -0,0 +1,12 @@
+"""Info to support mounting and unmounting of UF2 drives on linux and macos"""
+
+
+class UF2Disk:
+    """Info to support mounting and unmounting of UF2 drives on linux"""
+
+    device_path: str
+    label: str
+    mountpoint: str
+
+    def __repr__(self):
+        return repr(self.__dict__)

mpflash/mpflash/vendor/basicgit.py

@@ -0,0 +1,288 @@
+"""
+Simple Git module, where needed via powershell
+
+Some of the functions are based on the PyGithub module
+"""
+
+import os
+import subprocess
+from pathlib import Path
+from typing import List, Optional, Union
+
+import cachetools.func
+from github import Auth, Github
+from loguru import logger as log
+from packaging.version import parse
+
+# from stubber.utils.versions import SET_PREVIEW
+
+# Token with no permissions to avoid throttling
+# https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#getting-a-higher-rate-limit
+PAT_NO_ACCESS = (
+    "github_pat" + "_11AAHPVFQ0qAkDnSUaMKSp" + "_ZkDl5NRRwBsUN6EYg9ahp1Dvj4FDDONnXVgimxC2EtpY7Q7BUKBoQ0Jq72X"
+)
+PAT = os.environ.get("GITHUB_TOKEN") or PAT_NO_ACCESS
+GH_CLIENT = Github(auth=Auth.Token(PAT))
+
+
+def _run_local_git(
+    cmd: List[str],
+    repo: Optional[Union[Path, str]] = None,
+    expect_stderr=False,
+    capture_output=True,
+    echo_output=True,
+):
+    "run a external (git) command in the repo's folder and deal with some of the errors"
+    try:
+        if repo:
+            if isinstance(repo, str):
+                repo = Path(repo)
+            result = subprocess.run(
+                cmd, capture_output=capture_output, check=True, cwd=repo.absolute().as_posix(), encoding="utf-8"
+            )
+        else:
+            result = subprocess.run(cmd, capture_output=capture_output, check=True, encoding="utf-8")
+    except (NotADirectoryError, FileNotFoundError) as e:  # pragma: no cover
+        return None
+    except subprocess.CalledProcessError as e:  # pragma: no cover
+        # add some logging for github actions
+        log.error(f"{str(e)} : { e.stderr}")
+        return None
+    if result.stderr and result.stderr != b"":
+        stderr = result.stderr
+        if "cloning into" in stderr.lower():
+            # log.info(stderr)
+            expect_stderr = True
+        if "warning" in stderr.lower():
+            log.warning(stderr)
+            expect_stderr = True
+        elif capture_output and echo_output:  # pragma: no cover
+            log.info(stderr)
+        if not expect_stderr:
+            raise ChildProcessError(stderr)
+
+    if result.returncode and result.returncode < 0:
+        raise ChildProcessError(result.stderr)
+    return result
+
+
+def clone(remote_repo: str, path: Path, shallow: bool = False, tag: Optional[str] = None) -> bool:
+    """git clone [--depth 1] [--branch <tag_name>] <remote> <directory>"""
+    cmd = ["git", "clone"]
+    if shallow:
+        cmd += ["--depth", "1"]
+    if tag in {"preview", "latest", "master"}:
+        tag = None
+    cmd += [remote_repo, "--branch", tag, str(path)] if tag else [remote_repo, str(path)]
+    if result := _run_local_git(cmd, expect_stderr=True, capture_output=False):
+        return result.returncode == 0
+    else:
+        return False
+
+
+def get_local_tag(repo: Optional[Union[str, Path]] = None, abbreviate: bool = True) -> Union[str, None]:
+    """
+    get the most recent git version tag of a local repo
+    repo Path should be in the form of : repo = "./repo/micropython"
+
+    returns the tag or None
+    """
+    if not repo:
+        repo = Path(".")
+    elif isinstance(repo, str):
+        repo = Path(repo)
+
+    result = _run_local_git(
+        # ["git", "describe", "--tags"],
+        ["git", "describe", "--tags", "--dirty", "--always", "--match", "v[1-9].*"],
+        repo=repo.as_posix(),
+        expect_stderr=True,
+    )
+    if not result:
+        return None
+    tag: str = result.stdout
+    tag = tag.replace("\r", "").replace("\n", "")
+    if not abbreviate or "-" not in tag:
+        return tag
+    if "-preview" in tag:
+        tag = tag.split("-preview")[0] + "-preview"
+    return tag
+
+
+def get_local_tags(repo: Optional[Path] = None, minver: Optional[str] = None) -> List[str]:
+    """
+    get list of all tags of a local repo
+    """
+    if not repo:
+        repo = Path(".")
+
+    result = _run_local_git(["git", "tag", "-l"], repo=repo.as_posix(), expect_stderr=True)
+    if not result or result.returncode != 0:
+        return []
+    tags = result.stdout.replace("\r", "").split("\n")
+    tags = [tag for tag in tags if tag.startswith("v")]
+    if minver:
+        tags = [tag for tag in tags if parse(tag) >= parse(minver)]
+    return sorted(tags)
+
+
+@cachetools.func.ttl_cache(maxsize=16, ttl=60)  # 60 seconds
+def get_tags(repo: str, minver: Optional[str] = None) -> List[str]:
+    """
+    Get list of tag of a repote github repo
+    """
+    if not repo or not isinstance(repo, str) or "/" not in repo:  # type: ignore
+        return []
+    try:
+        gh_repo = GH_CLIENT.get_repo(repo)
+    except ConnectionError as e:
+        # TODO: unable to capture the exeption
+        log.warning(f"Unable to get tags - {e}")
+        return []
+    tags = [tag.name for tag in gh_repo.get_tags()]
+    if minver:
+        tags = [tag for tag in tags if parse(tag) >= parse(minver)]
+    return sorted(tags)
+
+
+def checkout_tag(tag: str, repo: Optional[Union[str, Path]] = None) -> bool:
+    """
+    checkout a specific git tag
+    """
+    cmd = ["git", "checkout", tag, "--quiet", "--force"]
+    result = _run_local_git(cmd, repo=repo, expect_stderr=True, capture_output=True)
+    if not result:
+        return False
+    # actually a good result
+    msg = {result.stdout}
+    if msg != {""}:
+        log.warning(f"git message: {msg}")
+    return True
+
+
+def sync_submodules(repo: Optional[Union[Path, str]] = None) -> bool:
+    """
+    make sure any submodules are in sync
+    """
+    cmds = [
+        ["git", "submodule", "sync", "--quiet"],
+        # ["git", "submodule", "update", "--quiet"],
+        ["git", "submodule", "update", "--init", "lib/micropython-lib"],
+    ]
+    for cmd in cmds:
+        if result := _run_local_git(cmd, repo=repo, expect_stderr=True):
+            # actually a good result
+            log.debug(result.stderr)
+        else:
+            return False
+    return True
+
+
+def checkout_commit(commit_hash: str, repo: Optional[Union[Path, str]] = None) -> bool:
+    """
+    Checkout a specific commit
+    """
+    cmd = ["git", "checkout", commit_hash, "--quiet", "--force"]
+    result = _run_local_git(cmd, repo=repo, expect_stderr=True)
+    if not result:
+        return False
+    # actually a good result
+    log.debug(result.stderr)
+    return True
+
+
+def switch_tag(tag: Union[str, Path], repo: Optional[Union[Path, str]] = None) -> bool:
+    """
+    switch to the specified version tag of a local repo
+    repo should be in the form of : path/.git
+    repo = '../micropython/.git'
+    returns None
+    """
+
+    cmd = ["git", "switch", "--detach", tag, "--quiet", "--force"]
+    result = _run_local_git(cmd, repo=repo, expect_stderr=True)
+    if not result:
+        return False
+    # actually a good result
+    log.debug(result.stderr)
+    return True
+
+
+def switch_branch(branch: str, repo: Optional[Union[Path, str]] = None) -> bool:
+    """
+    switch to the specified branch in a local repo"
+    repo should be in the form of : path/.git
+    repo = '../micropython/.git'
+    returns None
+    """
+    cmd = ["git", "switch", branch, "--quiet", "--force"]
+    result = _run_local_git(cmd, repo=repo, expect_stderr=True)
+    if not result:
+        return False
+    # actually a good result
+    log.debug(result.stderr)
+    return True
+
+
+def fetch(repo: Union[Path, str]) -> bool:
+    """
+    fetches a repo
+    repo should be in the form of : path/.git
+    repo = '../micropython/.git'
+    returns True on success
+    """
+    if not repo:
+        raise NotADirectoryError
+
+    cmd = ["git", "fetch", "--all", "--tags", "--quiet"]
+    result = _run_local_git(cmd, repo=repo, echo_output=False)
+    return result.returncode == 0 if result else False
+
+
+def pull(repo: Union[Path, str], branch: str = "main") -> bool:
+    """
+    pull a repo origin into main
+    repo should be in the form of : path/.git
+    repo = '../micropython/.git'
+    returns True on success
+    """
+    if not repo:
+        raise NotADirectoryError
+    repo = Path(repo)
+    # first checkout HEAD
+    cmd = ["git", "checkout", branch, "--quiet", "--force"]
+    result = _run_local_git(cmd, repo=repo, expect_stderr=True)
+    if not result:
+        log.error("error during git checkout main", result)
+        return False
+
+    cmd = ["git", "pull", "origin", branch, "--quiet", "--autostash"]
+    result = _run_local_git(cmd, repo=repo, expect_stderr=True)
+    if not result:
+        log.error("error durign pull", result)
+        return False
+    return result.returncode == 0
+
+
+def get_git_describe(folder: Optional[str] = None):
+    """
+    Based on MicroPython makeversionhdr.py
+    returns : current git tag, commits ,commit hash : "v1.19.1-841-g3446"
+    """
+    # Note: git describe doesn't work if no tag is available
+    try:
+        git_describe = subprocess.check_output(
+            ["git", "describe", "--tags", "--dirty", "--always", "--match", "v[1-9].*"],
+            stderr=subprocess.STDOUT,
+            universal_newlines=True,
+            cwd=folder,
+        ).strip()
+    except subprocess.CalledProcessError as er:
+        if er.returncode == 128:
+            # git exit code of 128 means no repository found
+            return None
+        git_describe = ""
+    except OSError:
+        return None
+    # format
+    return git_describe

mpflash/mpflash/vendor/dfu.py

@@ -1,5 +1,6 @@
 # sourcery skip: require-parameter-annotation
 # sourcery skip: replace-interpolation-with-fstring
+# type: ignore
 #!/usr/bin/python
 
 # Written by Antonio Galea - 2010/11/18

mpflash/mpflash/vendor/versions.py

@@ -9,6 +9,8 @@ from functools import lru_cache
 from loguru import logger as log
 from packaging.version import parse
 
+from mpflash.common import GH_CLIENT
+
 V_PREVIEW = "preview"
 "Latest preview version"
 
@@ -67,12 +69,12 @@ def clean_version(
 
 
 @lru_cache(maxsize=10)
-def micropython_versions(minver: str = "v1.20"):
+def micropython_versions(minver: str = "v1.20", reverse: bool = False):
     """Get the list of micropython versions from github tags"""
     try:
         gh_client = GH_CLIENT
         repo = gh_client.get_repo("micropython/micropython")
-        versions = [tag.name for tag in repo.get_tags() if parse(tag.name) >= parse(minver)]
+        versions = [tag.name for tag in repo.get_tags()]
     except Exception:
         versions = [
             "v9.99.9-preview",
@@ -94,7 +96,9 @@ def micropython_versions(minver: str = "v1.20"):
             "v1.11",
             "v1.10",
         ]
-        versions = [v for v in versions if parse(v) >= parse(minver)]
+    versions = [v for v in versions if parse(v) >= parse(minver)]
+    # remove all but the most recent (preview) version
+    versions = versions[:1] + [v for v in versions if "preview" not in v]
     return sorted(versions)