Merge branch 'main' into fix-issue-133604

Author: makridenko

.github/workflows/mypy.yml

@@ -14,10 +14,12 @@ on:
       - "Lib/tomllib/**"
       - "Misc/mypy/**"
       - "Tools/build/compute-changes.py"
+      - "Tools/build/deepfreeze.py"
       - "Tools/build/generate_sbom.py"
       - "Tools/build/generate-build-details.py"
       - "Tools/build/verify_ensurepip_wheels.py"
       - "Tools/build/update_file.py"
+      - "Tools/build/umarshal.py"
       - "Tools/cases_generator/**"
       - "Tools/clinic/**"
       - "Tools/jit/**"

.github/workflows/reusable-context.yml

@@ -97,6 +97,7 @@ jobs:
       run: python Tools/build/compute-changes.py
       env:
         GITHUB_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        GITHUB_EVENT_NAME: ${{ github.event_name }}
         CCF_TARGET_REF: ${{ github.base_ref || github.event.repository.default_branch }}
         CCF_HEAD_REF: ${{ github.event.pull_request.head.sha || github.sha }}
 

.pre-commit-config.yaml

@@ -47,6 +47,8 @@ repos:
         exclude: Lib/test/tokenizedata/coding20731.py
       - id: trailing-whitespace
         types_or: [c, inc, python, rst]
+      - id: trailing-whitespace
+        files: '\.(gram)$'
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
     rev: 0.33.0

Doc/deprecations/pending-removal-in-3.15.rst

@@ -99,8 +99,7 @@ Pending removal in Python 3.15
 
 * :mod:`wave`:
 
-  * The :meth:`~wave.Wave_read.getmark`, :meth:`!setmark`,
-    and :meth:`~wave.Wave_read.getmarkers` methods of
+  * The ``getmark()``, ``setmark()`` and ``getmarkers()`` methods of
     the :class:`~wave.Wave_read` and :class:`~wave.Wave_write` classes
     have been deprecated since Python 3.13.
 

Doc/library/fcntl.rst

@@ -107,15 +107,15 @@ The module defines the following functions:
    passed to the C :c:func:`fcntl` call.  The return value after a successful
    call is the contents of the buffer, converted to a :class:`bytes` object.
    The length of the returned object will be the same as the length of the
-   *arg* argument. This is limited to 1024 bytes.
+   *arg* argument.
 
    If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
 
    .. note::
-      If the type or the size of *arg* does not match the type or size
-      of the argument of the operation (for example, if an integer is
+      If the type or size of *arg* does not match the type or size
+      of the operation's argument (for example, if an integer is
       passed when a pointer is expected, or the information returned in
-      the buffer by the operating system is larger than 1024 bytes),
+      the buffer by the operating system is larger than the size of *arg*),
       this is most likely to result in a segmentation violation or
       a more subtle data corruption.
 
@@ -125,6 +125,9 @@ The module defines the following functions:
       Add support of arbitrary :term:`bytes-like objects <bytes-like object>`,
       not only :class:`bytes`.
 
+   .. versionchanged:: next
+      The size of bytes-like objects is no longer limited to 1024 bytes.
+
 
 .. function:: ioctl(fd, request, arg=0, mutate_flag=True, /)
 
@@ -161,8 +164,7 @@ The module defines the following functions:
       If the type or size of *arg* does not match the type or size
       of the operation's argument (for example, if an integer is
       passed when a pointer is expected, or the information returned in
-      the buffer by the operating system is larger than 1024 bytes,
-      or the size of the mutable bytes-like object is too small),
+      the buffer by the operating system is larger than the size of *arg*),
       this is most likely to result in a segmentation violation or
       a more subtle data corruption.
 
@@ -185,6 +187,10 @@ The module defines the following functions:
       The GIL is always released during a system call.
       System calls failing with EINTR are automatically retried.
 
+   .. versionchanged:: next
+      The size of not mutated bytes-like objects is no longer
+      limited to 1024 bytes.
+
 .. function:: flock(fd, operation, /)
 
    Perform the lock operation *operation* on file descriptor *fd* (file objects providing

Doc/library/logging.rst

@@ -1342,8 +1342,9 @@ functions.
 
 .. function:: basicConfig(**kwargs)
 
-   Does basic configuration for the logging system by creating a
-   :class:`StreamHandler` with a default :class:`Formatter` and adding it to the
+   Does basic configuration for the logging system by either creating a
+   :class:`StreamHandler` with a default :class:`Formatter`
+   or using the  given *formatter* instance, and adding it to the
    root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
    :func:`error` and :func:`critical` will call :func:`basicConfig` automatically
    if no handlers are defined for the root logger.
@@ -1428,6 +1429,19 @@ functions.
    |              | which means that it will be treated the     |
    |              | same as passing 'errors'.                   |
    +--------------+---------------------------------------------+
+   | *formatter*  | If specified, set this formatter instance   |
+   |              | (see :ref:`formatter-objects`)              |
+   |              | for all involved handlers.                  |
+   |              | If not specified, the default is to create  |
+   |              | and use an instance of                      |
+   |              | :class:`logging.Formatter` based on         |
+   |              | arguments *format*, *datefmt* and *style*.  |
+   |              | When *formatter* is specified together with |
+   |              | any of the three arguments *format*,        |
+   |              | *datefmt* and *style*, a ``ValueError`` is  |
+   |              | raised to signal that these arguments would |
+   |              | lose meaning otherwise.                     |
+   +--------------+---------------------------------------------+
 
    .. versionchanged:: 3.2
       The *style* argument was added.
@@ -1444,6 +1458,9 @@ functions.
    .. versionchanged:: 3.9
       The *encoding* and *errors* arguments were added.
 
+   .. versionchanged:: 3.15
+      The *formatter* argument was added.
+
 .. function:: shutdown()
 
    Informs the logging system to perform an orderly shutdown by flushing and

Doc/library/stdtypes.rst

@@ -2269,6 +2269,18 @@ expression support in the :mod:`re` module).
       >>> '   1   2   3   '.split()
       ['1', '2', '3']
 
+   If *sep* is not specified or is ``None`` and  *maxsplit* is ``0``, only
+   leading runs of consecutive whitespace are considered.
+
+   For example::
+
+      >>> "".split(None, 0)
+      []
+      >>> "   ".split(None, 0)
+      []
+      >>> "   foo   ".split(maxsplit=0)
+      ['foo   ']
+
 
 .. index::
    single: universal newlines; str.splitlines method

Doc/library/threading.rst

@@ -11,6 +11,52 @@
 This module constructs higher-level threading interfaces on top of the lower
 level :mod:`_thread` module.
 
+.. include:: ../includes/wasm-notavail.rst
+
+Introduction
+------------
+
+The :mod:`!threading` module provides a way to run multiple `threads
+<https://en.wikipedia.org/wiki/Thread_(computing)>`_ (smaller
+units of a process) concurrently within a single process. It allows for the
+creation and management of threads, making it possible to execute tasks in
+parallel, sharing memory space. Threads are particularly useful when tasks are
+I/O bound, such as file operations or making network requests,
+where much of the time is spent waiting for external resources.
+
+A typical use case for :mod:`!threading` includes managing a pool of worker
+threads that can process multiple tasks concurrently.  Here's a basic example of
+creating and starting threads using :class:`~threading.Thread`::
+
+   import threading
+   import time
+
+   def crawl(link, delay=3):
+       print(f"crawl started for {link}")
+       time.sleep(delay)  # Blocking I/O (simulating a network request)
+       print(f"crawl ended for {link}")
+
+   links = [
+       "https://python.org",
+       "https://docs.python.org",
+       "https://peps.python.org",
+   ]
+
+   # Start threads for each link
+   threads = []
+   for link in links:
+       # Using `args` to pass positional arguments and `kwargs` for keyword arguments
+       t = threading.Thread(target=crawl, args=(link,), kwargs={"delay": 2})
+       threads.append(t)
+
+   # Start each thread
+   for t in threads:
+       t.start()
+
+   # Wait for all threads to finish
+   for t in threads:
+       t.join()
+
 .. versionchanged:: 3.7
    This module used to be optional, it is now always available.
 
@@ -45,7 +91,25 @@ level :mod:`_thread` module.
    However, threading is still an appropriate model if you want to run
    multiple I/O-bound tasks simultaneously.
 
-.. include:: ../includes/wasm-notavail.rst
+GIL and performance considerations
+----------------------------------
+
+Unlike the :mod:`multiprocessing` module, which uses separate processes to
+bypass the :term:`global interpreter lock` (GIL), the threading module operates
+within a single process, meaning that all threads share the same memory space.
+However, the GIL limits the performance gains of threading when it comes to
+CPU-bound tasks, as only one thread can execute Python bytecode at a time.
+Despite this, threads remain a useful tool for achieving concurrency in many
+scenarios.
+
+As of Python 3.13, experimental :term:`free-threaded <free threading>` builds
+can disable the GIL, enabling true parallel execution of threads, but this
+feature is not available by default (see :pep:`703`).
+
+.. TODO: At some point this feature will become available by default.
+
+Reference
+---------
 
 This module defines the following functions:
 
@@ -62,7 +126,7 @@ This module defines the following functions:
 
    Return the current :class:`Thread` object, corresponding to the caller's thread
    of control.  If the caller's thread of control was not created through the
-   :mod:`threading` module, a dummy thread object with limited functionality is
+   :mod:`!threading` module, a dummy thread object with limited functionality is
    returned.
 
    The function ``currentThread`` is a deprecated alias for this function.
@@ -157,13 +221,13 @@ This module defines the following functions:
 
    .. index:: single: trace function
 
-   Set a trace function for all threads started from the :mod:`threading` module.
+   Set a trace function for all threads started from the :mod:`!threading` module.
    The *func* will be passed to  :func:`sys.settrace` for each thread, before its
    :meth:`~Thread.run` method is called.
 
 .. function:: settrace_all_threads(func)
 
-   Set a trace function for all threads started from the :mod:`threading` module
+   Set a trace function for all threads started from the :mod:`!threading` module
    and all Python threads that are currently executing.
 
    The *func* will be passed to  :func:`sys.settrace` for each thread, before its
@@ -186,13 +250,13 @@ This module defines the following functions:
 
    .. index:: single: profile function
 
-   Set a profile function for all threads started from the :mod:`threading` module.
+   Set a profile function for all threads started from the :mod:`!threading` module.
    The *func* will be passed to  :func:`sys.setprofile` for each thread, before its
    :meth:`~Thread.run` method is called.
 
 .. function:: setprofile_all_threads(func)
 
-   Set a profile function for all threads started from the :mod:`threading` module
+   Set a profile function for all threads started from the :mod:`!threading` module
    and all Python threads that are currently executing.
 
    The *func* will be passed to  :func:`sys.setprofile` for each thread, before its
@@ -257,8 +321,8 @@ when implemented, are mapped to module-level functions.
 All of the methods described below are executed atomically.
 
 
-Thread-Local Data
------------------
+Thread-local data
+^^^^^^^^^^^^^^^^^
 
 Thread-local data is data whose values are thread specific. If you
 have data that you want to be local to a thread, create a
@@ -389,8 +453,8 @@ affects what we see::
 
 .. _thread-objects:
 
-Thread Objects
---------------
+Thread objects
+^^^^^^^^^^^^^^
 
 The :class:`Thread` class represents an activity that is run in a separate
 thread of control.  There are two ways to specify the activity: by passing a
@@ -645,8 +709,8 @@ since it is impossible to detect the termination of alien threads.
 
 .. _lock-objects:
 
-Lock Objects
-------------
+Lock objects
+^^^^^^^^^^^^
 
 A primitive lock is a synchronization primitive that is not owned by a
 particular thread when locked.  In Python, it is currently the lowest level
@@ -738,8 +802,8 @@ All methods are executed atomically.
 
 .. _rlock-objects:
 
-RLock Objects
--------------
+RLock objects
+^^^^^^^^^^^^^
 
 A reentrant lock is a synchronization primitive that may be acquired multiple
 times by the same thread.  Internally, it uses the concepts of "owning thread"
@@ -848,8 +912,8 @@ call release as many times the lock has been acquired can lead to deadlock.
 
 .. _condition-objects:
 
-Condition Objects
------------------
+Condition objects
+^^^^^^^^^^^^^^^^^
 
 A condition variable is always associated with some kind of lock; this can be
 passed in or one will be created by default.  Passing one in is useful when
@@ -1026,8 +1090,8 @@ item to the buffer only needs to wake up one consumer thread.
 
 .. _semaphore-objects:
 
-Semaphore Objects
------------------
+Semaphore objects
+^^^^^^^^^^^^^^^^^
 
 This is one of the oldest synchronization primitives in the history of computer
 science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
@@ -1107,7 +1171,7 @@ Semaphores also support the :ref:`context management protocol <with-locks>`.
 
 .. _semaphore-examples:
 
-:class:`Semaphore` Example
+:class:`Semaphore` example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Semaphores are often used to guard resources with limited capacity, for example,
@@ -1135,8 +1199,8 @@ causes the semaphore to be released more than it's acquired will go undetected.
 
 .. _event-objects:
 
-Event Objects
--------------
+Event objects
+^^^^^^^^^^^^^
 
 This is one of the simplest mechanisms for communication between threads: one
 thread signals an event and other threads wait for it.
@@ -1192,8 +1256,8 @@ method.  The :meth:`~Event.wait` method blocks until the flag is true.
 
 .. _timer-objects:
 
-Timer Objects
--------------
+Timer objects
+^^^^^^^^^^^^^
 
 This class represents an action that should be run only after a certain amount
 of time has passed --- a timer.  :class:`Timer` is a subclass of :class:`Thread`
@@ -1230,8 +1294,8 @@ For example::
       only work if the timer is still in its waiting stage.
 
 
-Barrier Objects
----------------
+Barrier objects
+^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.2