[Python-Dev] Silent deprecation

[Guido van Rossum]

[Changed subject]

[Raymond Hettinger]
> Last month, I took the bait and went to comp.lang.py with a proposal
> to deprecate some builtins. I learned that every builtin (except for
> input()) has a lot of friends.

And input() has one important friend. :-)

> With each set of flames, I mean comments, I modified my proposal
> until it evolved to "psuedo-deprecation".  Amazingly, this attracted
> no flames at all.  The net result is that psuedo-deprecation seems
> to be acceptable as way of removing cruft and lowering the sum total
> pool of working knowledge that a Python programmer has to keep in
> mind.

I guess this means that people don't mind us telling them which
features are obsolete, but they hate it with a vengeance when their
programs that they have deployed in the field with end users start
spewing warning messages.

> Instead of de-documenting obsolete tools, I propose moving their
> documentation to a separate section of the docs set aside for cruft.
> This makes it possible to understand exactly what old code was
> doing.

Hm, getting the docs for a previous version is easy enough.  We never
throw anything away.

> It makes sure that the newly dedocumented features don't take on
> never-documented assumptions.  Putting it in a separate place allows
> us to document the rationale for psuedo-deprecation and to suggest
> alternatives.  Collecting it in one place provides authors with a
> checklist of things to take out of their book updates.

I think we can do two things.  Either we can keep the docs for
deprecated features but clearly mark the chapter or section with a
deprecation note at the start, in bold.

Or we can remove the docs for deprecated features, and add a chapter
"deprecated features" which mentions each deprecated feature without
describing it in detail, and provides information about what to use
instead.

> On the warning side of the equation, I have two ideas.  While there
> would not be warnings kicking out automatically, we could add an
> option or tool that developers could use to temporarily flag use of
> psuedo-deprecated features.

This is what I meant by having a SilentDeprecationWarning category --
a special form of the -W option can cause it to spew messages, but by
default it won't.

> The second idea, is to move responsibility for obsolesence warnings
> to PyChecker.

This is not always feasible; some things can only be discovered at
run-time (e.g. the oct/hex/<< warnings).

--Guido van Rossum (home page: http://www.python.org/~guido/)