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

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

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

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

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

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

marshal.dump(value, file, version=version, /, *, allow_code=True)

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

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

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

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

Изменено в версии 3.13: Добавлен параметр allow_code.

marshal.load(file, /, *, allow_code=True)

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

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

Примечание

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

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

Изменено в версии 3.13: Добавлен параметр allow_code.

marshal.dumps(value, version=version, /, *, allow_code=True)

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

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

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

Изменено в версии 3.13: Добавлен параметр allow_code.

marshal.loads(bytes, /, *, allow_code=True)

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

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

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

Изменено в версии 3.13: Добавлен параметр allow_code.

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

marshal.version

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

Примечания