Paul Moore wrote:
> On 4/22/06, Nick Coghlan <[EMAIL PROTECTED]> 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 | [EMAIL PROTECTED] | Brisbane, Australia
---------------------------------------------------------------
http://www.boredomandlaziness.org
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
