[Python-Dev] Choosing an official stance towards module deprecation in Python 3

[Brett Cannon]

There are two discussions going on in the issue tracker about deprecating
some modules and it has led to the inevitable discussion of Python 2/3
compatibility (I'm not even going to bother mentioning the issue #s as this
thread is not about the modules specifically but module deprecation in
general). Because I'm tired of rehashing the same discussion every time a
module deprecation comes up I would like to make an official decision that
we can follow any time we decide to deprecate a module.

The approaches to module deprecation I have seen are:
1. Nothing changes to the deprecation process; you deprecate a module and
remove it in one to two releases
2. Deprecate the module but with no plans for removal until Python 2.7
reaches its EOL (I have been calling this Python 4)
3. Document the deprecation but no actual code deprecation

I'm personally in the #2 camp. I want users to be fully aware that the
module in question is not being updated and possibly not even getting
non-critical bugfixes, but it's still there in Python 3 in order to make
sure that you can have code which straddles Python 2 & 3 more easily.

I don't like #1 because when the module exists in python 2.7 as it makes
transitioning from Python 2 a bit harder. Leaving code in the stdlib as
deprecated isn't going to kill us, especially if we make it clear the code
only exists for transitioning purposes and you very well may have to work
around any bugs you come across (and yes, this means changing my stance for
the formatter module's deprecation).

I don't like #3 because if you have an API memorized or you copied some
code you found online you very well may not realize a module is deprecated.
It's not difficult to silence a deprecation warning and you can make it so
that even if you use -Werror your deprecated module imports continue to
work without throwing an exception while all other deprecations do throw an
exception.

Whatever decision we come to I will update PEP 4 and then personally go
through the various deprecated modules in Python 3.6 and tweak them as
necessary to follow whatever policy we come up with.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20150908/bca71de7/attachment.html>