Difference between DeprecationWarning, PendingDeprecationWarning and FutureWarning

Question

What is the difference between DeprecationWarning, PendingDeprecationWarning and FutureWarning? I saw in the Python 3 documentation that there is a difference in term of target “audience”, especially I don't understand the difference between “developers” and “end users”. This notion is a little blur for me. Can anyone explain and give examples?

I made a little table to summarize the use cases:

+---------------+---------------------------+---------------+
|               | Developers                | End Users     |
+---------------+---------------------------+---------------+
| Now           | DeprecationWarning        | ???           |
| In the future | PendingDeprecationWarning | FutureWarning |
+---------------+---------------------------+---------------+

Is there a “deprecation warning” for end users?

If I develop my own library. Is it a good idea to use those warnings or should I use a subclass of something else? In which use case?

Answer 1

The audience question is largely related to the idea that some Python is written to be a library, intended to be used by other people who write python scripts, whereas some Python is written to be applications that are intended to be used by people who might not know any programming.

The specific description you're referring to was a change in Python 3.7 You can read the whole description of the change at https://www.python.org/dev/peps/pep-0565/, but here's a particularly relevant section, with example use cases:

This will give the following three distinct categories of backwards compatibility warning, with three different intended audiences:

• PendingDeprecationWarning: hidden by default for all code. The intended audience is Python developers that take an active interest in ensuring the future compatibility of their software (e.g. professional Python application developers with specific support obligations).
• DeprecationWarning: reported by default for code that runs directly in the __main__ module (as such code is considered relatively unlikely to have a dedicated test suite), but hidden by default for code in other modules. The intended audience is Python developers that are at risk of upgrades to their dependencies (including upgrades to Python itself) breaking their software (e.g. developers using Python to script environments where someone else is in control of the timing of dependency upgrades).
• FutureWarning: reported by default for all code. The intended audience is users of applications written in Python, rather than other Python developers (e.g. warning about use of a deprecated setting in a configuration file format).

I don't think your table is quite accurate -- FutureWarning, as I understand it, should be for things that are deprecated now. As I understand these, DeprecationWarning means "change your code now or it will break soon", PendingDeprecationWarning means "you're going to have to change something eventually", and FutureWarning means "something in the way you're using this isn't correct, and may lead to failure later."

FutureWarning is also used to warn you that things won't behave the same in a future update, even though they will be valid code. This can relevant to both developers and users. For example, many of the FutureWarnings I've seen in practice are things where the meaning of some convenience function may change (like does == for two arrays return an array of True/False for each element, or does it return a single True/False, True only if all the elements are equal? When numpy wants to change this, they make a FutureWarning)

In developing your library, definitely use these or subclasses of them. People writing code using your library will expect their integration tests to issue DeprecationWarnings if there's a potential problem (more accurately, testing tools may specifically look for these).