Skip to content

bpo-36404: recommend DeprecationWarning over PendingDeprecationWarning #12505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 5, 2019
Merged

bpo-36404: recommend DeprecationWarning over PendingDeprecationWarning #12505

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2398f0f
deprecate PendingDeprecationWarning in doc
methane Mar 23, 2019
f1d64da
fix based on PR comments
methane Mar 23, 2019
77910b8
deprecated -> note
methane Mar 30, 2019
ee8cabb
Update exceptions.rst
methane Apr 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions Doc/library/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -694,6 +694,14 @@ The following exceptions are used as warning categories; see the
Base class for warnings about features which will be deprecated in the
future.

.. note::
PendingDeprecationWarning was introduced as an "ignored by default"
version of DeprecationWarning. But :exc:`DeprecationWarning` is also
ignored by default since Python 2.7 and 3.2.
There is not much difference between PendingDeprecationWarning and
DeprecationWarning nowadays. DeprecationWarning is recommended
in general.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not accurate in Python 3.7+, since DeprecationWarning is not ignored by default in __main__ any more.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it really much different?
I didn't say any different.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In PEP 565, you used async keyword example. It is really nice example to demonstrate what difference PEP 565 introduces.

On the other hand, most reader of this document will not want to add new keyword. Most of them just want to deprecate their APIs that are not in __main__.
And, as you know, calling deprecated APIs from __main__ doesn't show warning by default.

So there are no much difference.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Calling deprecated APIs from __main__ does show the warning as long as the stack level on the warning is correctly set to refer to the API caller's frame - async becoming a keyword was just our motivation for finally doing something about the behaviour.

For example: all of Serhiy's new warnings about parameters that are going to become positional only? Those will display if the caller is __main__, as they set stacklevel=2 in the warning call, so the filtering ends up being based on the caller's frame, not the frame making the call to the warnings module API.

Copy link
Member Author

@methane methane Apr 8, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was wrong, I used Python 3.6 for testing it.

I still think it's not "much" difference. But if you don't like this phrase, how about this?

See :pep:`565` for current difference between PendingDeprecationWarning and
DeprecationWarning.  DeprecationWarning is recommended in general.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd drop the attention getting "Note" markup entirely, and simply reword the existing description with a comparison to DeprecationWarning:

Base class for warnings about features which are expected to be deprecated in the
future. For most deprecations, :exc:DeprecationWarning is preferred (as it's rare to
need to emit a warning about a possible upcoming deprecation in advance of the
deprecation itself).

Copy link
Member Author

@methane methane Apr 9, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is still confusing for people doesn't know Python history.

Base class for warnings about features which are expected to be deprecated in the
future.

It's still difficult to imagine what "expected to be deprecated".

For most deprecations, :exc:DeprecationWarning is preferred (as it's rare to
need to emit a warning about a possible upcoming deprecation in advance of the
deprecation itself).

I think DeprecationWarning is preferred for all deprecations. How about:

Base class for warnings about features which are obsolete and
expected to be deprecated in the future, but are not deprecated
at the moment.

This class is rarely used because it's rare to need warning about
a possible upcoming deprecation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The direct cross-reference to DeprecationWarning is probably worth keeping, so I'd amend the second paragraph a bit to add that back:

Base class for warnings about features which are obsolete and
expected to be deprecated in the future, but are not deprecated
at the moment.

This class is rarely used as emitting a warning about a possible
upcoming deprecation is unusual, and :exc:`DeprecationWarning`
is preferred for already active deprecations.



.. exception:: SyntaxWarning

Expand Down
10 changes: 5 additions & 5 deletions Doc/library/warnings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,11 +109,11 @@ The following warnings category classes are currently defined:
+----------------------------------+-----------------------------------------------+

.. versionchanged:: 3.7
Previously :exc:`DeprecationWarning` and :exc:`FutureWarning` were
distinguished based on whether a feature was being removed entirely or
changing its behaviour. They are now distinguished based on their
intended audience and the way they're handled by the default warnings
filters.
Previously :exc:`DeprecationWarning` and :exc:`FutureWarning` were
distinguished based on whether a feature was being removed entirely or
changing its behaviour. They are now distinguished based on their
intended audience and the way they're handled by the default warnings
filters.


.. _warning-filter:
Expand Down