Merge pull request #8508 from dhalbert/v1.21-merge

V1.21 merge

Author: tannewt

.git-blame-ignore-revs

@@ -1,3 +1,9 @@
+# all: Fix various spelling mistakes found by codespell 2.2.6.
+cf490a70917a1b2d38ba9b58e763e0837d0f7ca7
+
+# all: Fix spelling mistakes based on codespell check.
+b1229efbd1509654dec6053865ab828d769e29db
+
 # top: Update Python formatting to black "2023 stable style".
 8b2748269244304854b3462cb8902952b4dcb892
 

.github/workflows/run-tests.yml

@@ -57,11 +57,10 @@ jobs:
       run: |
         make -C examples/natmod/features1
         make -C examples/natmod/features2
-        make -C examples/natmod/uheapq
-        make -C examples/natmod/urandom
-        make -C examples/natmod/ure
-        make -C examples/natmod/uzlib
+        make -C examples/natmod/heapq
+        make -C examples/natmod/random
+        make -C examples/natmod/re
     - name: Test native modules
       if: matrix.test == 'all'
-      run: ./run-natmodtests.py extmod/{uheapq*,ure*,uzlib*}.py
+      run: ./run-natmodtests.py extmod/{heapq*,re*,zlib*}.py
       working-directory: tests

docs/library/gc.rst

@@ -24,7 +24,7 @@ Functions
 
 .. function:: mem_alloc()
 
-   Return the number of bytes of heap RAM that are allocated.
+   Return the number of bytes of heap RAM that are allocated by Python code.
 
    .. admonition:: Difference to CPython
       :class: attention
@@ -33,8 +33,8 @@ Functions
 
 .. function:: mem_free()
 
-   Return the number of bytes of available heap RAM, or -1 if this amount
-   is not known.
+   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

docs/library/index.rst

@@ -17,7 +17,7 @@ limited flash memory:
 ``binascii``, ``errno``, ``json``, ``re``.
 
 These libraries are not currently enabled in any CircuitPython build, but may be in the future:
-``ctypes``
+``ctypes``, ``platform``
 
 .. toctree::
    :maxdepth: 1
@@ -31,6 +31,7 @@ These libraries are not currently enabled in any CircuitPython build, but may be
    gc.rst
    io.rst
    json.rst
+   platform.rst
    re.rst
    sys.rst
    ctypes.rst

docs/library/platform.rst

@@ -0,0 +1,38 @@
+:mod:`platform` -- access to underlying platform’s identifying data
+===================================================================
+
+.. module:: platform
+   :synopsis: access to underlying platform’s identifying data
+
+|see_cpython_module| :mod:`python:platform`.
+
+This module tries to retrieve as much platform-identifying data as possible. It
+makes this information available via function APIs.
+
+Functions
+---------
+
+.. function:: platform()
+
+   Returns a string identifying the underlying platform. This string is composed
+   of several substrings in the following order, delimited by dashes (``-``):
+
+   - the name of the platform system (e.g. Unix, Windows or MicroPython)
+   - the MicroPython version
+   - the architecture of the platform
+   - the version of the underlying platform
+   - the concatenation of the name of the libc that MicroPython is linked to
+     and its corresponding version.
+
+   For example, this could be
+   ``"MicroPython-1.20.0-xtensa-IDFv4.2.4-with-newlib3.0.0"``.
+
+.. function:: python_compiler()
+
+   Returns a string identifying the compiler used for compiling MicroPython.
+
+.. function:: libc_ver()
+
+   Returns a tuple of strings *(lib, version)*, where *lib* is the name of the
+   libc that MicroPython is linked to, and *version* the corresponding version
+   of this libc.

docs/library/sys.rst

@@ -33,6 +33,7 @@ Constants
 
    * *name* - string "circuitpython"
    * *version* - tuple (major, minor, micro), e.g. (1, 7, 0)
+   * *_machine* - string describing the underlying machine
    * *_mpy* - supported mpy file-format version (optional attribute)
 
    This object is the recommended way to distinguish CircuitPython from other

docs/reference/glossary.rst

@@ -32,7 +32,7 @@ Glossary
 
     callee-owned tuple
         This is a MicroPython-specific construct where, for efficiency
-        reasons, some built-in functions or methods may re-use the same
+        reasons, some built-in functions or methods may reuse the same
         underlying tuple object to return data. This avoids having to allocate
         a new tuple for every call, and reduces heap fragmentation. Programs
         should not hold references to callee-owned tuples and instead only
@@ -120,7 +120,7 @@ Glossary
         <https://github.com/micropython/micropython-lib>`_ which provides
         implementations for many modules from CPython's standard library.
 
-        Some of the modules are are implemented in pure Python, and are able to
+        Some of the modules are implemented in pure Python, and are able to
         be used on all ports. However, the majority of these modules use
         :term:`FFI` to access operating system functionality, and as such can
         only be used on the :term:`MicroPython Unix port` (with limited support

docs/shared_bindings_matrix.py

@@ -63,7 +63,7 @@
 }
 
 ADDITIONAL_MODULES = {
-    "_asyncio": "MICROPY_PY_UASYNCIO",
+    "_asyncio": "MICROPY_PY_ASYNCIO",
     "adafruit_bus_device": "CIRCUITPY_BUSDEVICE",
     "adafruit_pixelbuf": "CIRCUITPY_PIXELBUF",
     "array": "CIRCUITPY_ARRAY",
@@ -79,7 +79,7 @@
     "keypad.Keys": "CIRCUITPY_KEYPAD_KEYS",
     "keypad.ShiftRegisterKeys": "CIRCUITPY_KEYPAD_SHIFTREGISTERKEYS",
     "os.getenv": "CIRCUITPY_OS_GETENV",
-    "select": "MICROPY_PY_USELECT_SELECT",
+    "select": "MICROPY_PY_SELECT_SELECT",
     "sys": "CIRCUITPY_SYS",
     "terminalio": "CIRCUITPY_DISPLAYIO",
     "usb": "CIRCUITPY_USB_HOST",

examples/natmod/README.md

@@ -0,0 +1,74 @@
+# Dynamic Native Modules
+
+Dynamic Native Modules are .mpy files that contain native machine code from a
+language other than Python. For more info see [the documentation]
+(https://docs.micropython.org/en/latest/develop/natmod.html).
+
+This should not be confused with [User C Modules]
+(https://docs.micropython.org/en/latest/develop/cmodules.html) which are a
+mechanism to add additional out-of-tree modules into the firmware build.
+
+## Examples
+
+This directory contains several examples of writing dynamic native modules, in
+two main categories:
+
+1.  Feature examples.
+
+    * `features0` - A module containing a single "factorial" function which
+      demonstrates working with integers.
+
+    * `features1` - A module that demonstrates some common tasks:
+        - defining simple functions exposed to Python
+        - defining local, helper C functions
+        - defining constant integers and strings exposed to Python
+        - getting and creating integer objects
+        - creating Python lists
+        - raising exceptions
+        - allocating memory
+        - BSS and constant data (rodata)
+        - relocated pointers in rodata
+
+    * `features2` - This is a hybrid module containing both Python and C code,
+      and additionally the C code is spread over multiple files. It also
+      demonstrates using floating point (only when the target supports
+      hardware floating point).
+
+    * `features3` - A module that shows how to use types, constant objects,
+      and creating dictionary instances.
+
+    * `features4` - A module that demonstrates how to define a class.
+
+2.  Dynamic version of existing built-ins.
+
+    This provides a way to add missing functionality to firmware that doesn't
+    include certain built-in modules. See the `heapq`, `random`, `re`,
+    `deflate`, `btree`, and `framebuf` directories.
+
+    So for example, if your firmware was compiled with `MICROPY_PY_FRAMEBUF`
+    disabled (e.g. to save flash space), then it would not include the
+    `framebuf` module. The `framebuf` native module provides a way to add the
+    `framebuf` module dynamically.
+
+    The way these work is they define a dynamic native module which
+    `#include`'s the original module and then does the necessary
+    initialisation of the module's globals dict.
+
+## Build instructions
+
+To compile an example, you need to have the same toolchain available as
+required for your target port. e.g. `arm-none-eabi-gcc` for any ARM Cortex M
+target. See the port instructions for details.
+
+You also need to have the `pyelftools` Python package available, either via
+your system package manager or installed from PyPI in a virtual environment
+with `pip`.
+
+Each example provides a Makefile. You should specify the `ARCH` argument to
+make (one of x86, x64, armv6m, armv7m, xtensa, xtensawin):
+
+```
+$ cd features0
+$ make ARCH=armv7m
+$ mpremote cp features0.mpy :
+```

examples/natmod/uzlib/Makefile renamed to examples/natmod/deflate/Makefile

@@ -2,10 +2,10 @@
 MPY_DIR = ../../..
 
 # Name of module (different to built-in uzlib so it can coexist)
-MOD = uzlib_$(ARCH)
+MOD = deflate_$(ARCH)
 
 # Source files (.c or .py)
-SRC = uzlib.c
+SRC = deflate.c
 
 # Architecture to build for (x86, x64, armv7m, xtensa, xtensawin)
 ARCH = x64