3.14.3 使用法

オブジェクト階層を直列化するには、まず pickler を生成し、続いてpickler の dump() メソッドを呼び出します。データストリームから非直列化するには、まず unpickler を生成し、続いて unpicklerの load() メソッドを呼び出します。pickle モジュールでは以下の定数を提供しています:

HIGHEST_PROTOCOL: 有効なプロトコルのうち、最も大きいバージョン。この値は、protocol として渡せます。バージョン 2.3 で新たに追加された仕様です。

この手続きを便利にするために、pickle モジュールでは以下の関数を提供しています:

dump( obj, file[, protocol[, bin]])

すでに開かれているファイルオブジェクト file に、obj を pickle 化したものを表現する文字列を書き込みます。 Pickler(file, protocol, bin).dump(obj) と同じです。

protocol を指定しない場合、プロトコル 0 が使われます。 protocol に負値か HIGHEST_PROTOCOL を指定すると、有効なプロトコルの内、もっとも高いバージョンのものが使われます。

バージョン 2.3 で変更された仕様: bin パラメータは非推奨で、後方互換性のためだけに提供されています。代わりに protocol を使うべきです。

オプションの bin 引数が真の場合、バイナリ pickle 化形式が使われます; そうでない場合 (より低効率の) テキスト pickle 化形式が使われます (以前のバージョンとの互換性のため、こちらが標準になっています)。

file は、単一の文字列引数を受理する write() メソッドを持たなければなりません。従って、 file としては、書き込みのために開かれたファイルオブジェクト、 StringIO オブジェクト、その他前述のインタフェースに適合する他のカスタムオブジェクトをとることができます。

load( file)

すでに開かれているファイルオブジェクト file から文字列を読み出し、読み出された文字列を pickle 化されたデータ列として解釈して、もとのオブジェクト階層を再構築して返します。Unpickler(file).load() と同じです。

file は、整数引数をとる read() メソッドと、引数の必要ない readline() メソッドを持たなければなりません。これらのメソッドは両方とも文字列を返さなければなりません。従って、 file としては、読み出しのために開かれたファイルオブジェクト、 StringIO オブジェクト、その他前述のインタフェースに適合する他のカスタムオブジェクトをとることができます。

この関数はデータ列の書き込まれているモードがバイナリかそうでないかを自動的に判断します。

dumps( obj[, protocol[, bin]])

obj の pickle 化された表現を、ファイルに書き込む代わりに文字列で返します。

バージョン 2.3 で変更された仕様: bin パラメータは非推奨で、後方互換性のためだけに提供されています。代わりに protocol を使うべきです。

オプションの bin 引数が真の場合、バイナリの pickle 形式が使われます; そうでない場合、(より低効率の) テキストの pickle 形式が使われます (こちらが標準の設定です)。

loads( string): pickle 化されたオブジェクト階層を文字列から読み出します。文字列中で pickle 化されたオブジェクト表現よりも後に続く文字列は無視されます。

pickle モジュールでは、以下の 3 つの例外も定義しています:

exception PickleError: 下で定義されている他の例外で共通の基底クラスです。Exception を継承しています。

exception PicklingError: この例外は unpickle 不可能なオブジェクトが dump() メソッドに渡された場合に送出されます。

exception UnpicklingError: この例外は、オブジェクトを unpickle 化する際に問題が発生した場合に送出されます。 unpickle 化中には AttributeError、 EOFError、 ImportError、および IndexError といった他の例外 (これだけとは限りません) も発生する可能性があるので注意してください。

pickle モジュールでは、2 つの呼び出し可能オブジェクト ^3.3として、Pickler および Unpickler を提供しています:

クラス Pickler( file[, protocol[, bin]])

pickle 化されたオブジェクトのデータ列を書き込むためのファイル類似のオブジェクトを引数にとります。

protocol を指定しない場合、プロトコル 0 が使われます。protocol に負値か HIGHEST_PROTOCOL を指定すると、有効なプロトコルの内、もっとも高いバージョンのものが使われます。

バージョン 2.3 で変更された仕様: bin パラメータは非推奨で、後方互換性のためだけに提供されています。代わりに protocol を使うべきです。

オプションの bin を真にすると、 pickler により高効率のバイナリ pickle 形式を使うように指示します。そうでない場合、ASCII 形式が使われます (こちらの方が標準です)。

file は単一の文字列引数を受理する write() メソッドを持たなければなりません。従って、 file としては、書き込みのために開かれたファイルオブジェクト、 StringIO オブジェクト、その他前述のインタフェースに適合する他のカスタムオブジェクトをとることができます。

Pickler オブジェクトでは、一つ (または二つ) の public なメソッドを定義しています:

dump( obj): コンストラクタで与えられた、すでに開かれているファイルオブジェクトに obj の pickle 化された表現を書き込みます。コンストラクタに渡された bin フラグの値に応じて、バイナリおよびASCII 形式が使われます。

clear_memo( )

picller の ``メモ'' を消去します。メモとは、共有オブジェクトまたは再帰的なオブジェクトが値ではなく参照で記憶されるようにするために、 pickler がこれまでどのオブジェクトに遭遇してきたかを記憶するデータ構造です。このメソッドは pickler を再利用する際に便利です。

注意: Python 2.3 以前では、clear_memo() は cPickle で生成された pickler でのみ利用可能でした。pickle モジュールでは、pickler は memo と呼ばれる Python 辞書型のインスタンス変数を持ちます。従って、pickler モジュールにおける pickler のメモを消去は、以下のようにしてできます:

mypickler.memo.clear()

以前のバージョンの Python での動作をサポートする必要のないコードでは、単に clear_memo() を使ってください。

同じ Pickler のインスタンスに対し、 dump() メソッドを複数回呼び出すことは可能です。この呼び出しは、対応する Unpickler インスタンスで同じ回数だけ load() を呼び出す操作に対応します。同じオブジェクトが dump() を複数回呼び出して pickle 化された場合、load() は全て同じオブジェクトに対して参照を行います ^3.4。。

Unpickler オブジェクトは以下のように定義されています:

クラス Unpickler( file): pickle データ列を読み出すためのファイル類似のオブジェクトを引数に取ります。このクラスはデータ列がバイナリモードかどうかを自動的に判別します。従って、Pickler のファクトリメソッドのようなフラグを必要としません。
file は、整数引数を取る read() メソッド、および引数を持たない readline() メソッドの、 2 つのメソッドを持ちます。両方のメソッドとも文字列を返します。従って、 file としては、読み出しのために開かれたファイルオブジェクト、 StringIO オブジェクト、その他前述のインタフェースに適合する他のカスタムオブジェクトをとることができます。

Unpickler オブジェクトは 1 つ (または 2 つ) の public なメソッドを持っています:

load( ): コンストラクタで渡されたファイルオブジェクトからオブジェクトの pickle 化表現を読み出し、中に収められている再構築されたオブジェクト階層を返します。

noload( ): load() に似ていますが、実際には何もオブジェクトを生成しないという点が違います。この関数は第一に pickle 化データ列中で参照されている、``永続化 id'' と呼ばれている値を検索する上で便利です。詳細は以下の 3.14.5 を参照してください。
注意: noload() メソッドは現在 cPickle モジュールで生成された Unpickler オブジェクトのみで利用可能です。pickle モジュールの Unpickler には、 noload() メソッドがありません。

... つの呼び出し可能オブジェクト ^3.3: pickleでは、これらの呼び出し可能オブジェクトはクラスであり、サブクラス化してその動作をカスタマイズすることができます。しかし、 cPickle モジュールでは、これらの呼び出し可能オブジェクトはファクトリ関数であり、サブクラス化することができません。サブクラスを作成する共通の理由の一つは、どのオブジェクトを実際に unpickle するかを制御することです。詳細については 3.14.6 を参照してください。
... は全て同じオブジェクトに対して参照を行います ^3.4: 警告: これは、複数のオブジェクトを pickle 化する際に、オブジェクトやそれらの一部に対する変更を妨げないようにするための仕様です。あるオブジェクトに変更を加えて、その後同じ Pickler を使って再度 pickle 化しようとしても、そのオブジェクトは pickle 化しなおされません -- そのオブジェクトに対する参照が pickle 化され、Unpickler は変更された値ではなく、元の値を返します。これには 2 つの問題点 : (1) 変更の検出、そして (2) 最小限の変更を整列化すること、があります。ガーベジコレクションもまた問題になります。

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