marshal --- 内部使用向けの Python オブジェクト直列化

このモジュールは、Python の値をバイナリ形式で読み書きする関数を提供します。 この形式は Python 固有ですが、マシンのアーキテクチャには依存しません (例えば PC で Python の値をファイルに書き込み、そのファイルを Mac に転送して読み戻せます)。 形式の詳細は意図的に文書化されていません。 Python のバージョンによって変更される場合があります (ただし、実際にはまれです)。 [1]

これは汎用の「永続化」モジュールではありません。 Python オブジェクトの汎用的な永続化や RPC 呼び出しによる転送には、pickle と shelve を参照してください。 marshal モジュールは主に、Python モジュールの「擬似コンパイル済み」コードを .pyc ファイルで読み書きするために存在します。 そのため、Python のメンテナーは、必要に応じて後方互換性のない形で marshal 形式を変更する権利を留保します。 形式のバージョンが同じでも、コードオブジェクトの形式は Python のバージョン間で互換性がありません。 誤った Python バージョンでコードオブジェクトを復元した場合の動作は未定義です。 Python オブジェクトを直列化したり復元したりするには、代わりに pickle モジュールを使ってください。 性能は同程度で、バージョンに依存しないことが保証され、marshal よりはるかに幅広いオブジェクトをサポートします。

警告

marshal モジュールは、誤ったデータや悪意を持って作成されたデータに対して安全であるようには設計されていません。 信頼できない、または認証されていない送信元から受け取ったデータを決して復元しないでください。

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

すべての Python オブジェクト型をサポートしているわけではありません。 一般に、このモジュールで読み書きできるのは、値が Python の特定の実行に依存しないオブジェクトだけです。 以下の型をサポートします。

  • 数値型: int、bool、float、complex。

  • 文字列 (str) と bytes。 bytearray のような bytes-like object は、bytes として直列化されます。

  • コンテナ: tuple、list、dict、frozendict (version 6 以降)、set、frozenset、slice (version 5 以降)。 これらは、格納する値もサポートされている場合にのみサポートされます。 再帰的なコンテナは version 3 以降でサポートされています。

  • シングルトンの None、Ellipsis、StopIteration。

  • allow_code が真の場合の code オブジェクト。 バージョンへの依存については、上の注意書きを参照してください。

バージョン 3.4 で変更:

  • 再帰的なリスト、集合、辞書の直列化をサポートする形式バージョン 3 を追加しました。

  • 短い文字列を効率的に表現する形式バージョン 4 を追加しました。

バージョン 3.14 で変更: スライスの直列化を可能にする形式バージョン 5 を追加しました。

バージョン 3.15 で変更: frozendict の直列化を可能にする形式バージョン 6 を追加しました。

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

marshal.dump(value, file, version=version, /, *, allow_code=True)

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

値がサポートされていない型であるか、その型のオブジェクトを含む場合、ValueError を送出しますが、不正なデータもファイルに書き込まれます。 このオブジェクトは load() で正しく読み戻せません。 コードオブジェクト は allow_code が真の場合にのみサポートされます。

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

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

バージョン 3.13 で変更: allow_code 引数を追加しました。

marshal.load(file, /, *, allow_code=True)

開かれたファイルから値を 1 つ読み取り、返します。 有効な値を読み取れない場合 (例えば、別の Python バージョンの互換性のない marshal 形式である場合)、EOFError、ValueError、TypeError のいずれかを送出します。 コードオブジェクト は allow_code が真の場合にのみサポートされます。 ファイルは読み取り可能な バイナリファイル でなければなりません。

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

注釈

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

バージョン 3.10 で変更: 以前はコードオブジェクトごとに code.__new__ 監査イベントを発生させていました。 現在は読み込み操作全体に対して marshal.load イベントを 1 回発生させます。

バージョン 3.13 で変更: allow_code 引数を追加しました。

marshal.dumps(value, version=version, /, *, allow_code=True)

dump(value, file) でファイルに書き込まれる内容を bytes オブジェクトとして返します。 値はサポートされている型でなければなりません。 値がサポートされていない型であるか、その型のオブジェクトを含む場合、ValueError を送出します。 コードオブジェクト は allow_code が真の場合にのみサポートされます。

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

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

バージョン 3.13 で変更: allow_code 引数を追加しました。

marshal.loads(bytes, /, *, allow_code=True)

bytes-like object を値に変換します。 有効な値が見つからなければ、EOFError、ValueError、TypeError のいずれかを送出します。 コードオブジェクト は allow_code が真の場合にのみサポートされます。 入力の余分なバイトは無視されます。

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

バージョン 3.10 で変更: 以前はコードオブジェクトごとに code.__new__ 監査イベントを発生させていました。 現在は読み込み操作全体に対して marshal.loads イベントを 1 回発生させます。

バージョン 3.13 で変更: allow_code 引数を追加しました。

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

marshal.version

モジュールが使う形式を示します。 バージョン 0 が最初のバージョンで、以降のバージョンでは新しい機能が追加されています。 通常、新しいバージョンは導入と同時にデフォルトになります。

Version

利用可能になったバージョン

新しい機能

1

Python 2.4

インターン化された文字列の共有

2

Python 2.5

浮動小数点数のバイナリ表現

3

Python 3.4

オブジェクトの共有と再帰のサポート

4

Python 3.4

短い文字列の効率的な表現

5

Python 3.14

slice オブジェクトのサポート

6

Python 3.15

frozendict オブジェクトのサポート

脚注