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])¶

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

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

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

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

marshal.load(file)¶

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

Вызывает auditing event marshal.load без аргументов.

Примечание

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

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

marshal.dumps(value[, version])¶

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

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

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

marshal.loads(bytes)¶

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

Вызывает auditing event marshal.loads с аргументом bytes.

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

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

marshal.version¶

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

Сноски

1

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