micropython-stubber 1.23.1__py3-none-any.whl → 1.23.2__py3-none-any.whl

stubber/publish/defaults.py

@@ -1,40 +1,40 @@
-"""Build and packaging defaults for stubber"""
-
-from typing import Dict, List
-
-from mpflash.versions import V_PREVIEW, clean_version
-from stubber.utils.config import CONFIG
-
-# The default board for the ports modules documented with base name only
-# as the MicroPython BOARD naming convention has changed over time there are different options to try
-# (newer to older)
-
-DEFAULT_BOARDS: Dict[str, List[str]] = {
-    "stm32": ["PYBV11", ""],
-    "esp32": ["ESP32_GENERIC", "GENERIC", ""],  #  "GENERIC_SPIRAM",
-    "esp8266": ["ESP8266_GENERIC", "GENERIC", ""],
-    "rp2": ["RPI_PICO", "PICO", ""],
-    "samd": ["SEEED_WIO_TERMINAL", ""],
-}
-
-GENERIC_L = "generic"
-"generic lowercase"
-GENERIC_U = "GENERIC"
-"GENERIC uppercase"
-GENERIC = {GENERIC_L, GENERIC_U}
-"GENERIC eithercase"
-
-
-def default_board(port: str, version=V_PREVIEW) -> str:  # sourcery skip: assign-if-exp
-    """Return the default board for the given version and port"""
-    ver_flat = clean_version(version, flat=True)
-    if port in DEFAULT_BOARDS:
-        for board in DEFAULT_BOARDS[port]:
-            base = f"micropython-{ver_flat}-{port}-{board}" if board else f"micropython-{ver_flat}-{port}"
-            # check if we have a (merged)stub for this version and port
-            if (CONFIG.stub_path / f"{base}-merged").exists() or (CONFIG.stub_path / base).exists():
-                return board
-        # fallback to first listed board
-        return DEFAULT_BOARDS[port][0]
-    # fallback to generic
-    return GENERIC_U
+"""Build and packaging defaults for stubber"""
+
+from typing import Dict, List
+
+from mpflash.versions import V_PREVIEW, clean_version
+from stubber.utils.config import CONFIG
+
+# The default board for the ports modules documented with base name only
+# as the MicroPython BOARD naming convention has changed over time there are different options to try
+# (newer to older)
+
+DEFAULT_BOARDS: Dict[str, List[str]] = {
+    "stm32": ["PYBV11", ""],
+    "esp32": ["ESP32_GENERIC", "GENERIC", ""],  #  "GENERIC_SPIRAM",
+    "esp8266": ["ESP8266_GENERIC", "GENERIC", ""],
+    "rp2": ["RPI_PICO", "PICO", ""],
+    "samd": ["SEEED_WIO_TERMINAL", ""],
+}
+
+GENERIC_L = "generic"
+"generic lowercase"
+GENERIC_U = "GENERIC"
+"GENERIC uppercase"
+GENERIC = {GENERIC_L, GENERIC_U}
+"GENERIC eithercase"
+
+
+def default_board(port: str, version=V_PREVIEW) -> str:  # sourcery skip: assign-if-exp
+    """Return the default board for the given version and port"""
+    ver_flat = clean_version(version, flat=True)
+    if port in DEFAULT_BOARDS:
+        for board in DEFAULT_BOARDS[port]:
+            base = f"micropython-{ver_flat}-{port}-{board}" if board else f"micropython-{ver_flat}-{port}"
+            # check if we have a (merged)stub for this version and port
+            if (CONFIG.stub_path / f"{base}-merged").exists() or (CONFIG.stub_path / base).exists():
+                return board
+        # fallback to first listed board
+        return DEFAULT_BOARDS[port][0]
+    # fallback to generic
+    return GENERIC_U

stubber/publish/enums.py

@@ -1,24 +1,24 @@
-"""Enumerations for the stubber package."""
-from enum import Enum
-
-
-class StubSource(str, Enum):
-    FIRMWARE = "MCU stubs"
-    "stubs built by combining the firmware, frozen and core stubs"
-    FROZEN = "Frozen stubs"
-    "stubs of python modules that are frozen as part of the firmware image"
-    CORE = "Core stubs"
-    "stubs that allow (some) MicroPython code to be run by CPython"
-    DOC = "Doc stubs"
-    "stubs built by parsing the micropython RST documentation files"
-    MERGED = "Merged stubs"
-    "stubs built by merging the information from doc-stubs and MCU stubs"
-
-    def __str__(self):
-        # Always force string values
-        return self.value
-
-    def __repr__(self):
-        # Always force string values
-        return self.value
-
+"""Enumerations for the stubber package."""
+from enum import Enum
+
+
+class StubSource(str, Enum):
+    FIRMWARE = "MCU stubs"
+    "stubs built by combining the firmware, frozen and core stubs"
+    FROZEN = "Frozen stubs"
+    "stubs of python modules that are frozen as part of the firmware image"
+    CORE = "Core stubs"
+    "stubs that allow (some) MicroPython code to be run by CPython"
+    DOC = "Doc stubs"
+    "stubs built by parsing the micropython RST documentation files"
+    MERGED = "Merged stubs"
+    "stubs built by merging the information from doc-stubs and MCU stubs"
+
+    def __str__(self):
+        # Always force string values
+        return self.value
+
+    def __repr__(self):
+        # Always force string values
+        return self.value
+

stubber/publish/helpers.py

@@ -1,29 +1,29 @@
-"""
-This module provides a function to retrieve the docstring of a Python module.
-"""
-
-from pathlib import Path
-from typing import Any, Union
-
-import libcst as cst
-
-
-def get_module_docstring(fname: Path) -> Union[str, Any]:
-    """
-    Retrieve the docstring of a Python module.
-
-    Args:
-        fname (Path): The path to the Python module file.
-
-    Returns:
-        Union[str, Any]: The docstring of the Python module, or None if no docstring is found.
-    """
-    try:
-        with open(fname, "r") as file:
-            content = file.read()
-        mod = cst.parse_module(content)
-        return mod.get_docstring()
-    except Exception as e:
-        print(e)
-        return None
-
+"""
+This module provides a function to retrieve the docstring of a Python module.
+"""
+
+from pathlib import Path
+from typing import Any, Union
+
+import libcst as cst
+
+
+def get_module_docstring(fname: Path) -> Union[str, Any]:
+    """
+    Retrieve the docstring of a Python module.
+
+    Args:
+        fname (Path): The path to the Python module file.
+
+    Returns:
+        Union[str, Any]: The docstring of the Python module, or None if no docstring is found.
+    """
+    try:
+        with open(fname, "r") as file:
+            content = file.read()
+        mod = cst.parse_module(content)
+        return mod.get_docstring()
+    except Exception as e:
+        print(e)
+        return None
+

stubber/publish/merge_docstubs.py

@@ -1,130 +1,136 @@
-""" 
-Merge MCU stubs and docstubs into a single folder
-"""
-
-import shutil
-from pathlib import Path
-from typing import List, Optional, Union
-
-from loguru import logger as log
-
-from stubber.codemod.enrich import enrich_folder
-from stubber.publish.candidates import board_candidates, filter_list
-from stubber.publish.defaults import GENERIC, GENERIC_L, default_board
-from stubber.publish.missing_class_methods import add_machine_pin_call
-from stubber.publish.pathnames import get_base, get_board_path, get_merged_path
-from stubber.utils.config import CONFIG
-
-
-def merge_all_docstubs(
-    versions: Optional[Union[List[str], str]] = None,
-    family: str = "micropython",
-    ports: Optional[Union[List[str], str]] = None,
-    boards: Optional[Union[List[str], str]] = None,
-    *,
-    mpy_path: Path = CONFIG.mpy_path,
-):
-    """merge docstubs and MCU stubs to merged stubs"""
-    if versions is None:
-        versions = [CONFIG.stable_version]
-    if ports is None:
-        ports = ["all"]
-    if boards is None:
-        boards = [GENERIC_L]
-    if isinstance(versions, str):
-        versions = [versions]
-    if isinstance(ports, str):
-        ports = [ports]
-    if isinstance(boards, str):
-        boards = [boards]
-
-    candidates = list(board_candidates(versions=versions, family=family))
-    candidates = filter_list(candidates, ports, boards)
-    if not candidates:
-        log.error("No candidates found")
-        return
-
-    log.info(f"checking {len(candidates)} possible board candidates")
-    merged = 0
-    for candidate in candidates:
-        # use the default board for the port
-        if candidate["board"] in GENERIC:
-            candidate["board"] = default_board(port=candidate["port"], version=candidate["version"])
-        # check if we have MCU stubs of this version and port
-        doc_path = CONFIG.stub_path / f"{get_base(candidate)}-docstubs"
-        # src and dest paths
-        board_path = get_board_path(candidate)
-        merged_path = get_merged_path(candidate)
-
-        # only continue if both folders exist
-        if not doc_path.exists():
-            log.warning(f"No docstubs found for {candidate['version']}")
-            continue
-        if not board_path.exists():
-            log.info(f"skipping {merged_path.name}, no MCU stubs found in {board_path}")
-            continue
-        log.info(f"Merge {candidate['version']} docstubs with boardstubs to {merged_path.name}")
-        result = copy_and_merge_docstubs(board_path, merged_path, doc_path)
-        # Add methods from docstubs to the MCU stubs that do not exist in the MCU stubs
-        # Add the __call__ method to the machine.Pin and pyb.Pin class
-        add_machine_pin_call(merged_path, candidate["version"])
-        if result:
-            merged += 1
-    log.info(f"merged {merged} of {len(candidates)} candidates")
-    return merged
-
-
-def copy_and_merge_docstubs(fw_path: Path, dest_path: Path, docstub_path: Path):
-    """
-    Parameters:
-        fw_path: Path to MCU stubs (absolute path)
-        dest_path: Path to destination (absolute path)
-        mpy_version: micropython version ('1.18')
-
-    Copy files from the firmware stub folders to the merged
-    - 1 - Copy all MCU stubs to the package folder
-    - 1.B - clean up a little bit
-    - 2 - Enrich the MCU stubs with the document stubs
-
-    """
-    if dest_path.exists():
-        # delete all files and folders from the destination
-        shutil.rmtree(dest_path, ignore_errors=True)
-    dest_path.mkdir(parents=True, exist_ok=True)
-
-    # 1 - Copy  the stubs to the package, directly in the package folder (no folders)
-    try:
-        log.debug(f"Copying MCU stubs from {fw_path}")
-        shutil.copytree(fw_path, dest_path, symlinks=True, dirs_exist_ok=True)
-    except OSError as e:
-        log.error(f"Error copying stubs from : { fw_path}, {e}")
-        raise (e)
-    # rename the module.json file to firmware.json
-    if (dest_path / "modules.json").exists():
-        (dest_path / "modules.json").rename(dest_path / "firmware_stubs.json")
-
-    # avoid duplicate modules : folder - file combinations
-    # prefer folder from frozen stubs, over file from MCU stubs
-    # No frozen here - OLD code ?
-    for f in dest_path.glob("*"):
-        if f.is_dir():
-            for suffix in [".py", ".pyi"]:
-                if (dest_path / f.name).with_suffix(suffix).exists():
-                    (dest_path / f.name).with_suffix(suffix).unlink()
-
-    # delete builtins.pyi in the package folder
-    for name in [
-        "builtins",  # creates conflicts, better removed
-        "pycopy_imphook",  # is not intended to be used directly, and has an unresolved subclass
-    ]:
-        for suffix in [".py", ".pyi"]:
-            if (dest_path / name).with_suffix(suffix).exists():  # type: ignore
-                (dest_path / name).with_suffix(suffix).unlink()  # type: ignore
-
-    # 2 - Enrich the MCU stubs with the document stubs
-    result = enrich_folder(dest_path, docstub_path=docstub_path, write_back=True)
-
-    # copy the docstubs manifest.json file to the package folder
-    if (docstub_path / "modules.json").exists():
-        shutil.copy(docstub_path / "modules.json", dest_path / "doc_stubs.json")
-    return result
+""" 
+Merge MCU stubs and docstubs into a single folder
+"""
+
+import shutil
+from pathlib import Path
+from typing import List, Optional, Union
+
+from mpflash.logger import log
+
+from stubber.codemod.enrich import enrich_folder
+from stubber.publish.candidates import board_candidates, filter_list
+from stubber.publish.defaults import GENERIC, GENERIC_L, default_board
+from stubber.publish.missing_class_methods import add_machine_pin_call
+from stubber.publish.pathnames import get_base, get_board_path, get_merged_path
+from stubber.utils.config import CONFIG
+
+
+def merge_all_docstubs(
+    versions: Optional[Union[List[str], str]] = None,
+    family: str = "micropython",
+    ports: Optional[Union[List[str], str]] = None,
+    boards: Optional[Union[List[str], str]] = None,
+    *,
+    mpy_path: Path = CONFIG.mpy_path,
+):
+    """merge docstubs and MCU stubs to merged stubs"""
+    if versions is None:
+        versions = [CONFIG.stable_version]
+    if ports is None:
+        ports = ["all"]
+    if boards is None:
+        boards = [GENERIC_L]
+    if isinstance(versions, str):
+        versions = [versions]
+    if isinstance(ports, str):
+        ports = [ports]
+    if isinstance(boards, str):
+        boards = [boards]
+
+    candidates = list(board_candidates(versions=versions, family=family))
+    candidates = filter_list(candidates, ports, boards)
+    if not candidates:
+        log.error("No candidates found")
+        return
+
+    log.info(f"checking {len(candidates)} possible board candidates")
+    merged = 0
+    for candidate in candidates:
+        # use the default board for the port
+        if candidate["board"] in GENERIC:
+            candidate["board"] = default_board(
+                port=candidate["port"], version=candidate["version"]
+            )
+        # check if we have MCU stubs of this version and port
+        doc_path = CONFIG.stub_path / f"{get_base(candidate)}-docstubs"
+        # src and dest paths
+        board_path = get_board_path(candidate)
+        merged_path = get_merged_path(candidate)
+
+        # only continue if both folders exist
+        if not doc_path.exists():
+            log.warning(f"No docstubs found for {candidate['version']}")
+            continue
+        if not board_path.exists():
+            log.info(f"skipping {merged_path.name}, no MCU stubs found in {board_path}")
+            continue
+        log.info(f"Merge {candidate['version']} docstubs with boardstubs to {merged_path.name}")
+        try:
+            result = copy_and_merge_docstubs(board_path, merged_path, doc_path)
+            # Add methods from docstubs to the MCU stubs that do not exist in the MCU stubs
+            # Add the __call__ method to the machine.Pin and pyb.Pin class
+            add_machine_pin_call(merged_path, candidate["version"])
+        except Exception as e:
+            log.error(f"Error parsing {candidate['version']} docstubs: {e}")
+            continue
+        if result:
+            merged += 1
+    log.info(f"merged {merged} of {len(candidates)} candidates")
+    return merged
+
+
+def copy_and_merge_docstubs(fw_path: Path, dest_path: Path, docstub_path: Path):
+    """
+    Parameters:
+        fw_path: Path to MCU stubs (absolute path)
+        dest_path: Path to destination (absolute path)
+        mpy_version: micropython version ('1.18')
+
+    Copy files from the firmware stub folders to the merged
+    - 1 - Copy all MCU stubs to the package folder
+    - 1.B - clean up a little bit
+    - 2 - Enrich the MCU stubs with the document stubs
+
+    """
+    if dest_path.exists():
+        # delete all files and folders from the destination
+        shutil.rmtree(dest_path, ignore_errors=True)
+    dest_path.mkdir(parents=True, exist_ok=True)
+
+    # 1 - Copy  the stubs to the package, directly in the package folder (no folders)
+    try:
+        log.debug(f"Copying MCU stubs from {fw_path}")
+        shutil.copytree(fw_path, dest_path, symlinks=True, dirs_exist_ok=True)
+    except OSError as e:
+        log.error(f"Error copying stubs from : { fw_path}, {e}")
+        raise (e)
+    # rename the module.json file to firmware.json
+    if (dest_path / "modules.json").exists():
+        (dest_path / "modules.json").rename(dest_path / "firmware_stubs.json")
+
+    # avoid duplicate modules : folder - file combinations
+    # prefer folder from frozen stubs, over file from MCU stubs
+    # No frozen here - OLD code ?
+    for f in dest_path.glob("*"):
+        if f.is_dir():
+            for suffix in [".py", ".pyi"]:
+                if (dest_path / f.name).with_suffix(suffix).exists():
+                    (dest_path / f.name).with_suffix(suffix).unlink()
+
+    # delete builtins.pyi in the package folder
+    for name in [
+        "builtins",  # creates conflicts, better removed
+        "pycopy_imphook",  # is not intended to be used directly, and has an unresolved subclass
+    ]:
+        for suffix in [".py", ".pyi"]:
+            if (dest_path / name).with_suffix(suffix).exists():  # type: ignore
+                (dest_path / name).with_suffix(suffix).unlink()  # type: ignore
+
+    # 2 - Enrich the MCU stubs with the document stubs
+    result = enrich_folder(dest_path, docstub_path=docstub_path, write_back=True)
+
+    # copy the docstubs manifest.json file to the package folder
+    if (docstub_path / "modules.json").exists():
+        shutil.copy(docstub_path / "modules.json", dest_path / "doc_stubs.json")
+    return result

stubber/publish/missing_class_methods.py

@@ -1,49 +1,51 @@
-"""
-Add missing methods to classes in the stubs that are documented in the docstubs
-
-"""
-
-from pathlib import Path
-
-import libcst as cst
-from loguru import logger as log
-
-from mpflash.versions import clean_version
-from stubber.codemod.add_method import CallAdder, CallFinder
-from stubber.utils.config import CONFIG
-from stubber.utils.post import run_black
-
-
-def add_machine_pin_call(merged_path: Path, version: str):
-    """
-    Add the __call__ method to the machine.Pin and pyb.Pin class
-    in all pyb and machine/umachine stubs
-    """
-    # TODO: this should be done in the merge_docstubs.py to avoid needing to run black twice
-    # and to avoid having to parse the file twice
-
-    # first find the __call__ method in the default stubs
-    mod_path = CONFIG.stub_path / f"micropython-{clean_version(version, flat=True)}-docstubs/machine.pyi"
-    if not mod_path.exists():
-        log.error(f"no docstubs found for {version}")
-        return False
-    log.trace(f"Parsing {mod_path} for __call__ method")
-    source = mod_path.read_text(encoding="utf-8")
-    module = cst.parse_module(source)
-
-    call_finder = CallFinder()
-    module.visit(call_finder)
-
-    if call_finder.call_meth is None:
-        log.error("no __call__ method found")
-        return False
-
-    # then use the CallAdder to add the __call__ method to all machine and pyb stubs
-    mod_paths = [f for f in merged_path.rglob("*.*") if f.stem in {"machine", "umachine", "pyb"}]
-    for mod_path in mod_paths:
-        source = mod_path.read_text(encoding="utf-8")
-        machine_module = cst.parse_module(source)
-        new_module = machine_module.visit(CallAdder(call_finder.call_meth))
-        mod_path.write_text(new_module.code, encoding="utf-8")
-        run_black(mod_path)
-    return True
+"""
+Add missing methods to classes in the stubs that are documented in the docstubs
+
+"""
+
+from pathlib import Path
+
+import libcst as cst
+from mpflash.logger import log
+
+from mpflash.versions import clean_version
+from stubber.codemod.add_method import CallAdder, CallFinder
+from stubber.utils.config import CONFIG
+from stubber.utils.post import run_black
+
+
+def add_machine_pin_call(merged_path: Path, version: str):
+    """
+    Add the __call__ method to the machine.Pin and pyb.Pin class
+    in all pyb and machine/umachine stubs
+    """
+    # TODO: this should be done in the merge_docstubs.py to avoid needing to run black twice
+    # and to avoid having to parse the file twice
+
+    # first find the __call__ method in the default stubs
+    mod_path = (
+        CONFIG.stub_path / f"micropython-{clean_version(version, flat=True)}-docstubs/machine.pyi"
+    )
+    if not mod_path.exists():
+        log.error(f"no docstubs found for {version}")
+        return False
+    log.trace(f"Parsing {mod_path} for __call__ method")
+    source = mod_path.read_text(encoding="utf-8")
+    module = cst.parse_module(source)
+
+    call_finder = CallFinder()
+    module.visit(call_finder)
+
+    if call_finder.call_meth is None:
+        log.error("no __call__ method found")
+        return False
+
+    # then use the CallAdder to add the __call__ method to all machine and pyb stubs
+    mod_paths = [f for f in merged_path.rglob("*.*") if f.stem in {"machine", "umachine", "pyb"}]
+    for mod_path in mod_paths:
+        source = mod_path.read_text(encoding="utf-8")
+        machine_module = cst.parse_module(source)
+        new_module = machine_module.visit(CallAdder(call_finder.call_meth))
+        mod_path.write_text(new_module.code, encoding="utf-8")
+        run_black(mod_path)
+    return True