initial v1.19.1 merge; not compiled yet

Author: dhalbert

.git-blame-ignore-revs

@@ -1,3 +1,15 @@
+#all: Reformat remaining C code that doesn't have a space after a comma.
+5b700b0af90591d6b1a2c087bb8de6b7f1bfdd2d
+
+# ports: Reformat more C and Python source code.
+5c32111fa0e31e451b0f1666bdf926be2fdfd82c
+
+# all: Update Python formatting to latest Black version 22.1.0.
+ab2923dfa1174dc177f0a90cb00a7e4ff87958d2
+
+# all: Update Python formatting to latest Black version 21.12b0.
+3770fab33449a5dadf8eb06edfae0767e75320a6
+
 # tools/gen-cpydiff.py: Fix formatting of doc strings for new Black.
 0f78c36c5aa458a954eed39a46942209107a553e
 

docs/library/array.rst

@@ -1,10 +1,10 @@
 :mod:`array` -- arrays of numeric data
-=======================================
+======================================
 
 .. module:: array
    :synopsis: efficient arrays of numeric data
 
-|see_cpython_module| :mod:`cpython:array`.
+|see_cpython_module| :mod:`python:array`.
 
 Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
 ``L``, ``q``, ``Q``, ``f``, ``d`` (the latter 2 depending on the

docs/library/binascii.rst

@@ -1,10 +1,10 @@
 :mod:`binascii` -- binary/ASCII conversions
-============================================
+===========================================
 
 .. module:: binascii
    :synopsis: binary/ASCII conversions
 
-|see_cpython_module| :mod:`cpython:binascii`.
+|see_cpython_module| :mod:`python:binascii`.
 
 This module implements conversions between binary data and various
 encodings of it in ASCII form (in both directions).
@@ -31,11 +31,11 @@ Functions
    Conforms to `RFC 2045 s.6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_.
    Returns a bytes object.
 
-.. function:: b2a_base64(data)
+.. function:: b2a_base64(data, *, newline=True)
 
    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, as a bytes object.
+   followed by a newline character if ``newline``is true, as a bytes object.
 
 .. function:: crc32(data, value=0, /)
 

docs/library/btree.rst

@@ -7,7 +7,7 @@
    :synopsis: simple BTree database
 
 The ``btree`` module implements a simple key-value database using external
-storage (disk files, or in general case, a random-access ``stream``). Keys are
+storage (disk files, or in general case, a random-access `stream`). Keys are
 stored sorted in the database, and besides efficient retrieval by a key
 value, a database also supports efficient ordered range scans (retrieval
 of values with the keys in a given range). On the application interface
@@ -80,7 +80,7 @@ Functions
 
 .. function:: open(stream, *, flags=0, pagesize=0, cachesize=0, minkeypage=0)
 
-   Open a database from a random-access ``stream`` (like an open file). All
+   Open a database from a random-access `stream` (like an open file). All
    other parameters are optional and keyword-only, and allow to tweak advanced
    parameters of the database operation (most users will not need them):
 

docs/library/builtins.rst

@@ -33,7 +33,7 @@ Functions and types
 
 .. class:: bytes()
 
-    |see_cpython| `bytes`.
+    |see_cpython| `python:bytes`.
 
 .. function:: callable()
 
@@ -68,7 +68,7 @@ Functions and types
 
 .. class:: frozenset()
 
-`frozenset()` is not enabled on non-Express CircuitPython boards.
+`frozenset()` is not enabled on the smallest CircuitPython boards for space reasons.
 
 .. function:: getattr()
 
@@ -88,12 +88,12 @@ Functions and types
 
    .. classmethod:: from_bytes(bytes, byteorder)
 
-      In CircuitPython, ``byteorder`` parameter must be positional (this is
+      In CircuitPython, the ``byteorder`` parameter must be positional (this is
       compatible with CPython).
 
    .. method:: to_bytes(size, byteorder)
 
-      In CircuitPython, ``byteorder`` parameter must be positional (this is
+      In CircuitPython, the ``byteorder`` parameter must be positional (this is
       compatible with CPython).
 
 .. function:: isinstance()
@@ -138,7 +138,7 @@ Functions and types
 
 .. function:: reversed()
 
-`reversed()` is not enabled on non-Express CircuitPython boards.
+`reversed()` is not enabled on the smallest CircuitPython boards for space reasons.
 
 .. function:: round()
 
@@ -224,10 +224,14 @@ Exceptions
 
 .. exception:: SystemExit
 
+    |see_cpython| `python:SystemExit`.
+
 .. exception:: TimeoutError
 
 .. exception:: TypeError
 
+    |see_cpython| `python:TypeError`.
+
 .. exception:: UnicodeError
 
 .. exception:: ValueError

docs/library/collections.rst

@@ -1,20 +1,20 @@
 :mod:`collections` -- collection and container types
-=====================================================
+====================================================
 
-.. include:: ../templates/unsupported_in_circuitpython.inc
+**Limitations:** Not implemented on the smallest CircuitPython boards for space reasons.
 
 .. module:: collections
    :synopsis: collection and container types
 
-|see_cpython_module| :mod:`cpython:collections`.
+|see_cpython_module| :mod:`python:collections`.
 
 This module implements advanced collection and container types to
 hold/accumulate various objects.
 
 Classes
 -------
 
-.. function:: deque(iterable, maxlen[, flags])
+.. class:: deque(iterable, maxlen[, flags])
 
     Deques (double-ended queues) are a list-like container that support O(1)
     appends and pops from either side of the deque.  New deques are created
@@ -59,7 +59,7 @@ Classes
         print(t1.name)
         assert t2.name == t2[1]
 
-.. function:: OrderedDict(...)
+.. class:: OrderedDict(...)
 
     ``dict`` type subclass which remembers and preserves the order of keys
     added. When ordered dict is iterated over, keys/items are returned in

docs/library/errno.rst

@@ -4,25 +4,24 @@
 .. module:: errno
    :synopsis: system error codes
 
-|see_cpython_module| :mod:`cpython:errno`.
+|see_cpython_module| :mod:`python:errno`.
 
 This module provides access to symbolic error codes for `OSError` exception.
-A particular inventory of codes depends on :term:`MicroPython port`.
+The codes available may vary per CircuitPython build.
 
 Constants
 ---------
 
 .. data:: EEXIST, EAGAIN, etc.
 
     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.args[0]``
+    "E". 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.args[0] == errno.EEXIST:
+            if exc.errno == errno.EEXIST:
                 print("Directory already exists")
 
 .. data:: errorcode

docs/library/gc.rst

@@ -1,12 +1,10 @@
 :mod:`gc` -- control the garbage collector
 ==========================================
 
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
 .. module:: gc
    :synopsis: control the garbage collector
 
-|see_cpython_module| :mod:`cpython:gc`.
+|see_cpython_module| :mod:`python:gc`.
 
 Functions
 ---------
@@ -63,6 +61,6 @@ Functions
    .. admonition:: Difference to CPython
       :class: attention
 
-      This function is a a MicroPython extension. CPython has a similar
+      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.

docs/library/heapq.rst

@@ -6,7 +6,7 @@
 .. module:: heapq
    :synopsis: heap queue algorithm
 
-|see_cpython_module| :mod:`cpython:heapq`.
+|see_cpython_module| :mod:`python:heapq`.
 
 This module implements the
 `min heap queue algorithm <https://en.wikipedia.org/wiki/Heap_%28data_structure%29>`_.

docs/library/index.rst

@@ -15,7 +15,7 @@ CircuitPython's long-term goal is that code written in CircuitPython
 using Python standard libraries will be runnable on CPython without changes.
 
 These libraries are not enabled on CircuitPython builds with
-limited flash memory, usually on non-Express builds:
+limited flash memory:
 ``binascii``, ``errno``, ``json``, ``re``.
 
 These libraries are not currently enabled in any CircuitPython build, but may be in the future:
@@ -42,21 +42,6 @@ Omitted functions in the ``string`` library
 -------------------------------------------
 
 A few string operations are not enabled on small builds
-(usually non-Express), due to limited flash memory:
+due to limited flash memory:
 ``string.center()``, ``string.partition()``, ``string.splitlines()``,
 ``string.reversed()``.
-
-
-CircuitPython/MicroPython-specific libraries
---------------------------------------------
-
-Functionality specific to the CircuitPython/MicroPython implementation is available in
-the following libraries. These libraries may change significantly or be removed in future
-versions of CircuitPython.
-
-.. toctree::
-   :maxdepth: 1
-
-   btree.rst
-   framebuf.rst
-   micropython.rst

docs/library/io.rst

@@ -1,10 +1,10 @@
 :mod:`io` -- input/output streams
-==================================
+=================================
 
 .. module:: io
    :synopsis: input/output streams
 
-|see_cpython_module| :mod:`cpython:io`.
+|see_cpython_module| :mod:`python:io`.
 
 This module contains additional types of ``stream`` (file-like) objects
 and helper functions.
@@ -112,3 +112,20 @@ Classes
     .. method:: getvalue()
 
         Get the current contents of the underlying buffer which holds data.
+
+.. class:: StringIO(alloc_size)
+    :noindex:
+.. class:: BytesIO(alloc_size)
+    :noindex:
+
+    Create an empty `StringIO`/`BytesIO` object, preallocated to hold up
+    to *alloc_size* number of bytes. That means that writing that amount
+    of bytes won't lead to reallocation of the buffer, and thus won't hit
+    out-of-memory situation or lead to memory fragmentation. These constructors
+    are a MicroPython extension and are recommended for usage only in special
+    cases and in system-level libraries, not for end-user applications.
+
+    .. admonition:: Difference to CPython
+        :class: attention
+
+        These constructors are a MicroPython extension.

docs/library/json.rst

@@ -1,25 +1,31 @@
 :mod:`json` -- JSON encoding and decoding
-==========================================
+=========================================
 
 .. module:: json
    :synopsis: JSON encoding and decoding
 
-|see_cpython_module| :mod:`cpython:json`.
+|see_cpython_module| :mod:`python:json`.
 
 This modules allows to convert between Python objects and the JSON
 data format.
 
 Functions
 ---------
 
-.. function:: dump(obj, stream)
+.. function:: dump(obj, stream, separators=None)
 
    Serialise ``obj`` to a JSON string, writing it to the given *stream*.
 
-.. function:: dumps(obj)
+   If specified, separators should be an ``(item_separator, key_separator)``
+   tuple. The default is ``(', ', ': ')``. To get the most compact JSON
+   representation, you should specify ``(',', ':')`` to eliminate whitespace.
+
+.. function:: dumps(obj, separators=None)
 
    Return ``obj`` represented as a JSON string.
 
+   The arguments have the same meaning as in `dump`.
+
 .. function:: load(stream)
 
    Parse the given ``stream``, interpreting it as a JSON string and