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

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

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

Предупреждение

Модуль marshal не предназначен для защиты от ошибочных или злонамеренно созданных данных. Никогда не отмаршаливайте данные, полученные из недоверенного или неаутентифицированного источника.

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

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

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

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

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

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

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

Поднимает auditing event marshal.dumps с аргументами value, version.

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

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

Прочитайте одно значение из открытого файла и верните его. Если корректное значение не считывается (например, из-за того, что данные имеют несовместимый формат маршала другой версии Python), вызовите сообщение EOFError, ValueError или TypeError. Code objects поддерживаются только в том случае, если allow_code равен true. Файл должен быть читаемым binary file.

Поднимает auditing event 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, если значение имеет (или содержит объект, который имеет) неподдерживаемый тип. Code objects поддерживаются только в том случае, если allow_code равен true.

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

Поднимает auditing event marshal.dumps с аргументами value, version.

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

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

Преобразуйте значение bytes-like object в значение. Если корректное значение не найдено, выведите EOFError, ValueError или TypeError. Code objects поддерживаются только в том случае, если allow_code равен true. Лишние байты во входных данных игнорируются.

Поднимает auditing event marshal.loads с аргументом bytes.

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

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

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

marshal.version

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

Сноски