"marshal" --- 内部使用向けの Python オブジェクト直列化
******************************************************

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

このモジュールは、Python の値をバイナリ形式で読み書きする関数を提供し
ます。 この形式は Python 固有ですが、マシンのアーキテクチャには依存し
ません (例えば PC で Python の値をファイルに書き込み、そのファイルを
Mac に転送して読み戻せます)。 形式の詳細は意図的に文書化されていません
。 Python のバージョンによって変更される場合があります (ただし、実際に
はまれです)。 [1]

これは汎用の「永続化」モジュールではありません。 Python オブジェクトの
汎用的な永続化や RPC 呼び出しによる転送には、"pickle" と "shelve" を参
照してください。 "marshal" モジュールは主に、Python モジュールの「擬似
コンパイル済み」コードを ".pyc" ファイルで読み書きするために存在します
。 そのため、Python のメンテナーは、必要に応じて後方互換性のない形で
marshal 形式を変更する権利を留保します。 形式のバージョンが同じでも、
コードオブジェクトの形式は Python のバージョン間で互換性がありません。
誤った Python バージョンでコードオブジェクトを復元した場合の動作は未定
義です。 Python オブジェクトを直列化したり復元したりするには、代わりに
"pickle" モジュールを使ってください。 性能は同程度で、バージョンに依存
しないことが保証され、marshal よりはるかに幅広いオブジェクトをサポート
します。

警告:

  "marshal" モジュールは、誤ったデータや悪意を持って作成されたデータに
  対して安全であるようには設計されていません。 信頼できない、または認
  証されていない送信元から受け取ったデータを決して復元しないでください
  。

bytes-like オブジェクトを操作する関数と同様に、ファイルの読み書きを行
う関数が提供されています。

すべての Python オブジェクト型をサポートしているわけではありません。
一般に、このモジュールで読み書きできるのは、値が Python の特定の実行に
依存しないオブジェクトだけです。 以下の型をサポートします。

* 数値型: "int"、"bool"、"float"、"complex"。

* 文字列 ("str") と "bytes"。 "bytearray" のような *bytes-like object*
  は、"bytes" として直列化されます。

* コンテナ: "tuple"、"list"、"dict"、"frozendict" ("version" 6 以降)、
  "set"、"frozenset"、"slice" ("version" 5 以降)。 これらは、格納する
  値もサポートされている場合にのみサポートされます。 再帰的なコンテナ
  は "version" 3 以降でサポートされています。

* シングルトンの "None"、"Ellipsis"、"StopIteration"。

* *allow_code* が真の場合の "code" オブジェクト。 バージョンへの依存に
  ついては、上の注意書きを参照してください。

バージョン 3.4 で変更:

* 再帰的なリスト、集合、辞書の直列化をサポートする形式バージョン 3 を
  追加しました。

* 短い文字列を効率的に表現する形式バージョン 4 を追加しました。

バージョン 3.14 で変更: スライスの直列化を可能にする形式バージョン 5
を追加しました。

バージョン 3.15 で変更: "frozendict" の直列化を可能にする形式バージョ
ン 6 を追加しました。

このモジュールでは、以下の関数が定義されています。

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

   開かれたファイルに値を書き込みます。値はサポートされている型でなく
   てはなりません。file は書き込み可能な  *バイナリファイル* である必
   要があります。

   値がサポートされていない型であるか、その型のオブジェクトを含む場合
   、"ValueError" を送出しますが、不正なデータもファイルに書き込まれま
   す。 このオブジェクトは "load()" で正しく読み戻せません。 コードオ
   ブジェクト は *allow_code* が真の場合にのみサポートされます。

   *version* 引数は "dump" が使用するデータフォーマットを指定します (
   下記を参照してください)。

   引数 "value", "version" を指定して 監査イベント "marshal.dumps" を
   送出します。

   バージョン 3.13 で変更: *allow_code* 引数を追加しました。

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

   開かれたファイルから値を 1 つ読み取り、返します。 有効な値を読み取
   れない場合 (例えば、別の Python バージョンの互換性のない marshal 形
   式である場合)、"EOFError"、"ValueError"、"TypeError" のいずれかを送
   出します。 コードオブジェクト は *allow_code* が真の場合にのみサポ
   ートされます。 ファイルは読み取り可能な *バイナリファイル* でなけれ
   ばなりません。

   引数無しで 監査イベント "marshal.load" を送出します。

   注釈:

     サポートされていない型を含むオブジェクトが "dump()" で整列化され
     ている場合、 "load()" は整列化不能な値を "None" で置き換えます。

   バージョン 3.10 で変更: 以前はコードオブジェクトごとに
   "code.__new__" 監査イベントを発生させていました。 現在は読み込み操
   作全体に対して "marshal.load" イベントを 1 回発生させます。

   バージョン 3.13 で変更: *allow_code* 引数を追加しました。

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

   "dump(value, file)" でファイルに書き込まれる内容を bytes オブジェク
   トとして返します。 値はサポートされている型でなければなりません。
   値がサポートされていない型であるか、その型のオブジェクトを含む場合
   、"ValueError" を送出します。 コードオブジェクト は *allow_code* が
   真の場合にのみサポートされます。

   *version* 引数は "dumps" が使用するデータフォーマットを指定します (
   下記を参照してください)。

   引数 "value", "version" を指定して 監査イベント "marshal.dumps" を
   送出します。

   バージョン 3.13 で変更: *allow_code* 引数を追加しました。

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

   *bytes-like object* を値に変換します。 有効な値が見つからなければ、
   "EOFError"、"ValueError"、"TypeError" のいずれかを送出します。 コー
   ドオブジェクト は *allow_code* が真の場合にのみサポートされます。
   入力の余分なバイトは無視されます。

   引数 "bytes" を指定して 監査イベント "marshal.loads" を送出します。

   バージョン 3.10 で変更: 以前はコードオブジェクトごとに
   "code.__new__" 監査イベントを発生させていました。 現在は読み込み操
   作全体に対して "marshal.loads" イベントを 1 回発生させます。

   バージョン 3.13 で変更: *allow_code* 引数を追加しました。

これに加えて、以下の定数が定義されています:

marshal.version

   モジュールが使う形式を示します。 バージョン 0 が最初のバージョンで
   、以降のバージョンでは新しい機能が追加されています。 通常、新しいバ
   ージョンは導入と同時にデフォルトになります。

   +---------+-----------------+------------------------------------------------------+
   | Version | 利用可能になっ  | 新しい機能                                           |
   |         | たバージョン    |                                                      |
   |=========|=================|======================================================|
   | 1       | Python 2.4      | インターン化された文字列の共有                       |
   +---------+-----------------+------------------------------------------------------+
   | 2       | Python 2.5      | 浮動小数点数のバイナリ表現                           |
   +---------+-----------------+------------------------------------------------------+
   | 3       | Python 3.4      | オブジェクトの共有と再帰のサポート                   |
   +---------+-----------------+------------------------------------------------------+
   | 4       | Python 3.4      | 短い文字列の効率的な表現                             |
   +---------+-----------------+------------------------------------------------------+
   | 5       | Python 3.14     | "slice" オブジェクトのサポート                       |
   +---------+-----------------+------------------------------------------------------+
   | 6       | Python 3.15     | "frozendict" オブジェクトのサポート                  |
   +---------+-----------------+------------------------------------------------------+

-[ 脚注 ]-

[1] このモジュールの名前は (特に) Modula-3 の設計者の間で使われていた
    用語の一つに由来しています。彼らはデータを自己充足的な形式で輸送す
    る操作に "整列化 (marshalling)" という用語を使いました。厳密に言え
    ば、"整列させる (to marshal)" とは、あるデータを (例えば RPC バッ
    ファのように) 内部表現形式から外部表現形式に変換することを意味し、
    "非整列化 (unmarshalling)" とはその逆を意味します。
