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

[Nick Coghlan]

Paul Moore wrote:
> Right. I'll still do as I promised, and have a better look through the
> latest documentation, but my gut feel is that this whole thing is
> getting way out of proportion. Naming and terminology is important,
> but we've now on our 3rd version of the docuentation.

Only the 2nd, really - prior to the work Phillip put into it, we didn't have 
any user-oriented documentation at all. (the changes I made really were just 
moving a bit of terminology).

I'm not counting the 'context object' -> 'context specifier' change as a 
different version, as it was the process of updating the docs to match the 
implementation that made me realise the term 'context object' was too 
imprecise (the various comments here naturally helped in coming to that 
understanding).

> My instinct is STILL that the original version of the docs were fine.

The original version of the docs moved the problem around, but it didn't solve 
it - the fundamental issue was that we had two names ("context manager" and 
"context"), but three entities (the original object with the __context__ 
method, the object it returned with __enter__ and __exit__ methods, and the 
'runtime context' that the __enter__ and __exit__ methods manipulated).

The latest version of the docs uses "context specifier", "context manager" and 
"context" for the three different things, and that seems to work reasonalbly well.

> The terms "context" (an abstract thingy relating to the environment in
> which a block of code executes) and "context manager" (a concrete
> object that manages contexts) seem natural to me. The fact that you
> pass "context managers" to the "with" statement emphasizes the idea
> that they are the concrete one of the pair.

Agreed. In the latest version of the docs, you pass in either a context 
specifier or a context manager to the with statement. A specifier just 
provides a __context__ method, a manager provides __enter__ and __exit__ as well.

> Your version swaps the terms around, and so messes up my intuition. I
> concede that your version is self-consistent, but it doesn't match my
> intuition. And in my view, intuition matters here, so I have to prefer
> the variant that matches my intuition.

Also agreed - the term 'context' needs to be reserved for the 'runtime 
context', so I don't think we can use it for *any* of the concrete objects 
involved.

I guess the python-dev discussion way back in the dim dark mists of time that 
rejected "context" as the name for the pre-__context__ method context managers 
was onto something :)

> I know my terminology is (slightly) inconsistent with respect to the
> decimal.Context class, but it doesn't disrupt my understanding. Worse
> (in terms of explaining myself!) it still feels natural to stick with
> decimal.Context even though I *know* that in my terms, it is formally
> a context manager.

With "context" no longer referring to any particular kind of object, this 
naming issue goes away. The decimal.Context object is just a context specifier 
for the active decimal context.

> OK, I really can't explain that any better, but the library object
> naming issue doesn't sway me.

It swayed me, but into (sort of) agreeing with you :)

> I'd like to see the @contextmanager decorator split (conceptually, if
> not actually) into 2 parts, one for use with generator functions which
> are to be context managers, and one for use with __context__ functions
> (generator functions which are to be functions returning contexts).

I believe the current docs avoid the need for doing this, as:
   - the with statement expects a context specifier
   - a context specifier's __context__ method must return a context manager
   - all context managers can be used as context specifiers

So creating a standalone context manager properly parallels the creation of a 
standalone iterator and creating a special purpose context manager as a 
context specifier's __context__ method  properly parallels creation of a 
special purpose iterator as an iterable's __iter__ method.

This problem with the @contextmanager decorator is what clued me in to the 
fact that the alpha 1 documentation just moved the terminology problem around 
rather than actually fixing it.

> I think I've now read enough on the subject that my value as an
> unbiased reader is being lost...

Your input really helped me figure out where the problem was, though. Trying 
to describe 3 different things using only 2 distinct terms was a recipe for 
confusion in anybody's book :)

> PS Is anyone else arguing with Nick on this? Now that I'm reduced to
> intuitive "well, I prefer it" arguments, it would be nice to hear what
> people's gut feelings are - "contexts create context managers",
> "context managers create contexts", "so confused I don't know"... :-)
> ?

With the current docs:
   "context specifiers create context managers"
   "context specifiers define a runtime context"
   "context managers enter and exit a runtime context"
   "context managers set up and tear down a runtime context"

The main thing this discussion showed me is that there was a real problem in 
the PEP - it used the term "context" for two different things (context 
specifiers and runtime contexts). Phillip noticed that problem, and tried to 
fix it in the documentation. Unfortunately, the attempted fix just moved the 
problem around because "context" was still used to refer to two different 
kinds of thing (only now the second kind of thing was context managers rather 
than context specifiers).

The changes I made this weekend are designed to give everything its own name, 
leaving "context" free to refer to either the runtime context or a context 
specifier or whatever else makes sense in context.

Cheers,
Nick.

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