Title: Update contextlib.nested docs in light of deprecation
Type: behavior Stage:
Components: Documentation Versions: Python 3.1
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ncoghlan Nosy List: asksol, benjamin.peterson, hagen, ncoghlan, rhettinger
Priority: high Keywords:

Created on 2009-06-15 21:43 by ncoghlan, last changed 2011-07-27 12:25 by ncoghlan. This issue is now closed.

Messages (12)
msg89415 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2009-06-15 21:43
Just a placeholder to remind me to implement the suggestion from
python-dev of updating the contextlib.nested docs to show:

1. The one remaining valid use case (variable number of context managers)
2. The warnings module incantation needed to suppress the deprecation
msg89425 - (view) Author: Hagen F├╝rstenau (hagen) Date: 2009-06-16 07:37
Does that mean that nested() can be removed or changed incompatibly in
3.2 at the same time that an alternative way for handling the remaining
use case is introduced?

This would seem to violate the promise in PEP 5, that "users will have
at least a year to test their programs and migrate them from use of the
deprecated construct to the alternative one".
msg89432 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2009-06-16 13:44
That's a good point actually - with 3.1's "in-between" status and the
lack of deprecation in 2.6, nested() is going to have to stick around
for 2.7/3.2 anyway.

So PendingDeprecation now with full deprecation in 2.7/3.2 when we will
hopefully have a better alternative in place is probably the way to go.

Updating the docs to cover only the recommended use case is still
something I want to do this week though (hopefully tomorrow).
msg89435 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2009-06-16 17:28
There is *no* reason to downgrade the warning.  We can leave it as
deprecated in 3.1 and remove it in 3.3 if we want.

A PendingDeprecationWarning is just a plain bad idea, it doesn't
actually warn the users.  We introduced that construct in Python 2.3 to
be used *rarely* for deeply entrenched things like string exceptions
that would be eventually removed.  For the most part, everything else
gets deprecated directly.  Also, remember that this construct is not
being deprecated just because it is duplicative; it is being deprecated
because it is a bug factory when used as advertised -- it is a harmful
construct -- it *needs* a warning.

Someone like Hagan, using it for a corner case, can easily put a copy
and paste version in their own code and use it forever.  There are
likely very few such users now (but there will be more if we fail to
provide a real warning).
msg89437 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2009-06-16 19:05
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

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
msg89452 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2009-06-17 12:13
In light of Raymond's comments (which make sense to me), I'm just
updating the documentation and leaving the full deprecation warning in

The new docs are deliberately explicit about *why* trying to use the
current form of nested is almost certainly a bad idea.

Added for 2.7 in r73465.
msg89453 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2009-06-17 12:30
And done for 3.1 in r73466
msg89469 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2009-06-17 16:30
Nice job on the new wording in the docs.

Do you think the docstring should also be updated?
msg89480 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2009-06-17 20:54
Good point - I forgot about the docstring.

Yes, I think that should be changed to use the new wording up to the new
example (similar to the way the old docstring stopped at the example).

Reopening until that is done (although reducing from release blocker status)
msg89625 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2009-06-23 11:00
Docstring updated in r73518 (2.7) and r73520 (3.1)
msg141214 - (view) Author: Ask Solem (asksol) (Python committer) Date: 2011-07-27 10:02
How would you replace the following functionality
with the multiple with statement syntax:

    x = (A(), B(), C())
    with nested(*x) as context:

It seems to me that nested() is still useful for this particular
use case.
msg141223 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-07-27 12:25
Indeed it is, although we think actually doing that is a bad idea (as discussed earlier on this tracker item).

See the 3.1 docs for the recommended workaround for the removal (basically grab a copy of the 3.1 code and drop it into your own utility module)
Date User Action Args
2011-07-27 12:25:59ncoghlansetmessages: + msg141223
2011-07-27 10:02:44asksolsetnosy: + asksol
messages: + msg141214
2009-06-23 11:00:11ncoghlansetstatus: open -> closed
resolution: fixed
messages: + msg89625
2009-06-17 20:54:33ncoghlansetstatus: closed -> open
priority: release blocker -> high
messages: + msg89480
2009-06-17 16:30:05rhettingersetmessages: + msg89469
2009-06-17 12:30:09ncoghlansetstatus: open -> closed

messages: + msg89453
2009-06-17 12:13:12ncoghlansetmessages: + msg89452
2009-06-16 19:05:59rhettingersetmessages: + msg89437
2009-06-16 17:28:17rhettingersetnosy: + rhettinger
messages: + msg89435
2009-06-16 13:44:20ncoghlansetmessages: + msg89432
2009-06-16 07:37:05hagensetnosy: + hagen
messages: + msg89425
2009-06-15 21:43:07ncoghlancreate