micropython-stubber 1.24.2__py3-none-any.whl → 1.24.4.post1__py3-none-any.whl

stubber/commands/get_docstubs_cmd.py

@@ -14,6 +14,8 @@ import stubber.utils as utils
 from mpflash.logger import log
 from stubber.codemod.enrich import enrich_folder
 from stubber.commands.cli import stubber_cli
+from stubber.merge_config import copy_type_modules
+from stubber.modcat import CP_REFERENCE_TO_DOCSTUB
 from stubber.stubs_from_docs import generate_from_rst
 from stubber.utils.config import CONFIG
 from stubber.utils.repos import fetch_repos
@@ -68,6 +70,22 @@ from stubber.utils.repos import fetch_repos
     help="Enrich with type information from reference/micropython",
     show_default=True,
 )
+# @click.option(
+#     "--copy-params",
+#     "copy_params",
+#     default=False,
+#     help="Copy the function/method parameters",
+#     show_default=True,
+#     is_flag=True,
+# )
+# @click.option(
+#     "--copy-docstr",
+#     "copy_docstr",
+#     default=False,
+#     help="Copy the docstrings",
+#     show_default=False,
+#     is_flag=True,
+# )
 @click.pass_context
 def cli_docstubs(
     ctx: click.Context,
@@ -126,9 +144,8 @@ def cli_docstubs(
 
     if enrich:
         if Version(version) < Version("1.24"):
-            log.warning(f"Enriching is not supported for version {version}")
+            log.warning(f"Enriching is only supported for version v1.24+, not {version}")
         else:
-            # !stubber enrich --params-only --source {reference} --dest {docstubs}
             reference_path = CONFIG.stub_path.parent / "reference/micropython"
             _ = enrich_folder(
                 reference_path,
@@ -136,8 +153,10 @@ def cli_docstubs(
                 show_diff=False,
                 write_back=True,
                 require_docstub=False,
-                params_only=True,
+                copy_params=True,
+                copy_docstr=False,
             )
+            copy_type_modules(reference_path, dst_path, CP_REFERENCE_TO_DOCSTUB)
             log.info("::group:: start post processing of retrieved stubs")
             # do not run stubgen
             utils.do_post_processing([dst_path], stubgen=False, black=black, autoflake=autoflake)

stubber/commands/get_frozen_cmd.py

@@ -109,6 +109,7 @@ def cli_get_frozen(
                 show_diff=False,
                 write_back=True,
                 require_docstub=False,
+                copy_docstr=True,
                 ext = ".pyi",
             ):
                 log.info(f" > Enriched {merged} frozen modules.")

stubber/commands/merge_cmd.py

@@ -5,8 +5,8 @@ enrich machinestubs with docstubs
 from typing import List, Union
 
 import rich_click as click
-from mpflash.logger import log
 
+from mpflash.logger import log
 from stubber.commands.cli import stubber_cli
 from stubber.publish.merge_docstubs import merge_all_docstubs
 from stubber.publish.package import GENERIC_L
@@ -60,6 +60,4 @@ def cli_merge_docstubs(
         versions = list(versions)
     # single version should be a string
     log.info(f"Merge docstubs for {family} {versions}")
-    _ = merge_all_docstubs(
-        versions=versions, family=family, boards=boards, ports=ports, mpy_path=CONFIG.mpy_path
-    )
+    _ = merge_all_docstubs(versions=versions, family=family, boards=boards, ports=ports)

stubber/merge_config.py

@@ -1,6 +1,6 @@
 """
 Merge configuration for the stubber.
-defines constants and util functions to copy, update or remove type modules
+util functions to copy, update or remove type modules
 """
 
 import shutil
@@ -8,46 +8,11 @@ from pathlib import Path
 from typing import Final, List
 
 from mpflash.logger import log
-from stubber.rst.lookup import U_MODULES
 
-EXT: Final = [".pyi", ".py", ""]
-CP_REFERENCE_TO_DOCSTUB: Final = [
-    "asyncio",
-    "rp2/PIOASMEmit.pyi",
-    "rp2/asm_pio.pyi",
-]
-"Modules to copy from reference modules to the docstubs"
-
-
-STDLIB_MODULES: Final = [
-    "collections",
-    "io",
-    "builtins",
-    "asyncio",
-    "sys",
-    # "os",  # TODO # Do not remove `os` to allow better typing by mypy for the `os` module
-    # "ssl",  # TODO
-]
-"""Modules that should be in /stdlib"""
-# and should not be in the individual packes as that causes duplication
+from stubber.modcat import (CP_REFERENCE_TO_DOCSTUB, RM_MERGED,
+                            STDLIB_ONLY_MODULES, U_MODULES)
 
-RM_MERGED: Final = (
-    [
-        "sys",  # use auto patched version from mpy_stdlib
-        "asyncio",  # use manually patched version from  mpy_stdlib
-        "_asyncio",  # ditto
-        "uasyncio",  # ditto
-        "_rp2",  # Leave out for now , to avoid conflicts with the rp2 module
-        "pycopy_imphook",  #  pycopy only: not needed in the merged stubs
-        # "os",
-        "types", # defined in webassembly pyscript - shadows stdlib
-        "abc", # defined in webassembly pyscript - shadows stdlib
-        # "uos", # ???? problems with mypy & webassembly stubs 
-    ]
-    + STDLIB_MODULES
-    + [f"u{mod}" for mod in U_MODULES]
-)
-"Modules to remove from merged stubs, U_MODULES will be recreated later"
+EXT: Final = [".pyi", ".py", ""]
 
 
 def copy_type_modules(source_folder: Path, target_folder: Path, CP_REFERENCE_MODULES: List[str]):
@@ -112,3 +77,4 @@ def remove_modules(target_folder: Path, RM_MODULES: List[str]):
                         target.unlink()
                 finally:
                     log.debug(f" - remove {target}")
+

stubber/minify.py

@@ -370,8 +370,8 @@ def cross_compile(
         # target must be a Path object
         _target = get_temp_file(suffix=".mpy")
     result = pipx_mpy_cross(version, source_file, _target)
-    if result.stderr and "No matching distribution found for mpy-cross==" in result.stderr:
-        log.warning(f"mpy-cross=={version} not found, using most current version.")
+    if result.stderr and "No matching distribution found for mpy-cross~=" in result.stderr:
+        log.warning(f"mpy-cross~={version} not found, using most current version.")
         result = pipx_mpy_cross(V_PREVIEW, source_file, _target)
 
     if result.returncode == 0:
@@ -395,7 +395,7 @@ def pipx_mpy_cross(version: str, source_file, _target):
     if version in SET_PREVIEW:
         version = ""
     if version:
-        version = "==" + version
+        version = "~=" + version.lstrip("v")
 
     cmd = ["pipx", "run", f"mpy-cross{version}"] if version else ["pipx", "run", "mpy-cross"]
     # Add params

stubber/modcat.py

@@ -0,0 +1,118 @@
+"""
+Used to define where stub modules should and should not be copied to, or merged to 
+
+This is shared between stubber, and external build scripts.
+"""
+from __future__ import annotations
+
+from typing import Final
+
+from stubber.publish.enums import StubSource
+
+########################################################
+STDLIB_ONLY_MODULES = [
+    "abc",
+    "array",
+    "collections",
+    "io",
+    "builtins",
+    "asyncio",
+    "sys",
+    "types",
+    "ssl",
+    "os", 
+    # Experiment
+    "json",
+    "struct"
+    # "socket", # should be ins tdlib - but is only available on networked boards 
+    # time # should be in stdlib - but has implementation differences per port)
+]
+"""Modules that should only be in stdlib, and not in the individual packages"""
+# and should not be in the individual packes as that causes duplication
+
+
+########################################################
+# stubber.publish.stubpacker                           #
+########################################################
+# Indicates which stubs will NOT be copied from the stub sources
+# and shared with multiple modules and the sdtbli build.py that is in the stubs repo
+STUBS_COPY_FILTER = {
+    StubSource.FROZEN: [
+        "espnow",  # merged stubs + documentation of the espnow module is better than the info in the frozen stubs
+        # "collections",  # must be in stdlib
+        # "types",  # must be in stdlib
+        # "abc",  # must be in stdlib
+        "time",  # used from merged ( should be in stdlib - but has implementation differences per port)
+        # "io",  # must be in stdlib
+    ] + STDLIB_ONLY_MODULES,
+    StubSource.FIRMWARE: [
+        "builtins",
+        # "collections",  # collections must be in stdlib
+    ] + STDLIB_ONLY_MODULES,
+    StubSource.MERGED: STDLIB_ONLY_MODULES,
+}
+
+# these modules will be replaced by a simple import statement to import from stdlib
+STDLIB_UMODULES = ["ucollections"]
+
+########################################################
+# stubber.rst...                                       #
+########################################################
+U_MODULES = [
+    "array",
+    "asyncio",
+    "binascii",
+    "bluetooth",
+    "errno",
+    "io",
+    "json",
+    "machine",
+    "os",
+    "platform",
+    "select",
+    "ssl",
+    "struct",
+    "socket",
+    "sys",
+    "time",
+    "zlib",
+]
+"""
+List of modules that are documented with the base name only, 
+but can also be imported with a `u` prefix
+"""
+
+########################################################
+# stubber.merge_config                                 #
+# defines constants to copy, update, remove type stubs #
+########################################################
+
+CP_REFERENCE_TO_DOCSTUB: Final = [
+    "asyncio", # just for documentation 
+    # stdlib stubs are using the version from stdlib/asyncio
+    "rp2/PIOASMEmit.pyi",
+    "rp2/asm_pio.pyi",
+]
+"Modules to copy from reference modules to the docstubs"
+
+
+
+
+RM_MERGED = (
+    [
+        "sys",  # use auto patched version from mpy_stdlib
+        "asyncio",  # use manually patched version from  mpy_stdlib
+        "_asyncio",  # ditto
+        "uasyncio",  # ditto
+        "_rp2",  # Leave out for now , to avoid conflicts with the rp2 module
+        "pycopy_imphook",  #  pycopy only: not needed in the merged stubs
+        # "os",
+        "types", # defined in webassembly pyscript - shadows stdlib
+        "abc", # defined in webassembly pyscript - shadows stdlib
+        # "uos", # ???? problems with mypy & webassembly stubs 
+    ]
+    + STDLIB_ONLY_MODULES
+    + [f"u{mod}" for mod in U_MODULES]
+)
+"Modules to remove from merged stubs, U_MODULES will be recreated later"
+

stubber/publish/merge_docstubs.py

@@ -20,8 +20,8 @@ def merge_all_docstubs(
     family: str = "micropython",
     ports: Optional[Union[List[str], str]] = None,
     boards: Optional[Union[List[str], str]] = None,
-    *,
-    mpy_path: Path = CONFIG.mpy_path,
+    # *,
+    # mpy_path: Path = CONFIG.mpy_path,
 ):
     """merge docstubs and MCU stubs to merged stubs"""
     if versions is None:
@@ -66,7 +66,19 @@ def merge_all_docstubs(
             continue
         log.info(f"Merge {candidate['version']} docstubs with boardstubs to {merged_path.name}")
         try:
+            # TODO : webassembly: Need to merge from reference/pyscript as well 
             result = copy_and_merge_docstubs(board_path, merged_path, doc_path)
+            if candidate["port"] == "webassembly":
+                # TODO : webassembly: Need to merge from reference/pyscript as well 
+                # use enrich_folder to merge the docstubs
+                enrich_folder(
+                    source_folder=CONFIG.mpy_stubs_path / "reference/pyscript",
+                    target_folder=merged_path,
+                    write_back=True,
+                    copy_params=True,
+                    copy_docstr=True,
+                )
+                pass
         except Exception as e:
             log.error(f"Error parsing {candidate['version']} docstubs: {e}")
             continue
@@ -121,7 +133,13 @@ def copy_and_merge_docstubs(fw_path: Path, dest_path: Path, docstub_path: Path):
     recreate_umodules(dest_path)
 
     # 2 - Enrich the MCU stubs with the document stubs
-    result = enrich_folder(source_folder=docstub_path, target_folder=dest_path, write_back=True)
+    result = enrich_folder(
+        source_folder=docstub_path,
+        target_folder=dest_path,
+        write_back=True,
+        copy_params=True,
+        copy_docstr=True,
+    )
 
     refactor_rp2_module(dest_path)
 

stubber/publish/stubpackage.py

@@ -18,8 +18,8 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
 import tenacity
-
 from mpflash.basicgit import get_git_describe
+
 from stubber.publish.helpers import get_module_docstring
 
 if sys.version_info >= (3, 11):
@@ -30,41 +30,20 @@ else:
 from typing import NewType
 
 import tomli_w
-from packaging.version import Version, parse
-
 from mpflash.logger import log
 from mpflash.versions import SET_PREVIEW, V_PREVIEW, clean_version
+from packaging.version import Version, parse
+
 from stubber.publish.bump import bump_version
 from stubber.publish.defaults import GENERIC_U, default_board
 from stubber.publish.enums import StubSource
 from stubber.publish.pypi import Version, get_pypi_versions
 from stubber.utils.config import CONFIG
+from stubber.modcat import STDLIB_UMODULES, STUBS_COPY_FILTER
 
 Status = NewType("Status", Dict[str, Union[str, None]])
 StubSources = List[Tuple[StubSource, Path]]
 
-# indicates which stubs will not be copyied from the stub sources
-STUBS_COPY_FILTER = {
-    StubSource.FROZEN: [
-        "espnow",  # merged stubs + documentation of the espnow module is better than the info in the frozen stubs
-        "collections",  # must be in stdlib
-        "types",  # must be in stdlib
-        "abc",  # must be in stdlib
-        "time",  # must be in stdlib
-        "io",  # must be in stdlib
-    ],
-    StubSource.FIRMWARE: [
-        "builtins",
-        "collections",  # collections must be in stdlib
-    ],
-    StubSource.MERGED: [
-        "collections",  # collections must be in stdlib
-    ],
-}
-
-# these modules will be replaced by a simple import statement to import from stdlib
-STDLIB_UMODULES = ["ucollections"]
-
 
 class VersionedPackage:
     """
@@ -287,8 +266,12 @@ class Builder(VersionedPackage):
         # make sure parent folder exists
         _toml = self.toml_path
         (_toml).parent.mkdir(parents=True, exist_ok=True)
-        with open(_toml, "wb") as output:
-            tomli_w.dump(pyproject, output)
+        try: 
+            with open(_toml, "wb") as output:
+                tomli_w.dump(pyproject, output)
+        except OSError as e:
+            log.error(e)
+            log.debug(repr(_toml))
 
     # -----------------------------------------------
     def create_update_pyproject_toml(self) -> None:

stubber/rst/lookup.py

@@ -16,7 +16,6 @@ __all__ = [
     "MODULE_GLUE",
     "RST_DOC_FIXES",
     "DOCSTUB_SKIP",
-    "U_MODULES",
 ]
 
 # all possible Types needed for the stubs - excess types should be removed later , and otherwise won't do much harm
@@ -52,25 +51,6 @@ class Fix:
     "the from_ string is a regular expression"
 
 
-U_MODULES = [
-    "array",
-    "asyncio",
-    "binascii",
-    "io",
-    "json",
-    "machine",
-    "os",
-    "select",
-    "ssl",
-    "struct",
-    "socket",
-    "time",
-    "zlib",
-]
-"""
-List of modules that are documented with the base name only, 
-but can also be imported with a `u` prefix
-"""
 
 # This table is used to try to correct the errors in the documentation,
 #  or adapt the human readable documentation to machine readable.
@@ -157,8 +137,8 @@ LOOKUP_LIST = {
     "uio.open": ("IO", 0.95),  #  Open a file.
     "uos.listdir": ("List[Incomplete]", 0.95),
     "os.uname": ("uname_result", 0.95),
-    # undocumented CPython class ssl.SSLSocket
-    # TODO: include  ssl.SSLSocket from stdlib / mpy_typeshed, currently Incomplete
+    # ssl.SSLSocket is defined in reference/micropython/ssl
+    
     "ssl.wrap_socket": ("SSLSocket", 0.95),
     "ussl.wrap_socket": ("SSLSocket", 0.95),
     #
@@ -370,7 +350,7 @@ MODULE_GLUE = {
     "ssl": [
         "from typing_extensions import TypeAlias",
         "from _mpy_shed import StrOrBytesPath",
-        "SSLSocket : TypeAlias = Incomplete",
+        # SSLSocket is part of the refence stubs
     ],
     "struct": ANY_BUF,
     "time": [

stubber/stubs_from_docs.py

@@ -10,7 +10,8 @@ from typing import List, Optional
 from mpflash.logger import log
 
 from stubber import utils
-from stubber.rst import DOCSTUB_SKIP, U_MODULES
+from stubber.rst import DOCSTUB_SKIP
+from stubber.modcat import  U_MODULES
 from stubber.rst.reader import RSTWriter
 
 

stubber/{cst_transformer.py → typing_collector.py}

@@ -44,12 +44,33 @@ MODULE_KEY = ("__module",)
 MOD_DOCSTR_KEY = ("__module_docstring",)
 
 # debug helper
-_m = cst.parse_module("")
+_code = cst.parse_module("").code_for_node
+
+
+def is_property(node: cst.FunctionDef) -> bool:
+    """check if the function is a property"""
+    return any(m.matches(dec, m.Decorator(decorator=m.Name(value="property"))) for dec in node.decorators)
+
+
+# FIXME : this is a clumsy way - but I cant find a working matcher for this
+def is_setter(node: cst.FunctionDef) -> bool:
+    """check if the function is a setter"""
+    return any(d for d in _code(node).split("\n") if d.startswith("@") and d.endswith(".setter"))
+
+
+def is_getter(node: cst.FunctionDef) -> bool:
+    """check if the function is a getter"""
+    return any(d for d in _code(node).split("\n") if d.startswith("@") and d.endswith(".getter"))
+
+
+def is_deleter(node: cst.FunctionDef) -> bool:
+    """check if the function is a deleter"""
+    return any(d for d in _code(node).split("\n") if d.startswith("@") and d.endswith(".deleter"))
 
 
 class StubTypingCollector(cst.CSTVisitor):
     """
-    Collect the function/method and class definitions from the stubs source
+    Collect the function/method and class definitions from ta rich .py or .pyi source
     """
 
     def __init__(self):
@@ -120,11 +141,21 @@ class StubTypingCollector(cst.CSTVisitor):
             def_type="funcdef",
             def_node=node,
         )
-        key = tuple(self.stack)
+        if is_getter(node):
+            extra = ["getter"]
+        elif is_setter(node):
+            extra = ["setter"]
+        elif is_deleter(node):
+            extra = ["deleter"]
+        else:
+            extra = []
+        key = tuple(self.stack + extra)
+
         if not key in self.annotations:
             # store the first function/method signature
             self.annotations[key] = AnnoValue(type_info=ti)
 
+
         if any(m.matches(dec , m.Decorator(decorator=m.Name("overload"))) for dec in node.decorators):
             # and store the overloads
             self.annotations[key].overloads.append(ti)