データ整列化 (data marshalling) のサポート¶
以下のルーチン群は、 marshal モジュールと同じ形式を使った整列化オブジェクトを C コードから使えるようにします。整列化形式でデータを書き出す関数に加えて、データを読み戻す関数もあります。整列化されたデータを記録するファイルはバイナリモードで開かれていなければなりません。
数値は最下位バイトから順に格納されます。
このモジュールは複数のデータ形式のバージョンをサポートしています。
詳細は Python モジュールのドキュメント を参照してください。
-
Py_MARSHAL_VERSION¶
現在の形式のバージョン。
marshal.versionを参照してください。
-
void PyMarshal_WriteLongToFile(long value, FILE *file, int version)¶
long 型の整数値 value を file へ整列化します。この関数は value の下桁 32 ビットを書き込むだけです; ネイティブの long 型サイズには関知しません。 version はファイルフォーマットを示します。
この関数は失敗することがあり、その場合はエラー指示子を設定します。それを確認するために
PyErr_Occurred()を使います。注釈
Python 3.15 以前では、
fileへの書き込みに失敗しても、この関数はエラー指示子を設定しません。PyMarshal_WriteObjectToFile()と同じ注意事項が当てはまります。
-
void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)¶
Python オブジェクト value を file へ整列化します。version はファイルフォーマットを示します。
この関数は失敗することがあり、その場合はエラー指示子を設定します。それを確認するために
PyErr_Occurred()を使います。注釈
Python 3.15 以前では、
fileにデータの一部だけを書き込んで、エラー指示子を設定せずに戻る場合があります。 例えば、valueに整列化できないオブジェクトが含まれる場合や、fileへの書き込みに失敗した場合です (gh-155907 を参照)。 これらのバージョンをサポートするコードでは、PyErr_Occurred()だけを使ってデータ全体が書き込まれたかどうかを判断することはできません。PyMarshal_WriteObjectToString()を使ってその結果を自分で書き込むか、書き込まれた内容を検証してください。
-
PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)¶
- 戻り値: 新しい参照。
value の整列化表現が入ったバイト列オブジェクトを返します。version はファイルフォーマットを示します。
以下の関数を使うと、整列化された値を読み戻せます。
-
long PyMarshal_ReadLongFromFile(FILE *file)¶
読み出し用に開かれた FILE* 内のデータストリームから、 C の long 型データを読み出して返します。この関数は、ネイティブの long のサイズに関係なく、 32 ビットの値だけを読み出せます。
エラーの場合、適切な例外 (
EOFError) を設定し-1を返します。
-
int PyMarshal_ReadShortFromFile(FILE *file)¶
読み出し用に開かれた FILE* 内のデータストリームから、 C の short 型データを読み出して返します。この関数は、ネイティブの short のサイズに関係なく、 16 ビットの値だけを読み出せます。
エラーの場合、適切な例外 (
EOFError) を設定し-1を返します。
-
PyObject *PyMarshal_ReadObjectFromFile(FILE *file)¶
- 戻り値: 新しい参照。
読み出し用に開かれた FILE* 内のデータストリームから Python オブジェクトを返します。
エラーの場合、適切な例外 (
EOFError,ValueError,TypeError) を設定しNULLを返します。
-
PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)¶
- 戻り値: 新しい参照。
読み取り用に開かれた FILE* のデータストリームから Python オブジェクトを読み取って返します。
PyMarshal_ReadObjectFromFile()と異なり、この関数はファイルからこれ以上オブジェクトを読み取らないことを前提とします。 そのため、ファイルのデータをまとめてメモリに読み込み、ファイルから 1 バイトずつ読み取る代わりにメモリ上のデータから復元できます。 そのファイルからほかに何も読み取らないと確信できる場合だけ使ってください。エラーの場合、適切な例外 (
EOFError,ValueError,TypeError) を設定しNULLを返します。
-
PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)¶
- 戻り値: 新しい参照。
data が指す len バイトのバイト列バッファ内のデータストリームから Python オブジェクトを返します。
エラーの場合、適切な例外 (
EOFError,ValueError,TypeError) を設定しNULLを返します。