Merge branch 'main' into pycfunctionobject_freelist

python · Jan 15, 2025 · 6c9d056 · 6c9d056
2 parents a76224b + 6e4f641
commit 6c9d056
Show file tree

Hide file tree

Showing 218 changed files with 5,372 additions and 2,142 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -96,13 +96,14 @@ Doc/library/site.rst          @FFY00
 Lib/test/test_except*.py      @iritkatriel
 Objects/exceptions.c          @iritkatriel
 
-# Hashing
-**/*hashlib*                  @gpshead @tiran
+# Hashing & cryptographic primitives
+**/*hashlib*                  @gpshead @tiran @picnixz
 **/*pyhash*                   @gpshead @tiran
-**/sha*                       @gpshead @tiran
-Modules/md5*                  @gpshead @tiran
-**/*blake*                    @gpshead @tiran
+**/sha*                       @gpshead @tiran @picnixz
+Modules/md5*                  @gpshead @tiran @picnixz
+**/*blake*                    @gpshead @tiran @picnixz
 Modules/_hacl/**              @gpshead
+**/*hmac*                     @gpshead @picnixz
 
 # logging
 **/*logging*                  @vsajip

diff --git a/.github/workflows/reusable-change-detection.yml b/.github/workflows/reusable-change-detection.yml
@@ -83,7 +83,22 @@ jobs:
           # into the PR branch anyway.
           #
           # https://github.com/python/core-workflow/issues/373
-          git diff --name-only "origin/$GITHUB_BASE_REF.." | grep -qvE '(\.rst$|^Doc|^Misc|^\.pre-commit-config\.yaml$|\.ruff\.toml$|\.md$|mypy\.ini$)' && echo "run-tests=true" >> "$GITHUB_OUTPUT" || true
+          grep_ignore_args=(
+            # file extensions
+              -e '\.md$'
+              -e '\.rst$'
+            # top-level folders
+              -e '^Doc/'
+              -e '^Misc/'
+            # configuration files
+              -e '^\.github/CODEOWNERS$'
+              -e '^\.pre-commit-config\.yaml$'
+              -e '\.ruff\.toml$'
+              -e 'mypy\.ini$'
+          )
+          git diff --name-only "origin/$GITHUB_BASE_REF.."        \
+            | grep -qvE "${grep_ignore_args[@]}"                  \
+            && echo "run-tests=true" >> "$GITHUB_OUTPUT" || true
         fi
 
         # Check if we should run hypothesis tests

diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
@@ -234,7 +234,7 @@ Operating System Utilities
 
    The caller must hold the GIL.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 
 .. c:function:: int Py_fclose(FILE *file)
@@ -246,7 +246,7 @@ Operating System Utilities
    In either case, any further access (including another call to
    :c:func:`Py_fclose`) to the stream results in undefined behavior.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 
 .. _systemfunctions:

diff --git a/Doc/deprecations/pending-removal-in-3.16.rst b/Doc/deprecations/pending-removal-in-3.16.rst
@@ -57,6 +57,11 @@ Pending removal in Python 3.16
     In the rare case that you need the bitwise inversion of
     the underlying integer, convert to ``int`` explicitly (``~int(x)``).
 
+* :mod:`functools`:
+
+  * Calling the Python implementation of :func:`functools.reduce` with *function*
+    or *sequence* as keyword arguments has been deprecated since Python 3.14.
+
 * :mod:`shutil`:
 
   * The :class:`!ExecError` exception
@@ -79,8 +84,3 @@ Pending removal in Python 3.16
 
   * The undocumented and unused :attr:`!TarFile.tarfile` attribute
     has been deprecated since Python 3.13.
-
-* :mod:`functools`:
-
-  * Calling the Python implementation of :func:`functools.reduce` with *function*
-    or *sequence* as keyword arguments has been deprecated since Python 3.14.
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
@@ -73,7 +73,7 @@ an event loop:
 
    Set *loop* as the current event loop for the current OS thread.
 
-   .. deprecated:: next
+   .. deprecated:: 3.14
       The :func:`set_event_loop` function is deprecated and will be removed
       in Python 3.16.
 

diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst
@@ -48,7 +48,7 @@ for the current process:
 
    Return the current process-wide policy.
 
-   .. deprecated:: next
+   .. deprecated:: 3.14
       The :func:`get_event_loop_policy` function is deprecated and
       will be removed in Python 3.16.
 
@@ -58,7 +58,7 @@ for the current process:
 
    If *policy* is set to ``None``, the default policy is restored.
 
-   .. deprecated:: next
+   .. deprecated:: 3.14
       The :func:`set_event_loop_policy` function is deprecated and
       will be removed in Python 3.16.
 
@@ -95,7 +95,7 @@ The abstract event loop policy base class is defined as follows:
 
       This method should never return ``None``.
 
-   .. deprecated:: next
+   .. deprecated:: 3.14
       The :class:`AbstractEventLoopPolicy` class is deprecated and
       will be removed in Python 3.16.
 
@@ -121,7 +121,7 @@ asyncio ships with the following built-in policies:
       The :meth:`get_event_loop` method of the default asyncio policy now
       raises a :exc:`RuntimeError` if there is no set event loop.
 
-   .. deprecated:: next
+   .. deprecated:: 3.14
       The :class:`DefaultEventLoopPolicy` class is deprecated and
       will be removed in Python 3.16.
 
@@ -133,7 +133,7 @@ asyncio ships with the following built-in policies:
 
    .. availability:: Windows.
 
-   .. deprecated:: next
+   .. deprecated:: 3.14
       The :class:`WindowsSelectorEventLoopPolicy` class is deprecated and
       will be removed in Python 3.16.
 
@@ -145,7 +145,7 @@ asyncio ships with the following built-in policies:
 
    .. availability:: Windows.
 
-   .. deprecated:: next
+   .. deprecated:: 3.14
       The :class:`WindowsProactorEventLoopPolicy` class is deprecated and
       will be removed in Python 3.16.
 

diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
@@ -173,7 +173,7 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       on the first weekday as specified in the constructor or set by the
       :meth:`setfirstweekday` method.
 
-      .. versionchanged:: next
+      .. versionchanged:: 3.14
          If *highlight_day* is given, this date is highlighted in color.
          This can be :ref:`controlled using environment variables
          <using-on-controlling-color>`.
@@ -201,7 +201,7 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       on the first weekday as specified in the constructor or set by the
       :meth:`setfirstweekday` method.
 
-      .. versionchanged:: next
+      .. versionchanged:: 3.14
          If *highlight_day* is given, this date is highlighted in color.
          This can be :ref:`controlled using environment variables
          <using-on-controlling-color>`.
@@ -229,7 +229,7 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       :meth:`setfirstweekday` method.  The earliest year for which a calendar
       can be generated is platform-dependent.
 
-      .. versionchanged:: next
+      .. versionchanged:: 3.14
          If *highlight_day* is given, this date is highlighted in color.
          This can be :ref:`controlled using environment variables
          <using-on-controlling-color>`.
@@ -727,7 +727,7 @@ The following options are accepted:
    The number of months printed per row.
    Defaults to 3.
 
-.. versionchanged:: next
+.. versionchanged:: 3.14
    By default, today's date is highlighted in color and can be
    :ref:`controlled using environment variables <using-on-controlling-color>`.
 

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
@@ -870,6 +870,36 @@ invalid non-\ ``NULL`` pointers would crash Python)::
    ValueError: NULL pointer access
    >>>
 
+.. _ctypes-thread-safety:
+
+Thread safety without the GIL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Python 3.13, the :term:`GIL` may be disabled on :term:`experimental free threaded <free threading>` builds.
+In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects:
+
+   .. code-block:: pycon
+
+      >>> number = c_int(42)
+      >>> pointer_a = pointer(number)
+      >>> pointer_b = pointer(number)
+
+In the above, it's only safe for one object to read and write to the address at once if the GIL is disabled.
+So, ``pointer_a`` can be shared and written to across multiple threads, but only if ``pointer_b``
+is not also attempting to do the same. If this is an issue, consider using a :class:`threading.Lock`
+to synchronize access to memory:
+
+   .. code-block:: pycon
+
+      >>> import threading
+      >>> lock = threading.Lock()
+      >>> # Thread 1
+      >>> with lock:
+      ...    pointer_a.contents = 24
+      >>> # Thread 2
+      >>> with lock:
+      ...    pointer_b.contents = 42
+
 
 .. _ctypes-type-conversions:
 
@@ -2203,7 +2233,7 @@ Utility functions
 
    .. audit-event:: ctypes.memoryview_at address,size,readonly
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 
 .. _ctypes-data-types:

diff --git a/Doc/library/faulthandler.rst b/Doc/library/faulthandler.rst
@@ -91,7 +91,7 @@ Fault handler state
       The dump now mentions if a garbage collector collection is running
       if *all_threads* is true.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.14
       Only the current thread is dumped if the :term:`GIL` is disabled to
       prevent the risk of data races.
 

diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst
@@ -46,9 +46,15 @@ module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
 a period are not special for this module, and are matched by the ``*`` and ``?``
 patterns.
 
-Also note that :func:`functools.lru_cache` with the *maxsize* of 32768 is used to
-cache the compiled regex patterns in the following functions: :func:`fnmatch`,
-:func:`fnmatchcase`, :func:`.filter`.
+Unless stated otherwise, "filename string" and "pattern string" either refer to
+:class:`str` or ``ISO-8859-1`` encoded :class:`bytes` objects. Note that the
+functions documented below do not allow to mix a :class:`!bytes` pattern with
+a :class:`!str` filename, and vice-versa.
+
+Finally, note that :func:`functools.lru_cache` with a *maxsize* of 32768
+is used to cache the (typed) compiled regex patterns in the following
+functions: :func:`fnmatch`, :func:`fnmatchcase`, :func:`.filter`.
+
 
 .. function:: fnmatch(name, pat)
 
@@ -78,16 +84,16 @@ cache the compiled regex patterns in the following functions: :func:`fnmatch`,
 
 .. function:: filter(names, pat)
 
-   Construct a list from those elements of the :term:`iterable` *names*
-   that match pattern *pat*.
+   Construct a list from those elements of the :term:`iterable` of filename
+   strings *names* that match the pattern string *pat*.
    It is the same as ``[n for n in names if fnmatch(n, pat)]``,
    but implemented more efficiently.
 
 
 .. function:: translate(pat)
 
    Return the shell-style pattern *pat* converted to a regular expression for
-   using with :func:`re.match`.
+   using with :func:`re.match`. The pattern is expected to be a :class:`str`.
 
    Example:
 

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
@@ -5424,7 +5424,7 @@ operating system.
 
    Scheduling policy for tasks with deadline constraints.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 .. data:: SCHED_IDLE
 
@@ -5434,7 +5434,7 @@ operating system.
 
    Alias for :data:`SCHED_OTHER`.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 .. data:: SCHED_SPORADIC
 

diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
@@ -179,13 +179,15 @@ slightly different way:
    .. versionadded:: 3.14
       The *commands* argument.
 
-.. function:: post_mortem(traceback=None)
+.. function:: post_mortem(t=None)
 
-   Enter post-mortem debugging of the given *traceback* object.  If no
-   *traceback* is given, it uses the one of the exception that is currently
-   being handled (an exception must be being handled if the default is to be
-   used).
+   Enter post-mortem debugging of the given exception or
+   :ref:`traceback object <traceback-objects>`. If no value is given, it uses
+   the exception that is currently being handled, or raises ``ValueError`` if
+   there isn’t one.
 
+   .. versionchanged:: 3.13
+      Support for exception objects was added.
 
 .. function:: pm()
 

diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst
@@ -945,7 +945,7 @@ The ``errors`` module has the following attributes:
 
    The parser was tried to be stopped or suspended before it started.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 
 .. rubric:: Footnotes

diff --git a/Doc/library/re.rst b/Doc/library/re.rst
@@ -572,7 +572,7 @@ character ``'$'``.
    Word boundaries are determined by the current locale
    if the :py:const:`~re.LOCALE` flag is used.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.14
       ``\B`` now matches empty input string.
 
 .. index:: single: \d; in regular expressions

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
@@ -678,7 +678,7 @@ Constants
 
    Constant to enable duplicate address and port bindings with load balancing.
 
-  .. versionadded:: next
+  .. versionadded:: 3.14
 
   .. availability:: FreeBSD >= 12.0
 

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
@@ -938,7 +938,7 @@ Constants
 
    Whether the OpenSSL library has built-in support for TLS-PHA.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 .. data:: CHANNEL_BINDING_TYPES