[Python-Dev] 'With' context documentation draft (was Re: Terminology for PEP 343

[Raymond Hettinger]

[Nick Coghlan]
> OK, here's some draft documentation using Phillip's context
> terminology. I think it works very well.
> 
> """
> With Statements and Context Management
> 
> A frequent need in programming is to ensure a particular action is
> taken after a specific section of code has been executed (such as
> closing a file or releasing a lock). The tool to achieve this in
> Python is to use the 'with' statement along with the appropriate
> context manager.

"the tool"  -->  "a tool"

The other tool is, of course, try/finally.

What is offered by "with" and context manager objects is the
encapulsation specific try/finally blocks.  This enables repeated,
common code to be factored-out.

There only new magic here is factoring.  Context management has always
been possible.



>      __enter__(self):
>      __exit__(self, exc_type, exc_value, exc_traceback):

These names should be changed to __beginwith__ and __endwith__.  The
current names are too vague, not obviously paired with each other, not
obviously tied to the with-statement, and provide no hint about what
calls them.  Remember, the methods will appear among a slew of other
methods that have nothing to do with with-statements.  There will be no
surrounding contextual clue as to what these methods are for.



Raymond