# `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)。

pickle_file

  A pickle file to read, or `-` to indicate reading from standard input.

在 3.15 版被加入: Output is in color by default and can be controlled using environment variables.

## 程式化介面

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 效率也更高。