## 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 化された表現を、ファイルに書き込む代わりに 文字列で返します。

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

  バージョン 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 つの呼び出し可能オブジェクト 15として、`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()` は全て同じオブジェクトに対して参照を行います 16。 。

`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()` メソッドがありません。

#### Footnotes

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