Merge tag 'v3.12.0' into 3.12

Python 3.12.0

.azure-pipelines/pr.yml

@@ -26,34 +26,3 @@ jobs:
 
   steps:
   - template: ./posix-steps.yml
-
-
-- job: Windows_PR_Tests
-  displayName: Windows PR Tests
-  dependsOn: Prebuild
-  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
-
-  pool:
-    vmImage: windows-2022
-
-  strategy:
-    matrix:
-      win32:
-        arch: win32
-        buildOpt: '-p Win32'
-        testRunTitle: '$(System.PullRequest.TargetBranch)-win32'
-        testRunPlatform: win32
-      win64:
-        arch: amd64
-        buildOpt: '-p x64'
-        testRunTitle: '$(System.PullRequest.TargetBranch)-win64'
-        testRunPlatform: win64
-      winarm64:
-        arch: arm64
-        buildOpt: '-p arm64'
-    maxParallel: 4
-
-  steps:
-  - template: ./windows-steps.yml
-    parameters:
-      targetBranch: $(System.PullRequest.TargetBranch)

.github/workflows/build.yml

@@ -161,6 +161,8 @@ jobs:
           path: config.cache
           key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
       - uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
       - name: Install Dependencies
         run: sudo ./.github/workflows/posix-deps-apt.sh
       - name: Add ccache to PATH
@@ -244,6 +246,21 @@ jobs:
     - name: Tests
       run: .\PCbuild\rt.bat -p x64 -d -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
 
+  build_win_arm64:
+    name: 'Windows (arm64)'
+    runs-on: windows-latest
+    timeout-minutes: 60
+    needs: check_source
+    if: needs.check_source.outputs.run_tests == 'true'
+    env:
+       IncludeUwp: 'true'
+    steps:
+    - uses: actions/checkout@v4
+    - name: Register MSVC problem matcher
+      run: echo "::add-matcher::.github/problem-matchers/msvc.json"
+    - name: Build CPython
+      run: .\PCbuild\build.bat -e -d -p arm64
+
   build_macos:
     name: 'macOS'
     runs-on: macos-latest
@@ -287,7 +304,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
-      OPENSSL_VER: 1.1.1v
+      OPENSSL_VER: 3.0.11
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v4
@@ -356,7 +373,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        openssl_ver: [1.1.1v, 3.0.10, 3.1.2]
+        openssl_ver: [1.1.1w, 3.0.11, 3.1.3]
     env:
       OPENSSL_VER: ${{ matrix.openssl_ver }}
       MULTISSL_DIR: ${{ github.workspace }}/multissl
@@ -408,7 +425,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true' && needs.check_source.outputs.run_hypothesis == 'true'
     env:
-      OPENSSL_VER: 1.1.1v
+      OPENSSL_VER: 3.0.11
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v4
@@ -517,7 +534,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
-      OPENSSL_VER: 1.1.1v
+      OPENSSL_VER: 3.0.11
       PYTHONSTRICTEXTENSIONBUILD: 1
       ASAN_OPTIONS: detect_leaks=0:allocator_may_return_null=1:handle_segv=0
     steps:
@@ -573,6 +590,7 @@ jobs:
     - check_generated_files
     - build_win32
     - build_win_amd64
+    - build_win_arm64
     - build_macos
     - build_ubuntu
     - build_ubuntu_ssltests
@@ -589,6 +607,7 @@ jobs:
           build_macos,
           build_ubuntu_ssltests,
           build_win32,
+          build_win_arm64,
           test_hypothesis,
         allowed-skips: >-
           ${{
@@ -604,6 +623,7 @@ jobs:
             check_generated_files,
             build_win32,
             build_win_amd64,
+            build_win_arm64,
             build_macos,
             build_ubuntu,
             build_ubuntu_ssltests,

.github/workflows/reusable-docs.yml

@@ -74,7 +74,7 @@ jobs:
     - name: 'Set up Python'
       uses: actions/setup-python@v4
       with:
-        python-version: '3.11'  # known to work with Sphinx 3.2
+        python-version: '3.11'  # known to work with Sphinx 4.2
         cache: 'pip'
         cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
     - name: 'Install build dependencies'

Doc/c-api/intro.rst

@@ -105,6 +105,30 @@ defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
 Others of a more general utility are defined here.  This is not necessarily a
 complete listing.
 
+.. c:macro:: PyMODINIT_FUNC
+
+   Declare an extension module ``PyInit`` initialization function. The function
+   return type is :c:expr:`PyObject*`. The macro declares any special linkage
+   declarations required by the platform, and for C++ declares the function as
+   ``extern "C"``.
+
+   The initialization function must be named :samp:`PyInit_{name}`, where
+   *name* is the name of the module, and should be the only non-\ ``static``
+   item defined in the module file. Example::
+
+       static struct PyModuleDef spam_module = {
+           PyModuleDef_HEAD_INIT,
+           .m_name = "spam",
+           ...
+       };
+
+       PyMODINIT_FUNC
+       PyInit_spam(void)
+       {
+           return PyModule_Create(&spam_module);
+       }
+
+
 .. c:macro:: Py_ABS(x)
 
    Return the absolute value of ``x``.

Doc/conf.py

@@ -66,7 +66,7 @@
 highlight_language = 'python3'
 
 # Minimum version of sphinx required
-needs_sphinx = '3.2'
+needs_sphinx = '4.2'
 
 # Ignore any .rst files in the includes/ directory;
 # they're embedded in pages but not rendered individually.

Doc/constraints.txt

@@ -10,8 +10,7 @@ colorama<0.5
 imagesize<1.5
 Jinja2<3.2
 packaging<24
-# Pygments==2.15.0 breaks CI
-Pygments<2.16,!=2.15.0
+Pygments>=2.16.1,<3
 requests<3
 snowballstemmer<3
 sphinxcontrib-applehelp<1.1

Doc/extending/windows.rst

@@ -132,4 +132,4 @@ modules (including Python) to be able to see your identifiers, you have to say
 Developer Studio will throw in a lot of import libraries that you do not really
 need, adding about 100K to your executable.  To get rid of them, use the Project
 Settings dialog, Link tab, to specify *ignore default libraries*.  Add the
-correct :file:`msvcrtxx.lib` to the list of libraries.
+correct :file:`msvcrt{xx}.lib` to the list of libraries.

Doc/howto/logging-cookbook.rst

@@ -1728,7 +1728,7 @@ when (and if) the logged message is actually about to be output to a log by a
 handler. So the only slightly unusual thing which might trip you up is that the
 parentheses go around the format string and the arguments, not just the format
 string. That's because the __ notation is just syntax sugar for a constructor
-call to one of the XXXMessage classes.
+call to one of the :samp:`{XXX}Message` classes.
 
 If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar effect
 to the above, as in the following example::
@@ -2644,7 +2644,7 @@ when (and if) the logged message is actually about to be output to a log by a
 handler. So the only slightly unusual thing which might trip you up is that the
 parentheses go around the format string and the arguments, not just the format
 string. That’s because the __ notation is just syntax sugar for a constructor
-call to one of the ``XXXMessage`` classes shown above.
+call to one of the :samp:`{XXX}Message` classes shown above.
 
 
 .. _filters-dictconfig:

Doc/howto/logging.rst

@@ -979,7 +979,7 @@ provided:
 
 #. :class:`NullHandler` instances do nothing with error messages. They are used
    by library developers who want to use logging, but want to avoid the 'No
-   handlers could be found for logger XXX' message which can be displayed if
+   handlers could be found for logger *XXX*' message which can be displayed if
    the library user has not configured logging. See :ref:`library-config` for
    more information.
 

Doc/howto/urllib2.rst

@@ -194,11 +194,11 @@ which comes after we have a look at what happens when things go wrong.
 Handling Exceptions
 ===================
 
-*urlopen* raises :exc:`URLError` when it cannot handle a response (though as
+*urlopen* raises :exc:`~urllib.error.URLError` when it cannot handle a response (though as
 usual with Python APIs, built-in exceptions such as :exc:`ValueError`,
 :exc:`TypeError` etc. may also be raised).
 
-:exc:`HTTPError` is the subclass of :exc:`URLError` raised in the specific case of
+:exc:`~urllib.error.HTTPError` is the subclass of :exc:`~urllib.error.URLError` raised in the specific case of
 HTTP URLs.
 
 The exception classes are exported from the :mod:`urllib.error` module.
@@ -229,12 +229,12 @@ the status code indicates that the server is unable to fulfil the request. The
 default handlers will handle some of these responses for you (for example, if
 the response is a "redirection" that requests the client fetch the document from
 a different URL, urllib will handle that for you). For those it can't handle,
-urlopen will raise an :exc:`HTTPError`. Typical errors include '404' (page not
+urlopen will raise an :exc:`~urllib.error.HTTPError`. Typical errors include '404' (page not
 found), '403' (request forbidden), and '401' (authentication required).
 
 See section 10 of :rfc:`2616` for a reference on all the HTTP error codes.
 
-The :exc:`HTTPError` instance raised will have an integer 'code' attribute, which
+The :exc:`~urllib.error.HTTPError` instance raised will have an integer 'code' attribute, which
 corresponds to the error sent by the server.
 
 Error Codes
@@ -317,7 +317,7 @@ dictionary is reproduced here for convenience ::
         }
 
 When an error is raised the server responds by returning an HTTP error code
-*and* an error page. You can use the :exc:`HTTPError` instance as a response on the
+*and* an error page. You can use the :exc:`~urllib.error.HTTPError` instance as a response on the
 page returned. This means that as well as the code attribute, it also has read,
 geturl, and info, methods as returned by the ``urllib.response`` module::
 
@@ -338,7 +338,7 @@ geturl, and info, methods as returned by the ``urllib.response`` module::
 Wrapping it Up
 --------------
 
-So if you want to be prepared for :exc:`HTTPError` *or* :exc:`URLError` there are two
+So if you want to be prepared for :exc:`~urllib.error.HTTPError` *or* :exc:`~urllib.error.URLError` there are two
 basic approaches. I prefer the second approach.
 
 Number 1
@@ -365,7 +365,7 @@ Number 1
 .. note::
 
     The ``except HTTPError`` *must* come first, otherwise ``except URLError``
-    will *also* catch an :exc:`HTTPError`.
+    will *also* catch an :exc:`~urllib.error.HTTPError`.
 
 Number 2
 ~~~~~~~~
@@ -391,7 +391,7 @@ Number 2
 info and geturl
 ===============
 
-The response returned by urlopen (or the :exc:`HTTPError` instance) has two
+The response returned by urlopen (or the :exc:`~urllib.error.HTTPError` instance) has two
 useful methods :meth:`info` and :meth:`geturl` and is defined in the module
 :mod:`urllib.response`..
 

Doc/library/__main__.rst

@@ -238,9 +238,9 @@ package.  For more details, see :ref:`intra-package-references` in the
 Idiomatic Usage
 ^^^^^^^^^^^^^^^
 
-The contents of ``__main__.py`` typically isn't fenced with
-``if __name__ == '__main__'`` blocks.  Instead, those files are kept short,
-functions to execute from other modules.  Those other modules can then be
+The content of ``__main__.py`` typically isn't fenced with an
+``if __name__ == '__main__'`` block.  Instead, those files are kept
+short and import functions to execute from other modules.  Those other modules can then be
 easily unit-tested and are properly reusable.
 
 If used, an ``if __name__ == '__main__'`` block will still work as expected

Doc/library/codecs.rst

@@ -345,9 +345,10 @@ The following error handlers can be used with all Python
 +-------------------------+-----------------------------------------------+
 | ``'backslashreplace'``  | Replace with backslashed escape sequences.    |
 |                         | On encoding, use hexadecimal form of Unicode  |
-|                         | code point with formats ``\xhh`` ``\uxxxx``   |
-|                         | ``\Uxxxxxxxx``. On decoding, use hexadecimal  |
-|                         | form of byte value with format ``\xhh``.      |
+|                         | code point with formats :samp:`\\x{hh}`       |
+|                         | :samp:`\\u{xxxx}` :samp:`\\U{xxxxxxxx}`.      |
+|                         | On decoding, use hexadecimal form of byte     |
+|                         | value with format :samp:`\\x{hh}`.            |
 |                         | Implemented in                                |
 |                         | :func:`backslashreplace_errors`.              |
 +-------------------------+-----------------------------------------------+
@@ -373,8 +374,9 @@ The following error handlers are only applicable to encoding (within
 +=========================+===============================================+
 | ``'xmlcharrefreplace'`` | Replace with XML/HTML numeric character       |
 |                         | reference, which is a decimal form of Unicode |
-|                         | code point with format ``&#num;`` Implemented |
-|                         | in :func:`xmlcharrefreplace_errors`.          |
+|                         | code point with format :samp:`&#{num};`.      |
+|                         | Implemented in                                |
+|                         | :func:`xmlcharrefreplace_errors`.             |
 +-------------------------+-----------------------------------------------+
 | ``'namereplace'``       | Replace with ``\N{...}`` escape sequences,    |
 |                         | what appears in the braces is the Name        |
@@ -478,8 +480,9 @@ functions:
 
    Malformed data is replaced by a backslashed escape sequence.
    On encoding, use the hexadecimal form of Unicode code point with formats
-   ``\xhh`` ``\uxxxx`` ``\Uxxxxxxxx``. On decoding, use the hexadecimal form of
-   byte value with format ``\xhh``.
+   :samp:`\\x{hh}` :samp:`\\u{xxxx}` :samp:`\\U{xxxxxxxx}`.
+   On decoding, use the hexadecimal form of
+   byte value with format :samp:`\\x{hh}`.
 
    .. versionchanged:: 3.5
       Works with decoding and translating.
@@ -492,7 +495,7 @@ functions:
 
    The unencodable character is replaced by an appropriate XML/HTML numeric
    character reference, which is a decimal form of Unicode code point with
-   format ``&#num;`` .
+   format :samp:`&#{num};` .
 
 
 .. function:: namereplace_errors(exception)
@@ -1346,9 +1349,10 @@ encodings.
 |                    |         | supported.                |
 +--------------------+---------+---------------------------+
 | raw_unicode_escape |         | Latin-1 encoding with     |
-|                    |         | ``\uXXXX`` and            |
-|                    |         | ``\UXXXXXXXX`` for other  |
-|                    |         | code points. Existing     |
+|                    |         | :samp:`\\u{XXXX}` and     |
+|                    |         | :samp:`\\U{XXXXXXXX}`     |
+|                    |         | for other code points.    |
+|                    |         | Existing                  |
 |                    |         | backslashes are not       |
 |                    |         | escaped in any way.       |
 |                    |         | It is used in the Python  |

Doc/library/compileall.rst

@@ -29,7 +29,7 @@ compile Python sources.
 
    Positional arguments are files to compile or directories that contain
    source files, traversed recursively.  If no argument is given, behave as if
-   the command line was ``-l <directories from sys.path>``.
+   the command line was :samp:`-l {<directories from sys.path>}`.
 
 .. cmdoption:: -l
 

Doc/library/concurrent.futures.rst

@@ -293,6 +293,14 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
       The *max_tasks_per_child* argument was added to allow users to
       control the lifetime of workers in the pool.
 
+   .. versionchanged:: 3.12
+      On POSIX systems, if your application has multiple threads and the
+      :mod:`multiprocessing` context uses the ``"fork"`` start method:
+      The :func:`os.fork` function called internally to spawn workers may raise a
+      :exc:`DeprecationWarning`. Pass a *mp_context* configured to use a
+      different start method. See the :func:`os.fork` documentation for
+      further explanation.
+
 .. _processpoolexecutor-example:
 
 ProcessPoolExecutor Example

Doc/library/devmode.rst

@@ -59,8 +59,9 @@ Effects of the Python Development Mode:
   ``default``.
 
 * Call :func:`faulthandler.enable` at Python startup to install handlers for
-  the :const:`SIGSEGV`, :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and
-  :const:`SIGILL` signals to dump the Python traceback on a crash.
+  the :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`,
+  :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS` and
+  :const:`~signal.SIGILL` signals to dump the Python traceback on a crash.
 
   It behaves as if the :option:`-X faulthandler <-X>` command line option is
   used or if the :envvar:`PYTHONFAULTHANDLER` environment variable is set to