bpo-36404: recommend DeprecationWarning over PendingDeprecationWarning (GH-12505)
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 57ed291..2509380 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -694,6 +694,14 @@
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.
+
.. exception:: SyntaxWarning
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index b04bd79..d121f32 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -109,11 +109,11 @@
+----------------------------------+-----------------------------------------------+
.. 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: