Merge branch 'main' into fix/gzip-seek-write-position

Author: repzakske

Doc/library/mmap.rst

@@ -14,7 +14,8 @@ where :class:`bytearray` are expected; for example, you can use the :mod:`re`
 module to search through a memory-mapped file.  You can also change a single
 byte by doing ``obj[index] = 97``, or change a subsequence by assigning to a
 slice: ``obj[i1:i2] = b'...'``.  You can also read and write data starting at
-the current file position, and :meth:`seek` through the file to different positions.
+the current file position, and :meth:`~mmap.mmap.seek` through the file to
+different positions.
 
 A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is
 different on Unix and on Windows.  In either case you must provide a file
@@ -103,7 +104,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
    *prot*, if specified, gives the desired memory protection; the two most
    useful values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify
    that the pages may be read or written.  *prot* defaults to
-   :const:`PROT_READ \| PROT_WRITE`.
+   :const:`PROT_READ` \| :const:`PROT_WRITE`.
 
    *access* may be specified in lieu of *flags* and *prot* as an optional
    keyword parameter.  It is an error to specify both *flags*, *prot* and
@@ -386,9 +387,55 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
       the mmap was created with :const:`ACCESS_READ`, then writing to it will
       raise a :exc:`TypeError` exception.
 
+.. _access-constants:
+
+ACCESS_* constants
+++++++++++++++++++
+
+.. data:: ACCESS_DEFAULT
+          ACCESS_READ
+          ACCESS_WRITE
+          ACCESS_COPY
+
+   These constants specify the access mode for a memory mapping.
+   :const:`ACCESS_READ` provides read-only access, :const:`ACCESS_WRITE`
+   provides write-through access, and :const:`ACCESS_COPY` provides
+   copy-on-write access. :const:`ACCESS_DEFAULT` defers to the *prot*
+   argument of :class:`mmap`.
+
+.. _page-size-constants:
+
+Page size constants
++++++++++++++++++++
+
+.. data:: PAGESIZE
+          ALLOCATIONGRANULARITY
+
+   :const:`PAGESIZE` is the system memory page size in bytes.
+   :const:`ALLOCATIONGRANULARITY` is the minimum alignment in bytes required
+   for the *offset* argument of :class:`mmap`. On Unix,
+   :const:`ALLOCATIONGRANULARITY` is equal to :const:`PAGESIZE`.
+
+.. _prot-constants:
+
+PROT_* constants
+++++++++++++++++
+
+.. data:: PROT_READ
+          PROT_WRITE
+          PROT_EXEC
+
+   Memory protection flags accepted by the *prot* argument of :class:`mmap`.
+   :const:`PROT_READ` allows pages to be read, :const:`PROT_WRITE` allows pages
+   to be written, and :const:`PROT_EXEC` allows pages to be executed. Values
+   can be combined using the bitwise OR operator. Not every option is present
+   on every system.
+
+   .. availability:: Unix.
+
 .. _madvise-constants:
 
-MADV_* Constants
+MADV_* constants
 ++++++++++++++++
 
 .. data:: MADV_NORMAL
@@ -425,7 +472,7 @@ MADV_* Constants
 
 .. _map-constants:
 
-MAP_* Constants
+MAP_* constants
 +++++++++++++++
 
 .. data:: MAP_SHARED
@@ -472,7 +519,7 @@ MAP_* Constants
 
 .. _ms-constants:
 
-MS_* Constants
+MS_* constants
 ++++++++++++++
 
 .. data:: MS_SYNC

Doc/library/profiling.sampling.rst

@@ -1270,8 +1270,8 @@ The :option:`--compression` option controls data compression:
 
    python -m profiling.sampling run --binary --compression=zstd -o profile.bin script.py
 
-To analyze binary profiles, use the :ref:`replay-command` to convert them to
-other formats like flame graphs or pstats output.
+To analyze binary profiles, use the :ref:`replay command <replay-command>` to convert
+them to other formats like flame graphs or pstats output.
 
 
 Record and replay workflow

Doc/library/wave.rst

@@ -74,11 +74,15 @@ The :mod:`!wave` module defines the following function and exception:
 
    Format code for IEEE floating-point audio.
 
+   .. versionadded:: 3.15
+
 
 .. data:: WAVE_FORMAT_EXTENSIBLE
 
    Format code for WAVE extensible headers.
 
+   .. versionadded:: 3.12
+
 
 .. _wave-read-objects:
 
@@ -281,6 +285,8 @@ Wave_write Objects
       When setting :data:`WAVE_FORMAT_IEEE_FLOAT`, the sample width must be
       4 or 8 bytes.
 
+      .. versionadded:: 3.15
+
 
    .. method:: getformat()
 
@@ -300,6 +306,9 @@ Wave_write Objects
 
       For ``format=WAVE_FORMAT_IEEE_FLOAT``, *sampwidth* must be 4 or 8.
 
+      .. versionchanged:: 3.15
+         Added optional item *format* to the *tuple*.
+
 
    .. method:: getparams()
 

Doc/tools/.nitignore

@@ -8,7 +8,6 @@ Doc/library/email.charset.rst
 Doc/library/email.parser.rst
 Doc/library/logging.config.rst
 Doc/library/logging.handlers.rst
-Doc/library/mmap.rst
 Doc/library/multiprocessing.rst
 Doc/library/optparse.rst
 Doc/library/pickletools.rst

Lib/asyncio/unix_events.py

@@ -968,7 +968,15 @@ def _do_waitpid(self, loop, expected_pid, callback, args):
             # This makes the reaping of the child and notification of the return code
             # atomic with respect to the event loop thread.
             try:
-                os.waitid(os.P_PID, expected_pid, os.WEXITED | os.WNOWAIT)
+                while True:
+                    res = os.waitid(os.P_PID, expected_pid, os.WEXITED | os.WNOWAIT)
+                    # On macOS, waitid() with WEXITED incorrectly returns stopped
+                    # child processes (si_code == CLD_STOPPED). Consume the stop
+                    # notification so we wait for actual process termination.
+                    if res.si_code == os.CLD_STOPPED:
+                        os.waitid(os.P_PID, expected_pid, os.WSTOPPED | os.WNOHANG)
+                        continue
+                    break
             except ChildProcessError:
                 # The child process is already reaped
                 pass

Lib/test/test_asyncio/test_subprocess.py

@@ -3,6 +3,7 @@
 import signal
 import sys
 import textwrap
+import threading
 import unittest
 import warnings
 from unittest import mock
@@ -1162,6 +1163,63 @@ async def run():
 
             self.loop.run_until_complete(run())
 
+        @unittest.skipUnless(hasattr(os, 'waitid'), 'needs os.waitid()')
+        @unittest.skipUnless(hasattr(signal, 'SIGSTOP'), 'needs SIGSTOP')
+        def test_stopped_child_does_not_block_event_loop(self):
+            # gh-158287: on macOS, waitid() with WEXITED incorrectly reports
+            # stopped children (si_code == CLD_STOPPED). The child watcher
+            # must not mistake this for process termination and attempt to reap
+            # the child with waitpid(), which blocks the event loop thread.
+            proc = None
+            timed_out = False
+
+            def watchdog():
+                nonlocal timed_out
+                timed_out = True
+                # If the event loop gets stuck in waitpid() because of this bug,
+                # killing the child process unblocks waitpid() so the test fails
+                # instead of hanging indefinitely.
+                if proc is not None:
+                    if hasattr(signal, 'SIGCONT'):
+                        try:
+                            os.kill(proc.pid, signal.SIGCONT)
+                        except ProcessLookupError:
+                            pass
+                    try:
+                        os.kill(proc.pid, signal.SIGKILL)
+                    except ProcessLookupError:
+                        pass
+
+            timer = threading.Timer(support.SHORT_TIMEOUT, watchdog)
+            timer.start()
+            try:
+                async def run():
+                    nonlocal proc
+                    proc = await asyncio.create_subprocess_exec(*PROGRAM_BLOCKED)
+                    try:
+                        proc.send_signal(signal.SIGSTOP)
+                        # Verify event loop remains responsive while child is stopped
+                        for _ in range(3):
+                            await asyncio.sleep(0.05)
+                        self.assertFalse(timed_out, "event loop was blocked by stopped child")
+                        self.assertIsNone(proc.returncode)
+                    finally:
+                        if hasattr(signal, 'SIGCONT'):
+                            try:
+                                proc.send_signal(signal.SIGCONT)
+                            except ProcessLookupError:
+                                pass
+                        try:
+                            proc.kill()
+                        except ProcessLookupError:
+                            pass
+                        await proc.wait()
+
+                self.loop.run_until_complete(run())
+            finally:
+                timer.cancel()
+                timer.join()
+
     @unittest.skipUnless(
         unix_events.can_use_pidfd(),
         "operating system does not support pidfds",

Lib/test/test_descr.py

@@ -2231,10 +2231,22 @@ def some_number(self_, key):
         def swallow(*args): pass
         def format_impl(self, spec):
             return "hello"
-
-        # It would be nice to have every special method tested here, but I'm
-        # only listing the ones I can remember outside of typeobject.c, since it
-        # does it right.
+        def do_eq(obj):
+            return obj == 1
+        def do_ne(obj):
+            return obj != 1
+        def do_lt(obj):
+            return obj < 1
+        def do_le(obj):
+            return obj <= 1
+        def do_gt(obj):
+            return obj > 1
+        def do_ge(obj):
+            return obj >= 1
+
+        # It would be nice to have every special method tested here.
+        # gh-131151: the rich comparison operators used to clear any exception
+        # raised by a descriptor's __get__.
         specials = [
             ("__bytes__", bytes, hello, set(), {}),
             ("__reversed__", reversed, empty_seq, set(), {}),
@@ -2255,6 +2267,12 @@ def format_impl(self, spec):
             ("__ceil__", math.ceil, zero, set(), {}),
             ("__dir__", dir, empty_seq, set(), {}),
             ("__round__", round, zero, set(), {}),
+            ("__eq__", do_eq, return_true, set(), {}),
+            ("__ne__", do_ne, return_true, set(), {}),
+            ("__lt__", do_lt, return_true, set(), {}),
+            ("__le__", do_le, return_true, set(), {}),
+            ("__gt__", do_gt, return_true, set(), {}),
+            ("__ge__", do_ge, return_true, set(), {}),
             ]
 
         class Checker(object):

Lib/test/test_profiling/test_sampling_profiler/test_children.py

@@ -16,6 +16,7 @@
     SHORT_TIMEOUT,
     reap_children,
     requires_remote_subprocess_debugging,
+    sleeping_retry,
 )
 
 # Guard imports that require _remote_debugging module.
@@ -84,29 +85,13 @@ def reader():
     return result[0]
 
 
-def _wait_for_process_ready(proc, timeout):
-    # Wait for a subprocess to be ready using polling instead of fixed sleep.
-    # Returns True if process is ready, False if it exited or timeout.
-    deadline = time.time() + timeout
-    poll_interval = 0.01
-
-    while time.time() < deadline:
-        if proc.poll() is not None:
-            return False
-
-        try:
-            if sys.platform == "linux":
-                if os.path.exists(f"/proc/{proc.pid}/exe"):
-                    return True
-            else:
-                return True
-        except OSError:
-            pass
-
-        time.sleep(poll_interval)
-        poll_interval = min(poll_interval * 2, 0.1)
-
-    return proc.poll() is None
+def _wait_for_process_exec(proc, name, timeout):
+    # Wait until a child process calls exec() to replace the forked process
+    # executable. Raise AssertionError on timeout.
+    for _ in sleeping_retry(timeout, max_delay=0.1):
+        exe = os.readlink(f"/proc/{proc.pid}/exe")
+        if os.path.basename(exe) == name:
+            break
 
 
 @unittest.skipIf(
@@ -634,17 +619,13 @@ def test_is_python_process_non_python_subprocess(self):
         """Test that a non-Python subprocess is not detected as Python."""
         # Start a non-Python subprocess (sleep command)
         proc = subprocess.Popen(
-            ["sleep", "10"],
+            ["sleep", "60"],
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
         )
 
         try:
-            # Wait for process to be ready using polling
-            self.assertTrue(
-                _wait_for_process_ready(proc, SHORT_TIMEOUT),
-                f"Process {proc.pid} should be ready within {SHORT_TIMEOUT}s",
-            )
+            _wait_for_process_exec(proc, "sleep", SHORT_TIMEOUT)
 
             self.assertFalse(
                 is_python_process(proc.pid),

Misc/NEWS.d/next/Library/2026-10-07-17-30-00.gh-issue-158287.xY9zQp.rst

@@ -0,0 +1 @@
+Fix a bug in :mod:`asyncio` where stopping a child process (such as with ``SIGSTOP``) on macOS caused the event loop to block indefinitely.