Merge in the main branch

Author: encukou

Android/android.py

@@ -50,7 +50,19 @@
     + (".bat" if os.name == "nt" else "")
 )
 
-logcat_started = False
+# Whether we've seen any output from Python yet.
+python_started = False
+
+# Buffer for verbose output which will be displayed only if a test fails and
+# there has been no output from Python.
+hidden_output = []
+
+
+def log_verbose(context, line, stream=sys.stdout):
+    if context.verbose:
+        stream.write(line)
+    else:
+        hidden_output.append((stream, line))
 
 
 def delete_glob(pattern):
@@ -118,7 +130,7 @@ def android_env(host):
     env_script = ANDROID_DIR / "android-env.sh"
     env_output = subprocess.run(
         f"set -eu; "
-        f"export HOST={host}; "
+        f"HOST={host}; "
         f"PREFIX={prefix}; "
         f". {env_script}; "
         f"export",
@@ -453,17 +465,19 @@ async def logcat_task(context, initial_devices):
 
     # `--pid` requires API level 24 or higher.
     args = [adb, "-s", serial, "logcat", "--pid", pid,  "--format", "tag"]
-    hidden_output = []
+    logcat_started = False
     async with async_process(
         *args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
     ) as process:
         while line := (await process.stdout.readline()).decode(*DECODE_ARGS):
             if match := re.fullmatch(r"([A-Z])/(.*)", line, re.DOTALL):
+                logcat_started = True
                 level, message = match.groups()
             else:
-                # If the regex doesn't match, this is probably the second or
-                # subsequent line of a multi-line message. Python won't produce
-                # such messages, but other components might.
+                # If the regex doesn't match, this is either a logcat startup
+                # error, or the second or subsequent line of a multi-line
+                # message. Python won't produce multi-line messages, but other
+                # components might.
                 level, message = None, line
 
             # Exclude high-volume messages which are rarely useful.
@@ -483,25 +497,22 @@ async def logcat_task(context, initial_devices):
             # tag indicators from Python's stdout and stderr.
             for prefix in ["python.stdout: ", "python.stderr: "]:
                 if message.startswith(prefix):
-                    global logcat_started
-                    logcat_started = True
+                    global python_started
+                    python_started = True
                     stream.write(message.removeprefix(prefix))
                     break
             else:
-                if context.verbose:
-                    # Non-Python messages add a lot of noise, but they may
-                    # sometimes help explain a failure.
-                    stream.write(line)
-                else:
-                    hidden_output.append(line)
+                # Non-Python messages add a lot of noise, but they may
+                # sometimes help explain a failure.
+                log_verbose(context, line, stream)
 
         # If the device disconnects while logcat is running, which always
         # happens in --managed mode, some versions of adb return non-zero.
         # Distinguish this from a logcat startup error by checking whether we've
-        # received a message from Python yet.
+        # received any logcat messages yet.
         status = await wait_for(process.wait(), timeout=1)
         if status != 0 and not logcat_started:
-            raise CalledProcessError(status, args, "".join(hidden_output))
+            raise CalledProcessError(status, args)
 
 
 def stop_app(serial):
@@ -516,16 +527,6 @@ async def gradle_task(context):
         task_prefix = "connected"
         env["ANDROID_SERIAL"] = context.connected
 
-    hidden_output = []
-
-    def log(line):
-        # Gradle may take several minutes to install SDK packages, so it's worth
-        # showing those messages even in non-verbose mode.
-        if context.verbose or line.startswith('Preparing "Install'):
-            sys.stdout.write(line)
-        else:
-            hidden_output.append(line)
-
     if context.command:
         mode = "-c"
         module = context.command
@@ -550,27 +551,27 @@ def log(line):
     ]
     if context.verbose >= 2:
         args.append("--info")
-    log("> " + join_command(args))
+    log_verbose(context, f"> {join_command(args)}\n")
 
     try:
         async with async_process(
             *args, cwd=TESTBED_DIR, env=env,
             stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
         ) as process:
             while line := (await process.stdout.readline()).decode(*DECODE_ARGS):
-                log(line)
+                # Gradle may take several minutes to install SDK packages, so
+                # it's worth showing those messages even in non-verbose mode.
+                if line.startswith('Preparing "Install'):
+                    sys.stdout.write(line)
+                else:
+                    log_verbose(context, line)
 
             status = await wait_for(process.wait(), timeout=1)
             if status == 0:
                 exit(0)
             else:
                 raise CalledProcessError(status, args)
     finally:
-        # If logcat never started, then something has gone badly wrong, so the
-        # user probably wants to see the Gradle output even in non-verbose mode.
-        if hidden_output and not logcat_started:
-            sys.stdout.write("".join(hidden_output))
-
         # Gradle does not stop the tests when interrupted.
         if context.connected:
             stop_app(context.connected)
@@ -600,6 +601,12 @@ async def run_testbed(context):
     except* MySystemExit as e:
         raise SystemExit(*e.exceptions[0].args) from None
     except* CalledProcessError as e:
+        # If Python produced no output, then the user probably wants to see the
+        # verbose output to explain why the test failed.
+        if not python_started:
+            for stream, line in hidden_output:
+                stream.write(line)
+
         # Extract it from the ExceptionGroup so it can be handled by `main`.
         raise e.exceptions[0]
 

Doc/c-api/init.rst

@@ -2306,6 +2306,12 @@ is resumed, and its locks reacquired.  This means the critical section API
 provides weaker guarantees than traditional locks -- they are useful because
 their behavior is similar to the :term:`GIL`.
 
+Variants that accept :c:type:`PyMutex` pointers rather than Python objects are also
+available. Use these variants to start a critical section in a situation where
+there is no :c:type:`PyObject` -- for example, when working with a C type that
+does not extend or wrap :c:type:`PyObject` but still needs to call into the C
+API in a manner that might lead to deadlocks.
+
 The functions and structs used by the macros are exposed for cases
 where C macros are not available. They should only be used as in the
 given macro expansions. Note that the sizes and contents of the structures may
@@ -2351,6 +2357,23 @@ code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
 
    .. versionadded:: 3.13
 
+.. c:macro:: Py_BEGIN_CRITICAL_SECTION_MUTEX(m)
+
+   Locks the mutex *m* and begins a critical section.
+
+   In the free-threaded build, this macro expands to::
+
+     {
+          PyCriticalSection _py_cs;
+          PyCriticalSection_BeginMutex(&_py_cs, m)
+
+   Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION`, there is no cast for
+   the argument of the macro - it must be a :c:type:`PyMutex` pointer.
+
+   On the default build, this macro expands to ``{``.
+
+   .. versionadded:: next
+
 .. c:macro:: Py_END_CRITICAL_SECTION()
 
    Ends the critical section and releases the per-object lock.
@@ -2380,6 +2403,23 @@ code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
 
    .. versionadded:: 3.13
 
+.. c:macro:: Py_BEGIN_CRITICAL_SECTION2_MUTEX(m1, m2)
+
+   Locks the mutexes *m1* and *m2* and begins a critical section.
+
+   In the free-threaded build, this macro expands to::
+
+     {
+          PyCriticalSection2 _py_cs2;
+          PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)
+
+   Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, there is no cast for
+   the arguments of the macro - they must be :c:type:`PyMutex` pointers.
+
+   On the default build, this macro expands to ``{``.
+
+   .. versionadded:: next
+
 .. c:macro:: Py_END_CRITICAL_SECTION2()
 
    Ends the critical section and releases the per-object locks.

Doc/howto/logging.rst

@@ -302,10 +302,10 @@ reading the following sections. If you're ready for that, grab some of your
 favourite beverage and carry on.
 
 If your logging needs are simple, then use the above examples to incorporate
-logging into your own scripts, and if you run into problems or don't
-understand something, please post a question on the comp.lang.python Usenet
-group (available at https://groups.google.com/g/comp.lang.python) and you
-should receive help before too long.
+logging into your own scripts, and if you run into problems or don't understand
+something, please post a question in the Help category of the `Python
+discussion forum <https://discuss.python.org/c/help/7>`_ and you should receive
+help before too long.
 
 Still here? You can carry on reading the next few sections, which provide a
 slightly more advanced/in-depth tutorial than the basic one above. After that,

Doc/library/enum.rst

@@ -504,16 +504,31 @@ Data Types
 
 .. class:: StrEnum
 
-   ``StrEnum`` is the same as :class:`Enum`, but its members are also strings and can be used
-   in most of the same places that a string can be used.  The result of any string
-   operation performed on or with a *StrEnum* member is not part of the enumeration.
+   *StrEnum* is the same as :class:`Enum`, but its members are also strings and
+   can be used in most of the same places that a string can be used. The result
+   of any string operation performed on or with a *StrEnum* member is not part
+   of the enumeration.
+
+   >>> from enum import StrEnum, auto
+   >>> class Color(StrEnum):
+   ...     RED = 'r'
+   ...     GREEN = 'g'
+   ...     BLUE = 'b'
+   ...     UNKNOWN = auto()
+   ...
+   >>> Color.RED
+   <Color.RED: 'r'>
+   >>> Color.UNKNOWN
+   <Color.UNKNOWN: 'unknown'>
+   >>> str(Color.UNKNOWN)
+   'unknown'
 
    .. note::
 
       There are places in the stdlib that check for an exact :class:`str`
       instead of a :class:`str` subclass (i.e. ``type(unknown) == str``
       instead of ``isinstance(unknown, str)``), and in those locations you
-      will need to use ``str(StrEnum.member)``.
+      will need to use ``str(MyStrEnum.MY_MEMBER)``.
 
    .. note::
 

Doc/library/os.path.rst

@@ -64,7 +64,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: basename(path)
+.. function:: basename(path, /)
 
    Return the base name of pathname *path*.  This is the second element of the
    pair returned by passing *path* to the function :func:`split`.  Note that
@@ -118,7 +118,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: dirname(path)
+.. function:: dirname(path, /)
 
    Return the directory name of pathname *path*.  This is the first element of
    the pair returned by passing *path* to the function :func:`split`.
@@ -237,7 +237,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: isabs(path)
+.. function:: isabs(path, /)
 
    Return ``True`` if *path* is an absolute pathname.  On Unix, that means it
    begins with a slash, on Windows that it begins with two (back)slashes, or a
@@ -261,7 +261,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: isdir(path)
+.. function:: isdir(path, /)
 
    Return ``True`` if *path* is an :func:`existing <exists>` directory.  This
    follows symbolic links, so both :func:`islink` and :func:`isdir` can be true
@@ -372,7 +372,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object` for *path* and *paths*.
 
 
-.. function:: normcase(path)
+.. function:: normcase(path, /)
 
    Normalize the case of a pathname.  On Windows, convert all characters in the
    pathname to lowercase, and also convert forward slashes to backward slashes.
@@ -509,7 +509,7 @@ the :mod:`glob` module.)
       Added Windows support.
 
 
-.. function:: split(path)
+.. function:: split(path, /)
 
    Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the
    last pathname component and *head* is everything leading up to that.  The
@@ -525,7 +525,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: splitdrive(path)
+.. function:: splitdrive(path, /)
 
    Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either
    a mount point or the empty string.  On systems which do not use drive
@@ -550,7 +550,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: splitroot(path)
+.. function:: splitroot(path, /)
 
    Split the pathname *path* into a 3-item tuple ``(drive, root, tail)`` where
    *drive* is a device name or mount point, *root* is a string of separators
@@ -583,7 +583,7 @@ the :mod:`glob` module.)
    .. versionadded:: 3.12
 
 
-.. function:: splitext(path)
+.. function:: splitext(path, /)
 
    Split the pathname *path* into a pair ``(root, ext)``  such that ``root + ext ==
    path``, and the extension, *ext*, is empty or begins with a period and contains at

Doc/library/sys.rst

@@ -2191,8 +2191,11 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 
 .. data:: api_version
 
-   The C API version for this interpreter.  Programmers may find this useful when
-   debugging version conflicts between Python and extension modules.
+   The C API version, equivalent to the C macro :c:macro:`PYTHON_API_VERSION`.
+   Defined for backwards compatibility.
+
+   Currently, this constant is not updated in new Python versions, and is not
+   useful for versioning. This may change in the future.
 
 
 .. data:: version_info

Doc/library/urllib.request.rst

@@ -210,6 +210,9 @@ The :mod:`urllib.request` module defines the following functions:
       Windows a UNC path is returned (as before), and on other platforms a
       :exc:`~urllib.error.URLError` is raised.
 
+   .. versionchanged:: 3.14
+      The URL query and fragment components are discarded if present.
+
    .. versionchanged:: 3.14
       The *require_scheme* and *resolve_host* parameters were added.
 

Doc/library/zipfile.rst

@@ -558,14 +558,6 @@ The following data attributes are also available:
    it should be no longer than 65535 bytes.  Comments longer than this will be
    truncated.
 
-.. attribute:: ZipFile.data_offset
-
-   The offset to the start of ZIP data from the beginning of the file. When the
-   :class:`ZipFile` is opened in either mode ``'w'`` or ``'x'`` and the
-   underlying file does not support ``tell()``, the value will be ``None``
-   instead.
-
-   .. versionadded:: 3.14
 
 .. _path-objects:
 

Doc/tutorial/modules.rst

@@ -579,8 +579,8 @@ module for example, you might use::
    from .. import formats
    from ..filters import equalizer
 
-Note that relative imports are based on the name of the current module.  Since
-the name of the main module is always ``"__main__"``, modules intended for use
+Note that relative imports are based on the name of the current module's package.
+Since the main module does not have a package, modules intended for use
 as the main module of a Python application must always use absolute imports.