[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:

Thanks for the patch!

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:


New changeset 604d003ab4d1084ef828ebca1b28f2bf1b93c744 by Jelle Zijlstra in 
branch '3.10':
[3.10] bpo-28516: document contextlib.ExitStack.__enter__ behavior (GH-31636) 
(GH-32171)
https://github.com/python/cpython/commit/604d003ab4d1084ef828ebca1b28f2bf1b93c744


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Jelle Zijlstra]

Change by Jelle Zijlstra :


--
pull_requests: +30249
pull_request: https://github.com/python/cpython/pull/32171

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:


New changeset 1e3132b1c3ebff8d28a6dd353bf217cb97c41e81 by Miss Islington (bot) 
in branch '3.9':
bpo-28516: document contextlib.ExitStack.__enter__ behavior (GH-31636) 
(GH-32145)
https://github.com/python/cpython/commit/1e3132b1c3ebff8d28a6dd353bf217cb97c41e81


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:


New changeset 86384cf83f96fcaec03e2ad6516e2e24f20d3b92 by vidhya in branch 
'main':
bpo-28516: document contextlib.ExitStack.__enter__ behavior (GH-31636)
https://github.com/python/cpython/commit/86384cf83f96fcaec03e2ad6516e2e24f20d3b92


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[miss-islington]

Change by miss-islington :


--
pull_requests: +30225
pull_request: https://github.com/python/cpython/pull/32145

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[miss-islington]

Change by miss-islington :


--
nosy: +miss-islington
nosy_count: 7.0 -> 8.0
pull_requests: +30224
pull_request: https://github.com/python/cpython/pull/32144

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Vidhya]

Vidhya  added the comment:

@Jelle: Thanks. The PR is submitted at
https://github.com/python/cpython/pull/31636

--
keywords: +patch
message_count: 9.0 -> 10.0
pull_requests: +29758
pull_request: https://github.com/python/cpython/pull/31636

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:

That sounds good. Feel free to request review from me if you make a PR.

--
nosy: +Jelle Zijlstra

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Vidhya]

Vidhya  added the comment:

[Entry level contributor seeking guidance] If this is still open, I can update 
the document.

After reading all the above comments, planning to add 

"The __enter__ method returns the ExitStack instance, and performs no 
additional operations." 

at

https://docs.python.org/3/library/contextlib.html#contextlib.ExitStack.enter_context.
 

Please let me know your thoughts.

--
nosy: +vidhya

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Andrei Kulakov]

Andrei Kulakov  added the comment:

It's a bit more readable to start by stating what a function does rather than 
what it doesn't do. I also wouldn't worry about possible future minor 
optimizations that might be added, because if that happens, a simple ".. aside 
from internal optimizations, ... " would suffice.

Something like this should work:

The __enter__ method returns the ExitStack instance, and performs no additional 
operations.

 OR

 ... and does not perform any additional operations.

--
nosy: +andrei.avk

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Irit Katriel]

Change by Irit Katriel :


--
keywords: +easy -patch
versions: +Python 3.11 -Python 3.5, Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Walker Hale IV]

Walker Hale IV added the comment:

Clarifying the documentation regarding the __enter__ method eliminates the need 
for further discussion on this point regarding pop_all(), which was really just 
the motivating use case.

That leaves the question of the most readable documentation change that 
accomplishes the result — some point between verbose and terse that minimizes 
the time required to comprehend the material.

My problem with the language "ExitStack instances return themselves when used 
in a with statement" is that it only specifies the return value of the 
__enter__ method but leaves open the question of whether the __enter__ method 
is doing anything else, particularly in the case of an ExitStack that is 
already loaded with context managers. How does a reader know that the __enter__ 
method of a loaded ExitStack doesn't call the __enter__ method of the the 
context managers inside? The documentation elsewhere provides strong evidence 
against this, but nothing that makes the point explicit. The reader is left 
with an exercise in deduction.

How about replacing my previous wording with: "The __enter__ method has no 
behavior besides returning the ExitStack instance?"

(I feel a little dirty using that language, since it might tie the hands of 
future developers. The truly correct wording would be "The __enter__ method is 
idempotent and behaves as if the only thing it does is return the ExitStack 
instance." That more verbose description gives future developers the freedom to 
do weird JIT optimizations and caching as needed, but who has the patience for 
such legally exhaustive specification?)

Placing the wording where I did — at the end of the class discussion and prior 
to the new methods — prevents this point from obscuring the main purpose of 
ExitStack while still leaving a place for such messy but important details. 
(Amazing the thought that goes into documenting a two-line method.)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[R. David Murray]

R. David Murray added the comment:

Actually, the __enter__ method is looked up on the class, so saying "the 
__enter__ method of the instance" could be a bit confusing.  Also, many context 
managers return self, so 'trivially' isn't really necessary as a modifier.

What if we added a sentence to the first paragraph that said "ExitStack 
instances return themselves when used in a with statement."  Since that is 
immediately followed by an example of doing that, it seems like the best place 
to put it.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Martin Panter]

Martin Panter added the comment:

I agree it is good to explicitly document the __enter__() result, rather than 
relying on assumptions and example code. The patch looks good to me.

I don’t understand the problem with pop_all() though. Is there still a problem 
if we apply your patch?

--
nosy: +martin.panter
stage:  -> patch review
versions:  -Python 3.3, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Walker Hale IV]

Walker Hale IV added the comment:

This one-line patch should clarify the point.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Walker Hale IV]

Changes by Walker Hale IV :


--
assignee:  -> docs@python
components: +Documentation
keywords: +patch
nosy: +docs@python
Added file: http://bugs.python.org/file45206/issue28516.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[R. David Murray]

R. David Murray added the comment:

Hmm.  I guess we just assume it is obvious, given that the with statement 
examples name the variable 'stack', and the pop_all docs mention that no 
callbacks are called until it is closed "or at the end of a with statement".  
So, technically, using the result of a pop_all in a with statement is 
documented.  I could be made clearer though if someone wants to propose a doc 
patch.  I'm not sure it is worth expanding the example, though.

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior

[Walker Hale IV]

New submission from Walker Hale IV:

contextlib.ExitStack implies but does not explicitly state that its __enter__ 
method trivially returns self.

This means that if a user invokes pop_all and then uses the resulting ExitStack 
instance in a with statement, the user will be relying on undocumented 
behavior. Avoiding undocumented behavior forces the user to instead use a 
tedious try/finally construct, partially defeating the elegance of context 
managers.

I propose that:

1. The ExitStack.__enter__ method be briefly mentioned as doing nothing besides 
returning self.

2. The example in pop_all documentation be expanded to show a following with 
statement that uses the new ExitStack instance.

The discussion in section 29.6.3.2 is not sufficient to make this trivial point 
clear.

--
messages: 279296
nosy: Walker Hale IV
priority: normal
severity: normal
status: open
title: contextlib.ExitStack.__enter__ has trivial but undocumented behavior
versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com