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

Этот модуль содержит функции для чтения и записи значений Python в двоичном формате. Формат специфичен для Python, но независим от архитектуры компьютера (например, вы можете записать значение Python в файл на ПК, переместить файл на Sun и прочитать его обратно). Подробности формата намеренно не документированы; он может меняться между версиями Python (хотя это редко происходит). 1

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

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

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

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

marshal.dump(value, file[, version])

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

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

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

Вызывает событие аудита аудита marshal.dumps с аргументами value, version.

marshal.load(file)

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

Вызывает событие аудита аудита marshal.load без аргументов.

Примечание

Если объект, содержащий неподдерживаемый тип, был маршаллирован с помощью dump(), load() заменит None на немаршаллируемый тип.

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

marshal.dumps(value[, version])

Возвращает объект байтов, который был бы записан в файл функцией dump(value, file). Значение должно быть поддерживаемого типа. Генерирует исключение ValueError, если значение имеет (или содержит объект, который имеет) неподдерживаемый тип.

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

Вызывает событие аудита аудита marshal.dumps с аргументами value, version.

marshal.loads(bytes)

Преобразует объект типа байты в значение. Если не найдено допустимое значение, генерируется исключение EOFError, ValueError или TypeError. Дополнительные байты в входных данных игнорируются.

Вызывает событие аудита аудита marshal.loads с аргументом bytes.

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

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

marshal.version

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

Примечания

1

Название этого модуля происходит от терминологии, используемой разработчиками Modula-3 (и другими), которые используют термин «маршаллинг» для передачи данных в самодостаточном виде. Строго говоря, «маршаллинг» означает преобразование некоторых данных из внутреннего в внешний вид (например, в буфере RPC), а «демаршаллинг» — обратный процесс.