28.7. contextlib --- with 文コンテキスト用ユーティリティ

バージョン 2.5 で追加.

ソースコード: Lib/contextlib.py

このモジュールは with 文に関わる一般的なタスクのためのユーティリティを提供します。詳しい情報は、 コンテキストマネージャ型 と with文とコンテキストマネージャ を参照してください。

提供されている関数:

contextlib.contextmanager(func)

この関数は with 文コンテキストマネージャのファクトリ関数を定義するために利用できる デコレータ です。新しいクラスや __enter__() と __exit__() メソッドを別々に定義しなくても、ファクトリ関数を定義することができます。

While many objects natively support use in with statements, sometimes a resource needs to be managed that isn't a context manager in its own right, and doesn't implement a close() method for use with contextlib.closing

An abstract example would be the following to ensure correct resource management:

from contextlib import contextmanager

@contextmanager
def managed_resource(*args, **kwds):
    # Code to acquire resource, e.g.:
    resource = acquire_resource(*args, **kwds)
    try:
        yield resource
    finally:
        # Code to release resource, e.g.:
        release_resource(resource)

>>> with managed_resource(timeout=3600) as resource:
...     # Resource is released at the end of this block,
...     # even if code in the block raises an exception

デコレート対象の関数は呼び出されたときに ジェネレータ-イテレータを返す必要があります。このイテレータは必ず値を1つ yield しなければなりません。 with 文の as 節が存在するなら、その値は as 節のターゲットへ束縛されることになります。

ジェネレータが yield を実行した箇所で with 文のネストされたブロックが実行されます。ブロックから抜けた後でジェネレータは再開されます。ブロック内で処理されない例外が発生した場合は、ジェネレータ内部の yield を実行した箇所で例外が再送出されます。なので、(もしあれば) エラーを捕捉したり、クリーンアップ処理を確実に実行したりするために、try...except...finally 構文を使用できます。例外を捕捉する目的が、(完全に例外を抑制してしまうのではなく) 単に例外のログをとるため、もしくはあるアクションを実行するためなら、ジェネレータはその例外を再送出しなければなりません。例外を再送出しない場合、ジェネレータのコンテキストマネージャは with 文に対して例外が処理されたことを示し、with 文の直後の文から実行を再開します。

contextlib.nested(mgr1[, mgr2[, ...]])

複数のコンテキストマネージャを一つのネストされたコンテキストマネージャへ結合します。

この関数は、 with 文にマルチマネージャー形式ができたために非推奨になりました。

この関数の with 文のマルチマネージャー形式に対する唯一の利点は、引数のアンパックによって、次の例のように可変数個のコンテキストマネージャーを扱えることです。

from contextlib import nested

with nested(*managers):
    do_something()

ネストされたコンテキストマネージャのうちのいずれかの __exit__() メソッドが例外を抑制すべきと判断した場合、外側にある残りのすべてのコンテキストマネージャに例外情報が渡されないということに注意してください。同様に、ネストされたコンテキストマネージャのうちのいずれかの __exit__() メソッドが例外を送出したならば、それ以前の例外状態は失われ、新しい例外が外側にある残りのすべてのコンテキストマネージャの __exit__() メソッドに渡されます。一般的に __exit__() メソッドが例外を送出することは避けるべきであり、特に渡された例外を再送出すべきではありません。

この関数が非推奨になった理由に、2つの大きな問題があります。 1つ目は、全てのコンテキストマネージャーが関数が呼び出される前に構築されることです。内側のコンテキストマネージャーの __new__() と __init__() メソッドは外側のコンテキストマネージャーの内側に入っていません。つまり、例えば nested() を2つのファイルを開くために利用した場合、 2つめのファイルを開くのに失敗すると1つめのファイルが正しく close されないというプログラムエラーになります。

2つ目の問題は、内側のコンテキストマネージャーの1つの __enter__() メソッドが例外を発生させたときに、外側のコンテキストマネージャーの __exit__() メソッドがその例外を捕まえて抑制させてしまうことで、この場合に with の body 部分の実行がスキップされるのではなく RuntimeError が発生する恐れがあります。

可変数個のコンテキストマネージャーのネストをサポートしなければならない場合、 warnings モジュールを利用してこの関数が発生させる DeprecationWarning を抑制するか、この関数を参考にしてアプリケーション独自の実装をすることができます。

バージョン 2.7 で非推奨: with 文がこの関数の機能を(この関数と違って奇妙なエラーを発生させることなしに) 直接サポートしました。

contextlib.closing(thing)

ブロックの完了時に thing を close するコンテキストマネージャを返します。これは基本的に以下と等価です:

from contextlib import contextmanager

@contextmanager
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()

そして、明示的に page を close する必要なしに、次のように書くことができます:

from contextlib import closing
import urllib

with closing(urllib.urlopen('http://www.python.org')) as page:
    for line in page:
        print line

page を明示的に close する必要は無く、エラーが発生した場合でも、 with ブロックを出るときに page.close() が呼ばれます。

参考

PEP 343 - "with" ステートメント

仕様、背景、および、Python with 文の例。