Модуль marshal содержит функции, которые могут читать и записывать значения Python в двоичном формате. Формат специфичен для Python, но не зависит от проблем архитектуры машины (например, можно записать значение Python в файл на ПК, перенести файл на Mac и прочитать его там). Детали формата намеренно не документированы, они могут меняться в разных версиях Python (хотя это случается редко).
Это не модуль общего назначения для "сохранения". Для сохранения и передачи объектов Python посредством вызовов RPC необходимо использовать модули pickle и shelve. Модуль marshal существует в основном для поддержки чтения и записи “псевдокомпилированного” кода для модулей Python из файлов .pyc. Следовательно, разработчики Python оставляют за собой право изменять формат marshal обратно несовместимыми способами, если возникнет необходимость. Формат объектов кода несовместим между версиями Python, даже если версия формата одинакова. Десериализация объекта code в неверной версии Python имеет неопределенное поведение. Если вы сериализуете и десериализуете объекты Python, используйте модуль pickle - производительность сопоставима, независимость от версии гарантирована, и pickle поддерживает существенно более широкий диапазон объектов, чем marshal.
Предупреждение модуль
marshalне предназначен для защиты от ошибочных или злонамеренно сконструированных данных. Никогда не отменяйте сериализацию данных, полученных из ненадежного или не прошедшего проверку подлинности источника.
Поддерживаются не все типы объектов Python. Этот модуль может писать и читать, только объекты, значение которых не зависит от конкретного вызова Python. Поддерживаются следующие типы: логические значения, целые числа, числа с плавающей запятой, комплексные числа, строки, байты, байтовые массивы, кортежи, списки, множества, неизменяемые множества, словари и объекты кода (если значение allow_code равно True), при этом следует понимать, что кортежи, списки, множества, неизменяемые множества и словари поддерживаются только до тех пор, пока поддерживаются сами значения, содержащиеся в них. Синглтоны None, Ellipsis и StopIteration также могут быть сериализованы и десериализованы. Для формата версии ниже 3 рекурсивные списки, наборы и словари не могут быть написаны.
Существуют функции, которые читают/записывают файлы, а также функции, работающие с байтоподобными объектами.
Название этого модуля происходит от терминологии, используемой разработчиками языка Modula-3, которые используют термин "маршалинг" для передачи данных в автономной форме. Строго говоря, "маршалинг" означает преобразование некоторых данных из внутренней во внешнюю форму (например, в буфере RPC) и "демаршалинг" для обратного процесса.
marshal.dump(value, file, version=version, /, *, allow_code=True):Функция marshal.dump() записывает значение value в открытый файл (аргумент file). Значение value должно быть поддерживаемого типа. Файл должен быть двоичным файлом, открытым на запись.
Если значение value имеет (или содержит объект, который имеет) неподдерживаемый тип, возникает исключение ValueError, при этом в файл также будут записаны мусорные данные. Объект не будет правильно прочитан функцией load(). Объекты кода поддерживаются только в том случае, если значение allow_code равно True.
Аргумент version указывает формат данных, который должен использовать дамп.
Вызывает событие аудита marshal.dumps со значением value, version.
Изменено в Python 3.13: Добавлен параметр allow_code.
marshal.load(file, /, *, allow_code=True):Функция marshal.load() читает одно значение из открытого файла file и возвращает его. Если допустимое значение не считывается (например, потому что данные имеют несовместимый формат версии Python), то возникает исключение EOFError, ValueError или TypeError. Объекты кода поддерживаются только в том случае, если значение allow_code равно True. Файл должен быть двоичным файлом, доступным для чтения.
Примечание. Если объект, содержащий неподдерживаемый тип, был серализован с помощью
marshal.dump(), тоmarshal.load()заменитNoneна несерализированный тип.
Изменено в Python 3.10: Этот вызов обычно поднимал событие аудита
code.__new__для каждого объекта кода. Теперь он поднимает одно событиеmarshal.load()для всей операции загрузки.
Изменено в Python 3.13: добавлен аргумент
allow_code.
marshal.dumps(value, version=version, /, *, allow_code=True):Функция marshal.dumps() возвращает объект bytes, который будет записан в файл с помощью команды marshal.dump(value, file). Значение аргумента value должно быть поддерживаемого типа. Вызывает исключение ValueError, если значение имеет (или содержит объект, который имеет) неподдерживаемый тип. Объекты кода поддерживаются только в том случае, если значение allow_code равно True.
Аргумент version указывает формат данных, который должен использовать дамп.
Вызывает событие аудита marshal.dumps со значением value, version.
Изменено в Python 3.13: Добавлен параметр allow_code.
marshal.loads(bytes, /, *, allow_code=True):Функция marshal.loads() преобразует байтовый объект bytes в значение Python. Если допустимое значение не найдено, то вызываются исключения EOFError, ValueError или TypeError. Объекты кода поддерживаются только в том случае, если значение allow_code равно True. Дополнительные байты во входных данных игнорируются.
Изменено в Python 3.10: Этот вызов обычно поднимал событие аудита
code.__new__для каждого объекта кода. Теперь он поднимает одно событиеmarshal.load()для всей операции загрузки.
Изменено в Python 3.13: добавлен аргумент
allow_code.
marshal.version:Константа marshal.version указывает формат, который использует модуль. Версия 0 - это исторический формат, версия 1 использует встроенные строки, а версия 2 использует двоичный формат для чисел с плавающей запятой. Версия 3 добавляет поддержку создания экземпляров объектов и рекурсии. Текущая версия - 4.