-
contextlib.
nullcontext
(
enter_result
=
None
)
¶
-
Return a context manager that returns
enter_result
from
__enter__
, but otherwise does nothing. It is intended to be used as a stand-in for an optional context manager, for example:
def myfunction(arg, ignore_exceptions=False):
if ignore_exceptions:
# Use suppress to ignore all exceptions.
cm = contextlib.suppress(Exception)
else:
# Do not ignore any exceptions, cm has no effect.
cm = contextlib.nullcontext()
with cm:
# Do something
范例使用
enter_result
:
def process_file(file_or_path):
if isinstance(file_or_path, str):
# If string, open file
cm = open(file_or_path)
else:
# Caller is responsible for closing file
cm = nullcontext(file_or_path)
with cm as file:
# Perform processing on the file
It can also be used as a stand-in for
异步上下文管理器
:
async def send_http(session=None):
if not session:
# If no http session, create it with aiohttp
cm = aiohttp.ClientSession()
else:
# Caller is responsible for closing the session
cm = nullcontext(session)
async with cm as session:
# Send http requests with session
3.7 版添加。
3.10 版改变：
异步上下文管理器
支持被添加。
-
class
contextlib.
ContextDecorator
¶
-
A base class that enables a context manager to also be used as a decorator.
Context managers inheriting from
ContextDecorator
必须实现
__enter__
and
__exit__
as normal.
__exit__
retains its optional exception handling even when used as a decorator.
ContextDecorator
用于
contextmanager()
, so you get this functionality automatically.
范例
ContextDecorator
:
from contextlib import ContextDecorator
class mycontext(ContextDecorator):
def __enter__(self):
print('Starting')
return self
def __exit__(self, *exc):
print('Finishing')
return False
The class can then be used like this:
>>> @mycontext()
... def function():
... print('The bit in the middle')
...
>>> function()
Starting
The bit in the middle
Finishing
>>> with mycontext():
... print('The bit in the middle')
...
Starting
The bit in the middle
Finishing
This change is just syntactic sugar for any construct of the following form:
def f():
with cm():
# Do stuff
ContextDecorator
lets you instead write:
@cm()
def f():
# Do stuff
It makes it clear that the
cm
applies to the whole function, rather than just a piece of it (and saving an indentation level is nice, too).
Existing context managers that already have a base class can be extended by using
ContextDecorator
as a mixin class:
from contextlib import ContextDecorator
class mycontext(ContextBaseClass, ContextDecorator):
def __enter__(self):
return self
def __exit__(self, *exc):
return False
注意
As the decorated function must be able to be called multiple times, the underlying context manager must support use in multiple
with
statements. If this is not the case, then the original construct with the explicit
with
statement inside the function should be used.
Added in version 3.2.
范例和配方
¶
This section describes some examples and recipes for making effective use of the tools provided by
contextlib
.
支持可变数上下文管理器
¶
The primary use case for
ExitStack
is the one given in the class documentation: supporting a variable number of context managers and other cleanup operations in a single
with
statement. The variability may come from the number of context managers needed being driven by user input (such as opening a user specified collection of files), or from some of the context managers being optional:
with ExitStack() as stack:
for resource in resources:
stack.enter_context(resource)
if need_special_resource():
special = acquire_special_resource()
stack.callback(release_special_resource, special)
# Perform operations that use the acquired resources
As shown,
ExitStack
also makes it quite easy to use
with
statements to manage arbitrary resources that don’t natively support the context management protocol.
捕获异常从
__enter__
方法
¶
It is occasionally desirable to catch exceptions from an
__enter__
method implementation,
without
inadvertently catching exceptions from the
with
statement body or the context manager’s
__exit__
method. By using
ExitStack
the steps in the context management protocol can be separated slightly in order to allow this:
stack = ExitStack()
try:
x = stack.enter_context(cm)
except Exception:
# handle __enter__ exception
else:
with stack:
# Handle normal case
Actually needing to do this is likely to indicate that the underlying API should be providing a direct resource management interface for use with
try
/
except
/
finally
statements, but not all APIs are well designed in that regard. When a context manager is the only resource management API provided, then
ExitStack
can make it easier to handle various situations that can’t be handled directly in a
with
语句。
清理在
__enter__
实现
¶
As noted in the documentation of
ExitStack.push()
, this method can be useful in cleaning up an already allocated resource if later steps in the
__enter__()
implementation fail.
Here’s an example of doing this for a context manager that accepts resource acquisition and release functions, along with an optional validation function, and maps them to the context management protocol:
from contextlib import contextmanager, AbstractContextManager, ExitStack
class ResourceManager(AbstractContextManager):
def __init__(self, acquire_resource, release_resource, check_resource_ok=None):
self.acquire_resource = acquire_resource
self.release_resource = release_resource
if check_resource_ok is None:
def check_resource_ok(resource):
return True
self.check_resource_ok = check_resource_ok
@contextmanager
def _cleanup_on_error(self):
with ExitStack() as stack:
stack.push(self)
yield
# The validation check passed and didn't raise an exception
# Accordingly, we want to keep the resource, and pass it
# back to our caller
stack.pop_all()
def __enter__(self):
resource = self.acquire_resource()
with self._cleanup_on_error():
if not self.check_resource_ok(resource):
msg = "Failed validation for {!r}"
raise RuntimeError(msg.format(resource))
return resource
def __exit__(self, *exc_details):
# We don't need to duplicate any of our resource release logic
self.release_resource()
替换任何使用的
try-finally
和标志变量
¶
A pattern you will sometimes see is a
try-finally
statement with a flag variable to indicate whether or not the body of the
finally
clause should be executed. In its simplest form (that can’t already be handled just by using an
except
clause instead), it looks something like this:
cleanup_needed = True
try:
result = perform_operation()
if result:
cleanup_needed = False
finally:
if cleanup_needed:
cleanup_resources()
As with any
try
statement based code, this can cause problems for development and review, because the setup code and the cleanup code can end up being separated by arbitrarily long sections of code.
ExitStack
makes it possible to instead register a callback for execution at the end of a
with
statement, and then later decide to skip executing that callback:
from contextlib import ExitStack
with ExitStack() as stack:
stack.callback(cleanup_resources)
result = perform_operation()
if result:
stack.pop_all()
This allows the intended cleanup behaviour to be made explicit up front, rather than requiring a separate flag variable.
If a particular application uses this pattern a lot, it can be simplified even further by means of a small helper class:
from contextlib import ExitStack
class Callback(ExitStack):
def __init__(self, callback, /, *args, **kwds):
super().__init__()
self.callback(callback, *args, **kwds)
def cancel(self):
self.pop_all()
with Callback(cleanup_resources) as cb:
result = perform_operation()
if result:
cb.cancel()
If the resource cleanup isn’t already neatly bundled into a standalone function, then it is still possible to use the decorator form of
ExitStack.callback()
to declare the resource cleanup in advance:
from contextlib import ExitStack
with ExitStack() as stack:
@stack.callback
def cleanup_resources():
...
result = perform_operation()
if result:
stack.pop_all()
Due to the way the decorator protocol works, a callback function declared this way cannot take any parameters. Instead, any resources to be released must be accessed as closure variables.
将上下文管理器用作函数装饰器
¶
ContextDecorator
makes it possible to use a context manager in both an ordinary
with
statement and also as a function decorator.
For example, it is sometimes useful to wrap functions or groups of statements with a logger that can track the time of entry and time of exit. Rather than writing both a function decorator and a context manager for the task, inheriting from
ContextDecorator
provides both capabilities in a single definition:
from contextlib import ContextDecorator
import logging
logging.basicConfig(level=logging.INFO)
class track_entry_and_exit(ContextDecorator):
def __init__(self, name):
self.name = name
def __enter__(self):
logging.info('Entering: %s', self.name)
def __exit__(self, exc_type, exc, exc_tb):
logging.info('Exiting: %s', self.name)
Instances of this class can be used as both a context manager:
with track_entry_and_exit('widget loader'):
print('Some time consuming activity goes here')
load_widget()
And also as a function decorator:
@track_entry_and_exit('widget loader')
def activity():
print('Some time consuming activity goes here')
load_widget()
Note that there is one additional limitation when using context managers as function decorators: there’s no way to access the return value of
__enter__()
. If that value is needed, then it is still necessary to use an explicit
with
语句。
一次性使用、可重用和可重入的上下文管理器
¶
Most context managers are written in a way that means they can only be used effectively in a
with
statement once. These single use context managers must be created afresh each time they’re used - attempting to use them a second time will trigger an exception or otherwise not work correctly.
This common limitation means that it is generally advisable to create context managers directly in the header of the
with
statement where they are used (as shown in all of the usage examples above).
Files are an example of effectively single use context managers, since the first
with
statement will close the file, preventing any further IO operations using that file object.
上下文管理器的创建使用
contextmanager()
are also single use context managers, and will complain about the underlying generator failing to yield if an attempt is made to use them a second time:
>>> from contextlib import contextmanager
>>> @contextmanager
... def singleuse():
... print("Before")
... yield
... print("After")
...
>>> cm = singleuse()
>>> with cm:
... pass
...
Before
After
>>> with cm:
... pass
...
Traceback (most recent call last):
...
RuntimeError: generator didn't yield
可重入上下文管理器
¶
More sophisticated context managers may be “reentrant”. These context managers can not only be used in multiple
with
statements, but may also be used
inside
a
with
statement that is already using the same context manager.
threading.RLock
is an example of a reentrant context manager, as are
suppress()
,
redirect_stdout()
，和
chdir()
. Here’s a very simple example of reentrant use:
>>> from contextlib import redirect_stdout
>>> from io import StringIO
>>> stream = StringIO()
>>> write_to_stream = redirect_stdout(stream)
>>> with write_to_stream:
... print("This is written to the stream rather than stdout")
... with write_to_stream:
... print("This is also written to the stream")
...
>>> print("This is written directly to stdout")
This is written directly to stdout
>>> print(stream.getvalue())
This is written to the stream rather than stdout
This is also written to the stream
Real world examples of reentrancy are more likely to involve multiple functions calling each other and hence be far more complicated than this example.
Note also that being reentrant is
not
the same thing as being thread safe.
redirect_stdout()
, for example, is definitely not thread safe, as it makes a global modification to the system state by binding
sys.stdout
to a different stream.
可重用上下文管理器
¶
Distinct from both single use and reentrant context managers are “reusable” context managers (or, to be completely explicit, “reusable, but not reentrant” context managers, since reentrant context managers are also reusable). These context managers support being used multiple times, but will fail (or otherwise not work correctly) if the specific context manager instance has already been used in a containing with statement.
threading.Lock
is an example of a reusable, but not reentrant, context manager (for a reentrant lock, it is necessary to use
threading.RLock
代替)。
Another example of a reusable, but not reentrant, context manager is
ExitStack
, as it invokes
all
currently registered callbacks when leaving any with statement, regardless of where those callbacks were added:
>>> from contextlib import ExitStack
>>> stack = ExitStack()
>>> with stack:
... stack.callback(print, "Callback: from first context")
... print("Leaving first context")
...
Leaving first context
Callback: from first context
>>> with stack:
... stack.callback(print, "Callback: from second context")
... print("Leaving second context")
...
Leaving second context
Callback: from second context
>>> with stack:
... stack.callback(print, "Callback: from outer context")
... with stack:
... stack.callback(print, "Callback: from inner context")
... print("Leaving inner context")
... print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Callback: from outer context
Leaving outer context
As the output from the example shows, reusing a single stack object across multiple with statements works correctly, but attempting to nest them will cause the stack to be cleared at the end of the innermost with statement, which is unlikely to be desirable behaviour.
Using separate
ExitStack
instances instead of reusing a single instance avoids that problem:
>>> from contextlib import ExitStack
>>> with ExitStack() as outer_stack:
... outer_stack.callback(print, "Callback: from outer context")
... with ExitStack() as inner_stack:
... inner_stack.callback(print, "Callback: from inner context")
... print("Leaving inner context")
... print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Leaving outer context
Callback: from outer context
