[issue28516] contextlib.ExitStack.__enter__ has trivial but undocumented behavior
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 <http://bugs.python.org/issue28516> ___ ___ 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
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 <http://bugs.python.org/issue28516> ___ ___ 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 added the comment: This one-line patch should clarify the point. -- ___ Python tracker <http://bugs.python.org/issue28516> ___ ___ 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 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 <http://bugs.python.org/issue28516> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
