Python3标准库：contextlib上下文管理器工具
1. contextlib上下文管理器工具
contextlib模块包含的工具用于处理上下文管理器和with语句。
1.1 上下文管理器API
上下文管理器(context manager)负责管理一个代码块中的资源，会在进入代码块时创建资源，然后在退出代码块后清理这个资源。例如，文件就支持上下文管理器API，可以确保完成文件读写后关闭文件。
with open(‘test.txt‘, ‘wt‘) as f:
f.write(‘contents go here‘)上下文管理器由with语句启用，这个API包括两个方法。执行流进入with中的代码块时会运行__enter__()方法。它会返回在这个上下文中使用的一个对象。执行流离开with块时，则掉哟这个上下文管理器的__exit__()方法来清理所使用的资源。
class Context:
def __init__(self):
print(‘__init__()‘)
def __enter__(self):
print(‘__enter__()‘)
return self
def __exit__(self, exc_type, exc_val, exc_tb):
print(‘__exit__()‘)
with Context():
print(‘Doing work in the context‘)相对于try:finally块，结合上下文管理器和with语句是一种更紧凑的写法，因为总会调用上下文管理器的__exit__()方法，即使产生异常的情况下也会调用这个方法。
如果with语句的as子句中指定了名，那么__enter__()方法可以返回与这个名关联的任何对象。在这个例子中，Context会返回一个使用打开的上下文的对象。
class WithinContext:
def __init__(self, context):
print(‘WithinContext.__init__({})‘.format(context))
def do_something(self):
print(‘WithinContext.do_something()‘)
def __del__(self):
print(‘WithinContext.__del__‘)
class Context:
def __init__(self):
print(‘Context.__init__()‘)
def __enter__(self):
print(‘Context.__enter__()‘)
return WithinContext(self)
def __exit__(self, exc_type, exc_val, exc_tb):
print(‘Context.__exit__()‘)
with Context() as c:
c.do_something()与变量c关联的值是__enter__()返回的对象，这不一定是with语句中创建的Context实例。
__exit__()方法接收一些参数，其中包含with块中产生的所有异常的详细信息。
class Context:
def __init__(self, handle_error):
print(‘__init__({})‘.format(handle_error))
self.handle_error = handle_error
def __enter__(self):
print(‘__enter__()‘)
return self
def __exit__(self, exc_type, exc_val, exc_tb):
print(‘__exit__()‘)
print(‘ exc_type =‘, exc_type)
print(‘ exc_val =‘, exc_val)
print(‘ exc_tb =‘, exc_tb)
return self.handle_error
with Context(True):
raise RuntimeError(‘error message handled‘)
print()
with Context(False):
raise RuntimeError(‘error message propagated‘)如果上下文管理器可以处理这个异常，那么__exit__()应当返回一个true值来指示这个异常不需要传播。如果返回false，则会在__exit__()返回后再次抛出这个异常。
1.2 上下文管理器作为函数修饰符
类ContextDecorator增加了对常规上下文管理器类的支持，因此其不仅可以作为上下文管理器，也可以作为函数修饰符。
import contextlib
class Context(contextlib.ContextDecorator):
def __init__(self, how_used):
self.how_used = how_used
print(‘__init__({})‘.format(how_used))
def __enter__(self):
print(‘__enter__({})‘.format(self.how_used))
return self
def __exit__(self, exc_type, exc_val, exc_tb):
print(‘__exit__({})‘.format(self.how_used))
@Context(‘as decorator‘)
def func(message):
print(message)
print()
with Context(‘as context manager‘):
print(‘Doing work in the context‘)
print()
func(‘Doing work in the wrapped function‘)使用上下文管理器作为修饰符时有一点不同：__enter__()返回的值在被修饰的函数中不可用，这与使用with和as时不一样。传入被修饰函数的参数可以正常使用。
1.3 从生成器到上下文管理器
采用传统方式创建上下文管理器并不难，即编写一个包含__enter__()和__exit__()方法的类。不过有些时候，如果只有很少的上下文要管理，那么完整的写出所有代码便会成为额外的负担。在这些情况下，可以使用contextmanager()修饰符将一个生成器函数转换为上下文管理器。
import contextlib
@contextlib.contextmanager
def make_context():
print(‘ entering‘)
try:
yield {}
except RuntimeError as err:
print(‘ ERROR:‘, err)
finally:
print(‘ exiting‘)
print(‘Normal:‘)
with make_context() as value:
print(‘ inside with statement:‘, value)
print(‘\nHandled error:‘)
with make_context() as value:
raise RuntimeError(‘showing example of handling an error‘)
print(‘\nUnhandled error:‘)
with make_context() as value:
raise ValueError(‘this exception is not handled‘)生成器要初始化上下文，调用一次yield，然后清理上下文。所生成的值（如果有）会绑定到with语句as子句中的变量。with块中抛出的异常会在生成器中再次抛出，从而可以在生成器中得到处理。
contextmanager()返回的上下文管理器派生自ContextDecorator，所以也可以被用作函数修饰符。
import contextlib
@contextlib.contextmanager
def make_context():
print(‘ entering‘)
try:
# Yield control, but not a value, because any value
# yielded is not available when the context manager
# is used as a decorator.
yield
except RuntimeError as err:
print(‘ ERROR:‘, err)
finally:
print(‘ exiting‘)
@make_context()
def normal():
print(‘ inside with statement‘)
@make_context()
def throw_error(err):
raise err
print(‘Normal:‘)
normal()
print(‘\nHandled error:‘)
throw_error(RuntimeError(‘showing example of handling an error‘))
print(‘\nUnhandled error:‘)
throw_error(ValueError(‘this exception is not handled‘))与前面的ContextDecorator例子一样，上下文管理器被用作修饰符时，生成器生成的值在被修饰的函数中不可用。传入被修饰函数的参数仍然可用，如这个例子中的throw_error()所示。
1.4 关闭打开的句柄
file类直接支持上下文管理器API，但另外一些表示打开句柄的对象却并不支持。contextlib的标准库文档中给出的示例是从urllib.urlopen()返回的对象。另外一些遗留的类会使用close()方法但不支持上下文管理器API。为了确保关闭句柄，要使用closing()为它创建一个上下文管理器。
import contextlib
class Door:
def __init__(self):
print(‘ __init__()‘)
self.status = ‘open‘
def close(self):
print(‘ close()‘)
self.status = ‘closed‘
print(‘Normal Example:‘)
with contextlib.closing(Door()) as door:
print(‘ inside with statement: {}‘.format(door.status))
print(‘ outside with statement: {}‘.format(door.status))
print(‘\nError handling example:‘)
try:
with contextlib.closing(Door()) as door:
print(‘ raising from inside with statement‘)
raise RuntimeError(‘error message‘)
except Exception as err:
print(‘ Had an error:‘, err)不论with块中是否有错误，都会关闭这个句柄。
1.5 忽略异常
很多情况下，忽略库产生的异常通常很有用，因为这个错误可能会显示期望的状态已经被实现，否则该错误可以被忽略。要忽略异常，最常见的方法是利用一个try:except语句，其在except块中只包含一个pass语句。
class NonFatalError(Exception):
pass
def non_idempotent_operation():
raise NonFatalError(
‘The operation failed because of existing state‘
)
try:
print(‘trying non-idempotent operation‘)
non_idempotent_operation()
print(‘succeeded!‘)
except NonFatalError:
pass
print(‘done‘)在这种情况下，这个操作会失败，而错误将被忽略。
try:except也可以被替换为contextlib.suppress()，以更显式的抑制with块中产生某一类异常。
import contextlib
class NonFatalError(Exception):
pass
def non_idempotent_operation():
raise NonFatalError(
‘The operation failed because of existing state‘
)
with contextlib.suppress(NonFatalError):
print(‘trying non-idempotent operation‘)
non_idempotent_operation()
print(‘succeeded!‘)
print(‘done‘)在这个更新后的版本中，异常会被完全丢弃。
1.6 重定向输出流
设计不当的库代码可能会直接些sys.stdout或sys.stderr，而没有提供参数来配置不同的输出目标。可以用redirect_stdout()和redirect_stderr()上下文管理器从这些函数捕捉输出，因为无法修改这些函数的源代码来接收新的输出参数。
from contextlib import redirect_stdout, redirect_stderr
import io
import sys
def misbehaving_function(a):
sys.stdout.write(‘(stdout) A: {!r}\n‘.format(a))
sys.stderr.write(‘(stderr) A: {!r}\n‘.format(a))
capture = io.StringIO()
with redirect_stdout(capture), redirect_stderr(capture):
misbehaving_function(5)
print(capture.getvalue())在这个例子中，misbehaving_function()同时写至stdout和stderr，不过两个上下文管理器将这个输出发送到同一个io.StringIO实例，会在这里保存以备以后使用。
1.7 动态上下文管理器栈
大多数上下文管理器都一次处理一个对象，如单个文件或数据库句柄。在这些情况下，对象是提前已知的，并且使用上下文管理器的代码可以建立这一个对象上。另外一些情况下，程序可能需要在一个上下文中常简未知数目的对象，控制流退出这个上下文时所有这些对象都要清理。ExitStack就是用来处理这些更动态的情况。
ExitStack实例会维护清理回调的一个栈数据结构。这些回调显式的填充在上下文中，在控制流退出上下文时会以逆序调用所有注册的回调。结果类似于有多个嵌套的with语句，只不过它们是动态建立的。
可以使用多种方法填充ExitStack。下面这个例子使用enter_context()来为栈增加一个新的上下文管理器。
import contextlib
@contextlib.contextmanager
def make_context(i):
print(‘{} entering‘.format(i))
yield {}
print(‘{} exiting‘.format(i))
def variable_stack(n, msg):
with contextlib.ExitStack() as stack:
for i in range(n):
stack.enter_context(make_context(i))
print(msg)
variable_stack(2, ‘inside context‘)enter_context()首先在上下文管理器上调用__enter__()。然后把它的__exit__()方法注册为一个回调，撤销栈时将调用这个回调。
