"pickletools" --- Tools for pickle developers
*********************************************

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

======================================================================

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


Command line usage
==================

バージョン 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


Command line options
--------------------

-a, --annotate

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

-o, --output=<file>

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

-l, --indentlevel=<num>

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

-m, --memo

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

-p, --preamble=<preamble>

   When more than one pickle file are specified, print given preamble
   before each disassembly.


Programmatic Interface
======================

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 化がより効
   率的になります。
