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

Этот модуль содержит функции для чтения и записи значений Python в двоичном формате. Формат специфичен для Python, но не зависит от особенностей архитектуры машины (например, можно записать значение Python в файл на ПК, перенести файл на Mac и прочитать его там). Подробности формата намеренно не документированы; он может меняться между версиями 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.dumps с аргументами value, version.

marshal.load(file)

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

Вызывает событие аудита marshal.load без аргументов.

Примечание

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

Изменено в версии 3.10: Раньше при каждом объекте кода этот вызов вызывал событие аудита code.__new__. Теперь он вызывает одно событие marshal.load для всей операции загрузки.

marshal.dumps(value[, version])

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

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

Вызывает событие аудита marshal.dumps с аргументами value, version.

marshal.loads(bytes)

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

Вызывает событие аудита marshal.loads с аргументом bytes.

Изменено в версии 3.10: Раньше при каждом объекте кода этот вызов вызывал событие аудита code.__new__. Теперь он вызывает одно событие marshal.loads для всей операции загрузки.

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

marshal.version

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

Сноски