引言

在 Python 2.2 中 pickling 新式物件的方式有些笨拙，與舊式類例項相比，會導致 pickle 大小膨脹。本 PEP 詳細介紹了一個新的 pickle 協議，該協議將在 Python 2.3 中引入，可以解決這個問題以及許多其他 pickle 問題。

指定新的 pickle 協議有兩個方面：需要指定構成 pickled 資料的位元組流，以及需要指定物件與 pickling 和 unpickling 引擎之間的介面。本 PEP 側重於 API 問題，儘管有時也會提及位元組流格式細節來解釋某種選擇。pickle 位元組流格式由標準庫模組 pickletools.py 正式記錄（該模組已在 Python 2.3 的 CVS 中提交）。

本 PEP 試圖完整地記錄 pickled 物件與 pickling 過程之間的介面，透過指定“本 PEP 新增”來突出新內容。（除了用於指定 pickler 的 pickling 協議的 API 更改外，不完全涵蓋用於呼叫 pickling 或 unpickling 的介面。）

動機

Pickling 新式物件會導致 pickle 大小嚴重膨脹。例如

class C(object): # Omit "(object)" for classic class
    pass
x = C()
x.foo = 42
print len(pickle.dumps(x, 1))

舊式物件的二進位制 pickle 佔用了 33 位元組，新式物件則佔用了 86 位元組。

膨脹的原因很複雜，但主要歸因於新式物件需要 __reduce__ 才能進行 pickling。經過充分考慮，我們得出結論，減少新式物件 pickle 大小的唯一方法是向 pickle 協議新增新的操作碼。最終結果是，使用新協議，上述示例中的 pickle 大小為 35（開頭使用了兩個額外的位元組來指示協議版本，儘管這並非嚴格必需）。

協議版本

以前，pickling（但不是 unpickling）區分文字模式和二進位制模式。根據設計，二進位制模式是文字模式的超集，unpickler 不需要提前知道傳入的 pickle 是使用文字模式還是二進位制模式。用於 unpickling 的虛擬機器在模式上是相同的；某些操作碼在文字模式下根本不使用。

追溯性地，文字模式現在稱為協議 0，二進位制模式稱為協議 1。新協議稱為協議 2。遵循 pickling 協議的傳統，協議 2 是協議 1 的超集。但為了避免未來的 pickling 協議需要成為最舊協議的超集，協議 2 pickle 的開頭插入了一個新的操作碼，指示它使用的是協議 2。到目前為止，Python 的每個版本都能夠讀取所有先前版本編寫的 pickle。當然，在協議 N 下編寫的 pickle 無法被引入協議 N 之前的 Python 版本讀取。

用於 pickling 的幾個函式、方法和建構函式以前接受一個名為‘bin’的位置引數，這是一個標誌，預設為 0，表示二進位制模式。此引數已重新命名為‘protocol’，現在給出協議編號，仍預設為 0。

碰巧，在以前的 Python 版本中，將 2 作為‘bin’引數具有與將 1 作為引數相同的效果。儘管如此，這裡添加了一個特殊情況：傳遞負數會選擇特定實現支援的最高協議版本。這在以前的 Python 版本中也有效，因此可以用來選擇最高可用協議，且兼顧向後和向前相容。此外，pickle 和 cPickle 模組都提供了一個新的模組常量 HIGHEST_PROTOCOL，它等於模組可以讀取的最高協議編號。這比傳遞 -1 更清晰，但在 Python 2.3 之前無法使用。

pickle.py 模組一直支援將‘bin’值作為關鍵字引數而不是位置引數傳遞。（不推薦這樣做，因為 cPickle 只接受位置引數，但它有效……）將‘bin’作為關鍵字引數傳遞已被棄用，在這種情況下會發出 PendingDeprecationWarning 警告。您必須使用 -Wa 或其變體來呼叫 Python 直譯器才能看到 PendingDeprecationWarning 訊息。在 Python 2.4 中，警告類可能會升級為 DeprecationWarning。

安全問題

在以前的 Python 版本中，unpickling 會對某些操作進行“安全檢查”，拒絕呼叫未透過“可安全 unpickling”標記的函式或建構函式，這些標記是透過具有 __safe_for_unpickling__ 屬性設定為 1，或在全域性登錄檔 copy_reg.safe_constructors 中註冊來實現的。

此功能給人一種虛假的安全感：沒有人進行過必要的、廣泛的程式碼審計來證明 unpickling 不受信任的 pickle 不會呼叫不希望的程式碼，事實上 Python 2.2 pickle.py 模組中的錯誤使得繞過這些安全措施變得容易。

我們堅信，在網際網路上，知道自己正在使用一個不安全的協議比信任一個未經充分檢查其實現而聲稱安全的協議要好。即使是廣泛使用的協議的高質量實現，也經常會發現存在缺陷；Python 的 pickle 實現如果沒有更多的時間投入，根本無法做出這樣的保證。因此，從 Python 2.3 開始，所有 unpickling 上的安全檢查都被正式移除，並替換為此警告：

儘管存在安全檢查，但同樣的警告也適用於以前的 Python 版本。

擴充套件的 __reduce__ API

類可以利用幾個 API 來控制 pickling。其中最受歡迎的可能是 __getstate__ 和 __setstate__；但最強大的是 __reduce__。（還有一個 __getinitargs__，我們將在下面新增 __getnewargs__。）

有幾種方法可以提供 __reduce__ 功能：類可以實現 __reduce__ 方法或 __reduce_ex__ 方法（見下一節），或者可以在 copy_reg 中宣告一個 reduce 函式（copy_reg.dispatch_table 將類對映到函式）。雖然返回值被完全相同地解釋，我們將它們統稱為 __reduce__。

重要提示： pickling 舊式類例項時，不會查詢 __reduce__ 或 __reduce_ex__ 方法，也不會在 copy_reg 分派表中查詢 reduce 函式，因此舊式類無法在此意義上提供 __reduce__ 功能。舊式類必須使用 __getinitargs__ 和/或 __getstate__ 來自定義 pickling。這些將在下面介紹。

__reduce__ 必須返回一個字串或一個元組。如果返回一個字串，則表示一個物件，其狀態不被 pickling，而是引用一個同等物件，該物件透過名稱進行引用。令人驚訝的是，__reduce__ 返回的字串應該是物件的本地名稱（相對於其模組）；pickle 模組會搜尋模組名稱空間來確定物件的模組。

本節其餘部分將討論 __reduce__ 返回的元組。它是一個可變長度元組，長度為 2 到 5。前兩個項（函式和引數）是必需的。其餘項是可選的，可以從末尾省略；為可選項的值提供 None 與省略它們的效果相同。最後兩項是本 PEP 中新增的。各項的順序是：

Unpickling 呼叫 function(*arguments) 來建立一個初始物件，下面稱為 *obj*。如果省略了其餘項，則 unpickling 對此物件的處理就結束了，*obj* 就是結果。否則，*obj* 在 unpickling 時會根據指定的每一項進行修改，如下所示。

obj.__dict__.update(state)

for k, v in state.items():
    setattr(obj, k, v)

注意：在 Python 2.2 及更早版本中，使用 cPickle 時，如果狀態存在，即使它是 None 也會被 pickling；避免 __setstate__ 呼叫唯一安全的方法是從 __reduce__ 返回一個二元元組。（但 pickle.py 不會 pickling None 狀態。）在 Python 2.3 中，當 __reduce__ 在 pickling 時返回值為 None 的狀態時，__setstate__ 在 unpickling 時永遠不會被呼叫。

一個 __reduce__ 實現，如果需要同時在 Python 2.2 和 Python 2.3 下工作，可以檢查變數 pickle.format_version 來確定是使用 *listitems* 和 *dictitems* 功能。如果此值 >= "2.0"，則支援它們。如果不支援，則任何列表或字典項都應以某種方式包含在“state”返回值中，並且 __setstate__ 方法應準備好接受列表或字典項作為狀態的一部分（如何實現取決於應用程式）。

__reduce_ex__ API

有時瞭解協議版本對於實現 __reduce__ 很有用。這可以透過實現一個名為 __reduce_ex__ 的方法而不是 __reduce__ 來完成。__reduce_ex__ 存在時，優先於 __reduce__ 呼叫（為向後相容，您仍然可以提供 __reduce__）。__reduce_ex__ 方法將使用一個整數引數呼叫，即協議版本。

‘object’類同時實現了 __reduce__ 和 __reduce_ex__；然而，如果子類覆蓋了 __reduce__ 但沒有覆蓋 __reduce_ex__，__reduce_ex__ 實現會檢測到這種情況並呼叫 __reduce__。

在沒有 __reduce__ 實現的情況下自定義 pickling

如果對於某個類沒有可用的 __reduce__ 實現，則需要分別考慮三種情況，因為它們的處理方式不同：

1. 舊式類例項，所有協議
2. 新式類例項，協議 0 和 1
3. 新式類例項，協議 2

用 C 實現的型別被視為新式類。但是，除了常見的內建型別外，這些型別需要提供 __reduce__ 實現才能使用協議 0 或 1 進行 pickling。協議 2 還支援使用 __getnewargs__、__getstate__ 和 __setstate__ 的內建型別。

basestate = B(obj)

obj = B.__new__(D, basestate)
B.__init__(obj, basestate)

obj = C.__new__(C, *args)

__newobj__ unpickling 函式

當 __reduce__ 返回的 unpickling 函式（返回元組的第一個元素）名稱為 __newobj__ 時，對於 pickle 協議 2 會發生特殊情況。一個名為 __newobj__ 的 unpickling 函式假定具有以下語義：

def __newobj__(cls, *args):
    return cls.__new__(cls, *args)

pickle 協議 2 特殊處理一個具有此名稱的 unpickling 函式，併發出一個 pickling 操作碼，該操作碼接收‘cls’和‘args’，將返回 cls.__new__(cls, *args)，而無需 pickling __newobj__ 的引用（這是協議 2 為新式類例項在沒有 __reduce__ 實現時使用的相同 pickling 操作碼）。這也是協議 2 pickle 比舊式 pickle 小得多的主要原因。當然，pickling 程式碼無法驗證名為 __newobj__ 的函式是否具有預期的語義。如果您使用的 unpickling 函式名為 __newobj__ 但返回不同的內容，那麼您將自食其果。

在 Python 2.2 下使用此功能是安全的；__newobj__ 的推薦實現中沒有任何內容依賴於 Python 2.3。

擴充套件登錄檔

協議 2 支援一種新的機制來減小 pickle 的大小。

當 pickling 類例項（舊式或新式）時，類的完整名稱（包括包名稱的模組名稱和類名稱）將被包含在 pickle 中。特別對於生成許多小型 pickle 的應用程式來說，這會產生大量開銷，並且必須在每個 pickle 中重複。對於大型 pickle，在使用協議 1 時，對同一類名的重複引用會使用“memo”功能進行壓縮；但每個類名必須在每個 pickle 中至少完整拼寫一次，這會導致小型 pickle 的開銷很大。

擴充套件登錄檔允許用小的整數來表示最常用的名稱，這些整數的 pickling 非常高效：程式碼範圍在 1-255 的擴充套件碼只需要兩個位元組（包括操作碼），範圍在 256-65535 的擴充套件碼只需要三個位元組（包括操作碼）。

pickle 協議的設計目標之一是使 pickle “無上下文”：只要您安裝了包含 pickle 所引用的類的模組，就可以 unpickle 它，而無需提前匯入任何這些類。

無限制地使用擴充套件碼可能會危及 pickle 的這一理想屬性。因此，擴充套件碼的主要用途保留給將由某個標準化機構標準化的編碼集。鑑於這是 Python，標準化機構是 PSF。PSF 將不時地決定一個對映表，將擴充套件碼對映到類名（或偶爾的其他全域性物件名稱；函式也符合資格）。此表將包含在下一個 Python 釋出版本中。

但是，對於某些應用程式，例如 Zope，無上下文 pickle 不是必需的，並且等待 PSF 標準化某些編碼可能不切實際。為這類應用程式提供了兩種解決方案。

首先，保留了一些擴充套件碼範圍供私人使用。任何應用程式都可以在這些範圍內註冊編碼。在這些範圍內交換使用編碼的兩個應用程式需要某種帶外機制來就擴充套件碼與名稱之間的對映達成一致。

其次，一些大型 Python 專案（例如 Zope）可以被分配一個“私人使用”範圍之外的擴充套件碼範圍，它們可以根據需要進行分配。

擴充套件登錄檔定義為擴充套件碼與名稱之間的對映。當 unpickle 一個擴充套件碼時，它最終會產生一個物件，但這個物件是透過將名稱解釋為模組名稱後跟類（或函式）名稱來獲取的。名稱到物件的對映被快取。某些名稱可能無法匯入；只要沒有包含對這些名稱引用的 pickle 需要 unpickle，這就不成問題。（對於協議 0 或 1 的 pickle 中的這些名稱的直接引用，已經存在同樣的問題。）

以下是擬議的擴充套件碼範圍的初始分配：

*MAX* 代表 2147483647，或 2**31-1。這是當前定義的協議的硬限制。

目前，還沒有分配任何特定的擴充套件碼。

copy 模組

傳統上，copy 模組支援 pickling API 的擴充套件子集，用於自定義 copy() 和 deepcopy() 操作。

特別是，除了檢查 __copy__ 或 __deepcopy__ 方法外，copy() 和 deepcopy() 始終查詢 __reduce__，對於舊式類，則查詢 __getinitargs__、__getstate__ 和 __setstate__。

在 Python 2.2 中，從‘object’繼承的預設 __reduce__ 實現使得複製簡單的新式類成為可能，但 slots 和各種其他特殊情況未被涵蓋。

在 Python 2.3 中，對 copy 模組進行了幾項更改：

• __reduce_ex__ 被支援（並且始終使用 2 作為協議版本引數呼叫）。
• 支援 __reduce__ 的四引數和五引數返回值。
• 在查詢 __reduce__ 方法之前，會像 pickling 一樣查詢 copy_reg.dispatch_table。
• 當 __reduce__ 方法從 object 繼承時，它會被（無條件地）替換為一個更好的實現，該實現使用與 pickle 協議 2 相同的 API：__getnewargs__、__getstate__ 和 __setstate__，並處理 list 和 dict 子類，以及處理 slots。

作為後一項更改的結果，某些在 Python 2.2 下可以複製的新式類在 Python 2.3 下將不再可複製。（這些類也無法使用 pickle 協議 2 進行 pickling。）此類的一個最小示例：

class C(object):
    def __new__(cls, a):
        return object.__new__(cls)

問題僅在覆蓋 __new__ 並且除了類引數外至少有一個強制引數時才會發生。

為了解決這個問題，應新增一個 __getnewargs__ 方法，該方法返回適當的引數元組（不包括類）。

Pickling Python 長整數

在協議 0 和 1 中，pickling 和 unpickling Python 長整數所需時間與數字位數成二次方關係。在協議 2 下，新的操作碼支援長整數的線性時間 pickling 和 unpickling。

Pickling 布林值

協議 2 引入了新的操作碼，用於直接 pickling True 和 False。在協議 0 和 1 下，布林值被 pickling 為整數，利用 pickle 中整數表示的技巧，以便 unpickler 可以識別出意圖是布林值。該技巧每個 pickling 的布林值消耗 4 位元組。新的布林操作碼每個布林值消耗 1 位元組。

Pickling 小元組

協議 2 引入了新的操作碼，用於更緊湊地 pickling 長度為 1、2 和 3 的元組。協議 1 以前引入了一個操作碼，用於更緊湊地 pickling 空元組。

協議識別

協議 2 引入了一個新的操作碼，所有協議 2 pickle 都以此開頭，指示該 pickle 是協議 2。因此，在舊版本 Python 中嘗試 unpickle 協議 2 pickle 將立即引發“未知操作碼”異常。

Pickling 大列表和字典

協議 1 將大列表和字典“一次性”pickling，從而最大程度地減小 pickle 大小，但這要求 unpickling 建立一個與被 unpickling 物件一樣大的臨時物件。協議 2 的部分更改將大列表和字典分解為每個不超過 1000 個元素的小塊，這樣 unpickling 就不必建立大於容納 1000 個元素所需大小的臨時物件。然而，這並非協議 2 的一部分：生成的操作碼仍屬於協議 1。__reduce__ 實現返回可選的新列表項或字典項迭代器也受益於此 unpickling 臨時空間最佳化。

版權

本文件已置於公共領域。