tooling: Add MicroPython type stubs in typings/ for Pylance resolution.

Author: nedseb

.vscode/settings.json

@@ -2,6 +2,7 @@
     "python.languageServer": "Pylance",
     "python.analysis.typeCheckingMode": "basic",
     "python.analysis.extraPaths": ["lib"],
+    "python.analysis.stubPath": "typings",
     "python.analysis.diagnosticSeverityOverrides": {
         "reportMissingModuleSource": "none",
         "reportWildcardImportFromLibrary": "none",

pyrightconfig.json

@@ -3,6 +3,7 @@
     "pythonPlatform": "All",
     "typeCheckingMode": "basic",
     "extraPaths": ["lib"],
+    "stubPath": "typings",
     "exclude": [
         ".build",
         "node_modules",

typings/__builtins__.pyi

@@ -0,0 +1,28 @@
+"""Allows for type checking of Micropython specific builtins by pyright and pylance.
+"""
+
+from typing import Tuple, TypeVar
+
+Const_T = TypeVar("Const_T", int, float, str, bytes, Tuple)  # constant
+
+def const(expr: Const_T) -> Const_T:
+    """
+    Used to declare that the expression is a constant so that the compiler can
+    optimise it.  The use of this function should be as follows::
+
+     from micropython import const
+
+     CONST_X = const(123)
+     CONST_Y = const(2 * CONST_X + 1)
+
+    Constants declared this way are still accessible as global variables from
+    outside the module they are declared in.  On the other hand, if a constant
+    begins with an underscore then it is hidden, it is not available as a global
+    variable, and does not take up any memory during execution.
+
+    This `const` function is recognised directly by the MicroPython parser and is
+    provided as part of the :mod:`micropython` module mainly so that scripts can be
+    written which run under both CPython and MicroPython, by following the above
+    pattern.
+    """
+    ...

typings/_mpy_shed/IRQs.pyi

@@ -0,0 +1,31 @@
+"""
+IRQ object types, used in the machine, bluetooth, _rp2 and rp2 modules
+
+_IRQ  is a union of the types _IRQ_ESP32, _IRQ_RP2 and _IRQ_PYB 
+to allow the same stubs to support of the different ports of MicroPython.
+
+"""
+
+from typing import Type
+
+from _typeshed import Incomplete
+from typing_extensions import TypeAlias
+
+class _IRQ_ESP32:
+    def trigger(self) -> int: ...
+    # def flags(self) -> int: ...
+
+class _IRQ_RP2:
+    # rp2040
+    # object <irq> is of type irq
+    #   flags -- <function>
+    #   trigger -- <function>
+    def flags(self) -> int: ...
+    def trigger(self) -> int: ...
+
+# pybv11
+# TODO: Not sure what the correct implementation is
+# NoneType
+_IRQ_PYB: TypeAlias = None
+
+_IRQ: TypeAlias = Type[_IRQ_ESP32] | Type[_IRQ_RP2] | Type[_IRQ_PYB] | Incomplete

typings/_mpy_shed/__init__.pyi

@@ -0,0 +1,112 @@
+"""
+MicroPython-stubs base types that are not present in typeshed.
+
+This is a collection of types that are not present in typeshed, but are used in the micropython stubs.
+
+Common cases are:
+- MicroPython implementation is different from CPython, so the types are different.
+- MicroPython has some types that are not present in CPython.
+
+"""
+
+from __future__ import annotations
+
+import abc  # type: ignore - not collections.abc
+import sys
+
+from typing import Final, final
+
+from _typeshed import Incomplete, structseq, AnyStr_co
+from typing_extensions import TypeAlias, TypeVar
+
+from .subscriptable import Subscriptable as Subscriptable
+from .IRQs import _IRQ
+from .neopixelbase import _NeoPixelBase as _NeoPixelBase
+from .blockdevice import (
+    _BlockDeviceProtocol as _BlockDeviceProtocol,
+    _OldAbstractBlockDev,
+    _OldAbstractReadOnlyBlockDev,
+)
+from .buffer_mp import AnyReadableBuf as AnyReadableBuf, AnyWritableBuf as AnyWritableBuf
+
+from .io_mp import (
+    BytesIO as BytesIO,
+    FileIO as FileIO,
+    IncrementalNewlineDecoder as IncrementalNewlineDecoder,
+    StringIO as StringIO,
+    TextIOWrapper as TextIOWrapper,
+    IOBase_mp as IOBase_mp,
+    _BufferedIOBase,
+    _IOBase,
+    _RawIOBase,
+    _TextIOBase,
+    open as open,
+)
+
+from .time_mp import _TimeTuple as _TimeTuple
+from .pathlike import PathLike as PathLike
+
+from .mp_implementation import _mp_implementation as _mp_implementation
+from .mp_available import mp_available as mp_available
+# ------------------
+# copied from _typeshed  os.pyi as os.pyi cannot import from a module with the same name
+GenericAlias = type(list[int])
+
+# ------------------------------------------------------------------------------------
+StrOrBytesPath: TypeAlias = str | bytes | PathLike[str] | PathLike[bytes]
+_StrOrBytesT = TypeVar("_StrOrBytesT", str, bytes)
+
+# ------------------------------------------------------------------------------------
+_AnyPath: TypeAlias = str | bytes | PathLike[str] | PathLike[bytes]
+_FdOrAnyPath: TypeAlias = int | _AnyPath
+
+# ------------------------------------------------------------------------------------
+# HID_Tuple is used in multiple pyb.submodules
+HID_Tuple: TypeAlias = tuple[int, int, int, int, bytes]
+
+#  ------------------------------------------------------------------------------------
+# copied from _typeshed  os.pyi as os.pyi cannot import from a module with the same nam@final
+@final
+class uname_result(structseq[str], tuple[str, str, str, str, str]):
+    if sys.version_info >= (3, 8):
+        __match_args__: Final = ("sysname", "nodename", "release", "version", "machine")
+
+    @property
+    def sysname(self) -> str: ...
+    @property
+    def nodename(self) -> str: ...
+    @property
+    def release(self) -> str: ...
+    @property
+    def version(self) -> str: ...
+    @property
+    def machine(self) -> str: ...
+
+# ------------------------------------------------------------------------------------
+
+###########################
+# HashLib
+
+# manual addition to hashlib.pyi
+
+class _Hash(abc.ABC):
+    """
+    Abstract base class for hashing algorithms that defines methods available in all algorithms.
+    """
+
+    def update(self, data: AnyReadableBuf, /) -> None:
+        """
+        Feed more binary data into hash.
+        """
+
+    def digest(self) -> bytes:
+        """
+        Return hash for all data passed through hash, as a bytes object. After this
+        method is called, more data cannot be fed into the hash any longer.
+        """
+
+    def hexdigest(self) -> str:
+        """
+        This method is NOT implemented. Use ``binascii.hexlify(hash.digest())``
+        to achieve a similar effect.
+        """

typings/_mpy_shed/_collections_abc.pyi

@@ -0,0 +1,98 @@
+import sys
+from abc import abstractmethod
+from types import MappingProxyType
+from typing import AbstractSet as Set  # noqa: Y022,Y038
+from typing import AsyncGenerator as AsyncGenerator
+from typing import AsyncIterable as AsyncIterable
+from typing import AsyncIterator as AsyncIterator
+from typing import Awaitable as Awaitable
+from typing import Callable as Callable
+from typing import Collection as Collection
+from typing import Container as Container
+from typing import Coroutine as Coroutine
+from typing import Generator as Generator
+from typing import Generic
+from typing import Hashable as Hashable
+from typing import ItemsView as ItemsView
+from typing import Iterable as Iterable
+from typing import Iterator as Iterator
+from typing import KeysView as KeysView
+from typing import Mapping as Mapping
+from typing import MappingView as MappingView
+from typing import MutableMapping as MutableMapping
+from typing import MutableSequence as MutableSequence
+from typing import MutableSet as MutableSet
+from typing import Protocol
+from typing import Reversible as Reversible
+from typing import Sequence as Sequence
+from typing import Sized as Sized
+from typing import TypeVar
+from typing import ValuesView as ValuesView
+from typing import final, runtime_checkable
+
+__all__ = [
+    "Awaitable",
+    "Coroutine",
+    "AsyncIterable",
+    "AsyncIterator",
+    "AsyncGenerator",
+    "Hashable",
+    "Iterable",
+    "Iterator",
+    "Generator",
+    "Reversible",
+    "Sized",
+    "Container",
+    "Callable",
+    "Collection",
+    "Set",
+    "MutableSet",
+    "Mapping",
+    "MutableMapping",
+    "MappingView",
+    "KeysView",
+    "ItemsView",
+    "ValuesView",
+    "Sequence",
+    "MutableSequence",
+]
+if sys.version_info < (3, 14):
+    from typing import ByteString as ByteString  # noqa: Y057
+
+    __all__ += ["ByteString"]
+
+if sys.version_info >= (3, 12):
+    __all__ += ["Buffer"]
+
+_KT_co = TypeVar("_KT_co", covariant=True)  # Key type covariant containers.
+_VT_co = TypeVar("_VT_co", covariant=True)  # Value type covariant containers.
+
+@final
+class dict_keys(KeysView[_KT_co], Generic[_KT_co, _VT_co]):  # undocumented
+    def __eq__(self, value: object, /) -> bool: ...
+    if sys.version_info >= (3, 13):
+        def isdisjoint(self, other: Iterable[_KT_co], /) -> bool: ...
+    if sys.version_info >= (3, 10):
+        @property
+        def mapping(self) -> MappingProxyType[_KT_co, _VT_co]: ...
+
+@final
+class dict_values(ValuesView[_VT_co], Generic[_KT_co, _VT_co]):  # undocumented
+    if sys.version_info >= (3, 10):
+        @property
+        def mapping(self) -> MappingProxyType[_KT_co, _VT_co]: ...
+
+@final
+class dict_items(ItemsView[_KT_co, _VT_co]):  # undocumented
+    def __eq__(self, value: object, /) -> bool: ...
+    if sys.version_info >= (3, 13):
+        def isdisjoint(self, other: Iterable[tuple[_KT_co, _VT_co]], /) -> bool: ...
+    if sys.version_info >= (3, 10):
+        @property
+        def mapping(self) -> MappingProxyType[_KT_co, _VT_co]: ...
+
+if sys.version_info >= (3, 12):
+    @runtime_checkable
+    class Buffer(Protocol):
+        @abstractmethod
+        def __buffer__(self, flags: int, /) -> memoryview: ...