gh-106137: Add SoftDeprecationWarning category by vstinner · Pull Request #106142 · python/cpython · GitHub
Skip to content

gh-106137: Add SoftDeprecationWarning category - #106142

Closed
vstinner wants to merge 3 commits into
python:mainfrom
vstinner:soft_deprecation
Closed

gh-106137: Add SoftDeprecationWarning category#106142
vstinner wants to merge 3 commits into
python:mainfrom
vstinner:soft_deprecation

Conversation

@vstinner

@vstinner vstinner commented Jun 27, 2023 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member
  • 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.

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

@vstinner
vstinner requested review from a team, encukou and iritkatriel as code owners June 27, 2023 14:21
@bedevere-bot bedevere-bot mentioned this pull request Jun 27, 2023
Closed
@vstinner
vstinner marked this pull request as draft June 27, 2023 14:22
@vstinner

vstinner commented Jun 27, 2023

Copy link
Copy Markdown
Member Author

@vstinner vstinner mentioned this pull request Jun 27, 2023
Merged
@vstinner

vstinner commented Jun 27, 2023

Copy link
Copy Markdown
Member Author

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

vstinner commented Jun 27, 2023

Copy link
Copy Markdown
Member Author

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

vstinner commented Jun 27, 2023 •
edited
Loading

Copy link
Copy Markdown
Member Author

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
vstinner force-pushed the soft_deprecation branch 3 times, most recently from ca9ff20 to 1e0e98d Compare June 28, 2023 01:25
vstinner added 2 commits June 28, 2023 03:51
@vstinner
pythongh-106137: Add SoftDeprecationWarning category
eb01d78 
* 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.
@vstinner
Update test_cmd_line
2a2370e
@vstinner

vstinner commented Jun 30, 2023

Copy link
Copy Markdown
Member Author

@vstinner vstinner closed this Jun 30, 2023
@vstinner
vstinner deleted the soft_deprecation branch June 30, 2023 09:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@encukou encukou Awaiting requested review from encukou encukou is a code owner
@iritkatriel iritkatriel Awaiting requested review from iritkatriel iritkatriel is a code owner
@ericsnowcurrently ericsnowcurrently Awaiting requested review from ericsnowcurrently ericsnowcurrently will be requested when the pull request is marked ready for review ericsnowcurrently is a code owner
@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner will be requested when the pull request is marked ready for review AA-Turner is a code owner
@ZeroIntensity ZeroIntensity Awaiting requested review from ZeroIntensity ZeroIntensity will be requested when the pull request is marked ready for review ZeroIntensity is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@vstinner @bedevere-bot