"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 來自不受信任的或來源未經驗證的資料。

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

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

* Numeric types: "int", "bool", "float", "complex".

* Strings ("str") and "bytes". *Bytes-like objects* like "bytearray"
  are marshalled as "bytes".

* Containers: "tuple", "list", "set", "frozenset", and (since
  "version" 5), "slice". It should be understood that these are
  supported only if the values contained therein are themselves
  supported. Recursive containers are supported since "version" 3.

* The singletons "None", "Ellipsis" and "StopIteration".

* "code" objects, if *allow_code* is true. See note above about
  version dependence.

在 3.4 版的變更:

* Added format version 3, which supports marshalling recursive lists,
  sets and dictionaries.

* Added format version 4, which supports efficient representations of
  short strings.

在 3.14 版的變更: Added format version 5, which allows marshalling
slices.

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

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 for "slice" objects                          |
   +---------+-----------------+------------------------------------------------------+

-[ 註解 ]-

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