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

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

This is not a general "persistence" module. For general persistence andtransfer of Python objects through RPC calls, see the modulespickle andshelve. Themarshal module exists mainly to support reading andwriting the "pseudo-compiled" code for Python modules of.pyc files.Therefore, the Python maintainers reserve the right to modify the marshal formatin backward incompatible ways should the need arise.The format of code objects is not compatible between Python versions,even if the version of the format is the same.De-serializing a code object in the incorrect Python version has undefined behavior.If you're serializing andde-serializing Python objects, use thepickle module instead -- theperformance is comparable, version independence is guaranteed, and picklesupports a substantially wider range of objects than 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"。