micropython-stubber 1.24.0__py3-none-any.whl → 1.24.2__py3-none-any.whl

stubber/codemod/visitors/type_helpers.py

@@ -0,0 +1,182 @@
+"""
+Gather all TypeVar and TypeAlias assignments in a module.
+"""
+
+from typing import List, Sequence, Tuple, Union
+
+import libcst
+import libcst.matchers as m
+from libcst import SimpleStatementLine
+from libcst.codemod._context import CodemodContext
+from libcst.codemod._visitor import ContextAwareTransformer, ContextAwareVisitor
+from libcst.codemod.visitors._add_imports import _skip_first
+from typing_extensions import TypeAlias
+
+from mpflash.logger import log
+
+TypeHelper: TypeAlias = Union[libcst.Assign, libcst.AnnAssign]
+TypeHelpers: TypeAlias = List[TypeHelper]
+Statement: TypeAlias = Union[libcst.SimpleStatementLine, libcst.BaseCompoundStatement]
+
+_mod = libcst.parse_module("")  # Debugging aid : _mod.code_for_node(node)
+_code = _mod.code_for_node  #     Debugging aid : _code(node)
+
+
+def is_TypeAlias(statement) -> bool:
+    "Annotated Assign -  Foo:TypeAlias = ..."
+    if m.matches(statement, m.SimpleStatementLine()):
+        statement = statement.body[0]
+    return m.matches(
+        statement,
+        m.AnnAssign(annotation=m.Annotation(annotation=m.Name(value="TypeAlias"))),
+    )
+
+
+def is_TypeVar(statement):
+    "Assing - Foo = Typevar(...)"
+    if m.matches(statement, m.SimpleStatementLine()):
+        statement = statement.body[0]
+    return m.matches(
+        statement,
+        m.Assign(value=m.Call(func=m.Name(value="TypeVar"))),
+    )
+
+
+def is_ParamSpec(statement):
+    "Assign - Foo = ParamSpec(...)"
+    if m.matches(statement, m.SimpleStatementLine()):
+        statement = statement.body[0]
+    return m.matches(
+        statement,
+        m.Assign(value=m.Call(func=m.Name(value="ParamSpec"))),
+    )
+
+
+def is_import(statement):
+    "import - import foo"
+    return m.matches(statement, m.SimpleStatementLine(body=[m.ImportFrom() | m.Import()]))
+
+
+class GatherTypeHelpers(ContextAwareVisitor):
+    """
+    A class for tracking visited TypeVars and TypeAliases.
+    """
+
+    def __init__(self, context: CodemodContext) -> None:
+        super().__init__(context)
+        # Track all of the TypeVar, TypeAlias and Paramspec assignments found
+        self.all_typehelpers: TypeHelpers = []
+
+    def visit_Assign(self, node: libcst.Assign) -> None:
+        """
+        Find all TypeVar assignments in the module.
+        format: T = TypeVar("T", int, float, str, bytes, Tuple)
+        """
+        # is this a TypeVar assignment?
+        # needs to be more robust
+        if is_TypeVar(node) or is_ParamSpec(node):
+            self.all_typehelpers.append(node)
+
+    def visit_AnnAssign(self, node: libcst.AnnAssign) -> None:
+        """ "
+        Find all TypeAlias assignments in the module.
+        format: T: TypeAlias = str
+        """
+        if is_TypeAlias(node):
+            self.all_typehelpers.append(node)
+
+
+class AddTypeHelpers(ContextAwareTransformer):
+    """
+    Visitor loosly based on AddImportsVisitor
+    """
+
+    CONTEXT_KEY = "AddTypeHelpers"
+
+    def __init__(self, context: CodemodContext) -> None:
+        super().__init__(context)
+        self.new_typehelpers: TypeHelpers = context.scratch.get(self.CONTEXT_KEY, [])
+        self.all_typehelpers: TypeHelpers = []
+
+    @classmethod
+    def add_typevar(cls, context: CodemodContext, node: libcst.Assign):
+        new_typehelpers = context.scratch.get(cls.CONTEXT_KEY, [])
+        new_typehelpers.append(node)
+        context.scratch[cls.CONTEXT_KEY] = new_typehelpers
+        # add the typevar to the module
+
+    def leave_Module(
+        self,
+        original_node: libcst.Module,
+        updated_node: libcst.Module,
+    ) -> libcst.Module:
+        if not self.new_typehelpers:
+            return updated_node
+
+        # split the module into 3 parts
+        # before and after the insertions point , and a list of the TV and TA statements
+        (
+            statements_before,
+            helper_statements,
+            statements_after,
+        ) = self._split_module(original_node, updated_node)
+
+        # simpler to compare as text than to compare the nodes -
+        existing_targets = [
+            helper.body[0].targets[0].target.value  # type: ignore
+            for helper in helper_statements
+            if is_TypeVar(helper) or is_ParamSpec(helper)
+        ] + [
+            helper.body[0].target.value  # type: ignore
+            for helper in helper_statements
+            if is_TypeAlias(helper)
+        ]
+        statements_to_add = []
+        for new_typehelper in self.new_typehelpers:
+            if isinstance(new_typehelper, libcst.AnnAssign):
+                if new_typehelper.target.value not in existing_targets:  # type: ignore
+                    statements_to_add.append(SimpleStatementLine(body=[new_typehelper]))
+            elif isinstance(new_typehelper, libcst.Assign):
+                if new_typehelper.targets[0].target.value not in existing_targets:  # type: ignore
+                    statements_to_add.append(SimpleStatementLine(body=[new_typehelper]))
+
+        body = (
+            *statements_before,
+            *statements_to_add,
+            *statements_after,
+        )
+
+        return updated_node.with_changes(body=body)
+
+    def _split_module(
+        self,
+        orig_module: libcst.Module,
+        updated_module: libcst.Module,
+    ) -> Tuple[Sequence[Statement], Sequence[libcst.SimpleStatementLine], Sequence[Statement]]:
+        """
+        Split the module into 3 parts:
+        - before any TypeAlias, TypeVar or ParamSpec statements
+        - the TypeAlias and TypeVar statements
+        - the rest of the module after the TypeAlias and TypeVar statements
+        """
+        last_import = first_typehelper = last_typehelper = -1
+        start = 0
+        if _skip_first(orig_module):
+            start = 1
+
+        for i, statement in enumerate(orig_module.body[start:]):
+            if is_import(statement):
+                last_import = i + start
+                continue
+            if is_TypeVar(statement) or is_TypeAlias(statement) or is_ParamSpec(statement):
+                if first_typehelper == -1:
+                    first_typehelper = i + start
+                last_typehelper = i + start
+        # insert as high as possible, but after the last import and last TypeVar/TypeAlias statement
+        insert_after = max(start, last_import + 1, last_typehelper + 1)
+        assert insert_after != -1, "insert_after must be != -1"
+        #
+        before = list(updated_module.body[:insert_after])
+        after = list(updated_module.body[insert_after:])
+        helper_statements: Sequence[libcst.SimpleStatementLine] = list(updated_module.body[first_typehelper : last_typehelper + 1])  # type: ignore
+        return (before, helper_statements, after)

stubber/commands/get_docstubs_cmd.py

@@ -5,14 +5,14 @@ get-docstubs
 
 from pathlib import Path
 from typing import Optional
+
+import rich_click as click
 from packaging.version import Version
 
 import mpflash.basicgit as git
-import rich_click as click
+import stubber.utils as utils
 from mpflash.logger import log
-
 from stubber.codemod.enrich import enrich_folder
-import stubber.utils as utils
 from stubber.commands.cli import stubber_cli
 from stubber.stubs_from_docs import generate_from_rst
 from stubber.utils.config import CONFIG
@@ -65,7 +65,7 @@ from stubber.utils.repos import fetch_repos
     "--enrich",
     is_flag=True,
     default=False,
-    help="Enrich with type information from micropython-reference",
+    help="Enrich with type information from reference/micropython",
     show_default=True,
 )
 @click.pass_context
@@ -129,8 +129,7 @@ def cli_docstubs(
             log.warning(f"Enriching is not supported for version {version}")
         else:
             # !stubber enrich --params-only --source {reference} --dest {docstubs}
-            reference_path = CONFIG.stub_path.parent / "micropython-reference"
-            log.info(f"Enriching from {reference_path}")
+            reference_path = CONFIG.stub_path.parent / "reference/micropython"
             _ = enrich_folder(
                 reference_path,
                 dst_path,

stubber/cst_transformer.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
 
 import libcst as cst
+from libcst import matchers as m
 
 
 @dataclass
@@ -124,7 +125,7 @@ class StubTypingCollector(cst.CSTVisitor):
             # store the first function/method signature
             self.annotations[key] = AnnoValue(type_info=ti)
 
-        if any(dec.decorator.value == "overload" for dec in node.decorators):  # type: ignore
+        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)
 

stubber/merge_config.py

@@ -40,6 +40,9 @@ RM_MERGED: Final = (
         "_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]

stubber/publish/merge_docstubs.py

@@ -7,7 +7,6 @@ from pathlib import Path
 from typing import List, Optional, Union
 
 from mpflash.logger import log
-
 from stubber.codemod.enrich import enrich_folder
 from stubber.merge_config import RM_MERGED, recreate_umodules, remove_modules
 from stubber.publish.candidates import board_candidates, filter_list
@@ -147,7 +146,7 @@ def refactor_rp2_module(dest_path: Path):
         rp2_file.rename(rp2_folder / "__init__.pyi")
     # copy the asm_pio.pyi file from the reference folder
     for submod in ["rp2/asm_pio.pyi"]:
-        file = CONFIG.mpy_stubs_path / "micropython-reference" / submod
+        file = CONFIG.mpy_stubs_path / "reference/micropython" / submod
         if file.exists():
             shutil.copy(file, rp2_folder / file.name)
             log.info(f" - add rp2/{ file.name}")

stubber/publish/stubpackage.py

@@ -1,4 +1,12 @@
-"""Create a stub-only package for a specific version of micropython"""
+"""
+Create a stub-only package for a specific 
+- version 
+- port 
+- board 
+of micropython
+
+
+"""
 
 import hashlib
 import json
@@ -10,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 mpflash.basicgit import get_git_describe
 from stubber.publish.helpers import get_module_docstring
 
 if sys.version_info >= (3, 11):
@@ -22,10 +30,10 @@ else:
 from typing import NewType
 
 import tomli_w
-from mpflash.logger import log
-from mpflash.versions import SET_PREVIEW, V_PREVIEW, clean_version
 from packaging.version import Version, parse
 
+from mpflash.logger import log
+from mpflash.versions import SET_PREVIEW, V_PREVIEW, clean_version
 from stubber.publish.bump import bump_version
 from stubber.publish.defaults import GENERIC_U, default_board
 from stubber.publish.enums import StubSource
@@ -35,10 +43,15 @@ from stubber.utils.config import CONFIG
 Status = NewType("Status", Dict[str, Union[str, None]])
 StubSources = List[Tuple[StubSource, Path]]
 
-# indicates which stubs will be skipped when copying for these stub sources
+# 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 forzen stubs
+        "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",
@@ -359,10 +372,14 @@ class Builder(VersionedPackage):
 
     def copy_folder(self, stub_type: StubSource, src_path: Path):
         Path(self.package_path).mkdir(parents=True, exist_ok=True)
-        for item in (CONFIG.stub_path / src_path).rglob("*"):
+        for item in (CONFIG.stub_path / src_path).rglob("*.pyi"):
             if item.is_file():
                 # filter the 'poorly' decorated files
-                if stub_type in STUBS_COPY_FILTER and item.stem in STUBS_COPY_FILTER[stub_type]:
+                if stub_type in STUBS_COPY_FILTER and (
+                        item.stem in STUBS_COPY_FILTER[stub_type] or 
+                        item.parent.name in STUBS_COPY_FILTER[stub_type]
+                    ):
+                    log.trace(f"Skipping {item.name}")
                     continue
 
                 target = Path(self.package_path) / item.relative_to(CONFIG.stub_path / src_path)
@@ -631,8 +648,10 @@ class PoetryBuilder(Builder):
         try:
             with open(_toml, "rb") as f:
                 pyproject = tomllib.load(f)
-            # pyproject["tool"]["poetry"]["version"] = version
-            pyproject["project"]["version"] = version
+            if "project"  in pyproject:
+                pyproject["project"]["version"] = version
+            else:
+                pyproject["tool"]["poetry"]["version"] = version
             # update the version in the toml file
             with open(_toml, "wb") as output:
                 tomli_w.dump(pyproject, output)
@@ -742,10 +761,13 @@ class PoetryBuilder(Builder):
                 raise (e)
 
         # update the name , version and description of the package
-        # _pyproject["tool"]["poetry"]["name"] = self.package_name
-        # _pyproject["tool"]["poetry"]["description"] = self.description
-        _pyproject["project"]["name"] = self.package_name
-        _pyproject["project"]["description"] = self.description
+        if 'project' in _pyproject:
+            _pyproject["project"]["name"] = self.package_name
+            _pyproject["project"]["description"] = self.description
+        else: 
+            _pyproject["tool"]["poetry"]["name"] = self.package_name
+            _pyproject["tool"]["poetry"]["description"] = self.description
+
         # write out the pyproject.toml file
         self.pyproject = _pyproject
 

stubber/rst/lookup.py

@@ -101,6 +101,9 @@ RST_DOC_FIXES: List[Tuple[str, str]] = [
         ".. method:: AIOESPNow._aiter__() / async AIOESPNow.__anext__()",
         ".. method:: AIOESPNow._aiter__()\n            async AIOESPNow.__anext__()",
     ),
+    # appended to in ssl.constant name  - ssl.PROTOCOL_DTLS_CLIENT(when DTLS support is enabled)
+    # Ugly hack to fix the documentation
+    ( '(when DTLS support is enabled)', " : Incomplete # (when DTLS support is enabled)")
 ]
 
 

stubber/rst/reader.py

@@ -69,19 +69,10 @@ from typing import List, Optional, Tuple
 
 from mpflash.logger import log
 from mpflash.versions import V_PREVIEW
-
-from stubber.rst import (
-    CHILD_PARENT_CLASS,
-    MODULE_GLUE,
-    PARAM_FIXES,
-    PARAM_RE_FIXES,
-    RST_DOC_FIXES,
-    TYPING_IMPORT,
-    ClassSourceDict,
-    FunctionSourceDict,
-    ModuleSourceDict,
-    return_type_from_context,
-)
+from stubber.rst import (CHILD_PARENT_CLASS, MODULE_GLUE, PARAM_FIXES,
+                         PARAM_RE_FIXES, RST_DOC_FIXES, TYPING_IMPORT,
+                         ClassSourceDict, FunctionSourceDict, ModuleSourceDict,
+                         return_type_from_context)
 from stubber.rst.lookup import Fix
 from stubber.utils.config import CONFIG
 
@@ -782,6 +773,10 @@ class RSTParser(RSTReader):
         self.line_no += counter - 1
         # clean up before returning
         names = [n.strip() for n in names if n.strip() != "etc."]  # remove etc.
+        # Ugly one-off hack 
+        # to remove the '(when DTLS support is enabled)' from the ssl constants
+        # names = [n.replace('(when DTLS support is enabled)', '') for n in names]  
+        
         return names
 
     def parse_data(self):

stubber/tools/manifestfile.py

@@ -29,6 +29,7 @@ from __future__ import print_function
 import contextlib
 import os
 import sys
+import glob
 import tempfile
 from collections import namedtuple
 
@@ -400,7 +401,7 @@ class ManifestFile:
                 self._metadata.pop()
 
     def _require_from_path(self, library_path, name, version, extra_kwargs):
-        for root, dirnames, filenames in os.walk(library_path): # type: ignore
+        for root, dirnames, filenames in os.walk(library_path):
             if os.path.basename(root) == name and "manifest.py" in filenames:
                 self.include(root, is_require=True, **extra_kwargs)
                 return True

stubber/codemod/visitors/typevars.py

@@ -1,200 +0,0 @@
-"""
-Gather all TypeVar and TypeAlias assignments in a module.
-"""
-
-from typing import List, Tuple, Union
-
-import libcst
-import libcst.matchers as m
-from libcst import SimpleStatementLine
-from libcst.codemod._context import CodemodContext
-from libcst.codemod._visitor import ContextAwareTransformer, ContextAwareVisitor
-from libcst.codemod.visitors._add_imports import _skip_first
-from mpflash.logger import log
-
-_mod = libcst.parse_module("")  # Debugging aid : _mod.code_for_node(node)
-_code = _mod.code_for_node  # Debugging aid : _code(node)
-
-
-class GatherTypeVarsVisitor(ContextAwareVisitor):
-    """
-    A class for tracking visited TypeVars and TypeAliases.
-    """
-
-    def __init__(self, context: CodemodContext) -> None:
-        super().__init__(context)
-        # Track all of the TypeVar assignments found in this transform
-        self.all_typealias_or_vars: List[Union[libcst.Assign, libcst.AnnAssign]] = []
-
-    def visit_Assign(self, node: libcst.Assign) -> None:
-        """
-        Find all TypeVar assignments in the module.
-        format: T = TypeVar("T", int, float, str, bytes, Tuple)
-        """
-        # is this a TypeVar assignment?
-        # needs to be more robust
-        if isinstance(node.value, libcst.Call) and node.value.func.value == "TypeVar":  # type: ignore
-            self.all_typealias_or_vars.append(node)
-
-    def visit_AnnAssign(self, node: libcst.AnnAssign) -> None:
-        """ "
-        Find all TypeAlias assignments in the module.
-        format: T: TypeAlias = str
-        """
-        if (
-            isinstance(node.annotation.annotation, libcst.Name)
-            and node.annotation.annotation.value == "TypeAlias"
-        ):
-            self.all_typealias_or_vars.append(node)
-
-
-def is_TypeAlias(statement) -> bool:
-    "Just the body of a simple statement" ""
-    return m.matches(
-        statement,
-        m.AnnAssign(annotation=m.Annotation(annotation=m.Name(value="TypeAlias"))),
-    )
-
-
-def is_TypeVar(statement):
-    "Just the body of a simple statement" ""
-    r = m.matches(
-        statement,
-        m.Assign(value=m.Call(func=m.Name(value="TypeVar"))),
-    )
-    # m.SimpleStatementLine(body=[m.Assign(value=m.Call(func=m.Name(value="TypeVar")))]),
-    return r
-
-
-class AddTypeVarsVisitor(ContextAwareTransformer):
-    """
-    Visitor loosly based on AddImportsVisitor
-    """
-
-    CONTEXT_KEY = "AddTypeVarsVisitor"
-
-    def __init__(self, context: CodemodContext) -> None:
-        super().__init__(context)
-        self.new_typealias_or_vars: List[Union[libcst.Assign, libcst.AnnAssign]] = (
-            context.scratch.get(self.CONTEXT_KEY, [])
-        )
-
-        self.all_typealias_or_vars: List[Union[libcst.Assign, libcst.AnnAssign]] = []
-
-    @classmethod
-    def add_typevar(cls, context: CodemodContext, node: libcst.Assign):
-        new_typealias_or_vars = context.scratch.get(cls.CONTEXT_KEY, [])
-        new_typealias_or_vars.append(node)
-        context.scratch[cls.CONTEXT_KEY] = new_typealias_or_vars
-        # add the typevar to the module
-
-    def leave_Module(
-        self,
-        original_node: libcst.Module,
-        updated_node: libcst.Module,
-    ) -> libcst.Module:
-
-        if not self.new_typealias_or_vars:
-            return updated_node
-
-        # split the module into 3 parts
-        # before and after the insertions point , and a list of the TV and TA statements
-        (
-            statements_before,
-            statements_after,
-            tv_ta_statements,
-        ) = self._split_module(original_node, updated_node)
-
-        # TODO: avoid duplication of TypeVars and TypeAliases
-        statements_to_add = []
-        for new_tvta in self.new_typealias_or_vars:
-            existing = False
-            for existing_line in tv_ta_statements:
-                try:
-                    existing_tv = existing_line.body[0]  # type: ignore
-                except (TypeError, IndexError):
-                    # catch 'SimpleStatementLine' object is not subscriptable when the statement is not a simple statement
-                    log.error("TypeVar or TypeAlias statement is not a simple statement")
-                    continue
-
-                # same type and same target?
-                if (
-                    is_TypeAlias(new_tvta)
-                    and is_TypeAlias(existing_tv)
-                    and new_tvta.target.value == existing_tv.target.value  # type: ignore
-                ):
-                    existing = True
-                    break
-
-                # same type and same targets?
-                if (
-                    is_TypeVar(new_tvta)
-                    and is_TypeVar(existing_tv)
-                    and new_tvta.targets[0].children[0].value == existing_tv.targets[0].children[0].value  # type: ignore
-                ):
-                    existing = True
-                    break
-
-            if not existing:
-                statements_to_add.append(SimpleStatementLine(body=[new_tvta]))
-
-        body = (
-            *statements_before,
-            *statements_to_add,
-            *statements_after,
-        )
-
-        return updated_node.with_changes(body=body)
-
-    def _split_module(
-        self,
-        orig_module: libcst.Module,
-        updated_module: libcst.Module,
-    ) -> Tuple[
-        List[Union[libcst.SimpleStatementLine, libcst.BaseCompoundStatement]],
-        List[Union[libcst.SimpleStatementLine, libcst.BaseCompoundStatement]],
-        List[Union[libcst.SimpleStatementLine, libcst.BaseCompoundStatement]],
-    ]:
-        """
-        Split the module into 3 parts:
-        - before any TypeAlias or TypeVar statements
-        - the TypeAlias and TypeVar statements
-        - the rest of the module after the TypeAlias and TypeVar statements
-        """
-        last_import = first_tv_ta = last_tv_ta = -1
-        start = 0
-        if _skip_first(orig_module):
-            start = 1
-
-        for i, statement in enumerate(orig_module.body[start:]):
-            # todo: optimize to avoid multiple parses
-            is_imp = m.matches(
-                statement, m.SimpleStatementLine(body=[m.ImportFrom() | m.Import()])
-            )
-            if is_imp:
-                last_import = i + start
-            is_ta = m.matches(
-                statement,
-                m.SimpleStatementLine(
-                    body=[
-                        m.AnnAssign(annotation=m.Annotation(annotation=m.Name(value="TypeAlias")))
-                    ]
-                ),
-            )
-            is_tv = m.matches(
-                statement,
-                m.SimpleStatementLine(body=[m.Assign(value=m.Call(func=m.Name(value="TypeVar")))]),
-            )
-            if is_tv or is_ta:
-                if first_tv_ta == -1:
-                    first_tv_ta = i + start
-                last_tv_ta = i + start
-        # insert as high as possible, but after the last import and last TypeVar/TypeAlias statement
-        insert_after = max(start, last_import + 1, last_tv_ta + 1)
-        assert insert_after != -1, "insert_after must be != -1"
-        #
-        first = list(updated_module.body[:insert_after])
-        last = list(updated_module.body[insert_after:])
-        ta_statements = list(updated_module.body[first_tv_ta : last_tv_ta + 1])
-
-        return (first, last, ta_statements)