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)

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

Сноски