
:mod:`marshal` --- 内部使用向けの Python オブジェクト整列化
===========================================================

.. module:: marshal
   :synopsis: Python オブジェクトをバイト列に変換したり、その逆を (異なる拘束条件下で) 行います。

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

.. index::
   module: pickle
   module: shelve
   object: code

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

.. warning::

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

全ての Python オブジェクト型がサポートされているわけではありません; 一般的には、どの起動中の Python 上に存在するかに依存しないオブジェクト
だけがこのモジュールで読み書きできます。以下の型: ``None`` 、整数、長整数、浮動小数点数、文字列、Unicode オブジェクト、
タプル、リスト、集合、辞書、タプルとして解釈されるコードオブジェクト、がサポートされています。リストと辞書は含まれている要素もサポート
されている型であるもののみサポートされています; 再帰的なリストおよび辞書は書き込んではなりません (無限ループを引き起こしてしまいます)。

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

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

このモジュールでは以下の関数を定義しています:


.. function:: dump(value, file[, version])

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

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

   .. versionadded:: 2.4
      ``dump`` が利用するデータフォーマットを表す *version* 引数 (下を参照).


.. function:: load(file)

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

   .. warning::

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


.. function:: dumps(value[, version])

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

   .. versionadded:: 2.4
      ``dump`` するデータフォーマットを表す *version* 引数(下を参照).

      .. 訳者note: ``dumps`` should は、 dumps が利用するべき（フォーマット）という意味だけど、
         訳からは should の部分を省略


.. function:: loads(string)

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

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


.. data:: version

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

   .. versionadded:: 2.4

.. rubric:: Footnotes

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

