[Python-Dev] Deprecating whrandom; and deprecating in general

Guido van Rossum guido@python.org
Wed, 10 Apr 2002 18:00:44 -0400

[Note changed subject]

> > You won't have much luck in doing s/whrandom/random/g on a 
> > hard-copy Python text book and this is what Python newbies
> > read. I'm not even talking about potential Python users who 
> > haven't gotten the slightest idea what sed is... :-)

> What Python textbooks use whrandom?
> > Note that the key point is a different one: every single 
> > deprecation causes work (convincing management, code changes, 
> > tests, deployment of the new code, training application 
> > developers, writing/buying new books). Work costs money. 
> > Money causes all sorts of problems.
> Would it be okay with you for whrandom to emit a deprecation warning,
> but not get deleted until Python 3.0?
> From my POV, what you're missing in this debate is the cost of
> keeping the code.  If code exists, people ask questions about it.
> Random issues keep popping up on c.l.py and the simpler the
> situation, the easier to explain it.

I was going to side with Aahz (keeping deprecated code around has
costs too), until I decided to go read PEP 4.  PEP 4 specifically says
that the status of all deprecated modules must be recorded in that
PEP.  Apparently we forgot all about that when we documented whrandom
as deprecated when 2.1 was first released.

PEP 4 doesn't say whether deprecated modules should emit a warning
when imported, although it says that deprecation proposals "MAY
include a patch for the module's source code to indicate deprecation
there as well."

PEP 4 also doesn't say how long a deprecated module must continue to
exist.  It says "It is expected that deprecated modules are included
in the Python releases that immediately follows the deprecation;" this
suggests at least two releases, which matches the deprecation
guidelines for language evolution in PEP 5, which suggests at least a

(I suggest that PEP 4 be augmented to be more clear about these

PEP 4 requires a rationale for deprecation.  Three of the four
deprecated modules listed there mention as the rationale that the
module is not actively being used, and quote no recent mention in
deja.com (now groups.google.com) as evidence.

So let's apply this to whrandom. and let's say the deprecation note in the docs was
invalid because it wasn't recorded in PEP 4.

Now we need a rationale.  AFAICT the rationale for deprecating
whrandom is that its functionality is a duplicate of the random
module, we don't want to have to maintain (and answer questions and
bug reports about) both modules, and the name is "wrong" (it refers to
a specific random algorithm which is known to be rather weak).  That's
not a particularly strong rationale: there are only three very old SF
bug reports about it, and the revision history has been quiet since
January 2001.  All changes after July 1998 seem to have been cosmetic,
from whitespace normalization to a docstring sweep (this can be used
as an argument pro or con deprecation).  Groups.google.com shows
plenty of recent mention of it in c.l.py (a couple per month), so it
doesn't appear that nobody is using it.

Suppose we decide to deprecate whrandom.  The first opportunity to do
so will be in 2.3.  (I think we shouldn't deprecate modules in micro
releases; the PEP is silent about that but I think it would be a bad
idea.)  Then it will have to continue to exist for at least a year.
Because whrandom is still in active use (see above), I think the one
year deprecation period is too short in this case and we should use
two years.  Maybe the warning should only be introduced in the second
year?  That probably means (assuming releases every 6 months):

2.3 - deprecate in docs

2.5 - issue warning

2.7 - move to Lib/lib-old

Now on to Marc's argument against deprecation:

> > If not absolutely needed in order to make way for new techniques 
> > or features, we should leave the old established code in place 
> > rather than causing endless support sessions with customers 
> > who fear that the code you've written for them 6 months ago 
> > starts making not so funny noises or that drag you to update 
> > the code on a warranty basis.
> > 
> > What's worse, is that management will not be delighted to
> > see that this "new technology we use, called Python" causes
> > quality assurance and training costs every 8-12 months. I
> > wouldn't want Python to go down that road, now that the
> > ball is starting to roll.

I think there are two different typical use cases for Python code, and
they have different preferences for deprecation (and other) warnings.

Use case #1 is what we usually think of.  Some programmer is
maintaining some Python code.  When he upgrades the Python version he
is using, being the programmer he probably wants to find out about
deprecated features in the new Python version, so that he can fix his
code so that it won't break outright in the future.  IOW, this
programmer is glad that there are deprecation warnings (compared to
the alternative, where he had no idea that he was using a deprecated
feature until it was removed and his program broke outright).

Use case #2 is Marc-Andre's and Fredrik's situation: a company
writes a program in Python which runs at a customer's site.  Assume
the program is not large and self-contained enough to warrant it
coming with its own version of Python.  The customer has lots of
Python code in production, maybe some that they wrote themselves, some
that they bought from different places, and maybe even some open
source downloads.

At some point the customer decides to upgrade their Python -- maybe
because they like to be on the bleeding edge for their own code base,
maybe because they need this for a new open source download, maybe
they believe it will fix some Python problem they've experienced
intermittently.  Now the program they brought from PythonWare or from
eGEnix suddenly starts to emit a warning each time it is run.

This is annoying: maybe the warning goes to a log file where
unexpected things cause alarms to go off, maybe it shows up in an end
user's shell window where it causes confusion, maybe there are a lot
of warnings and the extra output is simply annoying.  These users
probably aren't Python savvy, so they may panic and call customer
service.  Understandably, nobody is happy.  Marc-Andre and Fredrik
already know their program issues a warning, and they've fixed it in
their own version, and they don't want to waste time telling every
user how to disable or ignore the warning, or shipping upgrades.

How do we satisfy both use cases?  We could turn off deprecation
warnings by default.  But I suspect that most programmers in use case
#1 would probably never turn on deprecation warnings, thereby
defeating the point of them.

I would like to suggest that instead, professional software
distributors like eGenix and PythonWare tweak their distributions to
turn of warnings by default.  This is easy enough: in the main
program, insert

    import warnings

at the top (before other imports).  If the code needs to run on Python
2.0 or before, insert the whole thing inside a try: / except
ImportError: pass.  If you want an easy way to enable warnings, you
can invent something else (e.g. check an environment variable).

Would this be acceptable?

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