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

Doc/c-api/code.rst

@@ -115,3 +115,51 @@ bound into a function.
    the free variables. On error, ``NULL`` is returned and an exception is raised.
 
    .. versionadded:: 3.11
+
+.. c:function:: int PyCode_AddWatcher(PyCode_WatchCallback callback)
+
+   Register *callback* as a code object watcher for the current interpreter.
+   Return an ID which may be passed to :c:func:`PyCode_ClearWatcher`.
+   In case of error (e.g. no more watcher IDs available),
+   return ``-1`` and set an exception.
+
+   .. versionadded:: 3.12
+
+.. c:function:: int PyCode_ClearWatcher(int watcher_id)
+
+   Clear watcher identified by *watcher_id* previously returned from
+   :c:func:`PyCode_AddWatcher` for the current interpreter.
+   Return ``0`` on success, or ``-1`` and set an exception on error
+   (e.g. if the given *watcher_id* was never registered.)
+
+   .. versionadded:: 3.12
+
+.. c:type:: PyCodeEvent
+
+   Enumeration of possible code object watcher events:
+   - ``PY_CODE_EVENT_CREATE``
+   - ``PY_CODE_EVENT_DESTROY``
+
+   .. versionadded:: 3.12
+
+.. c:type:: int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject* co)
+
+   Type of a code object watcher callback function.
+
+   If *event* is ``PY_CODE_EVENT_CREATE``, then the callback is invoked
+   after `co` has been fully initialized. Otherwise, the callback is invoked
+   before the destruction of *co* takes place, so the prior state of *co*
+   can be inspected.
+
+   Users of this API should not rely on internal runtime implementation
+   details. Such details may include, but are not limited to, the exact
+   order and timing of creation and destruction of code objects. While
+   changes in these details may result in differences observable by watchers
+   (including whether a callback is invoked or not), it does not change
+   the semantics of the Python code being executed.
+
+   If the callback returns with an exception set, it must return ``-1``; this
+   exception will be printed as an unraisable exception using
+   :c:func:`PyErr_WriteUnraisable`. Otherwise it should return ``0``.
+
+   .. versionadded:: 3.12

Doc/library/asyncio-eventloop.rst

@@ -33,7 +33,8 @@ an event loop:
 
    Return the running event loop in the current OS thread.
 
-   If there is no running event loop a :exc:`RuntimeError` is raised.
+   Raise a :exc:`RuntimeError` if there is no running event loop.
+
    This function can only be called from a coroutine or a callback.
 
    .. versionadded:: 3.7
@@ -52,17 +53,19 @@ an event loop:
    :func:`get_running_loop` function is preferred to :func:`get_event_loop`
    in coroutines and callbacks.
 
-   Consider also using the :func:`asyncio.run` function instead of using
-   lower level functions to manually create and close an event loop.
+   As noted above, consider using the higher-level :func:`asyncio.run` function,
+   instead of using these lower level functions to manually create and close an
+   event loop.
 
    .. deprecated:: 3.10
-      Deprecation warning is emitted if there is no running event loop.
-      In future Python releases, this function will be an alias of
-      :func:`get_running_loop`.
+      Emits a deprecation warning if there is no running event loop.
+      In future Python releases, this function may become an alias of
+      :func:`get_running_loop` and will accordingly raise a
+      :exc:`RuntimeError` if there is no running event loop.
 
 .. function:: set_event_loop(loop)
 
-   Set *loop* as a current event loop for the current OS thread.
+   Set *loop* as the current event loop for the current OS thread.
 
 .. function:: new_event_loop()
 

Doc/library/base64.rst

@@ -53,21 +53,23 @@ The modern interface provides:
    Encode the :term:`bytes-like object` *s* using Base64 and return the encoded
    :class:`bytes`.
 
-   Optional *altchars* must be a :term:`bytes-like object` of at least
-   length 2 (additional characters are ignored) which specifies an alternative
-   alphabet for the ``+`` and ``/`` characters.  This allows an application to e.g.
-   generate URL or filesystem safe Base64 strings.  The default is ``None``, for
-   which the standard Base64 alphabet is used.
+   Optional *altchars* must be a :term:`bytes-like object` of length 2 which
+   specifies an alternative alphabet for the ``+`` and ``/`` characters.
+   This allows an application to e.g. generate URL or filesystem safe Base64
+   strings.  The default is ``None``, for which the standard Base64 alphabet is used.
+
+   May assert or raise a a :exc:`ValueError` if the length of *altchars* is not 2.  Raises a
+   :exc:`TypeError` if *altchars* is not a :term:`bytes-like object`.
 
 
 .. function:: b64decode(s, altchars=None, validate=False)
 
    Decode the Base64 encoded :term:`bytes-like object` or ASCII string
    *s* and return the decoded :class:`bytes`.
 
-   Optional *altchars* must be a :term:`bytes-like object` or ASCII string of
-   at least length 2 (additional characters are ignored) which specifies the
-   alternative alphabet used instead of the ``+`` and ``/`` characters.
+   Optional *altchars* must be a :term:`bytes-like object` or ASCII string
+   of length 2 which specifies the alternative alphabet used instead of the
+   ``+`` and ``/`` characters.
 
    A :exc:`binascii.Error` exception is raised
    if *s* is incorrectly padded.
@@ -80,6 +82,7 @@ The modern interface provides:
 
    For more information about the strict base64 check, see :func:`binascii.a2b_base64`
 
+   May assert or raise a :exc:`ValueError` if the length of *altchars* is not 2.
 
 .. function:: standard_b64encode(s)
 

Doc/library/dataclasses.rst

@@ -79,7 +79,8 @@ Module contents
      class C:
          ...
 
-     @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)
+     @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False,
+                match_args=True, kw_only=False, slots=False, weakref_slot=False)
      class C:
          ...
 

Doc/library/enum.rst

@@ -194,7 +194,7 @@ Data Types
 
    .. method:: EnumType.__getitem__(cls, name)
 
-      Returns the Enum member in *cls* matching *name*, or raises an :exc:`KeyError`::
+      Returns the Enum member in *cls* matching *name*, or raises a :exc:`KeyError`::
 
         >>> Color['BLUE']
         <Color.BLUE: 3>
@@ -241,7 +241,7 @@ Data Types
 
       .. note:: Enum member values
 
-         Member values can be anything: :class:`int`, :class:`str`, etc..  If
+         Member values can be anything: :class:`int`, :class:`str`, etc.  If
          the exact value is unimportant you may use :class:`auto` instances and an
          appropriate value will be chosen for you.  See :class:`auto` for the
          details.
@@ -255,7 +255,7 @@ Data Types
       names will also be removed from the completed enumeration.  See
       :ref:`TimePeriod <enum-time-period>` for an example.
 
-   .. method:: Enum.__call__(cls, value, names=None, \*, module=None, qualname=None, type=None, start=1, boundary=None)
+   .. method:: Enum.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
 
       This method is called in two different ways:
 
@@ -272,8 +272,8 @@ Data Types
          :module:    The name of the module the new Enum is created in.
          :qualname:  The actual location in the module where this Enum can be found.
          :type:  A mix-in type for the new Enum.
-         :start: The first integer value for the Enum (used by :class:`auto`)
-         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only)
+         :start: The first integer value for the Enum (used by :class:`auto`).
+         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only).
 
    .. method:: Enum.__dir__(self)
 
@@ -315,7 +315,7 @@ Data Types
          >>> PowersOfThree.SECOND.value
          6
 
-   .. method:: Enum.__init_subclass__(cls, \**kwds)
+   .. method:: Enum.__init_subclass__(cls, **kwds)
 
       A *classmethod* that is used to further configure subsequent subclasses.
       By default, does nothing.
@@ -373,7 +373,7 @@ Data Types
    .. method:: Enum.__format__(self)
 
       Returns the string used for *format()* and *f-string* calls.  By default,
-      returns :meth:`__str__` returns, but can be overridden::
+      returns :meth:`__str__` return value, but can be overridden::
 
          >>> class OtherStyle(Enum):
          ...     ALTERNATE = auto()
@@ -552,11 +552,11 @@ Data Types
       Using :class:`auto` with :class:`Flag` results in integers that are powers
       of two, starting with ``1``.
 
-   .. versionchanged:: 3.11  The *repr()* of zero-valued flags has changed.  It
+   .. versionchanged:: 3.11 The *repr()* of zero-valued flags has changed.  It
       is now::
 
-          >>> Color(0) # doctest: +SKIP
-          <Color: 0>
+         >>> Color(0) # doctest: +SKIP
+         <Color: 0>
 
 .. class:: IntFlag
 
@@ -600,7 +600,7 @@ Data Types
       *replacement of existing constants* use-case.  :meth:`~object.__format__` was
       already :meth:`!int.__format__` for that same reason.
 
-      Inversion of a :class:`!IntFlag` now returns a positive value that is the
+      Inversion of an :class:`!IntFlag` now returns a positive value that is the
       union of all flags not in the given flag, rather than a negative value.
       This matches the existing :class:`Flag` behavior.
 
@@ -612,7 +612,7 @@ Data Types
       * :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`
       * :meth:`!str.__str__` for :class:`StrEnum`
 
-   Inherit from :class:`!ReprEnum` to keep the :class:`str() <str> / :func:`format`
+   Inherit from :class:`!ReprEnum` to keep the :class:`str() <str>` / :func:`format`
    of the mixed-in data type instead of using the
    :class:`Enum`-default :meth:`str() <Enum.__str__>`.
 
@@ -658,7 +658,7 @@ Data Types
    .. attribute:: NAMED_FLAGS
 
       Ensure that any flag groups/masks contain only named flags -- useful when
-      values are specified instead of being generated by :func:`auto`
+      values are specified instead of being generated by :func:`auto`::
 
          >>> from enum import Flag, verify, NAMED_FLAGS
          >>> @verify(NAMED_FLAGS)
@@ -804,6 +804,11 @@ Utilities and Decorators
       * ``THREE = [auto(), -3]`` will *not* work (``<auto instance>, -3`` is used to
         create the ``THREE`` enum member)
 
+   .. versionchanged:: 3.11.1
+
+      In prior versions, ``auto()`` had to be the only thing
+      on the assignment line to work properly.
+
    ``_generate_next_value_`` can be overridden to customize the values used by
    *auto*.
 
@@ -885,23 +890,23 @@ Notes
 
 :class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`
 
-    These three enum types are designed to be drop-in replacements for existing
-    integer- and string-based values; as such, they have extra limitations:
+   These three enum types are designed to be drop-in replacements for existing
+   integer- and string-based values; as such, they have extra limitations:
 
-    - ``__str__`` uses the value and not the name of the enum member
+   - ``__str__`` uses the value and not the name of the enum member
 
-    - ``__format__``, because it uses ``__str__``, will also use the value of
-      the enum member instead of its name
+   - ``__format__``, because it uses ``__str__``, will also use the value of
+     the enum member instead of its name
 
-    If you do not need/want those limitations, you can either create your own
-    base class by mixing in the ``int`` or ``str`` type yourself::
+   If you do not need/want those limitations, you can either create your own
+   base class by mixing in the ``int`` or ``str`` type yourself::
 
-        >>> from enum import Enum
-        >>> class MyIntEnum(int, Enum):
-        ...     pass
+       >>> from enum import Enum
+       >>> class MyIntEnum(int, Enum):
+       ...     pass
 
    or you can reassign the appropriate :meth:`str`, etc., in your enum::
 
-        >>> from enum import IntEnum
-        >>> class MyIntEnum(IntEnum):
-        ...     __str__ = IntEnum.__str__
+       >>> from enum import IntEnum
+       >>> class MyIntEnum(IntEnum):
+       ...     __str__ = IntEnum.__str__

Doc/library/fnmatch.rst

@@ -48,7 +48,7 @@ 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`.
+:func:`fnmatchcase`, :func:`.filter`.
 
 .. function:: fnmatch(filename, pattern)
 

Doc/library/http.server.rst

@@ -512,3 +512,10 @@ Security Considerations
 :class:`SimpleHTTPRequestHandler` will follow symbolic links when handling
 requests, this makes it possible for files outside of the specified directory
 to be served.
+
+Earlier versions of Python did not scrub control characters from the
+log messages emitted to stderr from ``python -m http.server`` or the
+default :class:`BaseHTTPRequestHandler` ``.log_message``
+implementation. This could allow to remote clients connecting to your
+server to send nefarious control codes to your terminal.
+

Doc/library/re.rst

@@ -1565,16 +1565,22 @@ search() vs. match()
 
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
-Python offers two different primitive operations based on regular expressions:
-:func:`re.match` checks for a match only at the beginning of the string, while
-:func:`re.search` checks for a match anywhere in the string (this is what Perl
-does by default).
+Python offers different primitive operations based on regular expressions:
+
++ :func:`re.match` checks for a match only at the beginning of the string
++ :func:`re.search` checks for a match anywhere in the string
+  (this is what Perl does by default)
++ :func:`re.fullmatch` checks for entire string to be a match
+
 
 For example::
 
    >>> re.match("c", "abcdef")    # No match
    >>> re.search("c", "abcdef")   # Match
    <re.Match object; span=(2, 3), match='c'>
+   >>> re.fullmatch("p.*n", "python") # Match
+   <re.Match object; span=(0, 6), match='python'>
+   >>> re.fullmatch("r.*n", "python") # No match
 
 Regular expressions beginning with ``'^'`` can be used with :func:`search` to
 restrict the match at the beginning of the string::
@@ -1588,8 +1594,8 @@ Note however that in :const:`MULTILINE` mode :func:`match` only matches at the
 beginning of the string, whereas using :func:`search` with a regular expression
 beginning with ``'^'`` will match at the beginning of each line. ::
 
-   >>> re.match('X', 'A\nB\nX', re.MULTILINE)  # No match
-   >>> re.search('^X', 'A\nB\nX', re.MULTILINE)  # Match
+   >>> re.match("X", "A\nB\nX", re.MULTILINE)  # No match
+   >>> re.search("^X", "A\nB\nX", re.MULTILINE)  # Match
    <re.Match object; span=(4, 5), match='X'>
 
 

Doc/library/socketserver.rst

@@ -96,8 +96,7 @@ synchronous servers of four types::
 
 Note that :class:`UnixDatagramServer` derives from :class:`UDPServer`, not from
 :class:`UnixStreamServer` --- the only difference between an IP and a Unix
-stream server is the address family, which is simply repeated in both Unix
-server classes.
+server is the address family.
 
 
 .. class:: ForkingMixIn
@@ -431,11 +430,8 @@ Request Handler Objects
    The :attr:`self.rfile` and :attr:`self.wfile` attributes can be
    read or written, respectively, to get the request data or return data
    to the client.
-
-   The :attr:`rfile` attributes of both classes support the
-   :class:`io.BufferedIOBase` readable interface, and
-   :attr:`DatagramRequestHandler.wfile` supports the
-   :class:`io.BufferedIOBase` writable interface.
+   The :attr:`!rfile` attributes support the :class:`io.BufferedIOBase` readable interface,
+   and :attr:`!wfile` attributes support the :class:`!io.BufferedIOBase` writable interface.
 
    .. versionchanged:: 3.6
       :attr:`StreamRequestHandler.wfile` also supports the

Doc/library/sqlite3.rst

@@ -292,6 +292,7 @@ Module functions
        By default (``0``), type detection is disabled.
 
    :param isolation_level:
+       Control legacy transaction handling behaviour.
        See :attr:`Connection.isolation_level` and
        :ref:`sqlite3-transaction-control-isolation-level` for more information.
        Can be ``"DEFERRED"`` (default), ``"EXCLUSIVE"`` or ``"IMMEDIATE"``;
@@ -325,6 +326,7 @@ Module functions
        enabling various :ref:`sqlite3-uri-tricks`.
 
    :param autocommit:
+       Control :pep:`249` transaction handling behaviour.
        See :attr:`Connection.autocommit` and
        :ref:`sqlite3-transaction-control-autocommit` for more information.
        *autocommit* currently defaults to
@@ -2468,9 +2470,9 @@ which implies :pep:`249`-compliant transaction control.
 This means:
 
 * :mod:`!sqlite3` ensures that a transaction is always open,
-  so :meth:`Connection.commit` and :meth:`Connection.rollback`
-  will implicitly open a new transaction immediately after closing
-  the pending one.
+  so :func:`connect`, :meth:`Connection.commit`, and :meth:`Connection.rollback`
+  will implicitly open a new transaction
+  (immediately after closing the pending one, for the latter two).
   :mod:`!sqlite3` uses ``BEGIN DEFERRED`` statements when opening transactions.
 * Transactions should be committed explicitly using :meth:`!commit`.
 * Transactions should be rolled back explicitly using :meth:`!rollback`.