marshal – внутренняя сериализация объектов Python¶marshal – Internal Python object serialization

Этот модуль содержит функции, которые могут читать и записывать значения 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 истинно). При этом следует понимать, что кортежи, списки, множества, неизменяемые множества и словари поддерживаются только при условии, что содержащиеся в них значения также поддерживаются. Синглтоны 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)¶

Читает одно значение из открытого файла и возвращает его. Если не удаётся прочитать корректное значение (например, из-за несовместимого формата marshal другой версии Python), возбуждается 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)¶

Возвращает объект bytes, который был бы записан в файл функцией 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.

Сноски