Merge branch '3.13' into backport-9d63ae5-3.13

Author: Yhg1s

Doc/c-api/module.rst

@@ -523,9 +523,6 @@ state:
 
    On success, return ``0``. On error, raise an exception and return ``-1``.
 
-   Return ``-1`` if *value* is ``NULL``. It must be called with an exception
-   raised in this case.
-
    Example usage::
 
        static int
@@ -540,6 +537,10 @@ state:
            return res;
         }
 
+   To be convenient, the function accepts ``NULL`` *value* with an exception
+   set. In this case, return ``-1`` and just leave the raised exception
+   unchanged.
+
    The example can also be written without checking explicitly if *obj* is
    ``NULL``::
 

Doc/conf.py

@@ -28,6 +28,7 @@
     'changes',
     'glossary_search',
     'lexers',
+    'misc_news',
     'pyspecific',
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',

Doc/library/exceptions.rst

@@ -562,9 +562,13 @@ The following exceptions are the exceptions that are usually raised.
 
    Raised when the interpreter finds an internal error, but the situation does not
    look so serious to cause it to abandon all hope. The associated value is a
-   string indicating what went wrong (in low-level terms).
+   string indicating what went wrong (in low-level terms). In :term:`CPython`,
+   this could be raised by incorrectly using Python's C API, such as returning
+   a ``NULL`` value without an exception set.
 
-   You should report this to the author or maintainer of your Python interpreter.
+   If you're confident that this exception wasn't your fault, or the fault of
+   a package you're using, you should report this to the author or maintainer
+   of your Python interpreter.
    Be sure to report the version of the Python interpreter (``sys.version``; it is
    also printed at the start of an interactive Python session), the exact error
    message (the exception's associated value) and if possible the source of the

Doc/license.rst

@@ -374,7 +374,7 @@ Project, https://www.wide.ad.jp/. ::
       may be used to endorse or promote products derived from this software
       without specific prior written permission.
 
-   THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
+   THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
@@ -583,7 +583,7 @@ interface::
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
 
-  THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+  THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
   ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
@@ -884,7 +884,7 @@ sources unless the build is configured ``--with-system-libffi``::
 
    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
-   ``Software''), to deal in the Software without restriction, including
+   "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
@@ -893,7 +893,7 @@ sources unless the build is configured ``--with-system-libffi``::
    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.
 
-   THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
@@ -1122,7 +1122,7 @@ The file is distributed under the 2-Clause BSD License::
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
 
-  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+  THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,

Doc/make.bat

@@ -127,16 +127,14 @@ goto end
 :build
 if not exist "%BUILDDIR%" mkdir "%BUILDDIR%"
 
-rem PY_MISC_NEWS_DIR is also used by our Sphinx extension in tools/extensions/pyspecific.py
-if not defined PY_MISC_NEWS_DIR set PY_MISC_NEWS_DIR=%BUILDDIR%\%1
-if not exist "%PY_MISC_NEWS_DIR%" mkdir "%PY_MISC_NEWS_DIR%"
+if not exist build mkdir build
 if exist ..\Misc\NEWS (
-    echo.Copying Misc\NEWS to %PY_MISC_NEWS_DIR%\NEWS
-    copy ..\Misc\NEWS "%PY_MISC_NEWS_DIR%\NEWS" > nul
+    echo.Copying existing Misc\NEWS file to Doc\build\NEWS
+    copy ..\Misc\NEWS build\NEWS > nul
 ) else if exist ..\Misc\NEWS.D (
     if defined BLURB (
         echo.Merging Misc/NEWS with %BLURB%
-        %BLURB% merge -f "%PY_MISC_NEWS_DIR%\NEWS"
+        %BLURB% merge -f build\NEWS
     ) else (
         echo.No Misc/NEWS file and Blurb is not available.
         exit /B 1

Doc/tools/extensions/availability.py

@@ -6,6 +6,7 @@
 
 from docutils import nodes
 from sphinx import addnodes
+from sphinx.locale import _ as sphinx_gettext
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 
@@ -55,7 +56,7 @@ class Availability(SphinxDirective):
     final_argument_whitespace = True
 
     def run(self) -> list[nodes.container]:
-        title = "Availability"
+        title = sphinx_gettext("Availability")
         refnode = addnodes.pending_xref(
             title,
             nodes.inline(title, title, classes=["xref", "std", "std-ref"]),

Doc/tools/extensions/misc_news.py

@@ -0,0 +1,75 @@
+"""Support for including Misc/NEWS."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from sphinx.locale import _ as sphinx_gettext
+from sphinx.util.docutils import SphinxDirective
+
+if TYPE_CHECKING:
+    from typing import Final
+
+    from docutils.nodes import Node
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+
+BLURB_HEADER = """\
++++++++++++
+Python News
++++++++++++
+"""
+
+bpo_issue_re: Final[re.Pattern[str]] = re.compile(
+    "(?:issue #|bpo-)([0-9]+)", re.ASCII
+)
+gh_issue_re: Final[re.Pattern[str]] = re.compile(
+    "gh-(?:issue-)?([0-9]+)", re.ASCII | re.IGNORECASE
+)
+whatsnew_re: Final[re.Pattern[str]] = re.compile(
+    r"^what's new in (.*?)\??$", re.ASCII | re.IGNORECASE | re.MULTILINE
+)
+
+
+class MiscNews(SphinxDirective):
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self) -> list[Node]:
+        # Get content of NEWS file
+        source, _ = self.get_source_info()
+        news_file = Path(source).resolve().parent / self.arguments[0]
+        self.env.note_dependency(news_file)
+        try:
+            news_text = news_file.read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            text = sphinx_gettext("The NEWS file is not available.")
+            return [nodes.strong(text, text)]
+
+        # remove first 3 lines as they are the main heading
+        news_text = news_text.removeprefix(BLURB_HEADER)
+
+        news_text = bpo_issue_re.sub(r":issue:`\1`", news_text)
+        # Fallback handling for GitHub issues
+        news_text = gh_issue_re.sub(r":gh:`\1`", news_text)
+        news_text = whatsnew_re.sub(r"\1", news_text)
+
+        self.state_machine.insert_input(news_text.splitlines(), str(news_file))
+        return []
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_directive("miscnews", MiscNews)
+
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

Doc/tools/extensions/pyspecific.py

@@ -147,46 +147,6 @@ def run(self):
         return PyMethod.run(self)
 
 
-# Support for including Misc/NEWS
-
-issue_re = re.compile('(?:[Ii]ssue #|bpo-)([0-9]+)', re.I)
-gh_issue_re = re.compile('(?:gh-issue-|gh-)([0-9]+)', re.I)
-whatsnew_re = re.compile(r"(?im)^what's new in (.*?)\??$")
-
-
-class MiscNews(SphinxDirective):
-    has_content = False
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = False
-    option_spec = {}
-
-    def run(self):
-        fname = self.arguments[0]
-        source = self.state_machine.input_lines.source(
-            self.lineno - self.state_machine.input_offset - 1)
-        source_dir = getenv('PY_MISC_NEWS_DIR')
-        if not source_dir:
-            source_dir = path.dirname(path.abspath(source))
-        fpath = path.join(source_dir, fname)
-        self.env.note_dependency(path.abspath(fpath))
-        try:
-            with io.open(fpath, encoding='utf-8') as fp:
-                content = fp.read()
-        except Exception:
-            text = 'The NEWS file is not available.'
-            node = nodes.strong(text, text)
-            return [node]
-        content = issue_re.sub(r':issue:`\1`', content)
-        # Fallback handling for the GitHub issue
-        content = gh_issue_re.sub(r':gh:`\1`', content)
-        content = whatsnew_re.sub(r'\1', content)
-        # remove first 3 lines as they are the main heading
-        lines = ['.. default-role:: obj', ''] + content.splitlines()[3:]
-        self.state_machine.insert_input(lines, fname)
-        return []
-
-
 # Support for building "topic help" for pydoc
 
 pydoc_topic_labels = [
@@ -338,6 +298,5 @@ def setup(app):
     app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
     app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
     app.add_directive_to_domain('py', 'abstractmethod', PyAbstractMethod)
-    app.add_directive('miscnews', MiscNews)
     app.connect('env-check-consistency', patch_pairindextypes)
     return {'version': '1.0', 'parallel_read_safe': True}

Doc/tools/templates/dummy.html

@@ -7,6 +7,10 @@
 {% trans %}Deprecated since version {deprecated}, will be removed in version {removed}{% endtrans %}
 {% trans %}Deprecated since version {deprecated}, removed in version {removed}{% endtrans %}
 
+In extensions/availability.py:
+
+{% trans %}Availability{% endtrans %}
+
 In extensions/c_annotations.py:
 
 {% trans %}Part of the{% endtrans %}

Doc/whatsnew/changelog.rst

@@ -1,5 +1,7 @@
 .. _changelog:
 
+.. default-role:: py:obj
+
 +++++++++
 Changelog
 +++++++++