micropython-stubber 1.14.1__py3-none-any.whl → 1.15.1__py3-none-any.whl

stubber/publish/candidates.py

@@ -19,7 +19,7 @@ from packaging.version import parse
 
 import stubber.basicgit as git
 from stubber.publish.enums import COMBO_STUBS, DOC_STUBS, FIRMWARE_STUBS
-from stubber.publish.package import GENERIC, GENERIC_L, GENERIC_U
+from stubber.publish.defaults import GENERIC, GENERIC_L, GENERIC_U
 from stubber.utils.config import CONFIG
 from stubber.utils.versions import clean_version, micropython_versions
 
@@ -38,7 +38,11 @@ def subfolder_names(path: Path):
 
 
 def version_candidates(
-    suffix: str, prefix: str = r".*", *, path: Path = CONFIG.stub_path, oldest: str = OLDEST_VERSION
+    suffix: str,
+    prefix: str = r".*",
+    *,
+    path: Path = CONFIG.stub_path,
+    oldest: str = OLDEST_VERSION,
 ) -> Generator[str, None, None]:
     "get a list of versions for the given family and suffix"
     if path.exists():
@@ -91,8 +95,8 @@ def list_micropython_port_boards(
 def frozen_candidates(
     family: str = "micropython",
     versions: Union[str, List[str]] = V_LATEST,
-    ports: Union[str, List[str]] = "auto",
-    boards: Union[str, List[str]] = "auto",
+    ports: Union[str, List[str]] = "all",
+    boards: Union[str, List[str]] = "all",
     *,
     path: Path = CONFIG.stub_path,
 ) -> Generator[Dict[str, Any], None, None]:
@@ -125,7 +129,9 @@ def frozen_candidates(
                 # lookup the (frozen) micropython ports
                 ports = list_frozen_ports(family, version, path=path)
             else:
-                raise NotImplementedError(f"auto ports not implemented for family {family}")  # pragma: no cover
+                raise NotImplementedError(
+                    f"auto ports not implemented for family {family}"
+                )  # pragma: no cover
             # elif family == "pycom":
             #     ports = ["esp32"]
             # elif family == "lobo":
@@ -134,7 +140,13 @@ def frozen_candidates(
         for port in ports:
             port_path = path / f"{family}-{version}-frozen" / port
             if port_path.exists():
-                yield {"family": family, "version": version, "port": port, "board": GENERIC_L, "pkg_type": COMBO_STUBS}
+                yield {
+                    "family": family,
+                    "version": version,
+                    "port": port,
+                    "board": GENERIC_L,
+                    "pkg_type": COMBO_STUBS,
+                }
             # if not auto_board:
             #     for board in boards:
             #         port_path = board_path/ "board" / board
@@ -152,7 +164,9 @@ def frozen_candidates(
 
                 else:
                     # raise NotImplementedError(f"auto boards not implemented for family {family}")  # pragma: no cover
-                    raise NotImplementedError(f"auto boards not implemented for family {family}")  # pragma: no cover
+                    raise NotImplementedError(
+                        f"auto boards not implemented for family {family}"
+                    )  # pragma: no cover
                 # elif family == "pycom":
                 #     boards = ["wipy", "lopy", "gpy", "fipy"]
             # ---------------------------------------------------------------------------
@@ -166,12 +180,21 @@ def frozen_candidates(
                     "RELEASE",
                     "GENERIC_512K",
                 ]:
-                    yield {"family": family, "version": version, "port": port, "board": board, "pkg_type": COMBO_STUBS}
+                    yield {
+                        "family": family,
+                        "version": version,
+                        "port": port,
+                        "board": board,
+                        "pkg_type": COMBO_STUBS,
+                    }
 
 
 def is_auto(thing: Union[None, str, List[str]]):
     "Is this version/port/board specified as 'auto' ?"
-    return isinstance(thing, str) and thing == "auto" or isinstance(thing, list) and "auto" in thing
+    if isinstance(thing, str):
+        return thing in ["auto", "all"]
+    if isinstance(thing, list):
+        return any(i in ["auto", "all"] for i in thing)
 
 
 def docstub_candidates(
@@ -182,10 +205,10 @@ def docstub_candidates(
     """
     Generate a list of possible documentation stub candidates for the given family and version.
 
-    Note that the folders do not need to exist, with the exeption of auto which will scan the stubs folder for versions of docstubs
+    Note that the folders do not need to exist, with the exception of auto which will scan the stubs folder for versions of docstubs
     """
     if isinstance(versions, str):
-        if versions == "auto":  # auto with vprefix ...
+        if is_auto(versions):  # auto with vprefix ...
             versions = list(version_candidates(suffix="docstubs", prefix=family, path=path))
         else:
             versions = [versions]
@@ -196,7 +219,11 @@ def docstub_candidates(
 
 
 def board_candidates(
-    family: str = "micropython", versions: Union[str, List[str]] = V_LATEST, *, mpy_path: Path = CONFIG.mpy_path, pt: str = FIRMWARE_STUBS
+    family: str = "micropython",
+    versions: Union[str, List[str]] = V_LATEST,
+    *,
+    mpy_path: Path = CONFIG.mpy_path,
+    pt: str = FIRMWARE_STUBS,
 ):
     """
     generate a list of possible board stub candidates for the given family and version.
@@ -209,7 +236,7 @@ def board_candidates(
     versions = [clean_version(v, flat=False) for v in versions]
 
     for version in versions:
-        # check out the micropthon repo for this version
+        # check out the micropython repo for this version
         if version in ["latest", "master"]:
             r = git.switch_branch(repo=mpy_path, branch="master")
         else:
@@ -219,10 +246,22 @@ def board_candidates(
         ports = list_micropython_ports(family=family, mpy_path=mpy_path)
         for port in ports:
             # Yield the generic port exactly one time
-            yield {"family": family, "version": version, "port": port, "board": GENERIC_U, "pkg_type": pt}
+            yield {
+                "family": family,
+                "version": version,
+                "port": port,
+                "board": GENERIC_U,
+                "pkg_type": pt,
+            }
             for board in list_micropython_port_boards(family=family, mpy_path=mpy_path, port=port):
                 if board not in GENERIC:
-                    yield {"family": family, "version": version, "port": port, "board": board, "pkg_type": pt}
+                    yield {
+                        "family": family,
+                        "version": version,
+                        "port": port,
+                        "board": board,
+                        "pkg_type": pt,
+                    }
 
 
 def filter_list(
@@ -232,7 +271,7 @@ def filter_list(
     # versions: Optional[Union[List[str], str]] = None,
 ):
     """
-    filter a list of candidates down to the ones we want, based on the ports and boars specified (case insensitive)
+    filter a list of candidates down to the ones we want, based on the ports and boards specified (case insensitive)
     for board also match using a 'GENERIC_' prefix, so board 's3' will match candidate 'GENERIC_S3'
     """
     worklist = [i for i in worklist if i["board"] != ""]
@@ -241,5 +280,10 @@ def filter_list(
         worklist = [i for i in worklist if i["port"].lower() in ports_]
     if boards and not is_auto(boards):
         boards_ = [i.lower() for i in boards]
-        worklist = [i for i in worklist if i["board"].lower() in boards_ or i["board"].lower().replace("generic_", "") in boards_]
+        worklist = [
+            i
+            for i in worklist
+            if i["board"].lower() in boards_
+            or i["board"].lower().replace("generic_", "") in boards_
+        ]
     return worklist

stubber/publish/defaults.py

@@ -0,0 +1,44 @@
+"""Build and packaging defaults for stubber"""
+from typing import Dict, List
+from stubber.utils.config import CONFIG
+from stubber.utils.versions import clean_version
+
+# 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="latest") -> 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/merge_docstubs.py

@@ -4,45 +4,16 @@ Merge firmware stubs and docstubs into a single folder
 
 import shutil
 from pathlib import Path
-from typing import Dict, List, Optional, Union
+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.package import GENERIC, GENERIC_L
+from stubber.publish.pathnames import get_base, get_board_path, get_merged_path
 from stubber.utils.config import CONFIG
-from stubber.utils.versions import clean_version
-
-## Helper function
-
-
-def get_base(candidate: Dict[str, str], version: Optional[str] = None):
-    if not version:
-        version = clean_version(candidate["version"], flat=True)
-    base = f"{candidate['family']}-{version}"
-    return base.lower()
-
-
-def board_folder_name(fw: Dict, *, version: Optional[str] = None):
-    """Return the name of the firmware folder. Can be in AnyCase."""
-    base = get_base(fw, version=version)
-    folder_name = (
-        f"{base}-{fw['port']}" if fw["board"] in GENERIC else f"{base}-{fw['port']}-{fw['board']}"
-    )
-    # do NOT force name to lowercase
-    # remove GENERIC Prefix
-    folder_name = folder_name.replace("-generic_", "-").replace("-GENERIC_", "-")
-    return folder_name
-
-
-def get_board_path(fw: Dict):
-    return CONFIG.stub_path / board_folder_name(fw)
-
-
-def get_merged_path(fw: Dict):
-    return CONFIG.stub_path / (board_folder_name(fw) + "-merged")
 
 
 def merge_all_docstubs(
@@ -57,7 +28,7 @@ def merge_all_docstubs(
     if versions is None:
         versions = [CONFIG.stable_version]
     if ports is None:
-        ports = ["auto"]
+        ports = ["all"]
     if boards is None:
         boards = [GENERIC_L]
     if isinstance(versions, str):
@@ -69,40 +40,32 @@ def merge_all_docstubs(
 
     candidates = list(board_candidates(versions=versions, family=family))
     candidates = filter_list(candidates, ports, boards)
-    log.info(f"checking {len(candidates)} possible board candidates")
-
-    merged = 0
     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 board stubs of this version and port
         doc_path = CONFIG.stub_path / f"{get_base(candidate)}-docstubs"
-        if not doc_path.exists():
-            log.warning(f"No docstubs found for {candidate['version']}")
-            continue
         # 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"no firmware stubs found in {board_path}")
-            if candidate["version"] == "latest":
-                # for the latest we do a bit more effort to get something 'good enough'
-                # try to get the board_path from the last released version as the basis
-                board_path = CONFIG.stub_path / board_folder_name(candidate, version="latest")
-                # check again
-                if board_path.exists():
-                    log.info(f"using {board_path.name} as the basis for {merged_path.name}")
-                else:
-                    # only continue if both folders exist
-                    log.debug(f"skipping {merged_path.name}, no firmware stubs found")
-                    continue
-            else:
-                # only continue if both folders exist
-                log.debug(f"skipping {merged_path.name}, no firmware stubs found")
-                continue
-        log.info(f"Merge docstubs for {merged_path.name} {candidate['version']}")
+            log.info(f"skipping {merged_path.name}, no firmware 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 firmware stubs that do not exist in the firmware stubs
         # Add the __call__ method to the machine.Pin and pyb.Pin class

stubber/publish/package.py

@@ -10,30 +10,27 @@ from loguru import logger as log
 from packaging.version import parse
 from pysondb import PysonDB
 
+from stubber.publish.defaults import GENERIC, GENERIC_L, default_board
 from stubber.publish.enums import COMBO_STUBS, CORE_STUBS, DOC_STUBS, StubSource
 from stubber.publish.stubpacker import StubPackage, StubSources
 from stubber.utils.config import CONFIG
 from stubber.utils.versions import clean_version
 
-GENERIC_L = "generic"
-"generic lowercase"
-GENERIC_U = "GENERIC"
-"GENERIC uppercase"
-GENERIC = {GENERIC_L, GENERIC_U}
-"GENERIC eithercase"
-
 # replace std log handler with a custom one capped on INFO level
 log.remove()
 log.add(sys.stderr, level="INFO", backtrace=True, diagnose=True)
 
 
-def package_name(pkg_type: str, *, port: str = "", board: str = "", family: str = "micropython", **kwargs) -> str:
+def package_name(
+    pkg_type: str, *, port: str = "", board: str = "", family: str = "micropython", **kwargs
+) -> str:
     "generate a package name for the given package type"
     if pkg_type == COMBO_STUBS:
         # # {family}-{port}-{board}-stubs
         name = f"{family}-{port}-{board}-stubs".lower()
         name = name.replace("-generic-stubs", "-stubs")
-        name = name.replace("-generic_", "-")  # @GENERIC Prefix
+        # Use explicit generic_ names for the stubs
+        # name = name.replace("-generic_", "-")  # @GENERIC Prefix
         return name
     elif pkg_type == DOC_STUBS:
         return f"{family}-doc-stubs".lower()
@@ -41,10 +38,11 @@ def package_name(pkg_type: str, *, port: str = "", board: str = "", family: str
         return f"{family}-core-stubs".lower()
     # # {family}-{port}-{board}-{type}-stubs
     name = f"{family}-{port}-{board}-{pkg_type}-stubs".lower()
-    # remove -generic- from the name
-    name = name.replace(f"-generic-{pkg_type}-stubs", f"-{pkg_type}-stubs")
-    # remove -genetic_ from the name
-    name = name.replace("-generic_", "-")  # @GENERIC Prefix
+    # Use explicit generic_ names for the stubs
+    # # remove -generic- from the name
+    # name = name.replace(f"-generic-{pkg_type}-stubs", f"-{pkg_type}-stubs")
+    # # remove -genetic_ from the name
+    # name = name.replace("-generic_", "-")  # @GENERIC Prefix
     return name
 
 
@@ -67,7 +65,7 @@ def get_package(
         mpy_version=version,
     ):
         # create package from the information retrieved from the database
-        return StubPackage(pkg_name, version=version, json_data=package_info)
+        return StubPackage(pkg_name, port, board=board, version=version, json_data=package_info)
 
     log.debug(f"No package found for {pkg_name} in database, creating new package")
     return create_package(
@@ -80,7 +78,9 @@ def get_package(
     )
 
 
-def get_package_info(db: PysonDB, pub_path: Path, *, pkg_name: str, mpy_version: str) -> Union[Dict, None]:
+def get_package_info(
+    db: PysonDB, pub_path: Path, *, pkg_name: str, mpy_version: str
+) -> Union[Dict, None]:
     """
     get a package's record from the json db if it can be found
     matches om the package name and version
@@ -88,7 +88,9 @@ def get_package_info(db: PysonDB, pub_path: Path, *, pkg_name: str, mpy_version:
         mpy_version: micropython/firmware version (1.18)
     """
     # find in the database
-    recs = db.get_by_query(query=lambda x: x["mpy_version"] == mpy_version and x["name"] == pkg_name)
+    recs = db.get_by_query(
+        query=lambda x: x["mpy_version"] == mpy_version and x["name"] == pkg_name
+    )
     # dict to list
     recs = [{"id": key, "data": recs[key]} for key in recs]
     # sort
@@ -120,7 +122,7 @@ def create_package(
         assert port != "", "port must be specified for combo stubs"
         stubs = combo_sources(family, port, board, ver_flat)
     elif pkg_type == DOC_STUBS:
-        stubs: StubSources = [
+        stubs = [
             (
                 StubSource.DOC,
                 Path(f"{family}-{ver_flat}-docstubs"),
@@ -132,14 +134,12 @@ def create_package(
     else:
         raise NotImplementedError(type)
 
-    return StubPackage(pkg_name, version=mpy_version, stubs=stubs)
+    return StubPackage(pkg_name, port=port, board=board, version=mpy_version, stubs=stubs)
 
 
 def combo_sources(family: str, port: str, board: str, ver_flat: str) -> StubSources:
     """
     Build a source set for combo stubs
-        -
-
     """
     # Use lower case for paths to avoid case sensitive issues
     port = port.lower()
@@ -149,22 +149,29 @@ def combo_sources(family: str, port: str, board: str, ver_flat: str) -> StubSour
     board_u = board_l.upper()
     board_l = board_l.replace("generic_", "")  # @GENERIC Prefix
 
+    # StubSource.FIRMWARE,
+    # Path(f"{family}-{ver_flat}-{port}"),
+    # TODO: look for the most specific firmware stub folder that is available ?
+    # is it possible to prefer micropython-nrf-microbit-stubs over micropython-nrf-stubs
+    # that would also require the port - board - variant to be discoverable runtime
+
+    if board_l in GENERIC:
+        merged_path = Path(f"{family}-{ver_flat}-{port}-merged")
+        if not merged_path.exists():
+            board = default_board(port, ver_flat)
+            board_l = board.lower()
+            board_u = board
+            merged_path = Path(f"{family}-{ver_flat}-{port}-{board}-merged")
+    else:
+        merged_path = Path(f"{family}-{ver_flat}-{port}-{board}-merged")
+
+    # BOARD in source frozen path needs to be UPPERCASE
+    frozen_path = Path(f"{family}-{ver_flat}-frozen") / port / board_u.upper()
+    # TODO : Add version to core stubs
+    core_path = Path(f"{family}-core")
+
     return [
-        (
-            # StubSource.FIRMWARE,
-            # Path(f"{family}-{ver_flat}-{port}"),
-            # TODO: look for the most specific firmware stub folder that is available ?
-            # is it possible to prefer micropython-nrf-microbit-stubs over micropython-nrf-stubs
-            # that would also require the port - board - variant to be discoverable runtime
-            StubSource.MERGED,
-            Path(f"{family}-{ver_flat}-{port}-merged") if board_l in GENERIC else Path(f"{family}-{ver_flat}-{port}-{board_l}-merged"),
-        ),
-        (
-            StubSource.FROZEN,
-            Path(f"{family}-{ver_flat}-frozen") / port / board_u.upper(),  # BOARD in source frozen path needs to be UPPERCASE
-        ),
-        (
-            StubSource.CORE,
-            Path(f"{family}-core"),  # TODO : Add version to core stubs
-        ),
+        (StubSource.MERGED, merged_path),
+        (StubSource.FROZEN, frozen_path),
+        (StubSource.CORE, core_path),
     ]

stubber/publish/pathnames.py

@@ -0,0 +1,51 @@
+"""
+Helper functions to deal with path names and filenames for the folders in the stubs repo
+
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from loguru import logger as log
+
+from stubber.publish.defaults import default_board
+from stubber.publish.package import GENERIC
+from stubber.utils.config import CONFIG
+from stubber.utils.versions import clean_version
+
+
+## Helper functions
+def get_base(candidate: Dict[str, str], version: Optional[str] = None):
+    if version:
+        version = clean_version(version, flat=True)
+    else:
+        version = clean_version(candidate["version"], flat=True)
+    base = f"{candidate['family']}-{version}"
+    return base.lower()
+
+
+def board_folder_name(fw: Dict, *, version: Optional[str] = None) -> str:
+    """Return the name of the firmware folder. Can be in AnyCase."""
+    base = get_base(fw, version=version)
+    if fw["board"] in GENERIC:
+        board = default_board(fw["port"], fw["version"])
+    else:
+        board = fw["board"]
+    folder_name = f"{base}-{fw['port']}-{board}" if board else f"{base}-{fw['port']}"
+    # do NOT force name to lowercase
+    # remove GENERIC Prefix
+    # folder_name = folder_name.replace("-generic_", "-").replace("-GENERIC_", "-")
+    return folder_name
+
+
+def get_board_path(candidate: Dict) -> Path:
+    board_path = CONFIG.stub_path / board_folder_name(candidate)
+    if candidate["version"] == "latest" and not board_path.exists():
+        log.debug(f"no board stubs found for {candidate['version']}, trying stable")
+        board_path = CONFIG.stub_path / board_folder_name(candidate, version=CONFIG.stable_version)
+
+    return board_path
+
+
+def get_merged_path(fw: Dict) -> Path:
+    return CONFIG.stub_path / (board_folder_name(fw) + "-merged")

stubber/publish/publish.py

@@ -9,15 +9,16 @@ from loguru import logger as log
 
 from stubber.publish.candidates import board_candidates, filter_list
 from stubber.publish.database import get_database
+from stubber.publish.defaults import GENERIC_U
 from stubber.publish.enums import COMBO_STUBS
-from stubber.publish.package import GENERIC_U, get_package
+from stubber.publish.package import get_package
 from stubber.utils.config import CONFIG
 
 
 def build_multiple(
     family: str = "micropython",
     versions: List[str] = ["v1.19.1"],
-    ports: List[str] = ["auto"],
+    ports: List[str] = ["all"],
     boards: List[str] = [GENERIC_U],
     production: bool = False,
     clean: bool = False,
@@ -46,7 +47,7 @@ def build_multiple(
 def publish_multiple(
     family: str = "micropython",
     versions: List[str] = ["v1.19.1"],
-    ports: List[str] = ["auto"],
+    ports: List[str] = ["all"],
     boards: List[str] = [GENERIC_U],
     production: bool = False,
     clean: bool = False,
@@ -101,6 +102,6 @@ def build_worklist(
     worklist = filter_list(worklist, ports, boards)
 
     for b in boards:
-        if not any(i for i in worklist if i["board"] == b):
+        if not any(i for i in worklist if i["board"].lower() == b.lower()):
             log.warning(f"Could not find any package candidate for board {b}")
     return worklist