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

@@ -1509,7 +1509,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

@@ -2487,7 +2487,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

@@ -2299,7 +2299,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_int

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

@@ -1559,7 +1559,7 @@ Copying, renaming and deleting
       raises :exc:`OSError` when a symlink to a directory is encountered and
       *follow_symlinks* is false.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. method:: Path.copytree(target, *, follow_symlinks=True, dirs_exist_ok=False, \
@@ -1586,7 +1586,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

@@ -28,6 +28,7 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx.writers.text import TextWriter, TextTranslator
 from sphinx.util.display import status_iterator
+import sphinx.directives.other
 
 
 ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s'
@@ -393,7 +394,23 @@ 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, env):
+    """Expand "next" to the current version"""
+    if argument == 'next':
+        return sphinx_gettext('{} (unreleased)').format(env.config.release)
+    return argument
+
+
+class PyVersionChange(sphinx.directives.other.VersionChange):
+    def run(self):
+        env = self.state.document.settings.env
+        self.arguments = (
+            expand_version_arg(self.arguments[0], env),
+            *self.arguments[1:])
+        return super().run()
+
 
 class DeprecatedRemoved(Directive):
     has_content = True
@@ -409,17 +426,18 @@ def run(self):
         node = addnodes.versionmodified()
         node.document = self.state.document
         node['type'] = 'deprecated-removed'
-        version = (self.arguments[0], self.arguments[1])
-        node['version'] = version
         env = self.state.document.settings.env
+        deprecated = expand_version_arg(self.arguments[0], env)
+        version = (deprecated, self.arguments[1])
+        node['version'] = version
         current_version = tuple(int(e) for e in env.config.version.split('.'))
         removed_version = tuple(int(e) for e in self.arguments[1].split('.'))
         if current_version < removed_version:
             label = self._deprecated_label
         else:
             label = self._removed_label
 
-        text = label.format(deprecated=self.arguments[0], removed=self.arguments[1])
+        text = label.format(deprecated=deprecated, removed=self.arguments[1])
         if len(self.arguments) == 3:
             inodes, messages = self.state.inline_text(self.arguments[2],
                                                       self.lineno+1)
@@ -448,7 +466,6 @@ def run(self):
         env.get_domain('changeset').note_changeset(node)
         return [node] + messages
 
-
 # Support for including Misc/NEWS
 
 issue_re = re.compile('(?:[Ii]ssue #|bpo-)([0-9]+)', re.I)
@@ -698,6 +715,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,76 @@
+#!/usr/bin/env python3
+"""
+Replace `.. versionchanged:: next` lines in docs files by the given version.
+
+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,
+)
+
+basedir = (Path(__file__)
+           .parent  # cpython/Tools/doc
+           .parent  # cpython/Tools
+           .parent  # cpython
+           .resolve()
+           )
+docdir = basedir / 'Doc'
+
+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) 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') 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')