marshal – внутренняя сериализация объектов Python¶marshal – Internal Python object serialization

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

Это не универсальный модуль «persistence». Для общего сохранения и передачи объектов 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)¶

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

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

Примечание

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

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

marshal.dumps(value[, version])¶

Возвращает объект bytes, который был бы записан в файл функцией 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 (среди прочих), которые используют термин «marshalling» для передачи данных в самодостаточной форме. Строго говоря, «to marshal» означает преобразование некоторых данных из внутреннего представления во внешнее (например, в буфере RPC), а «unmarshalling» – обратный процесс.