[Python-Dev] Updated context management documentation

[Nick Coghlan]

I won't call this a resolution yet, since it'll probably be a few days before 
I get time to update the PEP itself, and the changes below are based on 
pulling together a few different threads of the recent discussion. However, I 
believe (hope?) we're very close to being done :)

The heart of the matter is that, having put together a full documentation set 
based on the interpretation I intended when I updated PEP 343 last year, I've 
come to agree that, despite its problems, the alpha 1 documentation generally 
reads better than my intended approach did.

So I just checked in a change that reverts to the alpha 1 terminology - the 
phrase "context specifier" disappears, and "context manager" goes back to 
referring to any object with a __context__ method. However, I made the changes 
below in order to address the conflicts between the alpha 1 documentation and 
implementation.

Avoiding ambiguity

   Reverting to the alpha 1 terminology still left the problem of ambiguity in 
the terms "context" and "context object". Aside from the terms "runtime 
context" and "context of execution" to refer to application state when 
particular code is run, and the general English usage of the word "context", 
there are also too many kinds of context object (like decimal.Context) already 
out in the wild for us to simply adopt the term "context object" without 
qualifying it in some fashion.
   Lacking a better solution, I went for the straightforward approach of using 
"with statement context object" (and variants along those lines) in a number 
of places where the alpha 1 docs just used "context object".
   It's clumsy, but it seems to work (and in cases where application domain 
context objects like decimal.Context don't intrude, it's still possible to 
shorten the phrase).
   (An idea that just occurred to me in writing this email is "managed 
context". That's a lot less clumsy, and fits with the context manager idea. If 
other folks like it, we could probably switch to that either before or after 
alpha 2, depending on when Anthony wants to make the alpha release happen).

Context expressions
   In response to a comment Aahz made, I tweaked the language reference to 
explicitly refer to the expression in the with statement as a "context 
expression". The result of the context expression must then be a context 
manager in order for the with statement to operate correctly.
   This means that, as far as users are concerned, the context expression 
defines the runtime context for the block of code in the with statement. 
Unless you're writing your own objects, the existence of context managers and 
with statement context objects will generally be an irrelevant implementation 
detail.

Dealing with decimal.ContextManager
   I renamed this to decimal.WithStatementContext. It's ugly but it works, and 
the existence of this object is really an implementation detail anyway.
   (decimal.ManagedContext would definitely look better. . .)

Dealing with contextlib.contextmanager
   As recently suggested (by Terry, IIRC), I renamed this to 
contextlib.contextfactory, as the decorator creates a factory function for 
producing with statement context objects. This name works fine for both 
standalone context factories and the __context__ method of a context manager 
(as that method is itself a context factory).
   (As a fortuitous accident, this actually aligns with descriptions I've read 
of normal generator functions as iterator factories. . .)

Dealing with contextlib.GeneratorContextManager
   I renamed this to contextlib.GeneratorContext. The fact that it's in the 
contextlib module provides sufficient context to indicate that this is a with 
statement context object, so I could avoid the clumsy naming that was needed 
in the decimal module.

Changes to contextlib.closing
   These changes weren't actually terminology related, but they got mixed in 
with the rest of the changes to the contextlib module. Firstly, as the state 
to be retained is trivial, contextlib.closing is now implemented directly 
rather than via a generator. Secondly, the documentation now shows an example 
of a class with a close() method using contextlib.closing directly as its own 
__context__() method.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org