[issue31975] Add a default filter for DeprecationWarning in __main__

[Nick Coghlan]

Nick Coghlan <ncoghlan at gmail.com> added the comment:

As far as documentation goes, there are the amendments I'm considering:

===================
exception DeprecationWarning

    Base class for warnings about deprecated features. Visible by default for APIs called from `__main__` modules and when using the unittest test runner. See :exc:`PendingDeprecationWarning` and :exc:`FutureWarning` to emit warnings for future backwards incompatible changes with different default visibility.

exception PendingDeprecationWarning

    Base class for warnings about features which will be deprecated in the future. Hidden by default, even for APIs called from `__main__` modules and when using the unittest test runner. See :exc:`DeprecationWarning` and :exc:`FutureWarning` to emit warnings for future backwards incompatible changes with different default visibility.

exception FutureWarning

    Base class for warnings about constructs that will change semantically or cease working in the future. Always visible by default, even for code in imported modules. See :exc:`PendingDeprecationWarning` and :exc:`DeprecationWarning` to emit warnings for future backwards incompatible changes with different default visibility.
===================

(I'd also add notes on default visibility to the other warning categories - ImportWarning, BytesWarning, and ResourceWarning are the other "hidden by default" categories)

DeprecationWarning gets the preferred name because it has the semantics we think we will like best for that use case (i.e. visible in __main__ and while running tests, hidden otherwise), while cross-referencing it with FutureWarning and PendingDeprecationWarning makes it clear Python developers are still free to opt-in to either the pre-2.7 behaviour or the pre-3.7 behaviour if that's what they prefer for the APIs they expose.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue31975>
_______________________________________