marshal --- Python 內部物件序列化

此模組包含的函式可以讀寫二進位制格式的 Python 值。該格式是 Python 特有的，但與機器架構無關（例如，你可以在 PC 上將一個 Python 值寫入檔案，將檔案傳輸到 Mac，然後再在那裡讀回）。此格式的細節有意不作文件說明；它可能在不同 Python 版本之間發生變化（儘管很少這樣做）。[1]

這不是一個通用的“持久化”模組。對於通用的持久化和透過 RPC 呼叫傳輸 Python 物件，請參閱 pickle 和 shelve 模組。marshal 模組的存在主要是為了支援讀寫 Python 模組的 .pyc 檔案中的“偽編譯”程式碼。因此，Python 維護者保留在需要時以向後不相容的方式修改 marshal 格式的權利。程式碼物件的格式在 Python 版本之間不相容，即使格式的版本號相同。在不正確的 Python 版本中反序列化程式碼物件的行為是未定義的。如果你要序列化和反序列化 Python 物件，請改用 pickle 模組——效能相當，保證版本獨立性，並且 pickle 支援的物件範圍比 marshal 廣泛得多。

警告

警告：marshal 模組不具備抵禦錯誤或惡意構造的資料的安全性。切勿 unmarshal 來自不受信任或未經身份驗證來源的資料。

該模組提供了讀寫檔案的函式以及操作類位元組物件的函式。

並非所有 Python 物件型別都受支援；通常，只有那些其值與 Python 的特定呼叫無關的物件才能被此模組寫入和讀取。支援以下型別：

在 3.4 版本發生變更

  • 增加了格式版本 3，支援序列化遞迴的列表、集合和字典。

  • 添加了格式版本 4，支援短字串的高效表示。

在 3.14 版本發生變更: 添加了格式版本 5，允許序列化切片。

該模組定義了以下函式

marshal.dump(value, file, version=version, /, *, allow_code=True)

將值寫入開啟的檔案中。該值必須是受支援的型別。檔案必須是可寫的二進位制檔案。

如果值包含（或其內部包含的物件包含）不支援的型別，則會引發 ValueError 異常——但垃圾資料也會被寫入檔案。該物件將無法透過 load() 正確讀回。程式碼物件僅在 *allow_code* 為真時受支援。

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

引發一個附帶引數 value, version 的審計事件 marshal.dumps。

在 3.13 版本發生變更: 添加了 *allow_code* 形參。

marshal.load(file, /, *, allow_code=True)

從開啟的檔案中讀取一個值並返回。如果未讀取到有效值（例如，因為資料是不同 Python 版本的不相容 marshal 格式），則引發 EOFError、ValueError 或 TypeError。程式碼物件僅在 *allow_code* 為真時受支援。檔案必須是可讀的二進位制檔案。

引發一個不帶引數的審計事件 marshal.load。

備註

如果一個包含不支援型別的物件被 dump() 序列化，load() 將會用 None 來替代那個無法被 unmarshal 的型別。

在 3.10 版本發生變更: 此呼叫過去會為每個程式碼物件引發一個 code.__new__ 審計事件。現在它會為整個載入操作引發一個 marshal.load 事件。

在 3.13 版本發生變更: 添加了 *allow_code* 形參。

marshal.dumps(value, version=version, /, *, allow_code=True)

返回 dump(value, file) 將會寫入檔案的位元組物件。值必須是受支援的型別。如果值包含（或其內部包含的物件包含）不支援的型別，則引發 ValueError 異常。程式碼物件僅在 *allow_code* 為真時受支援。

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

引發一個附帶引數 value, version 的審計事件 marshal.dumps。

在 3.13 版本發生變更: 添加了 *allow_code* 形參。

marshal.loads(bytes, /, *, allow_code=True)

將類位元組物件轉換為一個值。如果找不到有效值，則引發 EOFError、ValueError 或 TypeError。程式碼物件僅在 *allow_code* 為真時受支援。輸入中多餘的位元組將被忽略。

引發一個附帶引數 bytes 的審計事件 marshal.loads。

在 3.10 版本發生變更: 此呼叫過去會為每個程式碼物件引發一個 code.__new__ 審計事件。現在它會為整個載入操作引發一個 marshal.loads 事件。

在 3.13 版本發生變更: 添加了 *allow_code* 形參。

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

marshal.version

指示模組使用的格式。版本 0 是歷史上的第一個版本；後續版本增加了新功能。通常，新版本在引入時成為預設版本。

版本

始於

新特性

1

Python 2.4

共享駐留字串

2

Python 2.5

浮點數的二進位制表示

3

Python 3.4

支援物件例項化和遞迴

4

Python 3.4

短字串的高效表示

5

Python 3.14

支援 slice 物件

腳註