marshal.md

1> **Источник:** https://python-all.ru/3.16/library/marshal.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `marshal` – внутренняя сериализация объектов Python89---1011Этот модуль содержит функции, которые могут читать и записывать значения Python в двоичном формате. Формат является специфичным для Python, но не зависит от архитектуры машины (например, можно записать значение Python в файл на ПК, перенести файл на Mac и прочитать его там). Детали формата намеренно не документированы; он может меняться между версиями Python (хотя это происходит редко). [\[1\]](https://python-all.ru/3.16/library/marshal.html#id2)1213Это не универсальный модуль «персистентности». Для общего сохранения и передачи объектов Python через RPC-вызовы обратитесь к модулям [`pickle`](https://python-all.ru/3.16/library/pickle.html#module-pickle) и [`shelve`](https://python-all.ru/3.16/library/shelve.html#module-shelve). Модуль `marshal` существует в основном для поддержки чтения и записи «псевдокомпилированного» кода для модулей Python в файлах `.pyc`. Поэтому разработчики Python оставляют за собой право изменять формат marshal обратно несовместимым образом, если возникнет необходимость. Формат объектов кода несовместим между версиями Python, даже если версия формата одинакова. Десериализация объекта кода в неправильной версии Python приводит к неопределенному поведению. Если вы сериализуете и десериализуете объекты Python, используйте вместо этого модуль `pickle` – производительность сопоставима, гарантируется независимость от версии, и pickle поддерживает значительно более широкий диапазон объектов, чем marshal.1415> **Предупреждение**16>17> Модуль `marshal` не предназначен для защиты от ошибочных или вредоносных данных. Никогда не десериализуйте данные, полученные из ненадёжного или неаутентифицированного источника.1819Существуют функции для чтения/записи файлов, а также функции, работающие с байтоподобными объектами.2021Поддерживаются не все типы объектов Python; в целом, только объекты, значение которых не зависит от конкретного запуска Python, могут быть записаны и прочитаны этим модулем. Поддерживаются следующие типы:2223- Числовые типы: [`int`](https://python-all.ru/3.16/library/functions.html#int), [`bool`](https://python-all.ru/3.16/library/functions.html#bool), [`float`](https://python-all.ru/3.16/library/functions.html#float), [`complex`](https://python-all.ru/3.16/library/functions.html#complex).24- Строки ([`str`](https://python-all.ru/3.16/library/stdtypes.html#str)) и [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes). [Байтоподобные объекты](https://python-all.ru/3.16/glossary.html#term-bytes-like-object), такие как [`bytearray`](https://python-all.ru/3.16/library/stdtypes.html#bytearray), маршализируются как `bytes`.25- Контейнеры: [`tuple`](https://python-all.ru/3.16/library/stdtypes.html#tuple), [`list`](https://python-all.ru/3.16/library/stdtypes.html#list), [`dict`](https://python-all.ru/3.16/library/stdtypes.html#dict), [`frozendict`](https://python-all.ru/3.16/library/stdtypes.html#frozendict) (начиная с [`version`](https://python-all.ru/3.16/library/marshal.html#marshal.version) 6), [`set`](https://python-all.ru/3.16/library/stdtypes.html#set), [`frozenset`](https://python-all.ru/3.16/library/stdtypes.html#frozenset) и [`slice`](https://python-all.ru/3.16/library/functions.html#slice) (начиная с `version` 5). Следует понимать, что эти типы поддерживаются, только если поддерживаются содержащиеся в них значения. Рекурсивные контейнеры поддерживаются начиная с `version` 3.26- Синглтоны [`None`](https://python-all.ru/3.16/library/constants.html#None), [`Ellipsis`](https://python-all.ru/3.16/library/constants.html#Ellipsis) и [`StopIteration`](https://python-all.ru/3.16/library/exceptions.html#StopIteration).27- Объекты [`code`](https://python-all.ru/3.16/library/code.html#module-code), если *allow\_code* равен true. См. примечание выше о зависимости от версии.2829Изменено в версии 3.4:3031- Добавлена версия формата 3, которая поддерживает маршалинг рекурсивных списков, множеств и словарей.32- Добавлена версия формата 4, которая поддерживает эффективные представления коротких строк.3334Изменено в версии 3.14: Добавлена версия формата 5, которая позволяет маршалинг срезов.3536Изменено в версии 3.15: Добавлена версия формата 6, которая позволяет маршалинг [`frozendict`](https://python-all.ru/3.16/library/stdtypes.html#frozendict).3738Модуль определяет следующие функции:3940#### `marshal.dump(value, file, version=version, /, *, allow_code=True)`4142Записывает значение в открытый файл. Значение должно быть поддерживаемого типа. Файл должен быть [двоичным файлом для записи](https://python-all.ru/3.16/glossary.html#term-binary-file).4344Если значение имеет (или содержит объект, имеющий) неподдерживаемый тип, вызывается исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) – но в файл также будут записаны мусорные данные. Объект не будет правильно прочитан обратно функцией [`load()`](https://python-all.ru/3.16/library/marshal.html#marshal.load). [Объекты кода](https://python-all.ru/3.16/reference/datamodel.html#code-objects) поддерживаются только если *allow\_code* равен true.4546Аргумент *version* указывает формат данных, который должна использовать `dump` (см. ниже).4748Возбуждает [событие аудита](https://python-all.ru/3.16/library/sys.html#auditing) `marshal.dumps` с аргументами `value`, `version`.4950Изменено в версии 3.13: Добавлен параметр *allow\_code*.5152#### `marshal.load(file, /, *, allow_code=True)`5354Читает одно значение из открытого файла и возвращает его. Если не удаётся прочитать корректное значение (например, из-за несовместимого формата marshal другой версии Python), возбуждается [`EOFError`](https://python-all.ru/3.16/library/exceptions.html#EOFError), [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) или [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). [Объекты кода](https://python-all.ru/3.16/reference/datamodel.html#code-objects) поддерживаются только если *allow\_code* равен true. Файл должен быть [двоичным файлом для чтения](https://python-all.ru/3.16/glossary.html#term-binary-file).5556Возбуждает [событие аудита](https://python-all.ru/3.16/library/sys.html#auditing) `marshal.load` без аргументов.5758> **Примечание**59>60> Если объект, содержащий неподдерживаемый тип, был маршализирован с помощью [`dump()`](https://python-all.ru/3.16/library/marshal.html#marshal.dump), то `load()` подставит `None` вместо немаршализируемого типа.6162Изменено в версии 3.10: Ранее этот вызов генерировал событие аудита `code.__new__` для каждого объекта кода. Теперь он генерирует одно событие `marshal.load` для всей операции загрузки.6364Изменено в версии 3.13: Добавлен параметр *allow\_code*.6566#### `marshal.dumps(value, version=version, /, *, allow_code=True)`6768Возвращает объект bytes, который был бы записан в файл функцией `dump(value, file)`. Значение должно быть поддерживаемого типа. Возбуждает исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), если значение имеет (или содержит объект, имеющий) неподдерживаемый тип. [Объекты кода](https://python-all.ru/3.16/reference/datamodel.html#code-objects) поддерживаются только если *allow\_code* равен true.6970Аргумент *version* указывает формат данных, который должна использовать `dumps` (см. ниже).7172Возбуждает [событие аудита](https://python-all.ru/3.16/library/sys.html#auditing) `marshal.dumps` с аргументами `value`, `version`.7374Изменено в версии 3.13: Добавлен параметр *allow\_code*.7576#### `marshal.loads(bytes, /, *, allow_code=True)`7778Преобразует [байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object) в значение. Если корректное значение не найдено, возбуждается [`EOFError`](https://python-all.ru/3.16/library/exceptions.html#EOFError), [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) или [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). [Объекты кода](https://python-all.ru/3.16/reference/datamodel.html#code-objects) поддерживаются только если *allow\_code* равен true. Лишние байты во входных данных игнорируются.7980Вызывает [событие аудита](https://python-all.ru/3.16/library/sys.html#auditing) `marshal.loads` с аргументом `bytes`.8182Изменено в версии 3.10: Ранее этот вызов генерировал событие аудита `code.__new__` для каждого объекта кода. Теперь он генерирует одно событие `marshal.loads` для всей операции загрузки.8384Изменено в версии 3.13: Добавлен параметр *allow\_code*.8586Кроме того, определены следующие константы:8788#### `marshal.version`8990Указывает формат, который использует модуль. Версия 0 – это историческая первая версия; последующие версии добавляют новые возможности. Обычно новая версия становится версией по умолчанию при её введении.9192| Версия | Доступна начиная с | Новые возможности |93| --- | --- | --- |94| 1 | Python 2.4 | Совместное использование интернированных строк |95| 2 | Python 2.5 | Двоичное представление чисел с плавающей запятой |96| 3 | Python 3.4 | Поддержка создания экземпляров объектов и рекурсии |97| 4 | Python 3.4 | Эффективное представление коротких строк |98| 5 | Python 3.14 | Поддержка объектов [`slice`](https://python-all.ru/3.16/library/functions.html#slice) |99| 6 | Python 3.15 | Поддержка объектов [`frozendict`](https://python-all.ru/3.16/library/stdtypes.html#frozendict) |100101Сноски102103\[[1](https://python-all.ru/3.16/library/marshal.html#id1)\]104105Название этого модуля происходит от терминологии, используемой разработчиками Modula-3 (среди прочих), которые используют термин «marshalling» для передачи данных в самодостаточной форме. Строго говоря, «to marshal» означает преобразование некоторых данных из внутреннего представления во внешнее (например, в буфере RPC), а «unmarshalling» – обратный процесс.106