"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 ファイルを指定した場合、各逆アセンブル結果の前に指定
   された前置きの文字列を表示します。

pickle_file

   読み込む pickle ファイル。 標準入力から読み込む場合は "-" を指定し
   ます。

Added in version 3.15: デフォルトでは色付きで出力します。 環境変数で制
御できます。


プログラムから使うインターフェース
==================================

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

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

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

pickletools.genops(pickle)

   pickle 内の全ての opcode を取り出す *イテレータ* を返します。 この
   イテレータは "(opcode, arg, pos)" の 3 要素タプルを順に返します。
   *opcode* は "OpcodeInfo" クラスのインスタンスです。 *arg* は
   *opcode* の引数としてデコードされた Python オブジェクトの値です。
   *pos* は *opcode* の場所を表す値です。 *pickle* は文字列でもファイ
   ル類似オブジェクトでもかまいません。

pickletools.optimize(picklestring)

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