Add a new Sphinx soft-deprecated directive

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/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/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

@@ -954,9 +954,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

Doc/c-api/sequence.rst

@@ -109,9 +109,8 @@ Sequence Protocol
 
    Alias for :c:func:`PySequence_Contains`.
 
-   .. deprecated:: 3.14
-      The function is :term:`soft deprecated` and should no longer be used to
-      write new code.
+   .. soft-deprecated:: 3.14
+      The function should no longer be used to write new code.
 
 
 .. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)

Doc/library/ctypes.rst

@@ -1756,11 +1756,10 @@ as a default or fallback.
    (or by) Python.
    It is recommended to only use this function as a default or fallback,
 
-   .. deprecated:: 3.15
+   .. soft-deprecated:: 3.15
 
-      This function is :term:`soft deprecated`.
-      It is kept for use in cases where it works, but not expected to be
-      updated for additional platforms and configurations.
+      This function is kept for use in cases where it works, but not expected to
+      be updated for additional platforms and configurations.
 
 On Linux, :func:`!find_library` tries to run external
 programs (``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the

Doc/library/math.rst

@@ -781,9 +781,8 @@ the following functions from the :mod:`math.integer` module:
    Floats with integral values (like ``5.0``) are no longer accepted in the
    :func:`factorial` function.
 
-.. deprecated:: 3.15
-   These aliases are :term:`soft deprecated` in favor of the
-   :mod:`math.integer` functions.
+.. soft-deprecated:: 3.15
+   Use the :mod:`math.integer` functions instead of these aliases.
 
 
 Constants

Doc/library/mimetypes.rst

@@ -54,7 +54,7 @@ the information :func:`init` sets up.
    .. versionchanged:: 3.8
       Added support for *url* being a :term:`path-like object`.
 
-   .. deprecated:: 3.13
+   .. soft-deprecated:: 3.13
       Passing a file path instead of URL is :term:`soft deprecated`.
       Use :func:`guess_file_type` for this.
 

Doc/library/os.rst

@@ -5110,9 +5110,8 @@ written in Python, such as a mail server's external command delivery program.
       Use :class:`subprocess.Popen` or :func:`subprocess.run` to
       control options like encodings.
 
-   .. deprecated:: 3.14
-      The function is :term:`soft deprecated` and should no longer be used to
-      write new code. The :mod:`subprocess` module is recommended instead.
+   .. soft-deprecated:: 3.14
+      The :mod:`subprocess` module is recommended instead.
 
 
 .. function:: posix_spawn(path, argv, env, *, file_actions=None, \
@@ -5340,9 +5339,8 @@ written in Python, such as a mail server's external command delivery program.
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
-   .. deprecated:: 3.14
-      These functions are :term:`soft deprecated` and should no longer be used
-      to write new code. The :mod:`subprocess` module is recommended instead.
+   .. soft-deprecated:: 3.14
+      The :mod:`subprocess` module is recommended instead.
 
 
 .. data:: P_NOWAIT

Doc/library/re.rst

@@ -931,7 +931,6 @@ Functions
 
 
 .. function:: prefixmatch(pattern, string, flags=0)
-.. function:: match(pattern, string, flags=0)
 
    If zero or more characters at the beginning of *string* match the regular
    expression *pattern*, return a corresponding :class:`~re.Match`.  Return
@@ -954,7 +953,11 @@ Functions
    :func:`~re.match`.  Use that name when you need to retain compatibility with
    older Python versions.
 
-   .. deprecated:: 3.15
+   .. versionadded:: 3.15
+
+.. function:: match(pattern, string, flags=0)
+
+   .. soft-deprecated:: 3.15
       :func:`~re.match` has been :term:`soft deprecated` in favor of
       the alternate :func:`~re.prefixmatch` name of this API which is
       more explicitly descriptive. Use it to better
@@ -1285,7 +1288,6 @@ Regular expression objects
 
 
 .. method:: Pattern.prefixmatch(string[, pos[, endpos]])
-.. method:: Pattern.match(string[, pos[, endpos]])
 
    If zero or more characters at the *beginning* of *string* match this regular
    expression, return a corresponding :class:`~re.Match`. Return ``None`` if the
@@ -1310,7 +1312,11 @@ Regular expression objects
    :meth:`~Pattern.match`.  Use that name when you need to retain compatibility
    with older Python versions.
 
-   .. deprecated:: 3.15
+   .. versionadded:: 3.15
+
+.. method:: Pattern.match(string[, pos[, endpos]])
+
+   .. soft-deprecated:: 3.15
       :meth:`~Pattern.match` has been :term:`soft deprecated` in favor of
       the alternate :meth:`~Pattern.prefixmatch` name of this API which is
       more explicitly descriptive. Use it to