[Python-Dev] Why are contexts also managers? (was r45544 - peps/trunk/pep-0343.txt)

[Nick Coghlan]

Paul Moore wrote:
> On 4/22/06, Nick Coghlan <ncoghlan at gmail.com> wrote:
>> Alternatively, I could have a go at clearing it up for next week's alpha2, and
>> we can ask Anthony to make an explicit request for review of those docs in the
>> announcement. . .
> 
> I've just had a *very* quick scan through the 2.5a1 documentation. I
> did not look at the PEP, just the official documentation. I've been
> reading the messages going round on the subject, but I'm getting
> pretty confused, so I'd still count myself as "unprejudiced"... :-)

Thanks for doing that. I got lost in a maze of twisty contexts all alike 
around the same place you did, so we apparently need to do something different 
somewhere.

So I'm going to express my gratitude by asking you to read the same docs all 
over again in a few days time :)

> My immediate reaction was that the docs make reasonable sense:
> 
> - a context is a thing with enter/exit methods (a block of code is
> "in" a context)
> - the with statement delimits the block which is in a context
> - the with statement asks a context manager for the context in which
> the block runs
> - context managers have __context__ methods to produce contexts (they
> manage the production of explicit context objects)

I'll be making a pass through the docs (and PEP) this weekend using the 
definitions:

   - a context manager is a thing with enter/exit methods
     (it sets up and tears down an execution context for a block of code)
   - the with statement delimits the block which is in an execution context
   - the with statement asks a context object for a context manager to set up
     and tear down an execution context when the block runs
   - context objects have a __context__ method to produce context managers
     (hey, it isn't really that much worse than using the __iter__ method to
      ask an iterable for an iterator. . .)

I'll also add something in which parallels the current "Iterator Types" 
section in the library reference (only for "Context Types").

The big changes from where we are currently are that:
   - "execution context" will be introduced for the sundry effects that a 
context manager may have on the code in the body of a with statement (like 
affecting how exceptions are handled, redirecting IO, changing the thread's 
active decimal context, affecting thread synchronisation etc)
   - "context object" will be used where "context manager" is currently used. 
This is mainly so that decimal.Context can be safely referred to as being a 
context object.
   - "context manager" will be used where "context" is currently used. This is 
so that the __context__ method returns context managers, which means 
decorating the generator based ones with @contextlib.contextmanager makes sense.

I was considering producing a patch instead so it could be reviewed before I 
changed anything, but I don't think we'll really understand which is clearer 
until we can review it all together, and documentation patches are difficult 
to review properly without applying them and rebuilding the docs (which a lot 
of people aren't set up to do - just ask the effbot ;).

If the terminology *still* breaks down with those slightly different 
definitions, we'll have to try to come up with a third option after the 2nd 
alpha. I'm really hoping my planned changes actually work out, because if they 
don't I'm out of ideas for how to make these concepts easier to grok. . .

Cheers,
Nick.

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