Merge branch '3.12' into backport-55596ae-3.12

.github/workflows/build.yml

@@ -255,7 +255,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        openssl_ver: [1.1.1w, 3.0.13, 3.1.5, 3.2.1]
+        openssl_ver: [3.0.15, 3.1.7, 3.2.3, 3.3.2]
     env:
       OPENSSL_VER: ${{ matrix.openssl_ver }}
       MULTISSL_DIR: ${{ github.workspace }}/multissl
@@ -311,7 +311,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true' && needs.check_source.outputs.run_hypothesis == 'true'
     env:
-      OPENSSL_VER: 3.0.13
+      OPENSSL_VER: 3.0.15
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v4
@@ -424,7 +424,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
-      OPENSSL_VER: 3.0.13
+      OPENSSL_VER: 3.0.15
       PYTHONSTRICTEXTENSIONBUILD: 1
       ASAN_OPTIONS: detect_leaks=0:allocator_may_return_null=1:handle_segv=0
     steps:

.github/workflows/reusable-change-detection.yml

@@ -126,13 +126,18 @@ jobs:
           .github/workflows/reusable-docs.yml
         format: csv  # works for paths with spaces
     - name: Check for docs changes
+      # We only want to run this on PRs when related files are changed,
+      # or when user triggers manual workflow run.
       if: >-
-        github.event_name == 'pull_request'
-        && steps.changed-docs-files.outputs.added_modified_renamed != ''
+        (
+          github.event_name == 'pull_request'
+          && steps.changed-docs-files.outputs.added_modified_renamed != ''
+        ) || github.event_name == 'workflow_dispatch'
       id: docs-changes
       run: |
         echo "run-docs=true" >> "${GITHUB_OUTPUT}"
     - name: Get a list of the MSI installer-related files
+      if: github.event_name == 'pull_request'
       id: changed-win-msi-files
       uses: Ana06/[email protected]
       with:
@@ -141,10 +146,13 @@ jobs:
           .github/workflows/reusable-windows-msi.yml
         format: csv  # works for paths with spaces
     - name: Check for changes in MSI installer-related files
+      # We only want to run this on PRs when related files are changed,
+      # or when user triggers manual workflow run.
       if: >-
-        steps.changed-win-msi-files.outputs.added_modified_renamed != ''
+        (
+          github.event_name == 'pull_request'
+          && steps.changed-win-msi-files.outputs.added_modified_renamed != ''
+        ) || github.event_name == 'workflow_dispatch'
       id: win-msi-changes
       run: |
         echo "run-win-msi=true" >> "${GITHUB_OUTPUT}"
-
-...

.github/workflows/reusable-docs.yml

@@ -25,9 +25,15 @@ jobs:
     - name: 'Check out latest PR branch commit'
       uses: actions/checkout@v4
       with:
-        ref: ${{ github.event.pull_request.head.sha }}
+        ref: >-
+          ${{
+            github.event_name == 'pull_request'
+            && github.event.pull_request.head.sha
+            || ''
+          }}
     # Adapted from https://github.com/actions/checkout/issues/520#issuecomment-1167205721
     - name: 'Fetch commits to get branch diff'
+      if: github.event_name == 'pull_request'
       run: |
         # Fetch enough history to find a common ancestor commit (aka merge-base):
         git fetch origin ${{ env.refspec_pr }} --depth=$(( ${{ github.event.pull_request.commits }} + 1 )) \

.github/workflows/reusable-ubuntu.yml

@@ -16,7 +16,7 @@ jobs:
     timeout-minutes: 60
     runs-on: ubuntu-22.04
     env:
-      OPENSSL_VER: 3.0.13
+      OPENSSL_VER: 3.0.15
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v4

Doc/Makefile

@@ -188,54 +188,69 @@ dist:
 	mkdir -p dist
 
 	# archive the HTML
-	make html
+	@echo "Building HTML..."
+	$(MAKE) html
 	cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
 	bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
 	(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)
 	rm -r dist/python-$(DISTVERSION)-docs-html
 	rm dist/python-$(DISTVERSION)-docs-html.tar
+	@echo "Build finished and archived!"
 
 	# archive the text build
-	make text
+	@echo "Building text..."
+	$(MAKE) text
 	cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
 	bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar
 	(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text)
 	rm -r dist/python-$(DISTVERSION)-docs-text
 	rm dist/python-$(DISTVERSION)-docs-text.tar
+	@echo "Build finished and archived!"
 
 	# archive the A4 latex
+	@echo "Building LaTeX (A4 paper)..."
 	rm -rf build/latex
-	make latex PAPER=a4
-	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
-	(cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+	$(MAKE) latex PAPER=a4
+	# remove zip & bz2 dependency on all-pdf,
+	# as otherwise the full latexmk process is run twice.
+	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
+	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
+	@echo "Build finished and archived!"
 
 	# archive the letter latex
+	@echo "Building LaTeX (US paper)..."
 	rm -rf build/latex
-	make latex PAPER=letter
-	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
-	(cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+	$(MAKE) latex PAPER=letter
+	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
+	@echo "Build finished and archived!"
 
 	# copy the epub build
+	@echo "Building EPUB..."
 	rm -rf build/epub
-	make epub
+	$(MAKE) epub
 	cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
+	@echo "Build finished and archived!"
 
 	# archive the texinfo build
+	@echo "Building Texinfo..."
 	rm -rf build/texinfo
-	make texinfo
-	make info --directory=build/texinfo
+	$(MAKE) texinfo
+	$(MAKE) info --directory=build/texinfo
 	cp -pPR build/texinfo dist/python-$(DISTVERSION)-docs-texinfo
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-texinfo.tar python-$(DISTVERSION)-docs-texinfo
 	bzip2 -9 -k dist/python-$(DISTVERSION)-docs-texinfo.tar
 	(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-texinfo.zip python-$(DISTVERSION)-docs-texinfo)
 	rm -r dist/python-$(DISTVERSION)-docs-texinfo
 	rm dist/python-$(DISTVERSION)-docs-texinfo.tar
+	@echo "Build finished and archived!"
 
 .PHONY: _ensure-package
 _ensure-package: venv
@@ -247,11 +262,11 @@ _ensure-package: venv
 
 .PHONY: _ensure-pre-commit
 _ensure-pre-commit:
-	make _ensure-package PACKAGE=pre-commit
+	$(MAKE) _ensure-package PACKAGE=pre-commit
 
 .PHONY: _ensure-sphinx-autobuild
 _ensure-sphinx-autobuild:
-	make _ensure-package PACKAGE=sphinx-autobuild
+	$(MAKE) _ensure-package PACKAGE=sphinx-autobuild
 
 .PHONY: check
 check: _ensure-pre-commit
@@ -271,12 +286,12 @@ serve:
 # for development releases: always build
 .PHONY: autobuild-dev
 autobuild-dev:
-	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for quick rebuilds (HTML only)
 .PHONY: autobuild-dev-html
 autobuild-dev-html:
-	make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage
@@ -286,12 +301,12 @@ autobuild-stable:
 		echo "Not building; $(DISTVERSION) is not a release version."; \
 		exit 1;; \
 	esac
-	@make autobuild-dev
+	@$(MAKE) autobuild-dev
 
 .PHONY: autobuild-stable-html
 autobuild-stable-html:
 	@case $(DISTVERSION) in *[ab]*) \
 		echo "Not building; $(DISTVERSION) is not a release version."; \
 		exit 1;; \
 	esac
-	@make autobuild-dev-html
+	@$(MAKE) autobuild-dev-html

Doc/c-api/datetime.rst

@@ -318,10 +318,10 @@ Macros for the convenience of modules implementing the DB API:
 .. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
 
    Create and return a new :class:`datetime.datetime` object given an argument
-   tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`.
+   tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp`.
 
 
 .. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
 
    Create and return a new :class:`datetime.date` object given an argument
-   tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`.
+   tuple suitable for passing to :meth:`datetime.date.fromtimestamp`.

Doc/c-api/exceptions.rst

@@ -34,7 +34,7 @@ propagated, additional calls into the Python/C API may not behave as intended
 and may fail in mysterious ways.
 
 .. note::
-   The error indicator is **not** the result of :func:`sys.exc_info()`.
+   The error indicator is **not** the result of :func:`sys.exc_info`.
    The former corresponds to an exception that is not yet caught (and is
    therefore still propagating), while the latter returns an exception after
    it is caught (and has therefore stopped propagating).

Doc/c-api/import.rst

@@ -174,7 +174,7 @@ Importing Modules
 
    .. versionadded:: 3.2
    .. versionchanged:: 3.3
-      Uses :func:`!imp.source_from_cache()` in calculating the source path if
+      Uses :func:`!imp.source_from_cache` in calculating the source path if
       only the bytecode path is provided.
    .. versionchanged:: 3.12
       No longer uses the removed :mod:`!imp` module.

Doc/c-api/init_config.rst

@@ -311,7 +311,7 @@ PyPreConfig
       * Set :c:member:`PyConfig.filesystem_encoding` to ``"mbcs"``,
       * Set :c:member:`PyConfig.filesystem_errors` to ``"replace"``.
 
-      Initialized the from :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
+      Initialized from the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
       variable value.
 
       Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for

Doc/c-api/tuple.rst

@@ -33,25 +33,27 @@ Tuple Objects
 
 .. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
 
-   Return a new tuple object of size *len*, or ``NULL`` on failure.
+   Return a new tuple object of size *len*,
+   or ``NULL`` with an exception set on failure.
 
 
 .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
 
-   Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values
+   Return a new tuple object of size *n*,
+   or ``NULL`` with an exception set on failure. The tuple values
    are initialized to the subsequent *n* C arguments pointing to Python objects.
    ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
 
 
 .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
 
    Take a pointer to a tuple object, and return the size of that tuple.
+   On error, return ``-1`` and with an exception set.
 
 
 .. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
 
-   Return the size of the tuple *p*, which must be non-``NULL`` and point to a tuple;
-   no error checking is performed.
+   Like :c:func:`PyTuple_Size`, but without error checking.
 
 
 .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
@@ -74,8 +76,10 @@ Tuple Objects
 .. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
 
    Return the slice of the tuple pointed to by *p* between *low* and *high*,
-   or ``NULL`` on failure.  This is the equivalent of the Python expression
-   ``p[low:high]``.  Indexing from the end of the tuple is not supported.
+   or ``NULL`` with an exception set on failure.
+
+   This is the equivalent of the Python expression ``p[low:high]``.
+   Indexing from the end of the tuple is not supported.
 
 
 .. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
@@ -132,6 +136,8 @@ type.
    Create a new struct sequence type from the data in *desc*, described below. Instances
    of the resulting type can be created with :c:func:`PyStructSequence_New`.
 
+   Return ``NULL`` with an exception set on failure.
+
 
 .. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
 
@@ -140,8 +146,8 @@ type.
 
 .. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
 
-   The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
-   failure.
+   Like :c:func:`PyStructSequence_InitType`, but returns ``0`` on success
+   and ``-1`` with an exception set on failure.
 
    .. versionadded:: 3.4
 
@@ -198,6 +204,8 @@ type.
    Creates an instance of *type*, which must have been created with
    :c:func:`PyStructSequence_NewType`.
 
+   Return ``NULL`` with an exception set on failure.
+
 
 .. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
 

Doc/conf.py

@@ -294,6 +294,7 @@
 # Allow translation of index directives
 gettext_additional_targets = [
     'index',
+    'literal-block',
 ]
 
 # Options for HTML output

Doc/constraints.txt

@@ -7,18 +7,20 @@
 # Direct dependencies of Sphinx
 babel<3
 colorama<0.5
-imagesize<1.5
-Jinja2<3.2
+imagesize<2
+Jinja2<4
 packaging<25
 Pygments<3
 requests<3
 snowballstemmer<3
-sphinxcontrib-applehelp<2.1
-sphinxcontrib-devhelp<2.1
-sphinxcontrib-htmlhelp<2.2
-sphinxcontrib-jsmath<1.1
-sphinxcontrib-qthelp<2.1
-sphinxcontrib-serializinghtml<2.1
+# keep lower-bounds until Sphinx 8.1 is released
+# https://github.com/sphinx-doc/sphinx/pull/12756
+sphinxcontrib-applehelp>=1.0.7,<3
+sphinxcontrib-devhelp>=1.0.6,<3
+sphinxcontrib-htmlhelp>=2.0.6,<3
+sphinxcontrib-jsmath>=1.0.1,<2
+sphinxcontrib-qthelp>=1.0.6,<3
+sphinxcontrib-serializinghtml>=1.1.9,<3
 
 # Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
-MarkupSafe<2.2
+MarkupSafe<3

Doc/deprecations/pending-removal-in-3.13.rst

@@ -48,5 +48,5 @@ APIs:
   * ``read_binary()``
   * ``read_text()``
 
-  Use :func:`importlib.resources.files()` instead.  Refer to `importlib-resources: Migrating from Legacy
+  Use :func:`importlib.resources.files` instead.  Refer to `importlib-resources: Migrating from Legacy
   <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_ (:gh:`106531`)

Doc/deprecations/pending-removal-in-3.15.rst

@@ -9,8 +9,8 @@ Pending Removal in Python 3.15
 * :class:`locale`: :func:`locale.getdefaultlocale` was deprecated in Python 3.11
   and originally planned for removal in Python 3.13 (:gh:`90817`),
   but removal has been postponed to Python 3.15.
-  Use :func:`locale.setlocale()`, :func:`locale.getencoding()` and
-  :func:`locale.getlocale()` instead.
+  Use :func:`locale.setlocale`, :func:`locale.getencoding` and
+  :func:`locale.getlocale` instead.
   (Contributed by Hugo van Kemenade in :gh:`111187`.)
 
 * :mod:`pathlib`:

Doc/deprecations/pending-removal-in-3.16.rst

@@ -5,6 +5,9 @@ Pending Removal in Python 3.16
   :class:`array.array` ``'u'`` type (:c:type:`wchar_t`):
   use the ``'w'`` type instead (``Py_UCS4``).
 
+* :mod:`builtins`:
+  ``~bool``, bitwise inversion on bool.
+
 * :mod:`symtable`:
   Deprecate :meth:`symtable.Class.get_methods` due to the lack of interest.
   (Contributed by Bénédikt Tran in :gh:`119698`.)