データ整列化 (data marshalling) のサポート¶
以下のルーチン群は、 marshal モジュールと同じ形式を使った整列化オブジェクトを C コードから使えるようにします。整列化形式でデータを書き出す関数に加えて、データを読み戻す関数もあります。整列化されたデータを記録するファイルはバイナリモードで開かれていなければなりません。
数値は最下位バイトから順に格納されます。
このモジュールは複数のデータ形式のバージョンをサポートしています。
詳細は Python モジュールのドキュメント を参照してください。
The following exceptions can be raised by these functions:
ValueError if the value cannot be marshalled,
ValueError or TypeError if the data is malformed,
EOFError if the end of the data is reached before the value is complete,
OSError if reading from or writing to a FILE* fails,
KeyboardInterrupt if reading or writing is interrupted by a signal,
and MemoryError if memory allocation fails.
バージョン 3.16 で変更: Previously, in functions taking a FILE*,
the reading functions raised EOFError
instead of OSError and KeyboardInterrupt,
and the writing functions ignored I/O errors and interruptions.
-
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 はファイルフォーマットを示します。
The marshalled representation of value is built in memory and then written to file. Nothing is written if value cannot be marshalled.
この関数は失敗することがあり、その場合はエラー指示子を設定します。それを確認するために
PyErr_Occurred()を使います。注釈
Python 3.15 以前では、
fileにデータの一部だけを書き込んで、エラー指示子を設定せずに戻る場合があります。 例えば、valueに整列化できないオブジェクトが含まれる場合や、fileへの書き込みに失敗した場合です (gh-155907 を参照)。 これらのバージョンをサポートするコードでは、PyErr_Occurred()だけを使ってデータ全体が書き込まれたかどうかを判断することはできません。PyMarshal_WriteObjectToString()を使ってその結果を自分で書き込むか、書き込まれた内容を検証してください。バージョン 3.16 で変更: Previously, the data was written to file as it was produced, using a buffer of constant size, and incomplete data was written if value could not be marshalled.
-
PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)¶
- 戻り値: 新しい参照。
value の整列化表現が入ったバイト列オブジェクトを返します。version はファイルフォーマットを示します。
On error, raises an exception and returns
NULL.
以下の関数を使うと、整列化された値を読み戻せます。
-
long PyMarshal_ReadLongFromFile(FILE *file)¶
読み出し用に開かれた FILE* 内のデータストリームから、 C の long 型データを読み出して返します。この関数は、ネイティブの long のサイズに関係なく、 32 ビットの値だけを読み出せます。
On error, raises an exception and returns
-1.
-
int PyMarshal_ReadShortFromFile(FILE *file)¶
読み出し用に開かれた FILE* 内のデータストリームから、 C の short 型データを読み出して返します。この関数は、ネイティブの short のサイズに関係なく、 16 ビットの値だけを読み出せます。
On error, raises an exception and returns
-1.
-
PyObject *PyMarshal_ReadObjectFromFile(FILE *file)¶
- 戻り値: 新しい参照。
読み出し用に開かれた FILE* 内のデータストリームから Python オブジェクトを返します。
On error, raises an exception and returns
NULL.
-
PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)¶
- 戻り値: 新しい参照。
読み取り用に開かれた FILE* のデータストリームから Python オブジェクトを読み取って返します。
PyMarshal_ReadObjectFromFile()と異なり、この関数はファイルからこれ以上オブジェクトを読み取らないことを前提とします。 そのため、ファイルのデータをまとめてメモリに読み込み、ファイルから 1 バイトずつ読み取る代わりにメモリ上のデータから復元できます。 そのファイルからほかに何も読み取らないと確信できる場合だけ使ってください。On error, raises an exception and returns
NULL.
-
PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)¶
- 戻り値: 新しい参照。
data が指す len バイトのバイト列バッファ内のデータストリームから Python オブジェクトを返します。
On error, raises an exception and returns
NULL.