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

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

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

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

Not all Python object types are supported; in general, only objects whose valueis independent from a particular invocation of Python can be written and read bythis module. The following types are supported:

• Numeric types:int,bool,float,complex.

• Strings (str) andbytes.Bytes-like objects likebytearray aremarshalled asbytes.

• Containers:tuple,list,set,frozenset,and (sinceversion 5),slice.It should be understood that these are supported only if the values containedtherein are themselves supported.Recursive containers are supported sinceversion 3.

• The singletonsNone,Ellipsis andStopIteration.

• code objects, ifallow_code is true. See note above aboutversion dependence.

這個模組定義了以下函式：

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

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

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

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

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

在 3.13 版的變更:新增allow_code 參數。

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

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

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

備註

如果透過dump() marshal 了一個包含不支援型別的物件，load() 會將不可 marshal 的型別替換為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 的稽核事件 (auditing event)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 版為歷史上第一版本；後續版本會新增功能。當引入新版本時，它通常會成為預設版本。

版本	Available since	New features
1	Python 2.4	共享駐留字串
2	Python 2.5	Binary representation of floats
3	Python 3.4	Support for object instancing and recursion
4	Python 3.4	Efficient representation of short strings
5	Python 3.14	Support forslice objects

註解

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