[Python-Dev] PEP 343 update (with statement context terminology)

[Nick Coghlan]

Paul Moore wrote:
> 2. Nick, what can we do to persuade you to go back to the a1 version,
> and simply look at @contextmanager?

Using two names to describe three different things isn't intuitive for 
anybody. You might persuade me to change the names around, but you aren't 
going to persuade me to go back to using "context" for either of the concrete 
object types.

If we use "context object" as the name for any kind of concrete object, 
decimal.Context has to be an example of it. It wasn't in the alpha 1 docs, 
which was one of the main points of confusion (@contextmanager was the other). 
The alpha 2 docs have ended up sidestepping the issue by not using that term 
at all (introducing "context specifier" instead).

The extent to which I'm willing to consider reversion to alpha 1 terminology 
is to make it so that the context management protocol is the protocol with the 
single __context__ method. However, the objects with the __enter__/__exit__ 
methods need to be called something more specific than context objects (more 
on that below).

> I've proposed splitting it into
> two, but that seems not to suit you (you've never responded to it
> specifically, so I may be misreading your silence here).

Wanting to have two names for the same function tells me there's a problem 
with the terminology, not that we should actually have two names for the same 
function :)

I don't want to be fielding the question "what's the difference between 
contextlib.context and contextlib.contextmanager?" "Well, there isn't actually 
any difference." "Why two functions then?" "Ummm. . ."

So, if we really want to use the alpha 1 terminology where a context manager 
provides just a __context__ method, then I think the right answer is to 
introduce a separate term for the objects that are returned by that method.

However, while coming up with "when requested by the with statement, a context 
specifier object provides a context manager object to set up and tear down the 
desired runtime context" was pretty easy, I really struggle with that sentence 
when the starting object is a context manager.

Trying "a context manager object provides a context object to set up and tear 
down the desired runtime context" seems initially appealing, until you think 
about all the "context objects" that already exist in various domains, such as:

   decimal arithmetic contexts
   GUI toolkit drawing contexts
   parsing & compilation contexts

The fact that those are actually all candidate context specifiers, along with 
the temptation to abbreviate the term to just 'context', results in confusion 
just as bad as with the original PEP terminology.

However, if you can successfully fill in the blank in:

"when requested by the with statement, a context manager object provides a 
context <blank> object to set up and tear down the desired runtime context"

then we can simply change the name of the contextmanager decorator and the 
various ContextManager objects in the implementation to that new term, and 
make the appropriate changes to the documentation.

 From my POV, the fact that the specifier says what the context should be, and 
the manager makes that happen makes sense. I suppose you could call the second 
object an effector, since it effects the necessary changes:

"when requested by the with statement, a context manager object provides a 
context effector object to set up and tear down the desired runtime context"

Actually using the transitive verb form of effect is fairly unnatural English, 
though :)

> One thing I would say is that Nick has added a section on context
> types to the "Built-in types" section of the libref. At the moment, it
> reflects his terminology, but even if the terminology gets reverted to
> a1 style, I'd like to see that stay (suitably reworded, of course!)
> It's a useful addition.

And one with a fairly long history - I first drafted something along those 
lines nearly 10 months ago [1]. FWIW, that discussion last year is the biggest 
reason I've been trying so hard to preserve "context manager" as the name for 
the objects with the __enter__/__exit__ methods. We spent a lot of effort 
coming up with it, and the way I wrote those draft docs (and tried to convey 
in the PEP's standard terminology section), it makes far more sense to me for 
that term to continue to apply to the objects with __enter__ and __exit__ 
methods than it does to relocate it to the johnny-come-lately objects which 
only have a __context__ method.

But if we can agree on a different name for context managers (context objects 
is *not* an option), then changing those docs wouldn't be difficult.

> Oh, and if there's a huge group of people who prefer Nick's
> terminology, now is the time to shout!

So far I've only got Greg commenting that it would be a shame for 
decimal.Context to not be a 'context' anymore. And he loses that either way - 
the only difference in that respect between alpha 1 and alpha 2 is that the 
alpha 2 docs don't call *any* kind of concrete object a context object.

Cheers,
Nick.

[1]
http://mail.python.org/pipermail/python-dev/2005-July/054658.html

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