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

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

このモジュールには Python 値をバイナリ形式で読み書きできるような関数が
含まれています。このバイナリ形式は Python 特有のものですが、マシンアー
キテクチャ非依存のものです (つまり、Python の値を PC 上でファイルに書
き込み、Sun に転送し、そこで読み戻すことができます)。バイナリ形式の詳
細は意図的にドキュメント化されていません; この形式は (稀にしかないこと
ですが) Python のバージョン間で変更される可能性があるからです。[1]

このモジュールは汎用の "永続化 (persistence)" モジュールではありません
。汎用的な永続化や、RPC 呼び出しを通じた Python オブジェクトの転送につ
いては、モジュール "pickle" および "shelve" を参照してください。
"marshal" モジュールは主に、 "擬似コンパイルされた (pseudo-compiled)"
コードの ".pyc" ファイルへの読み書きをサポートするために存在します。し
たがって、 Python のメンテナンス担当者は、必要が生じれば marshal 形式
を後方互換性のないものに変更する権利を有しています。 Python オブジェク
トを直列化 (シリアライズ) および非直列化 (デシリアライズ) する場合には
、 "pickle" モジュールを使ってください。 "pickle" は速度は同等で、バー
ジョン間の互換性が保証されていて、 marshal より広範囲のオブジェクトを
サポートしています。

警告:

  "marshal" モジュールは、誤ったデータや悪意を持って作成されたデータに
  対する安全性を考慮していません。信頼できない、もしくは認証されていな
  い出所からのデータを非整列化してはなりません。

すべての Python オブジェクト型がサポートされているわけではありません。
一般に、このモジュールによって読み書きすることができるオブジェクトは、
その値が Python の特定の起動に依存していないオブジェクトに限ります。次
の型がサポートされています。真偽値、整数、浮動小数点数、複素数、文字列
、 byte 、bytearray 、タプル、リスト、 set 、frozenset 、辞書、コード
オブジェクト。ここで、タプル、リスト、 set 、 frozenset 、辞書は、その
中に含まれる値がそれ自身サポートされる場合に限りサポートされます。シン
グルトン "None" 、 "Ellipsis" 、 "StopIteration" も読み書き
(marshalled and unmarshalled) できます。3 未満のフォーマット *version*
では、再帰的なリスト、 set 、辞書を書き出すことはできません (下記参照)
。

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

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

marshal.dump(value, file[, version])

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

   値 (または値に含まれるオブジェクト) がサポートされていない型の場合
   、 "ValueError" 例外が送出されます --- しかし、同時にごみのデータが
   ファイルに書き込まれます。このオブジェクトは "load()" で適切に読み
   出されることはありません。

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

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

marshal.load(file)

   開かれたファイルから値を一つ読んで返します。 (異なるバージョンの
   Python の互換性のない marshal フォーマットだったなどの理由で) 有効
   な値が読み出せなかった場合、 "EOFError", "ValueError" または
   "TypeError" を送出します。file は読み込み可能な *バイナリファイル*
   でなければなりません.

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

   注釈:

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

   バージョン 3.9.7 で変更: This call used to raise a "code.__new__"
   audit event for each code object. Now it raises a single
   "marshal.load" event for the entire load operation.

marshal.dumps(value[, version])

   "dump(value, file)" でファイルに書き込まれるようなbytesオブジェクト
   を返します。値はサポートされている型でなければなりません。値がサポ
   ートされていない型のオブジェクト (またはサポートされていない型のオ
   ブジェクトを含むようなオブジェクト) の場合、 "ValueError" 例外が送
   出されます。

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

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

marshal.loads(bytes)

   *bytes-like オブジェクト* を値に変換します。有効な値が見つからなか
   った場合、 "EOFError", "ValueError" または "TypeError" が送出されま
   す。入力中の余分な bytes は無視されます。

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

   バージョン 3.9.7 で変更: This call used to raise a "code.__new__"
   audit event for each code object. Now it raises a single
   "marshal.loads" event for the entire load operation.

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

marshal.version

   このモジュールが利用するバージョンを表します。バージョン0 は歴史的
   なフォーマットです。バージョン1 は文字列の再利用をします。バージョ
   ン2 は浮動小数点数にバイナリフォーマットを使用します。バージョン3
   はオブジェクトのインスタンス化と再帰をサポートします。現在のバージ
   ョンは4です。

-[ 脚注 ]-

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