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. Поддерживаются следующие типы:

• Числовые типы: int, bool, float, complex.
• Строки (str) и bytes. Объекты, подобные байтовым строкам, например bytearray, маршалируются как bytes.
• Контейнеры: tuple, list, set, frozenset и (начиная с version 5) slice. Следует учитывать, что они поддерживаются только в том случае, если сами содержащиеся в них значения поддерживаются. Рекурсивные контейнеры поддерживаются начиная с version 3.
• Одиночные объекты None, Ellipsis и StopIteration.
• Объекты code, если значение allow_code равно true. См. приведённое выше примечание о зависимости от версии.

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

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	Python 2.4	Совместное использование интернированных строк
2	Python 2.5	Двоичное представление чисел с плавающей точкой
3	Python 3.4	Поддержка создания экземпляров объектов и рекурсии
4	Python 3.4	Эффективное представление коротких строк
5	Python 3.14	Поддержка объектов slice

Сноски