11.5. "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 の特定の起動から独立しているオブジェクトだけが、こ
のモジュールによって読み書きすることができます。次の型がサポートされま
す: 真偽値、整数、長整数、浮動小数点数、複素数、文字列、 Unicode 文字
列、タプル、リスト、 set 、frozensets 、辞書、コードオブジェクト。ここ
で、タプル、リスト、 set 、 frozenset 、辞書は、その中に含まれる値がそ
れ自身サポートされる場合に限りサポートされることを理解すべきです; また
、再帰的なリスト、 set 、辞書は書かれるべきではありません (無限ループ
を起こします)。シングルトン "None" 、 "Ellipsis" 、 "StopIteration" も
読み書きできます。

警告: (DEC Alpha のように) C言語の "long int" が 32 ビットよりも長い
  ビット 長を持つ場合、 32 ビットよりも長い Python 整数を作成すること
  が可能で す。そのような整数が整列化された後、 C 言語の "long int" の
  ビット長 が 32 ビットしかないマシン上で読み戻された場合、通常整数の
  代わりに Python 長整数が返されます。型は異なりますが、数値は同じです
  。 (この 動作は Python 2.2 で新たに追加されたものです。それ以前のバ
  ージョンで は、値のうち最小桁から 32 ビット以外の情報は失われ、警告
  メッセージが 出力されていました。)

文字列を操作する関数と同様に、ファイルの読み書きを行う関数が提供されて
います。

このモジュールにはこれらの関数が定義されています:

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

   開かれたファイルに値を書き込みます。値はサポートされている型でなく
   てはなりません。ファイルは "sys.stdout" か、 "open()" や
   "os.popen()" が返すようなファイルオブジェクトでなくてはなりません。
   Windows では TemporaryFile のようなラッパーは使えません。またファイ
   ルはバイナリモード ("'wb'" または "'w+b'") で開かれていなければなり
   ません。

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

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

marshal.load(file)

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

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

marshal.dumps(value[, version])

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

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

marshal.loads(string)

   データ文字列を値に変換します。有効な値が見つからなかった場合、
   "EOFError"、 "ValueError"、または "TypeError" が送出されます。文字
   列中の余分な文字は無視されます。

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

marshal.version

   このモジュールが利用するバージョンを表します。バージョン0 は歴史的
   なフォーマットです。バージョン1 は文字列の再利用をします (Python
   2.4で追加されました)。バージョン2 は浮動小数点数にバイナリフォーマ
   ットを使用します (Python 2.5で追加されました)。現在のバージョンは2
   です。

   バージョン 2.4 で追加.

-[ 脚注 ]-

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