Документация Python неофициальный перевод

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

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

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

Предупреждение

Модуль marshal не предназначен для защиты от ошибочных или вредоносных данных. Никогда не десериализуйте данные, полученные из ненадёжного или неаутентифицированного источника.

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

Предупреждение

На машинах, где тип long int в C имеет более 32 бит (например, DEC Alpha), можно создавать обычные целые Python длиннее 32 бит. Если такое целое число маршалировать и прочитать на машине, где тип long int в C имеет только 32 бита, вместо него будет возвращён объект целого числа произвольной длины (long). Хотя тип различается, числовое значение остаётся тем же. (Это поведение введено в Python 2.2. В более ранних версиях младшие 32 бита значения сохранялись, а остальные терялись, и выводилось предупреждение.)

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

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

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

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

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

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

marshal.load(file)

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