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])

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

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

marshal.loads(bytes)

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

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

marshal.version

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

Примечания

1

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