micropython-stubber 1.24.1__py3-none-any.whl → 1.24.4__py3-none-any.whl

mpflash/mpflash/mpremoteboard/__init__.py

@@ -1,271 +0,0 @@
-"""
-Module to run mpremote commands, and retry on failure or timeout
-"""
-
-import sys
-import time
-from pathlib import Path
-from typing import List, Optional, Union
-
-import serial.tools.list_ports
-from rich.progress import track
-from tenacity import retry, stop_after_attempt, wait_fixed
-
-from mpflash.errors import MPFlashError
-from mpflash.logger import log
-from mpflash.mpboard_id.board_id import find_board_id_by_description
-from mpflash.mpremoteboard.runner import run
-
-if sys.version_info >= (3, 11):
-    import tomllib  # type: ignore
-else:
-    import tomli as tomllib  # type: ignore
-
-###############################################################################################
-HERE = Path(__file__).parent
-
-OK = 0
-ERROR = -1
-RETRIES = 3
-###############################################################################################
-
-
-class MPRemoteBoard:
-    """Class to run mpremote commands"""
-
-    def __init__(self, serialport: str = "", update: bool = False, *, location: str = ""):
-        """
-        Initialize MPRemoteBoard object.
-
-        Parameters:
-        - 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.serialport: str = serialport
-        self.firmware = {}
-
-        self.connected = False
-        self.path: Optional[Path] = None
-        self.family = "unknown"
-        self.description = ""
-        self.version = ""
-        self.port = ""
-        self.board = ""
-        self.cpu = ""
-        self.arch = ""
-        self.mpy = ""
-        self.build = ""
-        self.location = location  # USB location
-        self.toml = {}
-        if update:
-            self.get_mcu_info()
-
-    def __str__(self):
-        """
-        Return a string representation of the MPRemoteBoard object.
-
-        Returns:
-        - str: The string representation of the object.
-        """
-        return f"MPRemoteBoard({self.serialport}, {self.family} {self.port}, {self.board}, {self.version})"
-
-    @staticmethod
-    def connected_boards(bluetooth: bool = False, description: bool = False) -> List[str]:
-        # TODO: rename to connected_comports
-        """
-        Get a list of connected comports.
-
-        Parameters:
-        - bluetooth (bool): Whether to include Bluetooth ports. Default is False.
-
-        Returns:
-        - List[str]: A list of connected board ports.
-        """
-        comports = serial.tools.list_ports.comports()
-
-        if not bluetooth:
-            # 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]
-        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):
-        """
-        Get MCU information from the connected board.
-
-        Parameters:
-        - timeout (int): The timeout value in seconds. Default is 2.
-
-        Raises:
-        - ConnectionError: If failed to get mcu_info for the serial port.
-        """
-        rc, result = self.run_command(
-            ["run", str(HERE / "mpy_fw_info.py")],
-            no_info=True,
-            timeout=timeout,
-            resume=False,  # Avoid restarts
-        )
-        if rc:
-            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()
-        if raw_info.startswith("{") and raw_info.endswith("}"):
-            info = eval(raw_info)
-            self.family = info["family"]
-            self.version = info["version"]
-            self.build = info["build"]
-            self.port = info["port"]
-            self.cpu = info["cpu"]
-            self.arch = info["arch"]
-            self.mpy = info["mpy"]
-            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
-            else:
-                self.board = "UNKNOWN_BOARD"
-            # get the board_info.toml
-            self.get_board_info_toml()
-        # now we know the board is connected
-        self.connected = True
-
-    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(0.2), reraise=True)  # type: ignore ## retry_error_cls=ConnectionError,
-    def get_board_info_toml(self, timeout: int = 1):
-        """
-        Reads the content of the board_info.toml file from the connected board,
-        and adds that to the board object.
-
-        Parameters:
-        - timeout (int): The timeout value in seconds.
-
-        Raises:
-        - ConnectionError: If failed to communicate with the serial port.
-        """
-        try:
-            rc, result = self.run_command(
-                ["cat", ":board_info.toml"],
-                no_info=True,
-                timeout=timeout,
-                log_errors=False,
-            )
-        except Exception as e:
-            raise ConnectionError(f"Failed to get board_info.toml for {self.serialport}: {e}")
-        # this is optional - so only parse if we got the file
-        self.toml = {}
-        if rc in [OK]:  # sometimes we get an -9 ???
-            try:
-                # Ok we have the info, now parse it
-                self.toml = tomllib.loads("".join(result))
-                log.debug(f"board_info.toml: {self.toml}")
-            except Exception as e:
-                log.error(f"Failed to parse board_info.toml: {e}")
-        else:
-            log.trace(f"Did not find a board_info.toml: {result}")
-
-    def disconnect(self) -> bool:
-        """
-        Disconnect from a board.
-
-        Returns:
-        - bool: True if successfully disconnected, False otherwise.
-        """
-        if not self.connected:
-            return True
-        if not self.serialport:
-            log.error("No port connected")
-            self.connected = False
-            return False
-        log.info(f"Disconnecting from {self.serialport}")
-        result = self.run_command(["disconnect"])[0] == OK
-        self.connected = False
-        return result
-
-    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(2), reraise=True)
-    def run_command(
-        self,
-        cmd: Union[str, List[str]],
-        *,
-        log_errors: bool = True,
-        no_info: bool = False,
-        timeout: int = 60,
-        resume: Optional[bool] = None,
-        **kwargs,
-    ):
-        """
-        Run mpremote with the given command.
-
-        Parameters:
-        - cmd (Union[str, List[str]]): The command to run, either a string or a list of strings.
-        - log_errors (bool): Whether to log errors. Default is True.
-        - no_info (bool): Whether to skip printing info. Default is False.
-        - timeout (int): The timeout value in seconds. Default is 60.
-
-        Returns:
-        - bool: True if the command succeeded, False otherwise.
-        """
-        if isinstance(cmd, str):
-            cmd = cmd.split(" ")
-        prefix = [sys.executable, "-m", "mpremote"]
-        if self.serialport:
-            prefix += ["connect", self.serialport]
-        # if connected add resume to keep state between commands
-        if (resume != False) and self.connected or resume:
-            prefix += ["resume"]
-        cmd = prefix + cmd
-        log.debug(" ".join(cmd))
-        result = run(cmd, timeout, log_errors, no_info, **kwargs)
-        self.connected = result[0] == OK
-        return result
-
-    @retry(stop=stop_after_attempt(RETRIES), wait=wait_fixed(1))
-    def mip_install(self, name: str) -> bool:
-        """
-        Install a micropython package.
-
-        Parameters:
-        - name (str): The name of the package to install.
-
-        Returns:
-        - bool: True if the installation succeeded, False otherwise.
-        """
-        # install createstubs to the board
-        cmd = ["mip", "install", name]
-        result = self.run_command(cmd)[0] == OK
-        self.connected = True
-        return result
-
-    def wait_for_restart(self, timeout: int = 10):
-        """wait for the board to restart"""
-        for _ in track(
-            range(timeout),
-            description=f"Waiting for the board to restart ({timeout}s)",
-            transient=True,
-            show_speed=False,
-            refresh_per_second=1,
-            total=timeout,
-        ):
-            time.sleep(1)
-            try:
-                self.get_mcu_info()
-                break
-            except (ConnectionError, MPFlashError):
-                pass

mpflash/mpflash/mpremoteboard/mpy_fw_info.py

@@ -1,152 +0,0 @@
-# %%micropython
-import os
-import sys
-
-
-def _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'
-    if not s:
-        return ""
-    s = s.split(" on ", 1)[0] if " on " in s else s
-    if s.startswith("v"):
-        if not "-" in s:
-            return ""
-        b = s.split("-")[1]
-        return b
-    if not "-preview" in s:
-        return ""
-    b = s.split("-preview")[1].split(".")[1]
-    return b
-
-
-def _version_str(version: tuple):  #  -> str:
-    v_str = ".".join([str(n) for n in version[:3]])
-    if len(version) > 3 and version[3]:
-        v_str += "-" + version[3]
-    return v_str
-
-
-def _info():  # type:() -> dict[str, str]
-    # sourcery skip: use-contextlib-suppress, use-fstring-for-formatting, use-named-expression
-    info = dict(
-        {
-            "family": sys.implementation[0],  # type: ignore
-            "version": "",
-            "build": "",
-            "ver": "",
-            "port": (
-                "stm32" if sys.platform.startswith("pyb") else sys.platform
-            ),  # port: esp32 / win32 / linux / stm32
-            "board": "GENERIC",
-            "cpu": "",
-            "mpy": "",
-            "arch": "",
-        }
-    )
-    try:
-        info["version"] = _version_str(sys.implementation.version)
-    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 ""
-        info["mpy"] = (
-            sys.implementation._mpy
-            if "_mpy" in dir(sys.implementation)
-            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)
-        elif hasattr(os, "uname"):
-            info["build"] = _build(os.uname()[3])
-            if not info["build"]:
-                # extract build from uname().release if available
-                info["build"] = _build(os.uname()[2])
-    except (AttributeError, IndexError):
-        pass
-    # avoid  build hashes
-    if info["build"] and len(info["build"]) > 5:
-        info["build"] = ""
-
-    if info["version"] == "" and sys.platform not in ("unix", "win32"):
-        try:
-            u = os.uname()
-            info["version"] = u.release
-        except (IndexError, AttributeError, TypeError):
-            pass
-    # detect families
-    for fam_name, mod_name, mod_thing in [
-        ("pycopy", "pycopy", "const"),
-        ("pycom", "pycom", "FAT"),
-        ("ev3-pybricks", "pybricks.hubs", "EV3Brick"),
-    ]:
-        try:
-            _t = __import__(mod_name, None, None, (mod_thing))
-            info["family"] = fam_name
-            del _t
-            break
-        except (ImportError, KeyError):
-            pass
-
-    if info["family"] == "ev3-pybricks":
-        info["release"] = "2.0.0"
-
-    if info["family"] == "micropython":
-        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.19.9"
-        ):
-            # drop the .0 for newer releases
-            info["version"] = info["version"][:-2]
-
-    # spell-checker: disable
-    if "mpy" in info and info["mpy"]:  # mpy on some v1.11+ builds
-        sys_mpy = int(info["mpy"])
-        # .mpy architecture
-        try:
-            arch = [
-                None,
-                "x86",
-                "x64",
-                "armv6",
-                "armv6m",
-                "armv7m",
-                "armv7em",
-                "armv7emsp",
-                "armv7emdp",
-                "xtensa",
-                "xtensawin",
-                "hazard3riscv",  # assumed
-            ][sys_mpy >> 10]
-        except IndexError:
-            arch = "unknown"
-        if arch:
-            info["arch"] = arch
-        # .mpy version.minor
-        info["mpy"] = "v{}.{}".format(sys_mpy & 0xFF, sys_mpy >> 8 & 3)
-    # simple to use version[-build] string avoiding f-strings for backward compat
-    info["ver"] = (
-        "v{version}-{build}".format(version=info["version"], build=info["build"])
-        if info["build"]
-        else "v{version}".format(version=info["version"])
-    )
-
-    return info
-
-
-print(_info())
-del _info, _build, _version_str

mpflash/mpflash/mpremoteboard/runner.py

@@ -1,140 +0,0 @@
-"""
-Run a command and return the output and return code as a tuple
-"""
-
-import subprocess
-from dataclasses import dataclass
-from threading import Timer
-from typing import List, Optional, Tuple
-
-from loguru import logger as log
-
-LogTagList = List[str]
-
-
-@dataclass
-class LogTags:
-    reset_tags: LogTagList
-    error_tags: LogTagList
-    warning_tags: LogTagList
-    success_tags: LogTagList
-    ignore_tags: LogTagList
-
-
-DEFAULT_RESET_TAGS = [
-    # ESP32 reset causes
-    "rst cause:1, boot mode:",  # 1 -> hardware watch dog reset
-    "rst cause:2, boot mode:",  # 2 -> software watch dog reset (From an exception)
-    "rst cause:3, boot mode:",  # 3 -> software watch dog reset system_restart (Possibly unfed watchdog got angry)
-    "rst cause:4, boot mode:",  # 4 -> soft restart (Possibly with a restart command)
-    "boot.esp32: PRO CPU has been reset by WDT.",
-    "rst:0x10 (RTCWDT_RTC_RESET)",
-]
-
-
-def run(
-    cmd: List[str],
-    timeout: int = 60,
-    log_errors: bool = True,
-    no_info: bool = False,
-    *,
-    log_warnings: bool = False,
-    reset_tags: Optional[LogTagList] = None,
-    error_tags: Optional[LogTagList] = None,
-    warning_tags: Optional[LogTagList] = None,
-    success_tags: Optional[LogTagList] = None,
-    ignore_tags: Optional[LogTagList] = None,
-) -> Tuple[int, List[str]]:
-    # sourcery skip: no-long-functions
-    """
-    Run a command and return the output and return code as a tuple
-    Parameters
-    ----------
-    cmd : List[str]
-        The command to run
-    timeout : int, optional
-        The timeout in seconds, by default 60
-    log_errors : bool, optional
-        If False, don't log errors, Default: true
-    no_info : bool, optional
-        If True, don't log info, by default False
-    error_tags : Optional[LogTagList], optional
-        A list of strings to look for in the output to log as errors, by default None
-    warning_tags : Optional[LogTagList], optional
-        A list of strings to look for in the output to log as warnings, by default None
-    Returns
-    -------
-    Tuple[int, List[str]]
-        The return code and the output as a list of strings
-    """
-    if not reset_tags:
-        reset_tags = DEFAULT_RESET_TAGS
-    if not error_tags:
-        error_tags = ["Traceback ", "Error: ", "Exception: ", "ERROR :", "CRIT  :"]
-    if not warning_tags:
-        warning_tags = ["WARN  :", "TRACE :"]
-    if not success_tags:
-        success_tags = []
-    if not ignore_tags:
-        ignore_tags = ['  File "<stdin>",']
-
-    replace_tags = ["\x1b[1A"]
-
-    output = []
-    try:
-        proc = subprocess.Popen(
-            cmd,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            universal_newlines=True,
-            encoding="utf-8",
-        )
-    except FileNotFoundError as e:
-        raise FileNotFoundError(f"Failed to start {cmd[0]}") from e
-
-    def timed_out():
-        proc.kill()
-        if log_warnings:
-            log.warning(f"Command {cmd} timed out after {timeout} seconds")
-
-    timer = Timer(timeout, timed_out)
-    try:
-        timer.start()
-        # stdout has most of the output, assign log categories based on text tags
-        if proc.stdout:
-            for line in proc.stdout:
-                if not line or not line.strip():
-                    continue
-                for tag in replace_tags:
-                    line = line.replace(tag, "")
-                output.append(line)  # full output, no trimming
-                if any(tag in line for tag in reset_tags):
-                    raise RuntimeError("Board reset detected")
-
-                line = line.rstrip("\n")
-                # if any of the error tags in the line
-                if any(tag in line for tag in error_tags):
-                    if not log_errors:
-                        continue
-                    log.error(line)
-                elif any(tag in line for tag in warning_tags):
-                    log.warning(line)
-                elif any(tag in line for tag in success_tags):
-                    log.success(line)
-                elif any(tag in line for tag in ignore_tags):
-                    continue
-                else:
-                    if not no_info:
-                        if line.startswith(("INFO  : ", "WARN  : ", "ERROR : ")):
-                            line = line[8:].lstrip()
-                        log.info(line)
-        if proc.stderr and log_errors:
-            for line in proc.stderr:
-                log.warning(line)
-    except UnicodeDecodeError as e:
-        log.error(f"Failed to decode output: {e}")
-    finally:
-        timer.cancel()
-
-    proc.wait(timeout=1)
-    return proc.returncode or 0, output