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

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

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

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

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

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

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

Записывает значение в открытый файл. Значение должно быть поддерживаемого типа. Файл должен быть открытым объектом файла, таким как sys.stdout или возвращаемым функцией open() или os.popen(). Он не должен быть оболочкой, такой как TemporaryFile в Windows. Он должен быть открыт в двоичном режиме ('wb' или 'w+b').

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

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

marshal.load(file)

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

Примечание

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

marshal.dumps(value[, version])

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

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

marshal.loads(string)

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

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

marshal.version

Указывает формат, используемый модулем. Версия 0 — исторический формат, версия 1 (добавлена в Python 2.4) использует интернированные строки, а версия 2 (добавлена в Python 2.5) использует двоичный формат для чисел с плавающей точкой. Текущая версия — 2.

Новое в версии 2.4.

Сноски

1

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