gh-141004: Document old provisional names for vectorcall/code API (GH-143568)

gh-141004: Document old provisional names for vectorcall & code API

For vectorcall API, the underscore-prefixed provisional names
continue to be available per PEP 590:
https://peps.python.org/pep-0590/#finalizing-the-api
Use `versionadded`, `versionchanged`, and `:no-typesetting:`
to mark this up.

For PyCode API, use `:no-typesetting:` rather than `index::` so that
these are semantically documented as C functions.

diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst
index 7198d6bc056eb43e7a38c37d9d7c90986ae34d1d..9838879a528934ab02478fd9e871605c54c17026 100644 (file)
--- a/Doc/c-api/call.rst
+++ b/Doc/c-api/call.rst
@@ -347,6 +347,8 @@ please see individual documentation for details.
 
    .. versionadded:: 3.9
 
+.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
+   :no-typesetting:
 
 .. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
 
@@ -358,7 +360,12 @@ please see individual documentation for details.
    Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
-   .. versionadded:: 3.9
+   .. versionadded:: 3.8 as ``_PyObject_Vectorcall``
+
+   .. versionchanged:: 3.9
+
+      Renamed to the current name, without the leading underscore.
+      The old provisional name is :term:`soft deprecated`.
 
 .. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
 

diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 45f5e83adc48c62dd25ec6b02017974f06e23a1b..048bc2c2154e77627eb840c75adcb6e53a3852cf 100644 (file)
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -69,13 +69,14 @@ bound into a function.
       The old name is deprecated, but will remain available until the
       signature changes again.
 
+.. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(...)
+   :no-typesetting:
+
 .. c:function:: PyCodeObject* PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
 
    Similar to :c:func:`PyUnstable_Code_New`, but with an extra "posonlyargcount" for positional-only arguments.
    The same caveats that apply to ``PyUnstable_Code_New`` also apply to this function.
 
-   .. index:: single: PyCode_NewWithPosOnlyArgs (C function)
-
    .. versionadded:: 3.8 as ``PyCode_NewWithPosOnlyArgs``
 
    .. versionchanged:: 3.11
@@ -298,6 +299,9 @@ These functions are part of the unstable C API tier:
 this functionality is a CPython implementation detail, and the API
 may change without deprecation warnings.
 
+.. c:function:: Py_ssize_t _PyEval_RequestCodeExtraIndex(freefunc free)
+   :no-typesetting:
+
 .. c:function:: Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)
 
    Return a new opaque index value used to adding data to code objects.
@@ -310,8 +314,6 @@ may change without deprecation warnings.
    *free* will be called on non-``NULL`` data stored under the new index.
    Use :c:func:`Py_DecRef` when storing :c:type:`PyObject`.
 
-   .. index:: single: _PyEval_RequestCodeExtraIndex (C function)
-
    .. versionadded:: 3.6 as ``_PyEval_RequestCodeExtraIndex``
 
    .. versionchanged:: 3.12
@@ -320,6 +322,9 @@ may change without deprecation warnings.
      The old private name is deprecated, but will be available until the API
      changes.
 
+.. c:function:: int _PyCode_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
+   :no-typesetting:
+
 .. c:function:: int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
 
    Set *extra* to the extra data stored under the given index.
@@ -328,8 +333,6 @@ may change without deprecation warnings.
    If no data was set under the index, set *extra* to ``NULL`` and return
    0 without setting an exception.
 
-   .. index:: single: _PyCode_GetExtra (C function)
-
    .. versionadded:: 3.6 as ``_PyCode_GetExtra``
 
    .. versionchanged:: 3.12
@@ -338,13 +341,14 @@ may change without deprecation warnings.
      The old private name is deprecated, but will be available until the API
      changes.
 
+.. c:function:: int _PyCode_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
+   :no-typesetting:
+
 .. c:function:: int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
 
    Set the extra data stored under the given index to *extra*.
    Return 0 on success. Set an exception and return -1 on failure.
 
-   .. index:: single: _PyCode_SetExtra (C function)
-
    .. versionadded:: 3.6 as ``_PyCode_SetExtra``
 
    .. versionchanged:: 3.12

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index efac86078f9af559a4131425a47601c0a12b0a44..a33da367e6071f9c462d4bb581d78be09a6776a8 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1373,6 +1373,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
          type structure.
 
 
+   .. c:macro:: _Py_TPFLAGS_HAVE_VECTORCALL
+      :no-typesetting:
+
    .. c:macro:: Py_TPFLAGS_HAVE_VECTORCALL
 
       This bit is set when the class implements
@@ -1384,7 +1387,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)
       This bit is inherited if :c:member:`~PyTypeObject.tp_call` is also
       inherited.
 
-      .. versionadded:: 3.9
+      .. versionadded:: 3.8 as ``_Py_TPFLAGS_HAVE_VECTORCALL``
+
+      .. versionchanged:: 3.9
+
+      Renamed to the current name, without the leading underscore.
+      The old provisional name is :term:`soft deprecated`.
 
       .. versionchanged:: 3.12