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

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

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

Предупреждение

Модуль marshal не предназначен для защиты от ошибочных или злонамеренно созданных данных. Никогда не размаршалливайте данные, полученные от ненадежного или неподтвержденного источника.

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

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

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

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

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

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

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

marshal.load(file)

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

Примечание

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

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 для сущности) и «размаршалливание» для обратного процесса.