"pickletools" --- pickle 開發者的工具
*************************************

**原始碼：**Lib/pickletools.py

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

該模組包含與 "pickle" 模組的詳細資訊相關的各種常數、一些有關實作的冗長
註釋以及一些用於分析已 pickle 資料的有用函式。該模組的內容對於有
"pickle" 相關工作的 Python 核心開發人員很有用；"pickle" 模組的一般使用
者可能不會發現 "pickletools" 模組。


命令列用法
==========

在 3.2 版被加入.

當從命令列呼叫時，"python -m pickletools" 將拆解 (disassemble) 一個或
多個 pickle 檔案的內容。請注意，如果你想查看儲存在 pickle 中的 Python
物件而不是 pickle 格式的詳細資訊，你可能需要使用 "-m pickle"。但是，當
你要檢查的 pickle 檔案來自不受信任的來源時，"-m pickletools" 是一個更
安全的選項，因為它不執行 pickle 位元組碼。

例如，pickle 於檔案 "x.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

   用簡短的操作碼 (opcode) 描述註釋每一行。

-o, --output=<file>

   應將輸出結果寫入之檔案的名稱。

-l, --indentlevel=<num>

   新 MARK 級別縮進的空格數。

-m, --memo

   當拆解多個物件時，會在拆解間保留備忘錄。

-p, --preamble=<preamble>

   當指定多個 pickle 檔案時，會在每次拆解之前印出給定的一段序言
   (preamble)。


程式化介面
==========

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

   將 pickle 的符號拆解 (symbolic disassembly) 輸出到類檔案物件 *out*
   ，預設為 "sys.stdout"。*pickle* 可以是字串或類檔案物件。*memo* 可以
   是一個 Python 字典，將用作 pickle 的備忘錄；它可用於對同一 pickler
   建立的多個 pickle 執行拆解。串流中由 "MARK" 操作碼指示的連續級別由
   *indentlevel* 空格縮進。如果為 *annotate* 指定非零值，則輸出中的每
   個操作碼都會用簡短的描述進行註釋。*annotate* 的值用作為註釋之起始行
   提示。

   在 3.2 版的變更: 新增 *annotate* 參數。

pickletools.genops(pickle)

   提供 pickle 中所有操作碼的一個 *iterator*，回傳形式為 "(opcode,
   arg, pos)" 三元組序列。*opcode* 是 "OpcodeInfo" 類別的實例；*arg*
   是操作碼引數的解碼值（作為 Python 物件）；*pos* 是該操作碼所在的位
   置。*pickle* 可以是字串或類檔案物件。

pickletools.optimize(picklestring)

   消除未使用的 "PUT" 操作碼後回傳一個新的等效 pickle 字串。最佳化後的
   pickle 更短、傳輸時間更少、需要更小的儲存空間，且 unpickle 效率也更
   高。
