Merge branch 'main' into pythongh-101000-splitroot

.azure-pipelines/ci.yml

@@ -8,7 +8,7 @@ jobs:
   displayName: Pre-build checks
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   steps:
   - template: ./prebuild-checks.yml
@@ -20,7 +20,7 @@ jobs:
   condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   steps:
   - template: ./docs-steps.yml
@@ -52,7 +52,7 @@ jobs:
   condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   variables:
     testRunTitle: '$(build.sourceBranchName)-linux'
@@ -78,7 +78,7 @@ jobs:
     )
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   variables:
     testRunTitle: '$(Build.SourceBranchName)-linux-coverage'

.azure-pipelines/pr.yml

@@ -8,7 +8,7 @@ jobs:
   displayName: Pre-build checks
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   steps:
   - template: ./prebuild-checks.yml
@@ -20,7 +20,7 @@ jobs:
   condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   steps:
   - template: ./docs-steps.yml
@@ -52,7 +52,7 @@ jobs:
   condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   variables:
     testRunTitle: '$(system.pullRequest.TargetBranch)-linux'
@@ -78,7 +78,7 @@ jobs:
     )
 
   pool:
-    vmImage: ubuntu-20.04
+    vmImage: ubuntu-22.04
 
   variables:
     testRunTitle: '$(Build.SourceBranchName)-linux-coverage'

.github/CODEOWNERS

@@ -7,6 +7,9 @@
 # GitHub
 .github/**                    @ezio-melotti
 
+# Build system
+configure*                    @erlend-aasland
+
 # asyncio
 **/*asyncio*                  @1st1 @asvetlov @gvanrossum @kumaraditya303
 

Doc/howto/logging-cookbook.rst

@@ -1982,26 +1982,47 @@ Using a rotator and namer to customize log rotation processing
 --------------------------------------------------------------
 
 An example of how you can define a namer and rotator is given in the following
-snippet, which shows zlib-based compression of the log file::
+runnable script, which shows gzip compression of the log file::
+
+    import gzip
+    import logging
+    import logging.handlers
+    import os
+    import shutil
 
     def namer(name):
         return name + ".gz"
 
     def rotator(source, dest):
-        with open(source, "rb") as sf:
-            data = sf.read()
-            compressed = zlib.compress(data, 9)
-            with open(dest, "wb") as df:
-                df.write(compressed)
+        with open(source, 'rb') as f_in:
+            with gzip.open(dest, 'wb') as f_out:
+                shutil.copyfileobj(f_in, f_out)
         os.remove(source)
 
-    rh = logging.handlers.RotatingFileHandler(...)
+
+    rh = logging.handlers.RotatingFileHandler('rotated.log', maxBytes=128, backupCount=5)
     rh.rotator = rotator
     rh.namer = namer
 
-These are not "true" .gz files, as they are bare compressed data, with no
-"container" such as you’d find in an actual gzip file. This snippet is just
-for illustration purposes.
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    root.addHandler(rh)
+    f = logging.Formatter('%(asctime)s %(message)s')
+    rh.setFormatter(f)
+    for i in range(1000):
+        root.info(f'Message no. {i + 1}')
+
+After running this, you will see six new files, five of which are compressed:
+
+.. code-block:: shell-session
+
+    $ ls rotated.log*
+    rotated.log       rotated.log.2.gz  rotated.log.4.gz
+    rotated.log.1.gz  rotated.log.3.gz  rotated.log.5.gz
+    $ zcat rotated.log.1.gz
+    2023-01-20 02:28:17,767 Message no. 996
+    2023-01-20 02:28:17,767 Message no. 997
+    2023-01-20 02:28:17,767 Message no. 998
 
 A more elaborate multiprocessing example
 ----------------------------------------

Doc/library/asyncio-eventloop.rst

@@ -48,7 +48,7 @@ an event loop:
    running event loop.
 
    If there is no running event loop set, the function will return
-   the result of calling ``get_event_loop_policy().get_event_loop()``.
+   the result of the ``get_event_loop_policy().get_event_loop()`` call.
 
    Because this function has rather complex behavior (especially
    when custom event loop policies are in use), using the
@@ -59,11 +59,9 @@ an event loop:
    instead of using these lower level functions to manually create and close an
    event loop.
 
-   .. note::
-      In Python versions 3.10.0--3.10.8 and 3.11.0 this function
-      (and other functions which used it implicitly) emitted a
-      :exc:`DeprecationWarning` if there was no running event loop, even if
-      the current loop was set.
+   .. deprecated:: 3.12
+      Deprecation warning is emitted if there is no current event loop.
+      In some future Python release this will become an error.
 
 .. function:: set_event_loop(loop)
 

Doc/library/asyncio-policy.rst

@@ -116,9 +116,11 @@ asyncio ships with the following built-in policies:
 
       On Windows, :class:`ProactorEventLoop` is now used by default.
 
-   .. versionchanged:: 3.12
-      :meth:`get_event_loop` now raises a :exc:`RuntimeError` if there is no
-      current event loop set.
+   .. deprecated:: 3.12
+      The :meth:`get_event_loop` method of the default asyncio policy now emits
+      a :exc:`DeprecationWarning` if there is no current event loop set and it
+      decides to create one.
+      In some future Python release this will become an error.
 
 
 .. class:: WindowsSelectorEventLoopPolicy

Doc/library/ctypes.rst

@@ -466,6 +466,14 @@ integer, string, bytes, a :mod:`ctypes` instance, or an object with an
 Return types
 ^^^^^^^^^^^^
 
+.. testsetup::
+
+   from ctypes import CDLL, c_char, c_char_p
+   from ctypes.util import find_library
+   libc = CDLL(find_library('c'))
+   strchr = libc.strchr
+
+
 By default functions are assumed to return the C :c:expr:`int` type.  Other
 return types can be specified by setting the :attr:`restype` attribute of the
 function object.
@@ -502,18 +510,19 @@ If you want to avoid the ``ord("x")`` calls above, you can set the
 :attr:`argtypes` attribute, and the second argument will be converted from a
 single character Python bytes object into a C char::
 
+.. doctest::
+
    >>> strchr.restype = c_char_p
    >>> strchr.argtypes = [c_char_p, c_char]
    >>> strchr(b"abcdef", b"d")
-   'def'
+   b'def'
    >>> strchr(b"abcdef", b"def")
    Traceback (most recent call last):
-     File "<stdin>", line 1, in <module>
-   ArgumentError: argument 2: TypeError: one character string expected
+   ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray or integer expected
    >>> print(strchr(b"abcdef", b"x"))
    None
    >>> strchr(b"abcdef", b"d")
-   'def'
+   b'def'
    >>>
 
 You can also use a callable Python object (a function or a class for example) as
@@ -1656,12 +1665,12 @@ They are instances of a private class:
    passed arguments.
 
 
-.. audit-event:: ctypes.seh_exception code foreign-functions
+.. audit-event:: ctypes.set_exception code foreign-functions
 
    On Windows, when a foreign function call raises a system exception (for
    example, due to an access violation), it will be captured and replaced with
    a suitable Python exception. Further, an auditing event
-   ``ctypes.seh_exception`` with argument ``code`` will be raised, allowing an
+   ``ctypes.set_exception`` with argument ``code`` will be raised, allowing an
    audit hook to replace the exception with its own.
 
 .. audit-event:: ctypes.call_function func_pointer,arguments foreign-functions

Doc/library/datetime.rst

@@ -1351,7 +1351,7 @@ Instance methods:
 
       Because naive ``datetime`` objects are treated by many ``datetime`` methods
       as local times, it is preferred to use aware datetimes to represent times
-      in UTC; as a result, using ``utcfromtimetuple`` may give misleading
+      in UTC; as a result, using :meth:`datetime.utctimetuple` may give misleading
       results. If you have a naive ``datetime`` representing UTC, use
       ``datetime.replace(tzinfo=timezone.utc)`` to make it aware, at which point
       you can use :meth:`.datetime.timetuple`.

Doc/library/dis.rst

@@ -1043,6 +1043,15 @@ iterations of the loop.
    ``cmp_op[opname]``.
 
 
+.. opcode:: COMPARE_AND_BRANCH (opname)
+
+   Compares the top two values on the stack, popping them, then branches.
+   The direction and offset of the jump is embedded as a ``POP_JUMP_IF_TRUE``
+   or ``POP_JUMP_IF_FALSE`` instruction immediately following the cache.
+
+   .. versionadded:: 3.12
+
+
 .. opcode:: IS_OP (invert)
 
    Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.

Doc/library/email.mime.rst

@@ -114,9 +114,9 @@ Here are the classes:
 
    A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
    :class:`MIMEApplication` class is used to represent MIME message objects of
-   major type :mimetype:`application`.  *_data* is a string containing the raw
-   byte data.  Optional *_subtype* specifies the MIME subtype and defaults to
-   :mimetype:`octet-stream`.
+   major type :mimetype:`application`.  *_data* contains the bytes for the raw
+   application data.  Optional *_subtype* specifies the MIME subtype and defaults
+   to :mimetype:`octet-stream`.
 
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the data for transport.  This callable takes one argument, which is
@@ -145,7 +145,7 @@ Here are the classes:
 
    A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
    :class:`MIMEAudio` class is used to create MIME message objects of major type
-   :mimetype:`audio`. *_audiodata* is a string containing the raw audio data.  If
+   :mimetype:`audio`. *_audiodata* contains the bytes for the raw audio data.  If
    this data can be decoded as au, wav, aiff, or aifc, then the
    subtype will be automatically included in the :mailheader:`Content-Type` header.
    Otherwise you can explicitly specify the audio subtype via the *_subtype*
@@ -179,7 +179,7 @@ Here are the classes:
 
    A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
    :class:`MIMEImage` class is used to create MIME message objects of major type
-   :mimetype:`image`. *_imagedata* is a string containing the raw image data.  If
+   :mimetype:`image`. *_imagedata* contains the bytes for the raw image data.  If
    this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm,
    rast, xbm, bmp, webp, and exr attempted), then the subtype will be
    automatically included in the :mailheader:`Content-Type` header. Otherwise

Doc/library/enum.rst

@@ -52,11 +52,11 @@ are not normal Python classes.  See
 
 .. note:: Nomenclature
 
-   - The class :class:`Color` is an *enumeration* (or *enum*)
-   - The attributes :attr:`Color.RED`, :attr:`Color.GREEN`, etc., are
+   - The class :class:`!Color` is an *enumeration* (or *enum*)
+   - The attributes :attr:`!Color.RED`, :attr:`!Color.GREEN`, etc., are
      *enumeration members* (or *members*) and are functionally constants.
    - The enum members have *names* and *values* (the name of
-     :attr:`Color.RED` is ``RED``, the value of :attr:`Color.BLUE` is
+     :attr:`!Color.RED` is ``RED``, the value of :attr:`!Color.BLUE` is
      ``3``, etc.)
 
 ---------------
@@ -165,8 +165,8 @@ Data Types
    to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>`
    for details.
 
-   *EnumType* is responsible for setting the correct :meth:`__repr__`,
-   :meth:`__str__`, :meth:`__format__`, and :meth:`__reduce__` methods on the
+   *EnumType* is responsible for setting the correct :meth:`!__repr__`,
+   :meth:`!__str__`, :meth:`!__format__`, and :meth:`!__reduce__` methods on the
    final *enum*, as well as creating the enum members, properly handling
    duplicates, providing iteration over the enum class, etc.
 
@@ -424,9 +424,9 @@ Data Types
       Using :class:`auto` with :class:`IntEnum` results in integers of increasing
       value, starting with ``1``.
 
-   .. versionchanged:: 3.11 :meth:`__str__` is now :func:`int.__str__` to
+   .. versionchanged:: 3.11 :meth:`~object.__str__` is now :meth:`!int.__str__` to
       better support the *replacement of existing constants* use-case.
-      :meth:`__format__` was already :func:`int.__format__` for that same reason.
+      :meth:`~object.__format__` was already :meth:`!int.__format__` for that same reason.
 
 
 .. class:: StrEnum
@@ -617,7 +617,7 @@ Data Types
 
 .. class:: ReprEnum
 
-   :class:`!ReprEum` uses the :meth:`repr() <Enum.__repr__>` of :class:`Enum`,
+   :class:`!ReprEnum` uses the :meth:`repr() <Enum.__repr__>` of :class:`Enum`,
    but the :class:`str() <str>` of the mixed-in data type:
 
       * :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`
@@ -761,11 +761,11 @@ Data Types
 Supported ``__dunder__`` names
 """"""""""""""""""""""""""""""
 
-:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member``
+:attr:`~EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
 items.  It is only available on the class.
 
-:meth:`__new__`, if specified, must create and return the enum members; it is
-also a very good idea to set the member's :attr:`_value_` appropriately.  Once
+:meth:`~object.__new__`, if specified, must create and return the enum members; it is
+also a very good idea to set the member's :attr:`!_value_` appropriately.  Once
 all the members are created it is no longer used.
 
 
@@ -804,7 +804,7 @@ Utilities and Decorators
 .. class:: auto
 
    *auto* can be used in place of a value.  If used, the *Enum* machinery will
-   call an *Enum*'s :meth:`_generate_next_value_` to get an appropriate value.
+   call an *Enum*'s :meth:`~Enum._generate_next_value_` to get an appropriate value.
    For *Enum* and *IntEnum* that appropriate value will be the last value plus
    one; for *Flag* and *IntFlag* it will be the first power-of-two greater
    than the highest value; for *StrEnum* it will be the lower-cased version of
@@ -847,7 +847,7 @@ Utilities and Decorators
 .. decorator:: unique
 
    A :keyword:`class` decorator specifically for enumerations.  It searches an
-   enumeration's :attr:`__members__`, gathering any aliases it finds; if any are
+   enumeration's :attr:`~EnumType.__members__`, gathering any aliases it finds; if any are
    found :exc:`ValueError` is raised with the details::
 
       >>> from enum import Enum, unique