# `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 の特定の起動に依存していないオブジェクトに限ります。次の型がサポートされています。真偽値、整数、浮動小数点数、複素数、文字列、 byte 、bytearray 、タプル、リスト、 set 、frozenset 、辞書、コードオブジェクト。ここで、タプル、リスト、 set 、 frozenset 、辞書は、その中に含まれる値がそれ自身サポートされる場合に限りサポートされます。シングルトン `None` 、 `Ellipsis` 、 `StopIteration` も読み書き (marshalled and unmarshalled) できます。3 未満のフォーマット version では、再帰的なリスト、 set 、辞書を書き出すことはできません (下記参照)。

bytes-like オブジェクトを操作する関数と同様に、ファイルの読み書きを行う関数が提供されています。

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

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

  開かれたファイルに値を書き込みます。値はサポートされている型でなくてはなりません。file は書き込み可能な バイナリファイル である必要があります。

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

  version 引数は `dump` が使用するデータフォーマットを指定します (下記を参照してください)。

  引数 `value`, `version` を指定して 監査イベント `marshal.dumps` を送出します。

`marshal.``load`(file)

  開かれたファイルから値を一つ読んで返します。 (異なるバージョンの Python の互換性のない marshal フォーマットだったなどの理由で) 有効な値が読み出せなかった場合、 `EOFError`, `ValueError` または `TypeError` を送出します。file は読み込み可能な バイナリファイル でなければなりません.

  引数無しで 監査イベント `marshal.load` を送出します。

  注釈

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

  バージョン 3.10 で変更: This call used to raise a `code.__new__` audit event for each code object. Now it raises a single `marshal.load` event for the entire load operation.

`marshal.``dumps`(value[, version])

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

  version 引数は `dumps` が使用するデータフォーマットを指定します (下記を参照してください)。

  引数 `value`, `version` を指定して 監査イベント `marshal.dumps` を送出します。

`marshal.``loads`(bytes)

  bytes-like オブジェクト を値に変換します。有効な値が見つからなかった場合、 `EOFError`, `ValueError` または `TypeError` が送出されます。入力中の余分な bytes は無視されます。

  引数 `bytes` を指定して 監査イベント `marshal.loads` を送出します。

  バージョン 3.10 で変更: This call used to raise a `code.__new__` audit event for each code object. Now it raises a single `marshal.loads` event for the entire load operation.

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

`marshal.``version`

  このモジュールが利用するバージョンを表します。バージョン0 は歴史的なフォーマットです。バージョン1 は文字列の再利用をします。バージョン2 は浮動小数点数にバイナリフォーマットを使用します。バージョン3 はオブジェクトのインスタンス化と再帰をサポートします。現在のバージョンは4です。

脚注

1

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