Merge branch 'main' into dankm/getrandom

Author: dankm

.gitattributes

@@ -94,6 +94,8 @@ Lib/test/test_stable_abi_ctypes.py                  generated
 Lib/test/test_zoneinfo/data/*.json                  generated
 Lib/token.py                                        generated
 Misc/sbom.spdx.json                                 generated
+Modules/_testinternalcapi/test_cases.c.h            generated
+Modules/_testinternalcapi/test_targets.h            generated
 Objects/typeslots.inc                               generated
 PC/python3dll.c                                     generated
 Parser/parser.c                                     generated

Doc/c-api/module.rst

@@ -426,10 +426,10 @@ To retrieve the state from a given module, use the following functions:
    module state.
 
 
-.. c:function:: int PyModule_GetStateSize(PyObject *, Py_ssize_t *result)
+.. c:function:: int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)
 
-   Set *\*result* to the size of the module's state, as specified using
-   :c:macro:`Py_mod_state_size` (or :c:member:`PyModuleDef.m_size`),
+   Set *\*result* to the size of *module*'s state, as specified
+   using :c:macro:`Py_mod_state_size` (or :c:member:`PyModuleDef.m_size`),
    and return 0.
 
    On error, set *\*result* to -1, and return -1 with an exception set.
@@ -597,7 +597,7 @@ A module's token -- and the *your_token* value to use in the above code -- is:
 
 .. c:function:: int PyModule_GetToken(PyObject *module, void** result)
 
-   Set *\*result* to the module's token and return 0.
+   Set *\*result* to the module token for *module* and return 0.
 
    On error, set *\*result* to NULL, and return -1 with an exception set.
 
@@ -645,7 +645,7 @@ rather than from an extension's :ref:`export hook <extension-export-hook>`.
 
 .. c:function:: int PyModule_Exec(PyObject *module)
 
-   Execute the :c:data:`Py_mod_exec` slot(s) of the given *module*.
+   Execute the :c:data:`Py_mod_exec` slot(s) of *module*.
 
    On success, return 0.
    On error, return -1 with an exception set.
@@ -1021,6 +1021,9 @@ or code that creates modules dynamically.
    ``PyModuleDef`` (such as when using :ref:`multi-phase-initialization`,
    ``PyModule_Create``, or ``PyModule_FromDefAndSpec``).
 
+   Return ``0`` on success.
+   Return ``-1`` with an exception set on error.
+
    .. versionadded:: 3.5
 
 .. c:function:: int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

Doc/faq/programming.rst

@@ -1226,13 +1226,13 @@ This converts the list into a set, thereby removing duplicates, and then back
 into a list.
 
 
-How do you remove multiple items from a list
---------------------------------------------
+How do you remove multiple items from a list?
+---------------------------------------------
 
 As with removing duplicates, explicitly iterating in reverse with a
 delete condition is one possibility.  However, it is easier and faster
 to use slice replacement with an implicit or explicit forward iteration.
-Here are three variations.::
+Here are three variations::
 
    mylist[:] = filter(keep_function, mylist)
    mylist[:] = (x for x in mylist if keep_condition)

Doc/library/base64.rst

@@ -73,6 +73,7 @@ POST request.
 
 
 .. function:: b64decode(s, altchars=None, validate=False)
+              b64decode(s, altchars=None, validate=True, *, ignorechars)
 
    Decode the Base64 encoded :term:`bytes-like object` or ASCII string
    *s* and return the decoded :class:`bytes`.
@@ -84,11 +85,17 @@ POST request.
    A :exc:`binascii.Error` exception is raised
    if *s* is incorrectly padded.
 
-   If *validate* is false (the default), characters that are neither
+   If *ignorechars* is specified, it should be a :term:`bytes-like object`
+   containing characters to ignore from the input when *validate* is true.
+   The default value of *validate* is ``True`` if *ignorechars* is specified,
+   ``False`` otherwise.
+
+   If *validate* is false, characters that are neither
    in the normal base-64 alphabet nor the alternative alphabet are
    discarded prior to the padding check, but the ``+`` and ``/`` characters
    keep their meaning if they are not in *altchars* (they will be discarded
    in future Python versions).
+
    If *validate* is true, these non-alphabet characters in the input
    result in a :exc:`binascii.Error`.
 
@@ -99,6 +106,10 @@ POST request.
       is now deprecated.
 
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
+
 .. function:: standard_b64encode(s)
 
    Encode :term:`bytes-like object` *s* using the standard Base64 alphabet
@@ -254,8 +265,7 @@ Refer to the documentation of the individual functions for more information.
    *adobe* controls whether the input sequence is in Adobe Ascii85 format
    (i.e. is framed with <~ and ~>).
 
-   *ignorechars* should be a :term:`bytes-like object` or ASCII string
-   containing characters to ignore
+   *ignorechars* should be a byte string containing characters to ignore
    from the input. This should only contain whitespace characters, and by
    default contains all whitespace characters in ASCII.
 

Doc/library/binascii.rst

@@ -49,10 +49,16 @@ The :mod:`binascii` module defines the following functions:
 
 
 .. function:: a2b_base64(string, /, *, strict_mode=False)
+              a2b_base64(string, /, *, strict_mode=True, ignorechars)
 
    Convert a block of base64 data back to binary and return the binary data. More
    than one line may be passed at a time.
 
+   If *ignorechars* is specified, it should be a :term:`bytes-like object`
+   containing characters to ignore from the input when *strict_mode* is true.
+   The default value of *strict_mode* is ``True`` if *ignorechars* is specified,
+   ``False`` otherwise.
+
    If *strict_mode* is true, only valid base64 data will be converted. Invalid base64
    data will raise :exc:`binascii.Error`.
 
@@ -66,6 +72,9 @@ The :mod:`binascii` module defines the following functions:
    .. versionchanged:: 3.11
       Added the *strict_mode* parameter.
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
 .. function:: b2a_base64(data, *, wrapcol=0, newline=True)
 

Doc/library/contextvars.rst

@@ -77,6 +77,32 @@ Context Variables
       to restore the variable to its previous value via the
       :meth:`ContextVar.reset` method.
 
+      For convenience, the token object can be used as a context manager
+      to avoid calling :meth:`ContextVar.reset` manually::
+
+          var = ContextVar('var', default='default value')
+
+          with var.set('new value'):
+              assert var.get() == 'new value'
+
+          assert var.get() == 'default value'
+
+      It is a shorthand for::
+
+          var = ContextVar('var', default='default value')
+
+          token = var.set('new value')
+          try:
+              assert var.get() == 'new value'
+          finally:
+              var.reset(token)
+
+          assert var.get() == 'default value'
+
+      .. versionadded:: 3.14
+
+         Added support for using tokens as context managers.
+
    .. method:: reset(token)
 
       Reset the context variable to the value it had before the
@@ -93,24 +119,18 @@ Context Variables
           # After the reset call the var has no value again, so
           # var.get() would raise a LookupError.
 
+      The same *token* cannot be used twice.
+
 
 .. class:: Token
 
    *Token* objects are returned by the :meth:`ContextVar.set` method.
    They can be passed to the :meth:`ContextVar.reset` method to revert
    the value of the variable to what it was before the corresponding
-   *set*.
-
-   The token supports :ref:`context manager protocol <context-managers>`
-   to restore the corresponding context variable value at the exit from
-   :keyword:`with` block::
-
-       var = ContextVar('var', default='default value')
-
-       with var.set('new value'):
-           assert var.get() == 'new value'
+   *set*. A single token cannot reset a context variable more than once.
 
-       assert var.get() == 'default value'
+   Tokens support the :ref:`context manager protocol <context-managers>`
+   to automatically reset context variables. See :meth:`ContextVar.set`.
 
    .. versionadded:: 3.14
 

Doc/library/inspect.rst

@@ -524,7 +524,7 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 
    .. versionchanged:: 3.13
       Functions wrapped in :func:`functools.partialmethod` now return ``True``
-      if the wrapped function is a :term:`coroutine function`.
+      if the wrapped function is a :term:`asynchronous generator` function.
 
 .. function:: isasyncgen(object)
 

Doc/library/os.rst

@@ -4262,7 +4262,7 @@ features:
        import os
 
        # semaphore with start value '1'
-       fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
+       fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFD_CLOEXEC)
        try:
            # acquire semaphore
            v = os.eventfd_read(fd)

Doc/library/pickle.rst

@@ -56,19 +56,6 @@ files.
 
 The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
 
-* The :mod:`pickle` module keeps track of the objects it has already serialized,
-  so that later references to the same object won't be serialized again.
-  :mod:`marshal` doesn't do this.
-
-  This has implications both for recursive objects and object sharing.  Recursive
-  objects are objects that contain references to themselves.  These are not
-  handled by marshal, and in fact, attempting to marshal recursive objects will
-  crash your Python interpreter.  Object sharing happens when there are multiple
-  references to the same object in different places in the object hierarchy being
-  serialized.  :mod:`pickle` stores such objects only once, and ensures that all
-  other references point to the master copy.  Shared objects remain shared, which
-  can be very important for mutable objects.
-
 * :mod:`marshal` cannot be used to serialize user-defined classes and their
   instances.  :mod:`pickle` can save and restore class instances transparently,
   however the class definition must be importable and live in the same module as

Doc/library/symtable.rst

@@ -180,6 +180,12 @@ Examining Symbol Tables
       Return a tuple containing names of :term:`free (closure) variables <closure variable>`
       in this function.
 
+   .. method:: get_cells()
+
+      Return a tuple containing names of :term:`cell variables <closure variable>` in this table.
+
+      .. versionadded:: next
+
 
 .. class:: Class
 
@@ -291,6 +297,12 @@ Examining Symbol Tables
       Return ``True`` if the symbol is referenced in its block, but not assigned
       to.
 
+   .. method:: is_cell()
+
+      Return ``True`` if the symbol is referenced but not assigned in a nested block.
+
+      .. versionadded:: next
+
    .. method:: is_free_class()
 
       Return *True* if a class-scoped symbol is free from