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 на немаршалируемый тип.

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