Merge branch 'main' into specialize-for-iter-range

Author: markshannon

.gitignore

@@ -131,6 +131,7 @@ Tools/unicode/data/
 /autom4te.cache
 /build/
 /builddir/
+/compile_commands.json
 /config.cache
 /config.log
 /config.status

Doc/c-api/exceptions.rst

@@ -982,6 +982,7 @@ the variables:
 
 .. index::
    single: PyExc_BaseException (C var)
+   single: PyExc_BaseExceptionGroup (C var)
    single: PyExc_Exception (C var)
    single: PyExc_ArithmeticError (C var)
    single: PyExc_AssertionError (C var)
@@ -1041,6 +1042,8 @@ the variables:
 +=========================================+=================================+==========+
 | :c:data:`PyExc_BaseException`           | :exc:`BaseException`            | [1]_     |
 +-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_BaseExceptionGroup`      | :exc:`BaseExceptionGroup`       | [1]_     |
++-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_Exception`               | :exc:`Exception`                | [1]_     |
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ArithmeticError`         | :exc:`ArithmeticError`          | [1]_     |
@@ -1164,6 +1167,9 @@ the variables:
 .. versionadded:: 3.6
    :c:data:`PyExc_ModuleNotFoundError`.
 
+.. versionadded:: 3.11
+   :c:data:`PyExc_BaseExceptionGroup`.
+
 These are compatibility aliases to :c:data:`PyExc_OSError`:
 
 .. index::
@@ -1207,6 +1213,7 @@ the variables:
    single: PyExc_Warning (C var)
    single: PyExc_BytesWarning (C var)
    single: PyExc_DeprecationWarning (C var)
+   single: PyExc_EncodingWarning (C var)
    single: PyExc_FutureWarning (C var)
    single: PyExc_ImportWarning (C var)
    single: PyExc_PendingDeprecationWarning (C var)
@@ -1225,6 +1232,8 @@ the variables:
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_DeprecationWarning`       | :exc:`DeprecationWarning`       |          |
 +------------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_EncodingWarning`          | :exc:`EncodingWarning`          |          |
++------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_FutureWarning`            | :exc:`FutureWarning`            |          |
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ImportWarning`            | :exc:`ImportWarning`            |          |
@@ -1245,6 +1254,9 @@ the variables:
 .. versionadded:: 3.2
    :c:data:`PyExc_ResourceWarning`.
 
+.. versionadded:: 3.10
+   :c:data:`PyExc_EncodingWarning`.
+
 Notes:
 
 .. [3]

Doc/c-api/typeobj.rst

@@ -686,6 +686,26 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    instance, and call the type's :c:member:`~PyTypeObject.tp_free` function to
    free the object itself.
 
+   If you may call functions that may set the error indicator, you must use
+   :c:func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException`
+   to ensure you don't clobber a preexisting error indicator (the deallocation
+   could have occurred while processing a different error):
+
+   .. code-block:: c
+
+     static void
+     foo_dealloc(foo_object *self)
+     {
+         PyObject *et, *ev, *etb;
+         PyObject *exc = PyErr_GetRaisedException();
+         ...
+         PyErr_SetRaisedException(exc);
+     }
+
+   The dealloc handler itself must not raise an exception; if it hits an error
+   case it should call :c:func:`PyErr_FormatUnraisable` to log (and clear) an
+   unraisable exception.
+
    No guarantees are made about when an object is destroyed, except:
 
    * Python will destroy an object immediately or some time after the final

Doc/conf.py

@@ -234,6 +234,7 @@
     ('c:data', 'PyExc_AssertionError'),
     ('c:data', 'PyExc_AttributeError'),
     ('c:data', 'PyExc_BaseException'),
+    ('c:data', 'PyExc_BaseExceptionGroup'),
     ('c:data', 'PyExc_BlockingIOError'),
     ('c:data', 'PyExc_BrokenPipeError'),
     ('c:data', 'PyExc_BufferError'),
@@ -287,6 +288,7 @@
     # C API: Standard Python warning classes
     ('c:data', 'PyExc_BytesWarning'),
     ('c:data', 'PyExc_DeprecationWarning'),
+    ('c:data', 'PyExc_EncodingWarning'),
     ('c:data', 'PyExc_FutureWarning'),
     ('c:data', 'PyExc_ImportWarning'),
     ('c:data', 'PyExc_PendingDeprecationWarning'),

Doc/library/csv.rst

@@ -609,7 +609,7 @@ A slightly more advanced use of the reader --- catching and reporting errors::
            for row in reader:
                print(row)
        except csv.Error as e:
-           sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))
+           sys.exit(f'file {filename}, line {reader.line_num}: {e}')
 
 And while the module doesn't directly support parsing strings, it can easily be
 done::

Doc/library/ctypes.rst

@@ -714,10 +714,16 @@ item in the :attr:`~Structure._fields_` tuples::
    ...                 ("second_16", c_int, 16)]
    ...
    >>> print(Int.first_16)
-   <Field type=c_long, ofs=0:0, bits=16>
+   <ctypes.CField 'first_16' type=c_int, ofs=0, bit_size=16, bit_offset=0>
    >>> print(Int.second_16)
-   <Field type=c_long, ofs=0:16, bits=16>
-   >>>
+   <ctypes.CField 'second_16' type=c_int, ofs=0, bit_size=16, bit_offset=16>
+
+It is important to note that bit field allocation and layout in memory are not
+defined as a C standard; their implementation is compiler-specific.
+By default, Python will attempt to match the behavior of a "native" compiler
+for the current platform.
+See the :attr:`~Structure._layout_` attribute for details on the default
+behavior and how to change it.
 
 
 .. _ctypes-arrays:

Doc/library/stdtypes.rst

@@ -1018,7 +1018,7 @@ operations have the same priority as the corresponding numeric operations. [3]_
 | ``s * n`` or             | equivalent to adding *s* to    | (2)(7)   |
 | ``n * s``                | itself *n* times               |          |
 +--------------------------+--------------------------------+----------+
-| ``s[i]``                 | *i*\ th item of *s*, origin 0  | \(3)     |
+| ``s[i]``                 | *i*\ th item of *s*, origin 0  | (3)(9)   |
 +--------------------------+--------------------------------+----------+
 | ``s[i:j]``               | slice of *s* from *i* to *j*   | (3)(4)   |
 +--------------------------+--------------------------------+----------+
@@ -1150,6 +1150,9 @@ Notes:
    without copying any data and with the returned index being relative to
    the start of the sequence rather than the start of the slice.
 
+(9)
+   An :exc:`IndexError` is raised if *i* is outside the sequence range.
+
 
 .. _typesseq-immutable:
 

Doc/library/token.rst

@@ -51,7 +51,7 @@ The token constants are:
 .. data:: NAME
 
    Token value that indicates an :ref:`identifier <identifiers>`.
-   Note that keywords are also initially tokenized an ``NAME`` tokens.
+   Note that keywords are also initially tokenized as ``NAME`` tokens.
 
 .. data:: NUMBER
 

Doc/library/uuid.rst

@@ -257,6 +257,10 @@ The :mod:`uuid` module defines the following functions:
    non-specified arguments are substituted for a pseudo-random integer of
    appropriate size.
 
+   By default, *a*, *b* and *c* are generated by a non-cryptographically
+   secure pseudo-random number generator (CSPRNG). Use :func:`uuid4` when
+   a UUID needs to be used in a security-sensitive context.
+
    .. versionadded:: 3.14
 
 

Doc/tutorial/introduction.rst

@@ -13,10 +13,9 @@ end a multi-line command.
 
 .. only:: html
 
-   You can toggle the display of prompts and output by clicking on ``>>>``
-   in the upper-right corner of an example box.  If you hide the prompts
-   and output for an example, then you can easily copy and paste the input
-   lines into your interpreter.
+   You can use the "Copy" button (it appears in the upper-right corner
+   when hovering over or tapping a code example), which strips prompts
+   and omits output, to copy and paste the input lines into your interpreter.
 
 .. index:: single: # (hash); comment