Update contextlib.nested docs in light of deprecation

[ncoghlan]

BPO	6288
Nosy	@rhettinger, @ncoghlan, @benjaminp

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ncoghlan'
closed_at = <Date 2009-06-23.11:00:11.819>
created_at = <Date 2009-06-15.21:43:07.645>
labels = ['type-bug', 'docs']
title = 'Update contextlib.nested docs in light of deprecation'
updated_at = <Date 2011-07-27.12:25:59.418>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2011-07-27.12:25:59.418>
actor = 'ncoghlan'
assignee = 'ncoghlan'
closed = True
closed_date = <Date 2009-06-23.11:00:11.819>
closer = 'ncoghlan'
components = ['Documentation']
creation = <Date 2009-06-15.21:43:07.645>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 6288
keywords = []
message_count = 12.0
messages = ['89415', '89425', '89432', '89435', '89437', '89452', '89453', '89469', '89480', '89625', '141214', '141223']
nosy_count = 5.0
nosy_names = ['rhettinger', 'ncoghlan', 'benjamin.peterson', 'hagen', 'asksol']
pr_nums = []
priority = 'high'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue6288'
versions = ['Python 3.1']

[ncoghlan]

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
   warning

[hagen]

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

[ncoghlan]

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

[rhettinger]

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

[rhettinger]

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

[ncoghlan]

In light of Raymond's comments (which make sense to me), I'm just
updating the documentation and leaving the full deprecation warning in
place.

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.

[ncoghlan]

And done for 3.1 in r73466

[rhettinger]

Nice job on the new wording in the docs.

Do you think the docstring should also be updated?

[ncoghlan]

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)