[issue6288] Update contextlib.nested docs in light of deprecation

[Raymond Hettinger]

Raymond Hettinger <rhettinger at users.sourceforge.net> added the comment:

To be clear, I'm strongly -1 on switching to a PendingDeprecationWarning.  

That is not what it is for.  There is nothing in the PEP 5 language that
requires it (a PDW isn't even mentioned, the pep is mainly targeted at
deep language changes to the parser and compiler).

I realize that Hagan wants to resurrect this construct, but he needs to
recognize that it is unsalvagable.  

It is likely that most current uses of nested() are replaceable by the
new with-statement.  Some of those uses are buggy (no clean-up for
failed constructors).  The process of converting those cases will fix
the bugs.  We are doing these users a disservice if the warning is made
silent by default.  People *need* to be notified about the potential
bugginess.

Essentially, the new with-statement syntax is a bugfix (the old API was
hopelessly error-prone in a way that is hard to find and fix).  The
statement in the docs that nested() is *equivalent* to two nested withs
is erroneous -- the function is buggy because the equivalence is broken
(a user is much better-off just writing two with-statements than using
nested()).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue6288>
_______________________________________