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.9.7: Этот вызов ранее вызывал событие аудита 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.9.7: Этот вызов ранее вызывал событие аудита code.__new__ для каждого объекта кода. Теперь он вызывает одно событие аудита marshal.loads для всей операции загрузки.

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

marshal.version

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

Примечания

1

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