tooling: Override typeshed stdlib stubs with MicroPython versions.

Author: nedseb

pyrightconfig.json

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

typings/stdlib/binascii.pyi

@@ -0,0 +1,61 @@
+"""
+Binary/ASCII conversions.
+
+MicroPython module: https://docs.micropython.org/en/v1.27.0/library/binascii.html
+
+CPython module: :mod:`python:binascii` https://docs.python.org/3/library/binascii.html .
+
+This module implements conversions between binary data and various
+encodings of it in ASCII form (in both directions).
+
+---
+Module: 'binascii' on micropython-v1.27.0-stm32-PYBV11-NETWORK
+"""
+
+# MCU: {'variant': 'NETWORK', 'build': '', 'arch': 'armv7emsp', 'port': 'stm32', 'board': 'PYBV11', 'board_id': 'PYBV11-NETWORK', 'mpy': 'v6.3', 'ver': '1.27.0', 'family': 'micropython', 'cpu': 'STM32F405RG', 'version': '1.27.0'}
+# Stubber: v1.26.4
+from __future__ import annotations
+from _typeshed import Incomplete
+from typing import Any, Optional
+from typing_extensions import Awaitable, TypeAlias, TypeVar
+
+def crc32(data, value: Optional[Any] = None) -> Incomplete:
+    """
+    Compute CRC-32, the 32-bit checksum of *data*, starting with an initial CRC
+    of *value*. The default initial CRC is zero. The algorithm is consistent
+    with the ZIP file checksum.
+    """
+    ...
+
+def hexlify(data: bytes, sep: str | bytes = ..., /) -> bytes:
+    """
+    Convert the bytes in the *data* object to a hexadecimal representation.
+    Returns a bytes object.
+
+    If the additional argument *sep* is supplied it is used as a separator
+    between hexadecimal values.
+    """
+    ...
+
+def unhexlify(data: str | bytes, /) -> bytes:
+    """
+    Convert hexadecimal data to binary representation. Returns bytes string.
+    (i.e. inverse of hexlify)
+    """
+    ...
+
+def b2a_base64(data: bytes, /) -> bytes:
+    """
+    Encode binary data in base64 format, as in `RFC 3548
+    <https://tools.ietf.org/html/rfc3548.html>`_. Returns the encoded data
+    followed by a newline character if newline is true, as a bytes object.
+    """
+    ...
+
+def a2b_base64(data: str | bytes, /) -> bytes:
+    """
+    Decode base64-encoded data, ignoring invalid characters in the input.
+    Conforms to `RFC 2045 s.6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_.
+    Returns a bytes object.
+    """
+    ...

typings/stdlib/cmath.pyi

@@ -0,0 +1,84 @@
+"""
+Mathematical functions for complex numbers.
+
+MicroPython module: https://docs.micropython.org/en/v1.27.0/library/cmath.html
+
+CPython module: :mod:`python:cmath` https://docs.python.org/3/library/cmath.html .
+
+The ``cmath`` module provides some basic mathematical functions for
+working with complex numbers.
+
+Availability: not available on WiPy and ESP8266. Floating point support
+required for this module.
+
+---
+Module: 'cmath' on micropython-v1.27.0-stm32-PYBV11-NETWORK
+"""
+
+# MCU: {'variant': 'NETWORK', 'build': '', 'arch': 'armv7emsp', 'port': 'stm32', 'board': 'PYBV11', 'board_id': 'PYBV11-NETWORK', 'mpy': 'v6.3', 'ver': '1.27.0', 'family': 'micropython', 'cpu': 'STM32F405RG', 'version': '1.27.0'}
+# Stubber: v1.26.4
+from __future__ import annotations
+from _typeshed import Incomplete
+from typing import SupportsComplex, SupportsFloat, SupportsIndex, Tuple
+from typing_extensions import Awaitable, TypeAlias, TypeVar
+
+_C: TypeAlias = SupportsFloat | SupportsComplex | SupportsIndex | complex
+
+e: float = 2.7182818
+"""base of the natural logarithm"""
+pi: float = 3.1415928
+"""the ratio of a circle's circumference to its diameter"""
+
+def polar(z: _C, /) -> Tuple:
+    """
+    Returns, as a tuple, the polar form of ``z``.
+    """
+    ...
+
+def sqrt(z: _C, /) -> complex:
+    """
+    Return the square-root of ``z``.
+    """
+    ...
+
+def rect(r: float, phi: float, /) -> float:
+    """
+    Returns the complex number with modulus ``r`` and phase ``phi``.
+    """
+    ...
+
+def sin(z: _C, /) -> float:
+    """
+    Return the sine of ``z``.
+    """
+    ...
+
+def exp(z: _C, /) -> float:
+    """
+    Return the exponential of ``z``.
+    """
+    ...
+
+def cos(z: _C, /) -> float:
+    """
+    Return the cosine of ``z``.
+    """
+    ...
+
+def phase(z: _C, /) -> float:
+    """
+    Returns the phase of the number ``z``, in the range (-pi, +pi].
+    """
+    ...
+
+def log(z: _C, /) -> float:
+    """
+    Return the natural logarithm of ``z``.  The branch cut is along the negative real axis.
+    """
+    ...
+
+def log10(z: _C, /) -> float:
+    """
+    Return the base-10 logarithm of ``z``.  The branch cut is along the negative real axis.
+    """
+    ...

typings/stdlib/errno.pyi

@@ -0,0 +1,97 @@
+"""
+System error codes.
+
+MicroPython module: https://docs.micropython.org/en/v1.27.0/library/errno.html
+
+CPython module: :mod:`python:errno` https://docs.python.org/3/library/errno.html .
+
+This module provides access to symbolic error codes for `OSError` exception.
+A particular inventory of codes depends on :term:`MicroPython port`.
+
+---
+Module: 'errno' on micropython-v1.27.0-stm32-PYBV11-NETWORK
+"""
+
+# MCU: {'variant': 'NETWORK', 'build': '', 'arch': 'armv7emsp', 'port': 'stm32', 'board': 'PYBV11', 'board_id': 'PYBV11-NETWORK', 'mpy': 'v6.3', 'ver': '1.27.0', 'family': 'micropython', 'cpu': 'STM32F405RG', 'version': '1.27.0'}
+# Stubber: v1.26.4
+from __future__ import annotations
+from typing import Dict, Final
+from _typeshed import Incomplete
+from typing_extensions import Awaitable, TypeAlias, TypeVar
+
+ENOBUFS: Final[int] = 105
+"""No buffer space available"""
+ENODEV: Final[int] = 19
+"""No such device"""
+ENOENT: Final[int] = 2
+"""No such file or directory"""
+EISDIR: Final[int] = 21
+"""Is a directory"""
+EIO: Final[int] = 5
+"""I/O error"""
+EINVAL: Final[int] = 22
+"""Invalid argument"""
+EPERM: Final[int] = 1
+"""Operation not permitted"""
+ETIMEDOUT: Final[int] = 110
+"""Connection timed out"""
+ENOMEM: Final[int] = 12
+"""Out of memory"""
+EOPNOTSUPP: Final[int] = 95
+"""Operation not supported"""
+ENOTCONN: Final[int] = 107
+"""Transport endpoint is not connected"""
+errorcode: dict = {}
+"""\
+Dictionary mapping numeric error codes to strings with symbolic error
+code (see above)::
+
+>>> print(errno.errorcode[errno.EEXIST])
+EEXIST
+"""
+EAGAIN: Final[int] = 11
+"""\
+Error codes, based on ANSI C/POSIX standard. All error codes start with
+"E". As mentioned above, inventory of the codes depends on
+:term:`MicroPython port`. Errors are usually accessible as ``exc.errno``
+where ``exc`` is an instance of `OSError`. Usage example::
+
+try:
+os.mkdir("my_dir")
+except OSError as exc:
+if exc.errno == errno.EEXIST:
+print("Directory already exists")
+"""
+EALREADY: Final[int] = 114
+"""Operation already in progress"""
+EBADF: Final[int] = 9
+"""Bad file descriptor"""
+EADDRINUSE: Final[int] = 98
+"""Address already in use"""
+EACCES: Final[int] = 13
+"""Permission denied"""
+EINPROGRESS: Final[int] = 115
+"""Operation now in progress"""
+EEXIST: Final[int] = 17
+"""\
+Error codes, based on ANSI C/POSIX standard. All error codes start with
+"E". As mentioned above, inventory of the codes depends on
+:term:`MicroPython port`. Errors are usually accessible as ``exc.errno``
+where ``exc`` is an instance of `OSError`. Usage example::
+
+try:
+os.mkdir("my_dir")
+except OSError as exc:
+if exc.errno == errno.EEXIST:
+print("Directory already exists")
+"""
+EHOSTUNREACH: Final[int] = 113
+"""Host is unreachable"""
+ECONNABORTED: Final[int] = 103
+"""Connection aborted"""
+ECONNRESET: Final[int] = 104
+"""Connection reset by peer"""
+ECONNREFUSED: Final[int] = 111
+"""Connection refused"""
+ENOTSUP: Final[int] = ...
+"""Operation not supported"""

typings/stdlib/gc.pyi

@@ -0,0 +1,112 @@
+"""
+Control the garbage collector.
+
+MicroPython module: https://docs.micropython.org/en/v1.27.0/library/gc.html
+
+CPython module: :mod:`python:gc` https://docs.python.org/3/library/gc.html .
+
+---
+Module: 'gc' on micropython-v1.27.0-stm32-PYBV11-NETWORK
+"""
+
+# MCU: {'variant': 'NETWORK', 'build': '', 'arch': 'armv7emsp', 'port': 'stm32', 'board': 'PYBV11', 'board_id': 'PYBV11-NETWORK', 'mpy': 'v6.3', 'ver': '1.27.0', 'family': 'micropython', 'cpu': 'STM32F405RG', 'version': '1.27.0'}
+# Stubber: v1.26.4
+from __future__ import annotations
+from _typeshed import Incomplete
+from typing import overload
+from typing_extensions import Awaitable, TypeAlias, TypeVar
+
+def mem_alloc() -> int:
+    """
+    Return the number of bytes of heap RAM that are allocated by Python code.
+
+    Admonition:Difference to CPython
+       :class: attention
+
+       This function is MicroPython extension.
+    """
+    ...
+
+def isenabled(*args, **kwargs) -> Incomplete: ...
+def mem_free() -> int:
+    """
+    Return the number of bytes of heap RAM that is available for Python
+    code to allocate, or -1 if this amount is not known.
+
+    Admonition:Difference to CPython
+       :class: attention
+
+       This function is MicroPython extension.
+    """
+    ...
+
+@overload
+def threshold() -> int:
+    """
+    Set or query the additional GC allocation threshold. Normally, a collection
+    is triggered only when a new allocation cannot be satisfied, i.e. on an
+    out-of-memory (OOM) condition. If this function is called, in addition to
+    OOM, a collection will be triggered each time after *amount* bytes have been
+    allocated (in total, since the previous time such an amount of bytes
+    have been allocated). *amount* is usually specified as less than the
+    full heap size, with the intention to trigger a collection earlier than when the
+    heap becomes exhausted, and in the hope that an early collection will prevent
+    excessive memory fragmentation. This is a heuristic measure, the effect
+    of which will vary from application to application, as well as
+    the optimal value of the *amount* parameter.
+
+    Calling the function without argument will return the current value of
+    the threshold. A value of -1 means a disabled allocation threshold.
+
+    Admonition:Difference to CPython
+       :class: attention
+
+       This function is a MicroPython extension. CPython has a similar
+       function - ``set_threshold()``, but due to different GC
+       implementations, its signature and semantics are different.
+    """
+
+@overload
+def threshold(amount: int) -> None:
+    """
+    Set or query the additional GC allocation threshold. Normally, a collection
+    is triggered only when a new allocation cannot be satisfied, i.e. on an
+    out-of-memory (OOM) condition. If this function is called, in addition to
+    OOM, a collection will be triggered each time after *amount* bytes have been
+    allocated (in total, since the previous time such an amount of bytes
+    have been allocated). *amount* is usually specified as less than the
+    full heap size, with the intention to trigger a collection earlier than when the
+    heap becomes exhausted, and in the hope that an early collection will prevent
+    excessive memory fragmentation. This is a heuristic measure, the effect
+    of which will vary from application to application, as well as
+    the optimal value of the *amount* parameter.
+
+    Calling the function without argument will return the current value of
+    the threshold. A value of -1 means a disabled allocation threshold.
+
+    Admonition:Difference to CPython
+       :class: attention
+
+       This function is a MicroPython extension. CPython has a similar
+       function - ``set_threshold()``, but due to different GC
+       implementations, its signature and semantics are different.
+    """
+
+def collect() -> None:
+    """
+    Run a garbage collection.
+    """
+    ...
+
+def enable() -> None:
+    """
+    Enable automatic garbage collection.
+    """
+    ...
+
+def disable() -> None:
+    """
+    Disable automatic garbage collection.  Heap memory can still be allocated,
+    and garbage collection can still be initiated manually using :meth:`gc.collect`.
+    """
+    ...