gh-121277: Allow .. versionadded:: next in docs

Doc/c-api/long.rst

@@ -511,7 +511,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    On failure, return -1 with an exception set.  This function always succeeds
    if *obj* is a :c:type:`PyLongObject` or its subtype.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. c:function:: int PyUnstable_Long_IsCompact(const PyLongObject* op)

Doc/c-api/unicode.rst

@@ -1534,7 +1534,7 @@ PyUnicodeWriter
 The :c:type:`PyUnicodeWriter` API can be used to create a Python :class:`str`
 object.
 
-.. versionadded:: 3.14
+.. versionadded:: next
 
 .. c:type:: PyUnicodeWriter
 

Doc/library/ast.rst

@@ -2485,7 +2485,7 @@ effects on the compilation of a program:
    differ in whitespace or similar details. Attributes include line numbers
    and column offsets.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. _ast-cli:

Doc/library/ctypes.rst

@@ -2303,7 +2303,7 @@ These are the fundamental ctypes data types:
    Represents the C :c:expr:`double complex` datatype, if available.  The
    constructor accepts an optional :class:`complex` initializer.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. class:: c_float_complex

Doc/library/dis.rst

@@ -926,7 +926,7 @@ iterations of the loop.
    list of constants supported by this instruction.  Used by the :keyword:`assert`
    statement to load :exc:`AssertionError`.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. opcode:: LOAD_BUILD_CLASS
@@ -1798,7 +1798,7 @@ iterations of the loop.
    If ``type(STACK[-1]).__xxx__`` is not a method, leave
    ``STACK[-1].__xxx__; NULL`` on the stack.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 **Pseudo-instructions**

Doc/library/pathlib.rst

@@ -1554,7 +1554,7 @@ Copying, renaming and deleting
    extended attributes are copied where supported. This argument has no effect
    on Windows, where metadata is always preserved when copying.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. method:: Path.copytree(target, *, follow_symlinks=True, dirs_exist_ok=False, \
@@ -1581,7 +1581,7 @@ Copying, renaming and deleting
    nothing, in which case the copying operation continues. If *on_error* isn't
    given, exceptions are propagated to the caller.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. method:: Path.rename(target)

Doc/library/symtable.rst

@@ -239,7 +239,7 @@ Examining Symbol Tables
 
       Return ``True`` if the symbol is a type parameter.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_global()
 
@@ -286,7 +286,7 @@ Examining Symbol Tables
       be free from the perspective of ``C.method``, thereby allowing
       the latter to return *1* at runtime and not *2*.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_assigned()
 
@@ -296,13 +296,13 @@ Examining Symbol Tables
 
       Return ``True`` if the symbol is a comprehension iteration variable.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_comp_cell()
 
       Return ``True`` if the symbol is a cell in an inlined comprehension.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_namespace()
 

Doc/tools/extensions/pyspecific.py

@@ -29,6 +29,7 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx.writers.text import TextWriter, TextTranslator
 from sphinx.util.display import status_iterator
+import sphinx.domains.changeset
 
 
 ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s'
@@ -393,7 +394,22 @@ def run(self):
         return PyMethod.run(self)
 
 
-# Support for documenting version of removal in deprecations
+# Support for documenting version of changes, additions, deprecations
+
+def expand_version_arg(argument, release):
+    """Expand "next" to the current version"""
+    if argument == 'next':
+        return sphinx_gettext('{} (unreleased)').format(release)
+    return argument
+
+
+class PyVersionChange(sphinx.domains.changeset.VersionChange):
+    def run(self):
+        # Replace the 'next' special token with the current development version
+        self.arguments[0] = expand_version_arg(self.arguments[0],
+                                               self.config.release)
+        return super().run()
+
 
 class DeprecatedRemoved(VersionChange):
     required_arguments = 2
@@ -404,7 +420,8 @@ class DeprecatedRemoved(VersionChange):
     def run(self):
         # Replace the first two arguments (deprecated version and removed version)
         # with a single tuple of both versions.
-        version_deprecated = self.arguments[0]
+        version_deprecated = expand_version_arg(self.arguments[0],
+                                                self.config.release)
         version_removed = self.arguments.pop(1)
         self.arguments[0] = version_deprecated, version_removed
 
@@ -674,6 +691,10 @@ def setup(app):
     app.add_directive('availability', Availability)
     app.add_directive('audit-event', AuditEvent)
     app.add_directive('audit-event-table', AuditEventListDirective)
+    app.add_directive('versionadded', PyVersionChange, override=True)
+    app.add_directive('versionchanged', PyVersionChange, override=True)
+    app.add_directive('versionremoved', PyVersionChange, override=True)
+    app.add_directive('deprecated', PyVersionChange, override=True)
     app.add_directive('deprecated-removed', DeprecatedRemoved)
     app.add_builder(PydocTopicsBuilder)
     app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)

Doc/tools/version_next.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""
+Replace `.. versionchanged:: next` lines in docs files by the given version.
+
+Run this at release time to replace `next` with the just-released version
+in the sources.
+
+No backups are made; add/commit to Git before running the script.
+
+Applies to all the VersionChange directives. For deprecated-removed, only
+handle the first argument (deprecation version, not the removal version).
+
+"""
+
+import re
+import sys
+import argparse
+from pathlib import Path
+
+DIRECTIVE_RE = re.compile(
+    r'''
+        (?P<before>
+            \s*\.\.\s+
+            (version(added|changed|removed)|deprecated(-removed)?)
+            \s*::\s*
+        )
+        next
+        (?P<after>
+            .*
+        )
+    ''',
+    re.VERBOSE | re.DOTALL,
+)
+
+docdir = (Path(__file__)
+          .parent  # cpython/Doc/tools
+          .parent  # cpython/Doc
+          .resolve()
+          )
+
+parser = argparse.ArgumentParser(
+    description=__doc__,
+    formatter_class=argparse.RawDescriptionHelpFormatter)
+parser.add_argument('version',
+                    help='String to replace "next" with.')
+parser.add_argument('directory', type=Path, nargs='?',
+                    help=f'Directory to process. Default: {docdir}',
+                    default=docdir)
+parser.add_argument('--verbose', '-v', action='count', default=0)
+
+def main(argv):
+    args = parser.parse_args(argv)
+    version = args.version
+    if args.verbose:
+        print(
+            f'Updating "next" versions in {args.directory} to {version!r}',
+            file=sys.stderr)
+    for path in Path(args.directory).glob('**/*.rst'):
+        num_changed_lines = 0
+        lines = []
+        with open(path, encoding='utf-8') as file:
+            for lineno, line in enumerate(file, start=1):
+                if match := DIRECTIVE_RE.fullmatch(line):
+                    line = match['before'] + version + match['after']
+                    num_changed_lines += 1
+                lines.append(line)
+        if num_changed_lines:
+            if args.verbose:
+                print(f'Updating file {path} ({num_changed_lines} changes)',
+                    file=sys.stderr)
+            with open(path, 'w', encoding='utf-8') as file:
+                file.writelines(lines)
+        else:
+            if args.verbose > 1:
+                print(f'Unchanged file {path}', file=sys.stderr)
+
+
+if __name__ == '__main__':
+    main(sys.argv[1:])

Lib/test/test_tools/test_docs_version_next.py

@@ -0,0 +1,99 @@
+"""Sanity-check tests for the "docs/replace_versoin_next" tool."""
+
+from pathlib import Path
+import unittest
+
+from test.test_tools import basepath
+from test.support.import_helper import DirsOnSysPath, import_module
+from test.support import os_helper
+from test import support
+
+print(basepath)
+tooldir = Path(basepath) / 'Doc' / 'tools'
+print(tooldir)
+
+with DirsOnSysPath(str(tooldir)):
+    import sys
+    print(sys.path)
+    version_next = import_module('version_next')
+
+TO_CHANGE = """
+Directives to change
+--------------------
+
+Here, all occurences of NEXT (lowercase) should be changed:
+
+.. versionadded:: next
+
+.. versionchanged:: next
+
+.. deprecated:: next
+
+.. deprecated-removed:: next 4.0
+
+whitespace:
+
+..   versionchanged:: next
+
+.. versionchanged  :: next
+
+    .. versionadded:: next
+
+arguments:
+
+.. versionadded:: next
+    Foo bar
+
+.. versionadded:: next as ``previousname``
+"""
+
+UNCHANGED = """
+Unchanged
+---------
+
+Here, the word "next" should NOT be changed:
+
+.. versionchanged:: NEXT
+
+..versionchanged:: NEXT
+
+... versionchanged:: next
+
+foo .. versionchanged:: next
+
+.. otherdirective:: next
+
+.. VERSIONCHANGED: next
+
+.. deprecated-removed: 3.0 next
+"""
+
+EXPECTED_CHANGED = TO_CHANGE.replace('next', 'VER')
+
+
+class TestVersionNext(unittest.TestCase):
+    maxDiff = len(TO_CHANGE + UNCHANGED) * 10
+
+    def test_freeze_simple_script(self):
+        with os_helper.temp_dir() as testdir:
+            path = Path(testdir)
+            path.joinpath('source.rst').write_text(TO_CHANGE + UNCHANGED)
+            path.joinpath('subdir').mkdir()
+            path.joinpath('subdir/change.rst').write_text(
+                '.. versionadded:: next')
+            path.joinpath('subdir/keep.not-rst').write_text(
+                '.. versionadded:: next')
+            path.joinpath('subdir/keep.rst').write_text(
+                'nothing to see here')
+            args = ['VER', testdir]
+            if support.verbose:
+                args.append('-vv')
+            version_next.main(args)
+            self.assertEqual(path.joinpath('source.rst').read_text(),
+                             EXPECTED_CHANGED + UNCHANGED)
+            self.assertEqual(path.joinpath('subdir/change.rst').read_text(),
+                             '.. versionadded:: VER')
+            self.assertEqual(path.joinpath('subdir/keep.not-rst').read_text(),
+                             '.. versionadded:: next')
+            self.assertEqual(path.joinpath('subdir/keep.rst').read_text(),
+                             'nothing to see here')

Misc/NEWS.d/next/Documentation/2024-07-19-12-22-48.gh-issue-121277.wF_zKd.rst

@@ -0,0 +1,2 @@
+Writers of CPython's documentation can now use ``next`` as the version for
+the ``versionchanged``, ``versionadded``, ``deprecated`` directives.