Merge remote-tracking branch 'cpython/main' into pythongh-99726-2

Author: zooba

.github/workflows/build.yml

@@ -162,13 +162,11 @@ jobs:
     - uses: actions/checkout@v3
     - name: Install Homebrew dependencies
       run: brew install pkg-config openssl@1.1 xz gdbm tcl-tk
-    - name: Prepare Homebrew environment variables
-      run: |
-        echo "CFLAGS=-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix gdbm)/lib -I$(brew --prefix xz)/lib" >> $GITHUB_ENV
-        echo "PKG_CONFIG_PATH=$(brew --prefix openssl@1.1)/lib/pkgconfig:$(brew --prefix tcl-tk)/lib/pkgconfig" >> $GITHUB_ENV
     - name: Configure CPython
       run: |
+        CFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \
+        LDFLAGS="-L$(brew --prefix gdbm)/lib -I$(brew --prefix xz)/lib" \
+        PKG_CONFIG_PATH="$(brew --prefix tcl-tk)/lib/pkgconfig" \
         ./configure \
           --with-pydebug \
           --prefix=/opt/python-dev \

Doc/bugs.rst

@@ -70,7 +70,7 @@ Click on the "New issue" button in the top bar to report a new issue.
 The submission form has two fields, "Title" and "Comment".
 
 For the "Title" field, enter a *very* short description of the problem;
-less than ten words is good.
+fewer than ten words is good.
 
 In the "Comment" field, describe the problem in detail, including what you
 expected to happen and what did happen.  Be sure to include whether any

Doc/c-api/init.rst

@@ -818,7 +818,7 @@ Process-wide parameters
    .. deprecated:: 3.11
 
 
-.. c:function:: w_char* Py_GetPythonHome()
+.. c:function:: wchar_t* Py_GetPythonHome()
 
    Return the default "home", that is, the value set by a previous call to
    :c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`

Doc/howto/logging-cookbook.rst

@@ -2538,7 +2538,7 @@ should be logged, or the ``extra`` keyword parameter to indicate additional
 contextual information to be added to the log). So you cannot directly make
 logging calls using :meth:`str.format` or :class:`string.Template` syntax,
 because internally the logging package uses %-formatting to merge the format
-string and the variable arguments. There would no changing this while preserving
+string and the variable arguments. There would be no changing this while preserving
 backward compatibility, since all logging calls which are out there in existing
 code will be using %-format strings.
 

Doc/library/asyncio-eventloop.rst

@@ -524,8 +524,8 @@ Opening network connections
       When a server's IPv4 path and protocol are working, but the server's
       IPv6 path and protocol are not working, a dual-stack client
       application experiences significant connection delay compared to an
-      IPv4-only client.  This is undesirable because it causes the dual-
-      stack client to have a worse user experience.  This document
+      IPv4-only client.  This is undesirable because it causes the
+      dual-stack client to have a worse user experience.  This document
       specifies requirements for algorithms that reduce this user-visible
       delay and provides an algorithm.
 

Doc/library/decimal.rst

@@ -118,7 +118,8 @@ another rational number, or from a string.
    .. method:: as_integer_ratio()
 
       Return a tuple of two integers, whose ratio is equal
-      to the Fraction and with a positive denominator.
+      to the original Fraction.  The ratio is in lowest terms
+      and has a positive denominator.
 
       .. versionadded:: 3.8
 

Doc/library/fractions.rst

@@ -623,7 +623,7 @@ are always available.  They are listed here in alphabetical order.
 .. function:: filter(function, iterable)
 
    Construct an iterator from those elements of *iterable* for which *function*
-   returns true.  *iterable* may be either a sequence, a container which
+   is true.  *iterable* may be either a sequence, a container which
    supports iteration, or an iterator.  If *function* is ``None``, the identity
    function is assumed, that is, all elements of *iterable* that are false are
    removed.
@@ -634,7 +634,7 @@ are always available.  They are listed here in alphabetical order.
    ``None``.
 
    See :func:`itertools.filterfalse` for the complementary function that returns
-   elements of *iterable* for which *function* returns false.
+   elements of *iterable* for which *function* is false.
 
 
 .. class:: float(x=0.0)

Doc/library/functions.rst

@@ -86,6 +86,14 @@ The :mod:`functools` module defines the following functions:
    The cached value can be cleared by deleting the attribute.  This
    allows the *cached_property* method to run again.
 
+   The *cached_property* does not prevent a possible race condition in
+   multi-threaded usage. The getter function could run more than once on the
+   same instance, with the latest run setting the cached value. If the cached
+   property is idempotent or otherwise not harmful to run more than once on an
+   instance, this is fine. If synchronization is needed, implement the necessary
+   locking inside the decorated getter function or around the cached property
+   access.
+
    Note, this decorator interferes with the operation of :pep:`412`
    key-sharing dictionaries.  This means that instance dictionaries
    can take more space than usual.
@@ -110,6 +118,14 @@ The :mod:`functools` module defines the following functions:
            def stdev(self):
                return statistics.stdev(self._data)
 
+
+   .. versionchanged:: 3.12
+      Prior to Python 3.12, ``cached_property`` included an undocumented lock to
+      ensure that in multi-threaded usage the getter function was guaranteed to
+      run only once per instance. However, the lock was per-property, not
+      per-instance, which could result in unacceptably high lock contention. In
+      Python 3.12+ this locking is removed.
+
    .. versionadded:: 3.8
 
 

Doc/library/functools.rst

@@ -802,8 +802,9 @@ function.
 
    .. attribute:: Parameter.kind
 
-      Describes how argument values are bound to the parameter.  Possible values
-      (accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``):
+      Describes how argument values are bound to the parameter.  The possible
+      values are accessible via :class:`Parameter` (like ``Parameter.KEYWORD_ONLY``),
+      and support comparison and ordering, in the following order:
 
       .. tabularcolumns:: |l|L|
 

Doc/library/inspect.rst

@@ -398,7 +398,7 @@ loops that truncate the stream.
 .. function:: filterfalse(predicate, iterable)
 
    Make an iterator that filters elements from iterable returning only those for
-   which the predicate is ``False``. If *predicate* is ``None``, return the items
+   which the predicate is false. If *predicate* is ``None``, return the items
    that are false. Roughly equivalent to::
 
       def filterfalse(predicate, iterable):
@@ -831,7 +831,7 @@ which incur interpreter overhead.
        return next(g, True) and not next(g, False)
 
    def quantify(iterable, pred=bool):
-       "Count how many times the predicate is true"
+       "Count how many times the predicate is True"
        return sum(map(pred, iterable))
 
    def ncycles(iterable, n):

Doc/library/itertools.rst

@@ -370,11 +370,19 @@ MAP_* Constants
           MAP_ANONYMOUS
           MAP_POPULATE
           MAP_STACK
+          MAP_ALIGNED_SUPER
+          MAP_CONCEAL
 
-    These are the various flags that can be passed to :meth:`mmap.mmap`. Note that some options might not be present on some systems.
+    These are the various flags that can be passed to :meth:`mmap.mmap`.  :data:`MAP_ALIGNED_SUPER`
+    is only available at FreeBSD and :data:`MAP_CONCEAL` is only available at OpenBSD.  Note
+    that some options might not be present on some systems.
 
     .. versionchanged:: 3.10
-       Added MAP_POPULATE constant.
+       Added :data:`MAP_POPULATE` constant.
 
     .. versionadded:: 3.11
-       Added MAP_STACK constant.
+       Added :data:`MAP_STACK` constant.
+
+    .. versionadded:: 3.12
+       Added :data:`MAP_ALIGNED_SUPER` constant.
+       Added :data:`MAP_CONCEAL` constant.

Doc/library/mmap.rst

@@ -63,7 +63,7 @@ Cross Platform
    string is returned if the value cannot be determined.
 
 
-.. function:: platform(aliased=0, terse=0)
+.. function:: platform(aliased=False, terse=False)
 
    Returns a single string identifying the underlying platform with as much useful
    information as possible.

Doc/library/platform.rst

@@ -15,7 +15,7 @@ module implements all the required locking semantics.
 
 The module implements three types of queue, which differ only in the order in
 which the entries are retrieved.  In a :abbr:`FIFO (first-in, first-out)`
-queue, the first tasks added are the first retrieved. In a
+queue, the first tasks added are the first retrieved.  In a
 :abbr:`LIFO (last-in, first-out)` queue, the most recently added entry is
 the first retrieved (operating like a stack).  With a priority queue,
 the entries are kept sorted (using the :mod:`heapq` module) and the
@@ -57,7 +57,7 @@ The :mod:`queue` module defines the following classes and exceptions:
    *maxsize* is less than or equal to zero, the queue size is infinite.
 
    The lowest valued entries are retrieved first (the lowest valued entry is the
-   one that would be returned by ``min(entries)``). A typical pattern for
+   one that would be returned by ``min(entries)``).  A typical pattern for
    entries is a tuple in the form: ``(priority_number, data)``.
 
    If the *data* elements are not comparable, the data can be wrapped in a class
@@ -127,8 +127,8 @@ provide the public methods described below.
 
 .. method:: Queue.put(item, block=True, timeout=None)
 
-   Put *item* into the queue. If optional args *block* is true and *timeout* is
-   ``None`` (the default), block if necessary until a free slot is available. If
+   Put *item* into the queue.  If optional args *block* is true and *timeout* is
+   ``None`` (the default), block if necessary until a free slot is available.  If
    *timeout* is a positive number, it blocks at most *timeout* seconds and raises
    the :exc:`Full` exception if no free slot was available within that time.
    Otherwise (*block* is false), put an item on the queue if a free slot is
@@ -143,7 +143,7 @@ provide the public methods described below.
 
 .. method:: Queue.get(block=True, timeout=None)
 
-   Remove and return an item from the queue. If optional args *block* is true and
+   Remove and return an item from the queue.  If optional args *block* is true and
    *timeout* is ``None`` (the default), block if necessary until an item is available.
    If *timeout* is a positive number, it blocks at most *timeout* seconds and
    raises the :exc:`Empty` exception if no item was available within that time.
@@ -152,7 +152,7 @@ provide the public methods described below.
 
    Prior to 3.0 on POSIX systems, and for all versions on Windows, if
    *block* is true and *timeout* is ``None``, this operation goes into
-   an uninterruptible wait on an underlying lock. This means that no exceptions
+   an uninterruptible wait on an underlying lock.  This means that no exceptions
    can occur, and in particular a SIGINT will not trigger a :exc:`KeyboardInterrupt`.
 
 
@@ -184,7 +184,7 @@ fully processed by daemon consumer threads.
 
    The count of unfinished tasks goes up whenever an item is added to the queue.
    The count goes down whenever a consumer thread calls :meth:`task_done` to
-   indicate that the item was retrieved and all work on it is complete. When the
+   indicate that the item was retrieved and all work on it is complete.  When the
    count of unfinished tasks drops to zero, :meth:`join` unblocks.
 
 
@@ -227,7 +227,7 @@ SimpleQueue Objects
 
 .. method:: SimpleQueue.empty()
 
-   Return ``True`` if the queue is empty, ``False`` otherwise. If empty()
+   Return ``True`` if the queue is empty, ``False`` otherwise.  If empty()
    returns ``False`` it doesn't guarantee that a subsequent call to get()
    will not block.
 

Doc/library/queue.rst

@@ -271,7 +271,8 @@ The special characters are:
 
    * To match a literal ``']'`` inside a set, precede it with a backslash, or
      place it at the beginning of the set.  For example, both ``[()[\]{}]`` and
-     ``[]()[{}]`` will both match a parenthesis.
+     ``[]()[{}]`` will match a right bracket, as well as left bracket, braces,
+     and parentheses.
 
    .. .. index:: single: --; in regular expressions
    .. .. index:: single: &&; in regular expressions

Doc/library/re.rst

@@ -602,8 +602,8 @@ class`. In addition, it provides a few more methods:
 
 .. method:: int.as_integer_ratio()
 
-   Return a pair of integers whose ratio is exactly equal to the original
-   integer and with a positive denominator. The integer ratio of integers
+   Return a pair of integers whose ratio is equal to the original
+   integer and has a positive denominator.  The integer ratio of integers
    (whole numbers) is always the integer as the numerator and ``1`` as the
    denominator.
 
@@ -624,7 +624,7 @@ class`. float also has the following additional methods.
 .. method:: float.as_integer_ratio()
 
    Return a pair of integers whose ratio is exactly equal to the
-   original float and with a positive denominator.  Raises
+   original float. The ratio is in lowest terms and has a positive denominator.  Raises
    :exc:`OverflowError` on infinities and a :exc:`ValueError` on
    NaNs.
 

Doc/library/stdtypes.rst

@@ -371,7 +371,7 @@ ordering::
     >>> from struct import *
     >>> pack(">bhl", 1, 2, 3)
     b'\x01\x00\x02\x00\x00\x00\x03'
-    >>> unpack('>bhl', b'\x01\x00\x02\x00\x00\x00\x03'
+    >>> unpack('>bhl', b'\x01\x00\x02\x00\x00\x00\x03')
     (1, 2, 3)
     >>> calcsize('>bhl')
     7

Doc/library/struct.rst

@@ -2444,6 +2444,9 @@ The demo scripts are:
 | planet_and_moon| simulation of                | compound shapes,      |
 |                | gravitational system         | :class:`Vec2D`        |
 +----------------+------------------------------+-----------------------+
+| rosette        | a pattern from the wikipedia | :func:`clone`,        |
+|                | article on turtle graphics   | :func:`undo`          |
++----------------+------------------------------+-----------------------+
 | round_dance    | dancing turtles rotating     | compound shapes, clone|
 |                | pairwise in opposite         | shapesize, tilt,      |
 |                | direction                    | get_shapepoly, update |
@@ -2457,9 +2460,6 @@ The demo scripts are:
 | two_canvases   | simple design                | turtles on two        |
 |                |                              | canvases              |
 +----------------+------------------------------+-----------------------+
-| wikipedia      | a pattern from the wikipedia | :func:`clone`,        |
-|                | article on turtle graphics   | :func:`undo`          |
-+----------------+------------------------------+-----------------------+
 | yinyang        | another elementary example   | :func:`circle`        |
 +----------------+------------------------------+-----------------------+
 

Doc/library/turtle.rst

@@ -486,7 +486,7 @@ Coroutine Utility Functions
    The generator-based coroutine is still a :term:`generator iterator`,
    but is also considered to be a :term:`coroutine` object and is
    :term:`awaitable`.  However, it may not necessarily implement
-   the :meth:`__await__` method.
+   the :meth:`~object.__await__` method.
 
    If *gen_func* is a generator function, it will be modified in-place.
 

Doc/library/types.rst

@@ -91,6 +91,8 @@ annotations. These include:
     *Introducing* :data:`LiteralString`
 * :pep:`681`: Data Class Transforms
     *Introducing* the :func:`@dataclass_transform<dataclass_transform>` decorator
+* :pep:`698`: Adding an override decorator to typing
+    *Introducing* the :func:`@override<override>` decorator
 
 .. _type-aliases:
 
@@ -1588,7 +1590,7 @@ These are not used in annotations. They are building blocks for creating generic
         methods, not their type signatures. For example, :class:`ssl.SSLObject`
         is a class, therefore it passes an :func:`issubclass`
         check against :data:`Callable`.  However, the
-        :meth:`ssl.SSLObject.__init__` method exists only to raise a
+        ``ssl.SSLObject.__init__`` method exists only to raise a
         :exc:`TypeError` with a more informative message, therefore making
         it impossible to call (instantiate) :class:`ssl.SSLObject`.
 
@@ -2722,6 +2724,42 @@ Functions and decorators
    This wraps the decorator with something that wraps the decorated
    function in :func:`no_type_check`.
 
+
+.. decorator:: override
+
+   A decorator for methods that indicates to type checkers that this method
+   should override a method or attribute with the same name on a base class.
+   This helps prevent bugs that may occur when a base class is changed without
+   an equivalent change to a child class.
+
+   For example::
+
+      class Base:
+           def log_status(self)
+
+      class Sub(Base):
+          @override
+          def log_status(self) -> None:  # Okay: overrides Base.log_status
+              ...
+
+          @override
+          def done(self) -> None:  # Error reported by type checker
+              ...
+
+   There is no runtime checking of this property.
+
+   The decorator will set the ``__override__`` attribute to ``True`` on
+   the decorated object. Thus, a check like
+   ``if getattr(obj, "__override__", False)`` can be used at runtime to determine
+   whether an object ``obj`` has been marked as an override.  If the decorated object
+   does not support setting attributes, the decorator returns the object unchanged
+   without raising an exception.
+
+   See :pep:`698` for more details.
+
+   .. versionadded:: 3.12
+
+
 .. decorator:: type_check_only
 
    Decorator to mark a class or function to be unavailable at runtime.