marshal — 內部 Python 物件序列化

此模組包含可以讀寫二進位制格式的 Python 值的函式。該格式是 Python 特有的，但與機器架構問題無關（例如，您可以將 Python 值寫入 PC 上的檔案，將檔案傳輸到 Mac，然後在那裡讀取回來）。該格式的詳細資訊是有意未公開的；它可能會在 Python 版本之間更改（儘管很少發生）。[1]

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

警告

marshal 模組並非旨在安全地抵禦錯誤或惡意構造的資料。切勿反序列化來自不受信任或未經身份驗證的來源的資料。

並非所有 Python 物件型別都受支援；一般來說，只有其值獨立於特定 Python 呼叫的物件才能被此模組寫入和讀取。支援以下型別：布林值、整數、浮點數、複數、字串、位元組、位元組陣列、元組、列表、集合、凍結集合、字典和程式碼物件（如果 allow_code 為 true），其中應理解元組、列表、集合、凍結集合和字典只有在其中包含的值本身受支援的情況下才受支援。單例 None、Ellipsis 和 StopIteration 也可以被 marshal 和 unmarshal。對於低於 3 的格式版本，不能寫入遞迴列表、集合和字典（請參見下文）。

有一些讀取/寫入檔案的函式以及處理類似位元組物件的函式。

該模組定義了這些函式

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

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

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

version 引數指示 dump 應使用的資料格式（請參見下文）。

使用引數 value、version 引發 審計事件 marshal.dumps。

在 3.13 版本中更改：添加了 allow_code 引數。

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

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

引發沒有引數的 審計事件 marshal.load。

注意

如果使用 dump() 封送了包含不受支援型別的物件，則 load() 將用 None 替換無法反序列化的型別。

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

在 3.13 版本中更改：添加了 allow_code 引數。

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

返回透過 dump(value, file) 寫入檔案的位元組物件。該值必須是受支援的型別。如果該值具有（或包含具有）不受支援的型別，則引發 ValueError 異常。程式碼物件 僅在 allow_code 為 true 時才受支援。

version 引數指示 dumps 應使用的資料格式（請參見下文）。

使用引數 value、version 引發 審計事件 marshal.dumps。

在 3.13 版本中更改：添加了 allow_code 引數。

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

將bytes-like object轉換為一個值。 如果找不到有效的值，則引發 EOFError、 ValueError 或 TypeError。 僅當 allow_code 為 true 時，才支援程式碼物件。 輸入中多餘的位元組將被忽略。

使用引數 bytes 引發 審計事件 marshal.loads。

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

在 3.13 版本中更改：添加了 allow_code 引數。

此外，還定義了以下常量

marshal.version

指示模組使用的格式。 版本 0 是歷史格式，版本 1 共享 interned 字串，版本 2 對浮點數使用二進位制格式。 版本 3 增加了對物件例項化和遞迴的支援。 當前版本是 4。

腳註