[Python-Dev] Deprecating whrandom; and deprecating in general (original) (raw)

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

[Note changed subject]

[MAL]

> 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... :-)

[Aahz]

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 year.

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

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
warnings.filterwarnings("ignore")

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/)