Merge branch 'python:main' into configparser_perf

Author: 2trvl

Doc/conf.py

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

Doc/data/stable_abi.dat

@@ -658,6 +658,9 @@ Glossary
       and therefore it is never deallocated while the interpreter is running.
       For example, :const:`True` and :const:`None` are immortal in CPython.
 
+      Immortal objects can be identified via :func:`sys._is_immortal`, or
+      via :c:func:`PyUnstable_IsImmortal` in the C API.
+
    immutable
       An object with a fixed value.  Immutable objects include numbers, strings and
       tuples.  Such an object cannot be altered.  A new object has to

Doc/glossary.rst

@@ -855,6 +855,11 @@ always available. Unless explicitly noted otherwise, all variables are read-only
    reflect the actual number of references.  Consequently, do not rely
    on the returned value to be accurate, other than a value of 0 or 1.
 
+   .. impl-detail::
+
+      :term:`Immortal <immortal>` objects with a large reference count can be
+      identified via :func:`_is_immortal`.
+
    .. versionchanged:: 3.12
       Immortal objects have very large refcounts that do not match
       the actual number of references to the object.
@@ -1264,6 +1269,24 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 
    .. versionadded:: 3.12
 
+.. function:: _is_immortal(op)
+
+   Return :const:`True` if the given object is :term:`immortal`, :const:`False`
+   otherwise.
+
+   .. note::
+
+      Objects that are immortal (and thus return ``True`` upon being passed
+      to this function) are not guaranteed to be immortal in future versions,
+      and vice versa for mortal objects.
+
+   .. versionadded:: next
+
+   .. impl-detail::
+
+      This function should be used for specialized purposes only.
+      It is not guaranteed to exist in all implementations of Python.
+
 .. function:: _is_interned(string)
 
    Return :const:`True` if the given string is "interned", :const:`False`

Doc/library/sys.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/license.rst

@@ -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/make.bat

@@ -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/availability.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/misc_news.py

@@ -141,46 +141,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 documenting Opcodes
 
 opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?')
@@ -268,6 +228,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/extensions/pyspecific.py

@@ -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 %}