3.3 `weakref` -- 弱参照

バージョン 2.1 で新たに追加された仕様です。

weakrefモジュールは、Pythonプログラマがオブジェクトへの 弱参照を作成できるようにします。

以下では、用語リファレント (referent) は弱参照が参照するオブジェクトを意味します。

オブジェクトに対する弱参照は、そのオブジェクトを生かしておくのに十分な条件にはなりません: あるリファレントに対する参照が弱参照しか残っていない場合、ガベージコレクション機構は自由にリファレントを破壊し、そのメモリを別の用途に再利用できます。弱参照の主な用途は、巨大なオブジェクトを保持するキャッシュやマップ型の実装において、キャッシュやマップ型にあるという理由だけオブジェクトを存続させたくない場合です。例えば、巨大なバイナリ画像のオブジェクトがたくさんあり、それぞれに名前を関連付けたいとします。 Python の辞書型を使って名前を画像に対応付けたり画像を名前に対応付けたりすると、画像オブジェクトは辞書内のキーや値に使われているため存続しつづけることになります。weakref モジュールが提供している WeakKeyDictionary や WeakValueDictionary クラスはその代用で、対応付けを構築するのに弱参照を使い、キャッシュやマップ型に存在するという理由だけでオブジェクトを存続させないようにします。例えば、もしある画像オブジェクトが WeakValueDictionary の値になっていた場合、最後に残った画像オブジェクトへの参照を弱参照マップ型が保持していれば、ガーベジコレクションはこのオブジェクトを再利用でき、画像オブジェクトに対する弱参照内の対応付けはそのまま削除されます。

WeakKeyDictionary や WeakValueDictionary は弱参照を使って実装されていて、キーや値がガーベジコレクションによって回収されたことを弱参照辞書に知らせるような弱参照オブジェクトのコールバック関数を設定しています。

ほとんどのプログラムが、いずれかの弱参照辞書型を使うだけで必要を満たせるはずです -- 自作の弱参照辞書を直接作成する必要は普通はありません。とはいえ、弱参照辞書の実装に使われている低水準の機構は、高度な利用を行う際に恩恵をうけられるよう weakref モジュールで公開されています。

すべてのオブジェクトを弱参照できるわけではありません。弱参照できるオブジェクトは、クラスインスタンス、(Cではなく) Pythonで書かれた関数、 (束縛および非束縛の両方の)メソッド、set および frozenset 型、ファイルオブジェクト、ジェネレータ、型オブジェクト、 bsddb モジュールの DBcursor 型、ソケット型、 array型、deque型、および正規表現パターンオブジェクトです。バージョン 2.4 で変更された仕様: ファイル、ソケット、array、および正規表現パターンのサポートを追加しました

list やdict など、いくつかの組み込み型は弱参照を直接サポートしませんが、以下のようにサブクラス化を行えばサポートを追加できます:

class Dict(dict):
    pass

obj = Dict(red=1, green=2, blue=3)   # this object is weak referencable

弱参照をサポートするために拡張型を簡単に作れます。詳細については、3.3.3節 ``拡張型における弱参照''を読んでください。

クラス ref( object[, callback])

objectへの弱参照を返します。リファレントがまだ生きているならば、元のオブジェクトは参照オブジェクトの呼び出しで取り出せす。リファレントがもはや生きていないならば、参照オブジェクトを呼び出したときに None を返します。 callback に None 以外の値を与えた場合、オブジェクトをまさに後始末処理しようとするときに呼び出します。このとき弱参照オブジェクトはcallback の唯一のパラメタとして渡されます。リファレントはもはや利用できません。

同じオブジェクトに対してたくさんの弱参照を作れます。それぞれの弱参照に対して登録されたコールバックは、もっとも新しく登録されたコールバックからもっとも古いものへと呼び出されます。

コールバックが発生させた例外は標準エラー出力に書き込まれますが、伝搬させられません。それらはオブジェクトの__del__()メソッドが発生させる例外とまったく同様の方法で処理されます。

objectがハッシュ可能ならば、弱参照はハッシュ可能です。それらはobjectが削除された後でもそれらのハッシュ値を保持します。objectが削除されてから初めて hash()が呼び出された場合に、その呼び出しはTypeErrorを発生させます。

弱参照は等価性のテストをサポートしていますが、順序をサポートしていません。参照がまだ生きているならば、callbackに関係なく二つの参照はそれらのリファレントと同じ等価関係を持ちます。リファレントのどちらか一方が削除された場合、参照オブジェクトが同じオブジェクトである場合に限り、その参照は等価です。

バージョン 2.4 で変更された仕様: 以前はファクトリでしたが、サブクラス化可能な型になりました。 object 型から導出されています

proxy( object[, callback]): 弱参照を使うobjectへのプロキシを返します。弱参照オブジェクトとともに用いられる明示的な参照外しを要求する代わりに、これはほとんどのコンテキストにおけるプロキシの利用をサポートします。objectが呼び出し可能かどうかに依存して、返されるオブジェクトはProxyTypeまたはCallableProxyTypeのどちらか一方の型を持ちます。プロキシオブジェクトはリファレントに関係なくハッシュ可能ではありません。これによって、それらの基本的な変更可能という性質に関係する多くの問題を避けています。そして、辞書のキーとしてそれらの利用を妨げます。callbackはref()関数の同じ名前のパラメータと同じものです。

getweakrefcount( object): objectを参照する弱参照とプロキシの数を返します。

getweakrefs( object): objectを参照するすべての弱参照とプロキシオブジェクトのリストを返します。

クラス WeakKeyDictionary( [dict]): キーを弱く参照するマッピングクラス。もはやキーへの強い参照がなくなったときに、辞書のエントリは捨てられます。アプリケーションの他の部分が所有するオブジェクトへ属性を追加することもなく、それらのオブジェクトに追加データを関連づけるためにこれを使うことができます。これは属性へのアクセスをオーバーライドするオブジェクトに特に便利です。
注意: 注意: WeakKeyDictionary は Python 辞書型の上に作られているので、反復処理を行うときにはサイズ変更してはなりません。WeakKeyDictionary の場合、反復処理の最中にプログラムが行った操作が、(ガベージコレクションの副作用として) 「魔法のように」辞書内の要素を消し去ってしまうため、確実なサイズ変更は困難なのです。

クラス WeakValueDictionary( [dict]): 値を弱く参照するマッピングクラス。値への強い参照がもはや存在しなくなったときに、辞書のエントリは捨てられます。

ReferenceType: 弱参照オブジェクトのための型オブジェクト。

ProxyType: 呼び出し可能でないオブジェクトのプロキシのための型オブジェクト。

CallableProxyType: 呼び出し可能なオブジェクトのプロキシのための型オブジェクト。

ProxyTypes: プロキシのためのすべての型オブジェクトを含むシーケンス。これは両方のプロキシ型の名前付けに依存しないで、オブジェクトがプロキシかどうかのテストをより簡単にできます。

exception ReferenceError: プロキシオブジェクトが使われても、元のオブジェクトがガーベジコレクションされてしまっているときに発生する例外。これは標準のReferenceError例外と同じです。

参考:

PEP 0205, Weak References: この機能の提案と理論的根拠。初期の実装と他の言語における類似の機能についての情報へのリンクを含んでいます。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。

3.3 weakref -- 弱参照

3.3 `weakref` -- 弱参照