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)

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

Примечание

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

marshal.dumps(value[, version])

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

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

marshal.loads(bytes)

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

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

marshal.version

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

Примечания

1

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