Add a new Sphinx soft-deprecated directive (#148630)

Co-authored-by: Stan Ulbrych <stan@python.org>

Author: hugovk

Doc/c-api/allocation.rst

@@ -2,7 +2,7 @@
 
 .. _allocating-objects:
 
-Allocating Objects on the Heap
+Allocating objects on the heap
 ==============================
 
 
@@ -153,18 +153,20 @@ Allocating Objects on the Heap
       To allocate and create extension modules.
 
 
-Deprecated aliases
-^^^^^^^^^^^^^^^^^^
+Soft-deprecated aliases
+^^^^^^^^^^^^^^^^^^^^^^^
 
-These are :term:`soft deprecated` aliases to existing functions and macros.
+.. soft-deprecated:: 3.15
+
+These are aliases to existing functions and macros.
 They exist solely for backwards compatibility.
 
 
 .. list-table::
    :widths: auto
    :header-rows: 1
 
-   * * Deprecated alias
+   * * Soft-deprecated alias
      * Function
    * * .. c:macro:: PyObject_NEW(type, typeobj)
      * :c:macro:`PyObject_New`

Doc/c-api/bytes.rst

@@ -47,9 +47,9 @@ called with a non-bytes parameter.
    *len* on success, and ``NULL`` on failure.  If *v* is ``NULL``, the contents of
    the bytes object are uninitialized.
 
-   .. deprecated:: 3.15
-      ``PyBytes_FromStringAndSize(NULL, len)`` is :term:`soft deprecated`,
-      use the :c:type:`PyBytesWriter` API instead.
+   .. soft-deprecated:: 3.15
+      Use the :c:type:`PyBytesWriter` API instead of
+      ``PyBytes_FromStringAndSize(NULL, len)``.
 
 
 .. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
@@ -238,9 +238,8 @@ called with a non-bytes parameter.
    *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
    returned.
 
-   .. deprecated:: 3.15
-      The function is :term:`soft deprecated`,
-      use the :c:type:`PyBytesWriter` API instead.
+   .. soft-deprecated:: 3.15
+      Use the :c:type:`PyBytesWriter` API instead.
 
 
 .. c:function:: PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)

Doc/c-api/extension-modules.rst

@@ -191,10 +191,10 @@ the :c:data:`Py_mod_multiple_interpreters` slot.
 ``PyInit`` function
 ...................
 
-.. deprecated:: 3.15
+.. soft-deprecated:: 3.15
 
-   This functionality is :term:`soft deprecated`.
-   It will not get new features, but there are no plans to remove it.
+   This functionality will not get new features,
+   but there are no plans to remove it.
 
 Instead of :c:func:`PyModExport_modulename`, an extension module can define
 an older-style :dfn:`initialization function` with the signature:
@@ -272,10 +272,9 @@ For example, a module called ``spam`` would be defined like this::
 Legacy single-phase initialization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. deprecated:: 3.15
+.. soft-deprecated:: 3.15
 
-   Single-phase initialization is :term:`soft deprecated`.
-   It is a legacy mechanism to initialize extension
+   Single-phase initialization is a legacy mechanism to initialize extension
    modules, with known drawbacks and design flaws. Extension module authors
    are encouraged to use multi-phase initialization instead.
 

Doc/c-api/file.rst

@@ -2,7 +2,7 @@
 
 .. _fileobjects:
 
-File Objects
+File objects
 ------------
 
 .. index:: pair: object; file
@@ -136,11 +136,12 @@ the :mod:`io` APIs instead.
    failure; the appropriate exception will be set.
 
 
-Deprecated API
-^^^^^^^^^^^^^^
+Soft-deprecated API
+^^^^^^^^^^^^^^^^^^^
 
+.. soft-deprecated:: 3.15
 
-These are :term:`soft deprecated` APIs that were included in Python's C API
+These are APIs that were included in Python's C API
 by mistake. They are documented solely for completeness; use other
 ``PyFile*`` APIs instead.
 

Doc/c-api/float.rst

@@ -86,8 +86,7 @@ Floating-Point Objects
    It is equivalent to the :c:macro:`!INFINITY` macro from the C11 standard
    ``<math.h>`` header.
 
-   .. deprecated:: 3.15
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 
 .. c:macro:: Py_NAN
@@ -103,8 +102,7 @@ Floating-Point Objects
 
    Equivalent to :c:macro:`!INFINITY`.
 
-   .. deprecated:: 3.14
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.14
 
 
 .. c:macro:: Py_MATH_E
@@ -161,26 +159,26 @@ Floating-Point Objects
    that is, it is normal, subnormal or zero, but not infinite or NaN.
    Return ``0`` otherwise.
 
-   .. deprecated:: 3.14
-      The macro is :term:`soft deprecated`.  Use :c:macro:`!isfinite` instead.
+   .. soft-deprecated:: 3.14
+      Use :c:macro:`!isfinite` instead.
 
 
 .. c:macro:: Py_IS_INFINITY(X)
 
    Return ``1`` if the given floating-point number *X* is positive or negative
    infinity.  Return ``0`` otherwise.
 
-   .. deprecated:: 3.14
-      The macro is :term:`soft deprecated`.  Use :c:macro:`!isinf` instead.
+   .. soft-deprecated:: 3.14
+      Use :c:macro:`!isinf` instead.
 
 
 .. c:macro:: Py_IS_NAN(X)
 
    Return ``1`` if the given floating-point number *X* is a not-a-number (NaN)
    value.  Return ``0`` otherwise.
 
-   .. deprecated:: 3.14
-      The macro is :term:`soft deprecated`.  Use :c:macro:`!isnan` instead.
+   .. soft-deprecated:: 3.14
+      Use :c:macro:`!isnan` instead.
 
 
 Pack and Unpack functions

Doc/c-api/frame.rst

@@ -1,6 +1,6 @@
 .. highlight:: c
 
-Frame Objects
+Frame objects
 -------------
 
 .. c:type:: PyFrameObject
@@ -147,7 +147,7 @@ See also :ref:`Reflection <reflection>`.
    Return the line number that *frame* is currently executing.
 
 
-Frame Locals Proxies
+Frame locals proxies
 ^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.13
@@ -169,7 +169,7 @@ See :pep:`667` for more information.
    Return non-zero if *obj* is a frame :func:`locals` proxy.
 
 
-Legacy Local Variable APIs
+Legacy local variable APIs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing.
@@ -178,48 +178,42 @@ They exist solely for backwards compatibility.
 
 .. c:function:: void PyFrame_LocalsToFast(PyFrameObject *f, int clear)
 
-   This function is :term:`soft deprecated` and does nothing.
-
    Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals`
    attribute of *f* to the internal "fast" array of local variables, allowing
    changes in frame objects to be visible to the interpreter. If *clear* was
    true, this function would process variables that were unset in the locals
    dictionary.
 
-   .. versionchanged:: 3.13
+   .. soft-deprecated:: 3.13
       This function now does nothing.
 
 
 .. c:function:: void PyFrame_FastToLocals(PyFrameObject *f)
 
-   This function is :term:`soft deprecated` and does nothing.
-
    Prior to Python 3.13, this function would copy the internal "fast" array
    of local variables (which is used by the interpreter) to the
    :attr:`~frame.f_locals` attribute of *f*, allowing changes in local
    variables to be visible to frame objects.
 
-   .. versionchanged:: 3.13
+   .. soft-deprecated:: 3.13
       This function now does nothing.
 
 
 .. c:function:: int PyFrame_FastToLocalsWithError(PyFrameObject *f)
 
-   This function is :term:`soft deprecated` and does nothing.
-
    Prior to Python 3.13, this function was similar to
    :c:func:`PyFrame_FastToLocals`, but would return ``0`` on success, and
    ``-1`` with an exception set on failure.
 
-   .. versionchanged:: 3.13
+   .. soft-deprecated:: 3.13
       This function now does nothing.
 
 
 .. seealso::
    :pep:`667`
 
 
-Internal Frames
+Internal frames
 ^^^^^^^^^^^^^^^
 
 Unless using :pep:`523`, you will not need this.
@@ -249,5 +243,3 @@ Unless using :pep:`523`, you will not need this.
    Return the currently executing line number, or -1 if there is no line number.
 
    .. versionadded:: 3.12
-
-

Doc/c-api/intro.rst

@@ -536,16 +536,14 @@ have been standardized in C11 (or previous standards).
 
    Use the standard ``alignas`` specifier rather than this macro.
 
-   .. deprecated:: 3.15
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 .. c:macro:: PY_FORMAT_SIZE_T
 
    The :c:func:`printf` formatting modifier for :c:type:`size_t`.
    Use ``"z"`` directly instead.
 
-   .. deprecated:: 3.15
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 .. c:macro:: Py_LL(number)
              Py_ULL(number)
@@ -558,8 +556,7 @@ have been standardized in C11 (or previous standards).
 
    Consider using the C99 standard suffixes ``LL`` and ``LLU`` directly.
 
-   .. deprecated:: 3.15
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 .. c:macro:: PY_LONG_LONG
              PY_INT32_T
@@ -572,8 +569,7 @@ have been standardized in C11 (or previous standards).
    respectively.
    Historically, these types needed compiler-specific extensions.
 
-   .. deprecated:: 3.15
-      These macros are :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 .. c:macro:: PY_LLONG_MIN
              PY_LLONG_MAX
@@ -587,16 +583,14 @@ have been standardized in C11 (or previous standards).
    The required header, ``<limits.h>``,
    :ref:`is included <capi-system-includes>` in ``Python.h``.
 
-   .. deprecated:: 3.15
-      These macros are :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 .. c:macro:: Py_MEMCPY(dest, src, n)
 
    This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
    Use :c:func:`!memcpy` directly instead.
 
-   .. deprecated:: 3.14
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.14
 
 .. c:macro:: Py_UNICODE_SIZE
 
@@ -606,16 +600,14 @@ have been standardized in C11 (or previous standards).
    The required header for the latter, ``<limits.h>``,
    :ref:`is included <capi-system-includes>` in ``Python.h``.
 
-   .. deprecated:: 3.15
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 .. c:macro:: Py_UNICODE_WIDE
 
    Defined if ``wchar_t`` can hold a Unicode character (UCS-4).
    Use ``sizeof(wchar_t) >= 4`` instead
 
-   .. deprecated:: 3.15
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 .. c:macro:: Py_VA_COPY
 
@@ -627,8 +619,7 @@ have been standardized in C11 (or previous standards).
    .. versionchanged:: 3.6
       This is now an alias to ``va_copy``.
 
-   .. deprecated:: 3.15
-      The macro is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.15
 
 
 .. _api-objects:

Doc/c-api/long.rst

@@ -197,12 +197,10 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    .. c:function:: long PyLong_AS_LONG(PyObject *obj)
 
-      A :term:`soft deprecated` alias.
       Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
       it can fail with :exc:`OverflowError` or another exception.
 
-      .. deprecated:: 3.14
-         The function is soft deprecated.
+      .. soft-deprecated:: 3.14
 
 .. c:function:: int PyLong_AsInt(PyObject *obj)
 

Doc/c-api/module.rst

@@ -965,9 +965,7 @@ or code that creates modules dynamically.
         // PyModule_AddObject() stole a reference to obj:
         // Py_XDECREF(obj) is not needed here.
 
-   .. deprecated:: 3.13
-
-      :c:func:`PyModule_AddObject` is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.13
 
 
 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

Doc/c-api/monitoring.rst

@@ -205,6 +205,4 @@ would typically correspond to a Python function.
 
    .. versionadded:: 3.13
 
-   .. deprecated:: 3.14
-
-      This function is :term:`soft deprecated`.
+   .. soft-deprecated:: 3.14