[Python-Dev] Terminology for PEP 343
Nick Coghlan
ncoghlan at gmail.com
Sun Jul 3 14:59:50 CEST 2005
Ron Adam wrote:
> So it could be a "Resource Manager Block", which
> uses a "__begin__" and "__end__" method, which is defined in a "Resource
> Manger" object or a "Resource Manager Generator" object, which is called
> by the 'with' key word.
Here's an initial crack at an equivalent of the current 'Iterator
Types' in the library reference [1], which explains the iterator and
iterable protocols. I'm starting to understand what prompted Raymond's
original question, since the continued use of 'exited' sounds rather
awkward (the correct English word is actually 'left'). On the other
hand 'enter and exit' rolls off the tongue significantly better than
'enter and leave' (the natural pairing for the latter is 'arrive and
leave').
All of which just leads me to the conclusion that English is a screwy
language, and I already knew that ;)
Anyway, I stuck with 'exit' for this - I prefer slightly awkard
phrasing in the explanation to awkwardness in the pairing of the names.
"""
Suite Local Resource Management
A frequent need in programming is to ensure a particular resource is
released promptly after it is no longer needed. The tool to achieve
this in Python is the 'with' statement. 'with' statements can be used
to ensure a particular resource is acquired before the contained suite
is entered, and released when the suite is exited.
The main argument to the 'with' statement must be a resource manager -
an object which supports the resource management protocol. This
protocol consists of two methods:
__enter__():
Called without arguments before execution enters the contained
suite. Resource managers will generally acquire the resource in this
method, although some resource managers may accept the resource to be
managed as an argument to the constructor or acquire it during
construction.
The value returned from this method is assigned to the target
identified in the 'as' clause of the 'with' statement.
__exit__(exc_type, exc_value, exc_traceback):
Called as execution exits the contained suite. If the suite was
exited due to an exception, the details of that exception are passed
as arguments. Otherwise, all three arguments are set to None.
Resource managers will generally release the resource in this method.
If the suite was exited due to an exception, and this method
returns without incident, then the original exception continues to
propagate. Otherwise, the exception raised by this method will replace
the original exception.
While the primary purpose of the resource management protocol is to
manage simple resources such as files, locks or database connections,
more complex uses, such as automatic exception logging or transaction
handling, are also possible.
Some resources (e.g. thread.Lock) will support the resource management
protocol directly, acting as their own managers.
In conjunction with the 'resource_manager' decorator, Python's
generators provide a convenient way to implement the resource
management protocol, and share state between the __enter__ and
__exit__ methods. The generator must contain a single yield statement.
The generator is executed up to that point as part of the resource
manager's __enter__ method, and the value yielded is returned. The
remainder of the generator is executed as part of the __exit__ method.
Any exceptions that occur in the managed suite will be injected at the
location of the yield statement.
For example, the following resource manager allows prompt closure of
any resource with a 'close' method (e.g. a generator or file):
@resource_manager
def closing(resource):
try:
yield resource
finally:
resource.close()
"""
Cheers,
Nick.
[1] http://docs.python.org/lib/typeiter.html
--
Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
---------------------------------------------------------------
http://boredomandlaziness.blogspot.com
More information about the Python-Dev
mailing list