[Numpy-discussion] un-silencing Numpy's deprecation warnings

Robert Kern robert.kern at gmail.com
Tue May 22 06:06:50 EDT 2012

On Tue, May 22, 2012 at 9:27 AM, Nathaniel Smith <njs at pobox.com> wrote:
> So starting in Python 2.7 and 3.2, the Python developers have made
> DeprecationWarnings invisible by default:
>  http://docs.python.org/whatsnew/2.7.html#the-future-for-python-2-x
>  http://mail.python.org/pipermail/stdlib-sig/2009-November/000789.html
>  http://bugs.python.org/issue7319
> The only way to see them is to explicitly request them by running
> Python with -Wd.
> The logic seems to be that between the end-of-development for 2.7 and
> the moratorium on 3.2 changes, there were a *lot* of added
> deprecations that were annoying people, and deprecations in the Python
> stdlib mean "this code is probably sub-optimal but it will still
> continue to work indefinitely".

That's not quite it, I think, since this change was also made in
Python 3.2 and will remain for all future versions of Python.
DeprecationWarning *is* used for things that will definitely be going
away, not just things that are no longer recommended but will continue
to live. Note that the 3.2 moratorium was for changes to the language
proper. The point was to encourage stdlib development, including the
removal of deprecated code. It was not a moratorium on removing
deprecated things. The silencing discussion just came up first in a
discussion on the moratorium.

The main problem they were running into was that the people who saw
these warnings the most were not people directly using the deprecated
features; they were users of packages written by third parties that
used the deprecated features. Those people can't do anything to fix
the problem, and many of them think that something is broken when they
see the warning (I don't know why people do this, but they do). This
problem is exacerbated by the standard library's position as a
standard library. It's at the base of everyone's stack so these
indirect effects are quite frequent, quite possibly the majority case.
Users would use a newer version of Python library than the third party
developer tested on and see these errors instead of the developer.

I think this concern is fairly general and applies to numpy nearly as
much as it does the standard library. It is at the bottom of many
people's stacks. Someone calling matplotlib.pyplot.plot() should not
see a DeprecationWarning from numpy.

> So they consider that deprecation
> warnings are like a lint tool for conscientious developers who
> remember to test their code with -Wd, but not something to bother
> users with.
> In Numpy, the majority of our users are actually (relatively
> unsophisticated) developers,

Whether they sometimes wear a developer hat or not isn't the relevant
distinction. The question to ask is, "Are they the ones writing the
code that directly uses the deprecated features?"

> and we don't plan to support deprecated
> features indefinitely.

Again, this is not relevant. The silencing of DeprecationWarnings was
not driven by this.

> Our deprecations seem to better match what
> Python calls a "FutureWarning": "warnings about constructs that will
> change semantically in the future."
>  http://docs.python.org/library/warnings.html#warning-categories
> FutureWarning is displayed by default, and available in all versions of Python.
> So maybe we should change all our DeprecationWarnings into
> FutureWarnings (or at least the ones that we actually plan to follow
> through on). Thoughts?

Using FutureWarning for deprecated functions (i.e. functions that will
disappear in future releases) is an abuse of the semantics.
FutureWarning is for things like the numpy.histogram() changes from a
few years ago: changes in default arguments that will change the
semantics of a given function call. Some of our DeprecationWarnings
possibly should be FutureWarnings, but most shouldn't I don't think.

I can see a case being made for using a custom non-silenced exception
for some cases that really probably show up mostly in true end-user
scenarios, e.g. genfromtxt(). But there are many other cases where we
should continue to use DeprecationWarning, e.g. _array2string(). But
on the whole, I would just leave the DeprecationWarnings as they are.

Robert Kern

More information about the NumPy-Discussion mailing list