# `marshal` --- 内部 Python 物件序列化

此 module（模組）包含一個能以二進位制格式來讀寫 Python 值的函式。這種格式是 Python 專屬但獨立於機器架構的（例如，你可以在一臺 PC 上寫入某個 Python 值，再將檔案傳到一臺 Mac 上並在那裡讀取它）。這種格式的細節是有意地不在文件上說明的；它可能在不同 Python 版本中被改變（雖然這種情況極少發生）。[1]

這不是一個通用「持續性 (persistence)」module 。關於通用持續性以及透過 RPC 呼叫傳遞 Python 物件，請參閱 `pickle` 和 `shelve` 等 module 。`marshal` module 主要是為了支援用來讀寫「偽編譯 (pseudo-compiled)」 `.pyc` 檔案的 Python module。因此，Python 維護者保留了在必要時以不向後相容的方式修改 marshal 格式的權利。如果你要序列化和反序列化 Python 物件，請改用 `pickle` module -- 其執行效率相當、有保證版本獨立性，且實質上 pickle 還支援比 marshal 更多樣的物件。

警告

`marshal` module 對於錯誤或惡意構建的資料來說是不安全的。永遠不要 unmarshal 來自不受信任的或來源未經驗證的資料。

不是所有 Python 物件型別都有支援；一般來說，此 module 只能寫入和讀取不依賴於特定 Python 調用 (invocation) 的物件。下列型別是有支援的：布林 (boolean)、整數、浮點數 (floating-point number)、複數、字串、位元組串 (bytes)、位元組陣列 (bytearray)、元組 (tuple)、list、集合 (set)、凍結集合 (frozenset)、dictionary 和程式碼物件，需要了解的一點是元組、list、集合、凍結集合和 dictionary 只在其所包含的值也屬於這些型別時才會支援。單例 (singleton) 物件 `None`、`Ellipsis` 和 `StopIteration` 也可以被 marshal 和 unmarshal。對於 version 低於 3 的格式，遞迴 list、集合和 dictionary 無法被寫入（見下文）。

有些函式可以讀/寫檔案，還有些函式可以操作類位元組串物件 (bytes-like object)。

這個 module 定義了以下函式：

marshal.dump(value, file[, version])

  將值寫入被開啟的檔案。值必須為受支援的型別，檔案必須為可寫入的 binary file。

  如果值具有（或其所包含的物件具有）不支援的型別，則會引發 `ValueError` 例外 --- 但是垃圾資料 (garbage data) 也將寫入檔案，物件也無法正確地透過 `load()` 重新讀取。

  version 引數指明 `dump` 應該使用的資料格式（見下文）。

  引發一個附帶引數 `value` 與 `version` 的稽核事件 (auditing event) `marshal.dumps`。

marshal.load(file)

  從開啟的檔案讀取一個值並回傳。如果讀不到有效的值（例如，由於資料為不同 Python 版本的不相容 marshal 格式），則會引發 `EOFError`、`ValueError` 或 `TypeError`。檔案必須為可讀取的 binary file。

  引發一個沒有附帶引數的稽核事件 `marshal.load`。

  備註

  如果透過 `dump()` marshal 了一個包含不支援型別的物件，`load()` 會將不可 marshal 的型別替換為 `None`。

  在 3.10 版的變更: 使用此呼叫為每個程式碼物件引發一個 `code.__new__` 稽核事件。現在它會為整個載入操作引發單個 `marshal.load` 事件。

marshal.dumps(value[, version])

  回傳將透過 `dump(value, file)` 來被寫入一個檔案的位元組串物件，其值必須是有支援的型別，如果值（或其包含的任一物件）為不支援的型別則會引發 `ValueError`。

  version 引數指明 `dumps` 應當使用的資料型別（見下文）。

  引發一個附帶引數 `value` 與 `version` 的稽核事件 (auditing event) `marshal.dumps`。

marshal.loads(bytes)

  將 bytes-like object 轉換為一個值。如果找不到有效的值，則會引發 `EOFError`、`ValueError` 或 `TypeError`。輸入中額外的位元組串會被忽略。

  引發一個附帶引數 `bytes` 的稽核事件 `marshal.loads`。

  在 3.10 版的變更: 使用此呼叫為每個程式碼物件引發一個 `code.__new__` 稽核事件。現在它會為整個載入操作引發單個 `marshal.loads` 事件。

此外，還定義了以下常數：

marshal.version

  表示 module 所使用的格式。第 0 版為歷史格式，第 1 版共享了駐留字串 (interned string)，第 2 版對浮點數使用二進位制格式。第 3 版添加了對於物件實例化和遞迴的支援。目前使用的是第 4 版。

註解

[1]

此 module 的名稱來源於 Modula-3 (及其他語言) 的設計者所使用的術語，他們使用 "marshal" 來表示自包含 (self-contained) 形式資料的傳輸。嚴格來說，將資料從內部形式轉換為外部形式 (例如用於 RPC 緩衝區) 稱為 "marshal"，而其反向過程則稱為 "unmarshal"。