"marshal" --- 内部 Python 物件序列化
************************************

======================================================================

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

This is not a general "persistence" module.  For general persistence
and transfer of Python objects through RPC calls, see the modules
"pickle" and "shelve".  The "marshal" module exists mainly to support
reading and writing the "pseudo-compiled" code for Python modules of
".pyc" files. Therefore, the Python maintainers reserve the right to
modify the marshal format in 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 and de-serializing Python
objects, use the "pickle" module instead -- the performance is
comparable, version independence is guaranteed, and pickle supports a
substantially wider range of objects than marshal.

警告:

  "marshal" module 對於錯誤或惡意構建的資料來說是不安全的。永遠不要
  unmarshal 來自不受信任的或來源未經驗證的資料。

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: booleans, integers, floating-point numbers, complex
numbers, strings, bytes, bytearrays, tuples, lists, sets, frozensets,
dictionaries, and code objects (if *allow_code* is true), where it
should be understood that tuples, lists, sets, frozensets and
dictionaries are only supported as long as the values contained
therein are themselves supported.  The singletons "None", "Ellipsis"
and "StopIteration" can also be marshalled and unmarshalled. For
format *version* lower than 3, recursive lists, sets and dictionaries
cannot be written (see below).

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

這個 module 定義了以下函式：

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

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

   If the value has (or contains an object that has) an unsupported
   type, a "ValueError" exception is raised --- but garbage data will
   also be written to the file.  The object will not be properly read
   back by "load()". Code objects are only supported if *allow_code*
   is true.

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

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

   在 3.13 版的變更: Added the *allow_code* parameter.

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

   Read one value from the open file and return it.  If no valid value
   is read (e.g. because the data has a different Python version's
   incompatible marshal format), raise "EOFError", "ValueError" or
   "TypeError". Code objects are only supported if *allow_code* is
   true. The file must be a readable *binary file*.

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

   備註:

     如果透過 "dump()" marshal 了一個包含不支援型別的物件，"load()" 會
     將不可 marshal 的型別替換為 "None"。

   在 3.10 版的變更: 使用此呼叫為每個程式碼物件引發一個 "code.__new__"
   稽核事件。現在它會為整個載入操作引發單個 "marshal.load" 事件。

   在 3.13 版的變更: Added the *allow_code* parameter.

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

   Return the bytes object that would be written to a file by
   "dump(value, file)".  The value must be a supported type.  Raise a
   "ValueError" exception if value has (or contains an object that
   has) an unsupported type. Code objects are only supported if
   *allow_code* is true.

   *version* 引數指明 "dumps" 應當使用的資料型別（見下文）。

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

   在 3.13 版的變更: Added the *allow_code* parameter.

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

   Convert the *bytes-like object* to a value.  If no valid value is
   found, raise "EOFError", "ValueError" or "TypeError". Code objects
   are only supported if *allow_code* is true. Extra bytes in the
   input are ignored.

   引發一個附帶引數 "bytes" 的稽核事件 "marshal.loads"。

   在 3.10 版的變更: 使用此呼叫為每個程式碼物件引發一個 "code.__new__"
   稽核事件。現在它會為整個載入操作引發單個 "marshal.loads" 事件。

   在 3.13 版的變更: Added the *allow_code* parameter.

此外，還定義了以下常數：

marshal.version

   表示 module 所使用的格式。第 0 版為歷史格式，第 1 版共享了駐留字串
   (interned string)，第 2 版對浮點數使用二進位制格式。第 3 版添加了對
   於物件實例化和遞迴的支援。目前使用的是第 4 版。

-[ 註解 ]-

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