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

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, long integers, floating point numbers,
complex numbers, strings, Unicode objects, tuples, lists, sets,
frozensets, dictionaries, and code objects, 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; and recursive lists, sets and dictionaries should not be
written (they will cause infinite loops).  The singletons "None",
"Ellipsis" and "StopIteration" can also be marshalled and
unmarshalled.

警告: On machines where C’s "long int" type has more than 32 bits
  (such as the DEC Alpha), it is possible to create plain Python
  integers that are longer than 32 bits. If such an integer is
  marshaled and read back in on a machine where C’s "long int" type
  has only 32 bits, a Python long integer object is returned instead.
  While of a different type, the numeric value is the same.  (This
  behavior is new in Python 2.2.  In earlier versions, all but the
  least- significant 32 bits of the value were lost, and a warning
  message was printed.)

There are functions that read/write files as well as functions
operating on strings.

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

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

   Write the value on the open file.  The value must be a supported
   type.  The file must be an open file object such as "sys.stdout" or
   returned by "open()" or "os.popen()".  It may not be a wrapper such
   as TemporaryFile on Windows. It must be opened in binary mode
   ("'wb'" or "'w+b'").

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

   バージョン 2.4 で追加: *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 an open file object opened in binary
   mode ("'rb'" or "'r+b'").

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

marshal.dumps(value[, version])

   Return the string 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.

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

marshal.loads(string)

   Convert the string to a value.  If no valid value is found, raise
   "EOFError", "ValueError" or "TypeError".  Extra characters in the
   string are ignored.

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

marshal.version

   Indicates the format that the module uses. Version 0 is the
   historical format, version 1 (added in Python 2.4) shares interned
   strings and version 2 (added in Python 2.5) uses a binary format
   for floating point numbers. The current version is 2.

   バージョン 2.4 で追加.

-[ 脚注 ]-

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