\section{\module{marshal} ---
         内部使用向けの Python オブジェクト整列化}

\declaremodule{builtin}{marshal}
\modulesynopsis{Python オブジェクトをバイト列に変換したり、その逆を (異なる拘束条件下で) 行います。}

このモジュールには Python 値をバイナリ形式で読み書きできるような関数
が含まれています。このバイナリ形式は Python 特有のものですが、
マシンアーキテクチャ非依存のものです (つまり、Python の値を PC 上で
ファイルに書き込み、Sun に転送し、そこで読み戻すことができます)。
バイナリ形式の詳細がドキュメントされていないのは故意によるもの
です; この形式は (稀にしかないことですが) Python のバージョン間で
変更される可能性があるからです。\footnote{
このモジュールの名前は (特に) Modula-3 の設計者の間で使われて
いた用語の一つに由来しています。彼らはデータを自己充足的な形式
で輸送する操作に ``整列化 (marshalling)'' という用語を使いました。
厳密に言えば、``整列させる (to marshal)'' とは、あるデータを
(例えば RPC バッファのように) 内部表現形式から外部表現形式に変換する
ことを意味し、``非整列化 (unmarshalling)'' とはその逆を意味します。
}

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

\refstmodindex{pickle}
\refstmodindex{shelve}
\obindex{code}

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


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

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

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

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

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

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

\versionadded[\code{dump}で、データフォーマットを表す\var{version} 引
  数を利用するべきです。(下を参照)]{2.4}
\end{funcdesc}

\begin{funcdesc}{load}{file}
開かれたファイルから値を一つ読んで返します。有効な値が読み出せなかった
場合、\exception{EOFError}、\exception{ValueError}、または
\exception{TypeError} を送出します。ファイルはバイナリモード
(\code{'rb'} または \code{'r+b'}) で開かれたファイルオブジェクトでなければ
なりません.
\warning{サポートされない型を含むオブジェクトが \function{dump()} で
整列化されている場合、\function{load()} は整列化不能な値を \code{None} 
で置き換えます。}
\end{funcdesc}

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

\versionadded[\code{dump}で、データフォーマットを表す\var{version} 引
  数を利用するべきです。(下を参照)]{2.4}
\end{funcdesc}

\begin{funcdesc}{loads}{string}
データ文字列を値に変換します。有効な値が見つからなかった場合、
\exception{EOFError}、 \exception{ValueError}、または
\exception{TypeError} が送出されます。
文字列中の他の文字は無視されます。
\end{funcdesc}

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

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