12.4. "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 、辞書を書き出すことはできません (下記参照)
。

There are functions that read/write files as well as functions
operating on bytes-like objects.

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

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

   Write the value on the open file.  The value must be a supported
   type.  The file must be a writeable *binary file*.

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

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

marshal.load(file)

   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".  The file must be a readable *binary file*.

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

marshal.dumps(value[, version])

   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.

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

marshal.loads(bytes)

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

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

marshal.version

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

-[ 脚注 ]-

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