# `pickletools` --- pickle 開発者用のツール群

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

このモジュールには、 `pickle` モジュールの詳細に関わる様々な定数や実装に関する長大なコメント、そして pickle 化されたデータを解析する上で有用な関数をいくつか定義しています。このモジュールの内容は `pickle` の実装に関わっている Python コア開発者にとって有用なものです; 普通の `pickle` 利用者にとっては、 `pickletools` モジュールはおそらく関係ないものでしょう。

## コマンドラインの使い方

Added in version 3.2.

コマンドラインから実行するとき、`python -m pickletools` は 1 つもしくは複数の pickle ファイルの内容を逆アセンブルします。pickle 形式の詳細ではなく pickle に保存された Python オブジェクトを見たい場合は、そのコマンドではなく `-m pickle` を使いたいと思うかもしれません。しかし、調べたい pickle ファイルが信頼できないソースから来たものであるとき、`-m pickletools` は pickle のバイトコードを実行しないので、より安全な選択肢です。

例えば、 `x.pickle` ファイルに pickle 化されているタプル `(1, 2)` に対して実行すると次のようになります:

    $ python -m pickle x.pickle
    (1, 2)

    $ python -m pickletools x.pickle
        0: \x80 PROTO      3
        2: K    BININT1    1
        4: K    BININT1    2
        6: \x86 TUPLE2
        7: q    BINPUT     0
        9: .    STOP
    highest protocol among opcodes = 2

### コマンドラインオプション

-a, --annotate

  注釈として短い命令コードの説明を各行に表示します。

-o, --output=<file>

  出力結果を書き込むファイル名。

-l, --indentlevel=<num>

  新しい MARK レベルのインデントに使われる空白の数。

-m, --memo

  複数のオブジェクトが逆アセンブルされたとき、逆アセンブリ間でメモを保持します。

-p, --preamble=<preamble>

  複数の pickle ファイルが指定されたとき、各逆アセンブリの前に与えられたプリアンブルを表示します。

## プログラミングインターフェース

pickletools.dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)

  pickle の抽象的な逆アセンブリを file-like オブジェクト out (デフォルトは `sys.stdout`) に出力します。pickle は文字列または file-like オブジェクトです。memo は Python の辞書で、pickle のメモとして使われます; これは、pickle 処理を行う 1 つのオブジェクトが、複数の pickle にわたって逆アセンブルを行うために使われます。ストリーム上の `MARK` 命令コードが示す後続のレベルは、indentlevel 個の空白でインデントされます。annotate に非ゼロの値が与えられた場合、出力される各命令コードは短い命令コードに注釈が付けられます。annotate の値は、注釈の先頭の位置のヒントとして使われます。

  バージョン 3.2 で変更: annotate パラメーターを追加しました。

pickletools.genops(pickle)

  pickle 内の全ての opcode を取り出す イテレータ を返します。このイテレータは `(opcode, arg, pos)` の三つ組みからなる配列を返します。 opcode は `OpcodeInfo` クラスのインスタンスのクラスです。 arg は opcode の引数としてデコードされた Python オブジェクトの値です。 pos は opcode の場所を表す値です。 pickle は文字列でもファイル類似オブジェクトでもかまいません。

pickletools.optimize(picklestring)

  使われていない `PUT` 命令コードを除去した上で、その新しい pickle 文字列を返します。最適化された pickle は、長さがより短く、転送時間がより少なく、必要とするストレージ領域がより狭く、unpickle 化がより効率的になります。