前のトピックへ

11.4. shelve — Python オブジェクトの永続化

次のトピックへ

11.6. anydbm — DBM 形式のデータベースへの汎用アクセスインタフェース

このページ

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 、 frozenset 、辞書、コードオブジェクト、がサポートされています。ただし、タプル、リスト、 set 、 frozenset 、辞書は、それらに含まれた値がサポートされている型である限りサポートされると解釈しなければなりません; また、再帰的なリストおよび辞書は書き込んではなりません (無限ループを引き起こします)。シングルトンである NoneEllipsisStopIteration も整列化可能です。

警告

(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()posix.popen() が返すようなファイルオブジェクトでなくてはなりません。またファイルはバイナリモード ('wb' または 'w+b') で開かれていなければなりません。

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

バージョン 2.4 で追加: version 引数は dump が利用するデータフォーマットを表します (下記参照)。

marshal.load(file)

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

ノート

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

marshal.dumps(value[, version])

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

バージョン 2.4 で追加: version 引数は dumps が利用するデータフォーマットを表します (下記参照)。

marshal.loads(string)

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

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

marshal.version

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

バージョン 2.4 で追加.

注記

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