marshal — Внутренняя сериализация объектов Python

Этот модуль содержит функции, которые могут читать и записывать значения Python в двоичном формате. Формат специфичен для Python, но независим от архитектуры машины (например, вы можете записать значение Python в файл на ПК, передать файл на Sun и прочитать его обратно там). Подробности формата намеренно не документированы; он может меняться между версиями Python (хотя это происходит редко). 1

Это не общий модуль «постоянства». Для общего сохранения и передачи объектов Python через вызовы RPC см. модули pickle и shelve. Модуль marshal существует в основном для поддержки чтения и записи «псевдоскомпилированного» кода для модулей Python файлов .pyc. Поэтому разработчики Python оставляют за собой право изменять формат marshal несовместимым обратным образом, если в этом возникнет необходимость. Если вы сериализуете и десериализуете объекты Python, используйте модуль pickle вместо этого — производительность сопоставима, независимость от версии гарантирована, а pickle поддерживает значительно более широкий диапазон объектов, чем marshal.

Не все типы объектов Python поддерживаются; в общем, только объекты, значение которых независимо от конкретного вызова Python, могут быть записаны и считаны с помощью этого модуля. Поддерживаются следующие типы: булевы, целые, числа с плавающей запятой, комплексные числа, строки, байты, массивы байтов, кортежи, списки, множества, замороженные множества, словари и объекты кода, где следует понимать, что кортежи, списки, множества, замороженные множества и словари поддерживаются только в том случае, если значения, содержащиеся в них, сами поддерживаются. Также можно сериализовать и десериализовать объекты-синглетоны None, Ellipsis и StopIteration. Для формата версии ниже 3 рекурсивные списки, множества и словари не могут быть записаны (см. ниже).

Существуют функции для чтения/записи файлов, а также функции, работающие с объектами типа байты.

Модуль определяет эти функции:

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

Записать значение в открытый файл. Значение должно быть поддерживаемого типа. Файл должен быть записываемым двоичным файлом.

Если значение имеет (или содержит объект, который имеет) неподдерживаемый тип, возникает исключение ValueError — но в файл также будут записаны мусорные данные. Объект не будет правильно считаться обратно load().

Аргумент version указывает формат данных, который dump должен использовать (см. ниже).

marshal.load(file)

Прочитать одно значение из открытого файла и вернуть его. Если не будет считано ни одного значения (например, потому что данные имеют несовместимый с версией Python формат marshal), поднимите EOFError, ValueError или TypeError. Файл должен быть читаемым двоичным файлом.

Примечание

Если объект, содержащий неподдерживаемый тип, был сериализован с помощью dump(), load() заменит None на несериализуемый тип.

marshal.dumps(value[, version])

Возвращает объект bytes, который будет записан в файл функцией dump(value, file). Значение должно быть поддерживаемого типа. Вызывает исключение ValueError, если значение имеет (или содержит объект, который имеет) неподдерживаемый тип.

Аргумент version указывает формат данных, который dumps должен использовать (см. ниже).

marshal.loads(bytes)

Преобразует объект типа байты в значение. Если не найдено ни одного допустимого значения, вызываются EOFError, ValueError или TypeError. Дополнительные байты на входе игнорируются.

Кроме того, определены следующие константы:

marshal.version

Указывает формат, используемый модулем. Версия 0 — это исторический формат, версия 1 использует интернированные строки, а версия 2 использует двоичный формат для чисел с плавающей запятой. Версия 3 добавляет поддержку создания объектов и рекурсии. Текущая версия — 4.

Примечания

1

Название этого модуля происходит от немного терминологии, используемой разработчиками Modula-3 (среди прочих), которые используют термин «маршаллинг» для передачи данных в самодостаточной форме. Строго говоря, «маршаллинг» означает преобразование данных из внутреннего в внешний вид (например, в буфере RPC), а «демаршаллинг» — обратный процесс.