gh-106137: Add SoftDeprecationWarning category

* Add SoftDeprecationWarning warning category.
* Add default warnings filters for SoftDeprecationWarning: ignore
  SoftDeprecationWarning by default, except in the __main__ module
  (similar to PEP 565).
* Add warnings._soft_deprecated(): only emit SoftDeprecationWarning
  in Python Development Mode and if Python is built in debug mode.
* Add PyExc_SoftDeprecationWarning to the limited C API.

Author: vstinner

Doc/c-api/exceptions.rst

@@ -1166,6 +1166,7 @@ the variables:
    single: PyExc_PendingDeprecationWarning
    single: PyExc_ResourceWarning
    single: PyExc_RuntimeWarning
+   single: PyExc_SoftDeprecationWarning
    single: PyExc_SyntaxWarning
    single: PyExc_UnicodeWarning
    single: PyExc_UserWarning
@@ -1189,6 +1190,8 @@ the variables:
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_RuntimeWarning`           | :exc:`RuntimeWarning`           |          |
 +------------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_SoftDeprecationWarning`   | :exc:`SoftDeprecationWarning`   |          |
++------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_SyntaxWarning`            | :exc:`SyntaxWarning`            |          |
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_UnicodeWarning`           | :exc:`UnicodeWarning`           |          |
@@ -1199,6 +1202,9 @@ the variables:
 .. versionadded:: 3.2
    :c:data:`PyExc_ResourceWarning`.
 
+.. versionadded:: 3.13
+   :c:data:`PyExc_SoftDeprecationWarning`.
+
 Notes:
 
 .. [3]

Doc/data/stable_abi.dat

@@ -802,6 +802,19 @@ The following exceptions are used as warning categories; see the
    The deprecation policy is described in :pep:`387`.
 
 
+.. exception:: SoftDeprecationWarning
+
+   Base class for warnings about soft deprecated features when those warnings
+   are intended for other Python developers.
+
+   Ignored by the default warning filters, except in the ``__main__`` module.
+   Enabling the :ref:`Python Development Mode <devmode>` shows this warning.
+
+   The soft deprecation policy is described in :pep:`387`.
+
+   .. versionadded:: 3.13
+
+
 .. exception:: PendingDeprecationWarning
 
    Base class for warnings about features which are obsolete and

Doc/library/exceptions.rst

@@ -76,6 +76,9 @@ New Features
 Other Language Changes
 ======================
 
+* Add :exc:`SoftDeprecationWarning` warning category to implement soft
+  deprecation. The soft deprecation policy is described in :pep:`387`.
+  (Contributed by Victor Stinner in :gh:`106137`.)
 
 
 New Modules
@@ -441,6 +444,10 @@ New Features
   ``NULL`` if the referent is no longer live.
   (Contributed by Victor Stinner in :gh:`105927`.)
 
+* Add :c:data:`PyExc_SoftDeprecationWarning` warning category to implement soft
+  deprecation. The soft deprecation policy is described in :pep:`387`.
+  (Contributed by Victor Stinner in :gh:`106137`.)
+
 Porting to Python 3.13
 ----------------------
 

Doc/whatsnew/3.13.rst

@@ -153,6 +153,7 @@ PyAPI_DATA(PyObject *) PyExc_Warning;
 PyAPI_DATA(PyObject *) PyExc_UserWarning;
 PyAPI_DATA(PyObject *) PyExc_DeprecationWarning;
 PyAPI_DATA(PyObject *) PyExc_PendingDeprecationWarning;
+PyAPI_DATA(PyObject *) PyExc_SoftDeprecationWarning;
 PyAPI_DATA(PyObject *) PyExc_SyntaxWarning;
 PyAPI_DATA(PyObject *) PyExc_RuntimeWarning;
 PyAPI_DATA(PyObject *) PyExc_FutureWarning;

Include/pyerrors.h

@@ -62,6 +62,7 @@ BaseException
            ├── PendingDeprecationWarning
            ├── ResourceWarning
            ├── RuntimeWarning
+           ├── SoftDeprecationWarning
            ├── SyntaxWarning
            ├── UnicodeWarning
            └── UserWarning

Lib/test/exception_hierarchy.txt

@@ -13,6 +13,13 @@ def import_deprecated(name):
         return importlib.import_module(name)
 
 
+def import_soft_deprecated(name):
+    """Import *name* while suppressing SoftDeprecationWarning."""
+    with warnings.catch_warnings():
+        warnings.simplefilter('ignore', category=SoftDeprecationWarning)
+        return importlib.import_module(name)
+
+
 def check_syntax_warning(testcase, statement, errtext='',
                          *, lineno=1, offset=None):
     # Test also that a warning is emitted only once.

Lib/test/support/warnings_helper.py

@@ -542,7 +542,8 @@ def test_exceptions(self):
                            RecursionError,
                            EncodingWarning,
                            BaseExceptionGroup,
-                           ExceptionGroup):
+                           ExceptionGroup,
+                           SoftDeprecationWarning):
                     continue
                 if exc is not OSError and issubclass(exc, OSError):
                     self.assertEqual(reverse_mapping('builtins', name),

Lib/test/test_pickle.py

@@ -1242,8 +1242,10 @@ def test_default_filter_configuration(self):
                 main_module_filter = "__main__"
             expected_default_filters = [
                 ('default', None, DeprecationWarning, main_module_filter, 0),
+                ('default', None, SoftDeprecationWarning, main_module_filter, 0),
                 ('ignore', None, DeprecationWarning, None, 0),
                 ('ignore', None, PendingDeprecationWarning, None, 0),
+                ('ignore', None, SoftDeprecationWarning, None, 0),
                 ('ignore', None, ImportWarning, None, 0),
                 ('ignore', None, ResourceWarning, None, 0),
             ]

Lib/test/test_stable_abi_ctypes.py

@@ -529,6 +529,13 @@ def _deprecated(name, message=_DEPRECATED_MSG, *, remove, _version=sys.version_i
         warn(msg, DeprecationWarning, stacklevel=3)
 
 
+def _soft_deprecated(msg):
+    # only emit SoftDeprecationWarning in the Python Development Mode
+    # and if Python is built in debug mode
+    if sys.flags.dev_mode or hasattr(sys, 'gettotalrefcount'):
+        warn(msg, SoftDeprecationWarning, stacklevel=3)
+
+
 # Private utility function called by _PyErr_WarnUnawaitedCoroutine
 def _warn_unawaited_coroutine(coro):
     msg_lines = [
@@ -587,8 +594,11 @@ def _filters_mutated():
     if not hasattr(sys, 'gettotalrefcount'):
         filterwarnings("default", category=DeprecationWarning,
                        module="__main__", append=1)
+        filterwarnings("default", category=SoftDeprecationWarning,
+                       module="__main__", append=1)
         simplefilter("ignore", category=DeprecationWarning, append=1)
         simplefilter("ignore", category=PendingDeprecationWarning, append=1)
+        simplefilter("ignore", category=SoftDeprecationWarning, append=1)
         simplefilter("ignore", category=ImportWarning, append=1)
         simplefilter("ignore", category=ResourceWarning, append=1)
 

Lib/test/test_warnings/__init__.py

@@ -0,0 +1,3 @@
+Add :exc:`PyExc_SoftDeprecationWarning` warning category to implement soft
+deprecation. The soft deprecation policy is described in :pep:`387`. Patch
+by Victor Stinner.

Lib/warnings.py

@@ -0,0 +1,3 @@
+Add :exc:`SoftDeprecationWarning` warning category to implement soft
+deprecation. The soft deprecation policy is described in :pep:`387`. Patch
+by Victor Stinner.

Misc/NEWS.d/next/C API/2023-06-27-16-15-47.gh-issue-106137.GysR0_.rst

@@ -2432,3 +2432,5 @@
     added = '3.13'
 [function.PyWeakref_GetRef]
     added = '3.13'
+[data.PyExc_SoftDeprecationWarning]
+    added = '3.13'

Misc/NEWS.d/next/Core and Builtins/2023-06-27-16-16-19.gh-issue-106137.hArJmO.rst

@@ -3461,6 +3461,13 @@ SimpleExtendsException(PyExc_Warning, PendingDeprecationWarning,
     "in the future.");
 
 
+/*
+ *    SoftDeprecationWarning extends Warning
+ */
+SimpleExtendsException(PyExc_Warning, SoftDeprecationWarning,
+                       "Base class for warnings about soft deprecated features.");
+
+
 /*
  *    SyntaxWarning extends Warning
  */
@@ -3630,6 +3637,7 @@ static struct static_exception static_exceptions[] = {
     ITEM(PendingDeprecationWarning),
     ITEM(ResourceWarning),
     ITEM(RuntimeWarning),
+    ITEM(SoftDeprecationWarning),
     ITEM(SyntaxWarning),
     ITEM(UnicodeWarning),
     ITEM(UserWarning),

Misc/stable_abi.toml

@@ -96,7 +96,7 @@ init_filters(PyInterpreterState *interp)
     return PyList_New(0);
 #else
     /* Other builds ignore a number of warning categories by default */
-    PyObject *filters = PyList_New(5);
+    PyObject *filters = PyList_New(7);
     if (filters == NULL) {
         return NULL;
     }
@@ -106,8 +106,10 @@ init_filters(PyInterpreterState *interp)
     PyList_SET_ITEM(filters, pos++, \
                     create_filter(TYPE, &_Py_ID(ACTION), MODNAME));
     ADD(PyExc_DeprecationWarning, default, "__main__");
+    ADD(PyExc_SoftDeprecationWarning, default, "__main__");
     ADD(PyExc_DeprecationWarning, ignore, NULL);
     ADD(PyExc_PendingDeprecationWarning, ignore, NULL);
+    ADD(PyExc_SoftDeprecationWarning, ignore, NULL);
     ADD(PyExc_ImportWarning, ignore, NULL);
     ADD(PyExc_ResourceWarning, ignore, NULL);
 #undef ADD