Документация Python неофициальный перевод

Поддержка маршалинга данныхData marshalling support

Эти процедуры позволяют коду на C работать с сериализованными объектами, используя тот же формат данных, что и модуль marshal. Существуют функции для записи данных в формат сериализации, а также дополнительные функции для чтения данных обратно. Файлы, используемые для хранения маршалированных данных, должны быть открыты в бинарном режиме.

Числовые значения хранятся с младшим байтом первым.

Модуль поддерживает две версии формата данных: версия 0 – историческая, версия 1 разделяет интернированные строки в файле и при демаршалинге. Версия 2 использует бинарный формат для чисел с плавающей точкой. Py_MARSHAL_VERSION указывает текущий формат файла (на данный момент 2).

void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
Маршалирует целое число типа long, value, в file. Эта функция запишет только младшие 32 бита value, независимо от размера нативного типа long. version указывает формат файла.
void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
Маршалирует объект Python, value, в file. version указывает формат файла.
PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
Возвращаемое значение: новая ссылка.

Возвращает строковый объект, содержащий маршалированное представление value. version указывает формат файла.

Следующие функции позволяют считывать маршалированные значения обратно.

XXX Что насчёт обнаружения ошибок? Похоже, что чтение за концом файла всегда приводит к отрицательному числовому значению (там, где это имеет значение), но неясно, будут ли отрицательные значения корректно обрабатываться, когда ошибки нет. Как правильно определить? Следует ли записывать только неотрицательные значения с помощью этих процедур?

long PyMarshal_ReadLongFromFile(FILE *file)
Возвращает значение C типа long из потока данных в FILE*, открытом для чтения. С помощью этой функции можно прочитать только 32-битное значение, независимо от нативного размера типа long.
int PyMarshal_ReadShortFromFile(FILE *file)
Возвращает значение C типа short из потока данных в FILE*, открытом для чтения. С помощью этой функции можно прочитать только 16-битное значение, независимо от нативного размера типа short.
PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
Возвращаемое значение: новая ссылка.

Возвращает объект Python из потока данных в FILE*, открытом для чтения. В случае ошибки устанавливает соответствующее исключение (EOFError или TypeError) и возвращает NULL.

PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Возвращаемое значение: новая ссылка.

Возвращает объект Python из потока данных в FILE*, открытом для чтения. В отличие от PyMarshal_ReadObjectFromFile, эта функция предполагает, что из файла больше не будет читаться никаких объектов, что позволяет агрессивно загружать данные файла в память, чтобы десериализация могла работать с данными в памяти, а не читать по байту из файла. Используйте этот вариант, только если уверены, что больше ничего из файла читать не будете. При ошибке устанавливает соответствующее исключение (EOFError или TypeError) и возвращает NULL.

PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
Возвращаемое значение: новая ссылка.

Возвращает объект Python из потока данных в символьном буфере, содержащем len байт, на который указывает string. При ошибке устанавливает соответствующее исключение (EOFError или TypeError) и возвращает NULL.