3.12 組み込みモジュール marshal

 

本モジュールは、バイナリフォーマットのパイソンの値を読み書きできる 関数を含んでいます。 そのフォーマットはパイソン特有のものですが、 マシンアーキテクチャの問題からは独立しています （例えば、パソコン上でパイソンの値をファイルに書いて、そのファイルを Sunに転送し、戻して読み込む）。 そのフォーマットの詳細は次の理由からドキュメント化されていません。 すなわち、パイソンのバージョンによって変更されるかもしれないためです （めったにないかもしれませんが）。 ^3.1

本モジュールは、いわゆる永続的保存のためのモジュールではありません。 一般的な永続的保存やパイソンオブジェクトのRPCコールによる転送については、 pickleおよびshelveモジュールをご覧下さい。 主にmarshalモジュールは、".pyc"というパイソンモジュール の``pseudo-compiled''コードを読み書きするために存在します。    

全てのパイソンオブジェクトタイプがサポートされているわけではありません。 一般に、パイソンの特殊な呼び出しには依存しない値を持つオブジェクトだけを このモジュールで書いたり読んだりできます。 以下のタイプはサポートされています。： None, 整数, ロング整数, 浮動小数, 文字列、タプル、リスト、辞書、そしてコードオブジェクトです。 また、そこに含まれる値自身がサポートされているかぎりタプル、リストおよび 辞書もサポートされるはずです。ただし、再帰的なリストと辞書を書くべきでは ありません（それらは無限ループをひき起こします）。

警告： Cのlong intタイプが３２ビット（DEC Alphaのような）以上であるマシン では、３２ビットより長い単純なパイソンの整数を生成することが出来ます。 現在のmarshalモジュールは単純なパイソンの整数を転送するために ３２ビットを使うので、そのような値は無条件に切り詰められます。 これはパイソンモジュールで非常に長い整数リテラルを使うときには特に影響します。 つまり、これらはそのようなマシン上ではパーサは受け付けますが、".pyc" からモジュールが読み込まれた時には無条件に切り詰められます。 ^3.2

文字列上で操作する関数はもちろんファイルを読み書きする関数も用意されています。

以下の関数を定義しています：

dump (value, file)

オープンしたファイルにvalueを書きます。valueはサポートされている タイプでなければなりません。ファイルは、sys.stdoutまたは open()によって返されるもの、またはposix.popen()のような オープンしたファイルオブジェクトである必要があります。

valueがサポートされていないタイプを持っている（またはそういった値を持つ オブジェクトを含む）場合には、ValueError例外が発生します。 しかし、残りのデータがそのファイルには書き込まれます。そのオブジェクトは load()を使って正しく読み込むことはできないでしょう。

load (file)

オープンファイルからひとつの値を読み、返します。有効な値が読めなかった 場合にはEOFError、ValueError、TypeError 例外が発生します。fileはオープンされたファイルオブジェクトでなければ なりません。

警告： サポートされていないタイプを含むオブジェクトがdump()で marshalされたときは、load()はmarshalできなかったタイプに対して Noneで置き換えを行います。

dumps (value)

dump(value, file)でファイルに書かれる文字列を 返します。valueはサポートされているタイプでなければなりません。 valueがサポートされていないタイプを持っている（またはそういった値を持つ オブジェクトを含む）場合には、ValueError例外が発生します。

loads (string)

stringを値に変換します。有効な値が見つからなければ EOFError, ValueErrorまたはTypeError例外が発生します。 文字列の余分な文字は無視されます。