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 更多樣的物件。
警告
marshal
模組對於錯誤或惡意構建的資料來說是不安全的。永遠不要 unmarshal 來自不受信任的或來源未經驗證的資料。
不是所有 Python 物件型別都有支援;一般來說,此模組只能寫入和讀取不依賴於特定 Python 呼叫 (invocation) 的物件。下列型別是有支援的:布林 (boolean)、整數、浮點數 (floating-point number)、複數、字串、位元組串 (bytes)、位元組陣列 (bytearray)、元組 (tuple)、list、集合 (set)、凍結集合 (frozenset)、dictionary 和程式碼物件(如 allow_code 為 true),需要了解的一點是元組、list、集合、凍結集合和 dictionary 只在其所包含的值也屬於這些型別時才會支援。單例 (singleton) 物件 None
、Ellipsis
和 StopIteration
也可以被 marshal 和 unmarshal。對於 version 低於 3 的格式,遞迴 list、集合和 dictionary 無法被寫入(見下文)。
有些函式可以讀/寫檔案,還有些函式可以操作類位元組串物件 (bytes-like object)。
這個模組定義了以下函式:
- 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
。在 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 版為歷史格式,第 1 版共享了駐留字串 (interned string),第 2 版對浮點數使用二進位制格式。第 3 版添加了對於物件實例化和遞迴的支援。目前使用的是第 4 版。
註解