gh-106137: Add SoftDeprecationWarning category

[vstinner]

• 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.

• Issue: Add SoftDeprecationWarning warning category #106137

---

📚 Documentation preview 📚: https://cpython-previews--106142.org.readthedocs.build/

[vstinner]

I mark this PR as a draft until python/peps#3182 is merged.

[vstinner]

I will create a separated PR to add soft-deprecated:: markup in the Sphinx pyspecific extension (I have a local branch for that, but I prefer to create a separated PR).

[vstinner]

You can test this PR by soft deprecating the optparse module with this patch:

diff --git a/Lib/optparse.py b/Lib/optparse.py
index 1c450c6fcb..ff1e24e295 100644
--- a/Lib/optparse.py
+++ b/Lib/optparse.py
@@ -76,6 +76,10 @@
 import sys, os
 import textwrap
 
+import warnings
+warnings._soft_deprecated("the optparse module is soft deprecated: "
+                          "consider using the argparse module instead")
+
 def _repr(self):
     return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self)
 

[vstinner]

Examples with Python built in release mode.

SoftDeprecationWarning is ignored by default:

$ ./python -c 'import warnings, pprint; pprint.pprint(warnings.filters)'
[('default', None, <class 'DeprecationWarning'>, '__main__', 0),
 ('default', None, <class 'SoftDeprecationWarning'>, '__main__', 0),
 ('ignore', None, <class 'DeprecationWarning'>, None, 0),
 ('ignore', None, <class 'PendingDeprecationWarning'>, None, 0),
 ('ignore', None, <class 'SoftDeprecationWarning'>, None, 0),
 ('ignore', None, <class 'ImportWarning'>, None, 0),
 ('ignore', None, <class 'ResourceWarning'>, None, 0)]

Example with soft deprecated optparse module (see the patch above), the warning is ignored because it's not event emitted:

$ ./python -Wdefault -c 'import optparse; print("ok")'
ok

In the Python Development Mode, the warning is emitted and displayed:

$ ./python -Xdev -c 'import optparse; print("ok")'
<string>:1: SoftDeprecationWarning: the optparse module is soft deprecated: consider using the argparse module instead
ok

$ ./python -Xdev 
Python 3.13.0a0 (heads/soft_deprecation-dirty:b6dc14a213, Jun 27 2023, 16:25:49) [GCC 13.1.1 20230614 (Red Hat 13.1.1-4)] on linux
Type "help", "copyright", "credits" or "license" for more information.

>>> import optparse
<stdin>:1: SoftDeprecationWarning: the optparse module is soft deprecated: consider using the argparse module instead

Ignore the soft deprecation warning in the Python Development Mode with -Wignore::SoftDeprecationWarning command line option:

$ ./python -Xdev -Wignore::SoftDeprecationWarning -c 'import optparse; print("ok")'
ok

[vstinner]

The idea of issuing a warning for soft deprecations is not liked, so I abandon my idea: https://discuss.python.org/t/formalize-the-concept-of-soft-deprecation-dont-schedule-removal-in-pep-387-backwards-compatibility-policy/27957