pickle.md
1> **Источник:** https://python-all.ru/3.11/library/pickle.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) – сериализация объектов Python89**Исходный код:** [Lib/pickle.py](https://python-all.ru/src/3.11/Lib/pickle.py)1011---1213Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) реализует двоичные протоколы для сериализации и de-сериализации структуры объектов Python. *«Упаковка»* – это процесс преобразования иерархии объектов Python в поток байтов, а *«распаковка»* – обратная операция, при которой поток байтов (из [двоичного файла](https://python-all.ru/3.11/glossary.html#term-binary-file) или [байтоподобного объекта](https://python-all.ru/3.11/glossary.html#term-bytes-like-object)) преобразуется обратно в иерархию объектов. Упаковка (и распаковка) также известна как «сериализация», «маршалинг», [\[1\]](https://python-all.ru/3.11/library/pickle.html#id7) или «уплощение»; однако, чтобы избежать путаницы, здесь используются термины «упаковка» и «распаковка».1415> **Предупреждение**16>17> Модуль `pickle` **небезопасен**. Распаковывайте только те данные, которым доверяете.18>19> Существует возможность создать вредоносные данные pickle, которые **выполнят произвольный код во время распаковки**. Никогда не распаковывайте данные, которые могли поступить из ненадёжного источника или могли быть изменены.20>21> Если необходимо гарантировать, что данные не были изменены, рассмотрите их подписание с помощью [`hmac`](https://python-all.ru/3.11/library/hmac.html#module-hmac).22>23> Более безопасные форматы сериализации, такие как [`json`](https://python-all.ru/3.11/library/json.html#module-json), могут быть более подходящими, если вы обрабатываете ненадёжные данные. См. [Сравнение с json](https://python-all.ru/3.11/library/pickle.html#comparison-with-json).2425## Отношение к другим модулям Python2627### Сравнение с `marshal`2829В Python есть более примитивный модуль сериализации [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal), но в целом [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) всегда должен быть предпочтительным способом сериализации объектов Python. [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal) существует в первую очередь для поддержки файлов `.pyc` в Python.3031Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) отличается от [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal) несколькими важными особенностями:3233- Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) отслеживает уже сериализованные объекты, чтобы последующие ссылки на тот же объект не сериализовались повторно. [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal) этого не делает.3435 This has implications both for recursive objects and object sharing. Recursive objects are objects that contain references to themselves. These are not handled by marshal, and in fact, attempting to marshal recursive objects will crash your Python interpreter. Object sharing happens when there are multiple references to the same object in different places in the object hierarchy being serialized. [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) stores such objects only once, and ensures that all other references point to the master copy. Shared objects remain shared, which can be very important for mutable objects.36- [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal) нельзя использовать для сериализации пользовательских классов и их экземпляров. [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) может прозрачно сохранять и восстанавливать экземпляры классов, однако определение класса должно быть импортируемо и находиться в том же модуле, что и при сохранении объекта.37- Формат сериализации [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal) не гарантирует переносимость между версиями Python. Поскольку его основная задача – поддержка файлов `.pyc`, разработчики Python оставляют за собой право изменять формат сериализации несовместимым с предыдущими версиями образом, если возникнет необходимость. Формат сериализации [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) гарантированно обратно совместим между выпусками Python при условии выбора совместимого протокола pickle и обработки различий типов между Python 2 и Python 3 в коде упаковки и распаковки, если ваши данные пересекают эту уникальную границу изменения языка.3839### Сравнение с `json`4041Существуют принципиальные различия между протоколами pickle и [JSON (JavaScript Object Notation)](https://python-all.ru/3.11/library/pickle.html):4243- JSON – это текстовый формат сериализации (он выводит текст в юникоде, хотя чаще всего затем кодируется в `utf-8`), тогда как pickle – двоичный формат сериализации;44- JSON удобочитаем, а pickle – нет;45- JSON интероперабелен и широко используется за пределами экосистемы Python, тогда как pickle является специфичным для Python;46- JSON по умолчанию может представлять только подмножество встроенных типов Python и никаких пользовательских классов; pickle может представлять огромное количество типов Python (многие из них автоматически, благодаря умелому использованию возможностей интроспекции Python; сложные случаи можно решить, реализовав [специфические объектные API](https://python-all.ru/3.11/library/pickle.html#pickle-inst));47- В отличие от pickle, десериализация ненадёжного JSON сама по себе не создаёт уязвимости для выполнения произвольного кода.4849> **См. также**50>51> Модуль [`json`](https://python-all.ru/3.11/library/json.html#module-json): модуль стандартной библиотеки, обеспечивающий сериализацию и десериализацию JSON.5253## Формат потока данных5455Формат данных, используемый [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle), является специфичным для Python. Это даёт преимущество – нет ограничений, накладываемых внешними стандартами вроде JSON или XDR (которые не могут представлять разделяемые указатели); однако это означает, что программы на других языках могут не суметь восстановить объекты Python, сериализованные с помощью pickle.5657По умолчанию формат данных [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) использует относительно компактное двоичное представление. Если вам нужны оптимальные характеристики размера, вы можете эффективно [сжимать](https://python-all.ru/3.11/library/archiving.html) упакованные данные.5859Модуль [`pickletools`](https://python-all.ru/3.11/library/pickletools.html#module-pickletools) содержит инструменты для анализа потоков данных, созданных [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle). Исходный код [`pickletools`](https://python-all.ru/3.11/library/pickletools.html#module-pickletools) содержит обширные комментарии об опкодах, используемых протоколами pickle.6061В настоящее время существует 6 различных протоколов, которые можно использовать для упаковки. Чем выше используемый протокол, тем более новая версия Python требуется для чтения полученного pickle.6263- Протокол версии 0 – это исходный «человекочитаемый» протокол, обратно совместимый с более ранними версиями Python.64- Протокол версии 1 – это старый двоичный формат, также совместимый с более ранними версиями Python.65- Протокол версии 2 был представлен в Python 2.3. Он обеспечивает гораздо более эффективную упаковку [классов нового стиля](https://python-all.ru/3.11/glossary.html#term-new-style-class). Обратитесь к [**PEP 307**](https://python-all.ru/3.11/library/pickle.html) для получения информации об улучшениях, привнесённых протоколом 2.66- Протокол версии 3 был добавлен в Python 3.0. Он имеет явную поддержку объектов [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes) и не может быть распакован в Python 2.x. Это был протокол по умолчанию в Python 3.0–3.7.67- Версия протокола 4 была добавлена в Python 3.4. Она добавляет поддержку очень больших объектов, сериализацию большего количества типов объектов и некоторые оптимизации формата данных. Начиная с Python 3.8 это протокол по умолчанию. Смотрите [**PEP 3154**](https://python-all.ru/3.11/library/pickle.html) для информации об улучшениях, внесённых протоколом 4.68- Версия протокола 5 была добавлена в Python 3.8. Она добавляет поддержку внешних данных и ускорение для внутренних данных. Смотрите [**PEP 574**](https://python-all.ru/3.11/library/pickle.html) для информации об улучшениях, внесённых протоколом 5.6970> **Примечание**71>72> Сериализация – это более примитивное понятие, чем сохранение (persistence); хотя [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) читает и записывает файловые объекты, он не решает ни проблему именования сохраняемых объектов, ни (ещё более сложную) проблему параллельного доступа к сохраняемым объектам. Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) может преобразовать сложный объект в поток байтов и обратно – в объект с той же внутренней структурой. Возможно, самое очевидное применение этих потоков байтов – запись в файл, но также можно передавать их по сети или хранить в базе данных. Модуль [`shelve`](https://python-all.ru/3.11/library/shelve.html#module-shelve) предоставляет простой интерфейс для упаковки (pickle) и распаковки (unpickle) объектов в файлах баз данных в стиле DBM.7374## Интерфейс модуля7576Чтобы сериализовать иерархию объектов, достаточно вызвать функцию [`dumps()`](https://python-all.ru/3.11/library/pickle.html#pickle.dumps). Аналогично, для десериализации потока данных вызывается функция [`loads()`](https://python-all.ru/3.11/library/pickle.html#pickle.loads). Однако если требуется более тонкий контроль над сериализацией и десериализацией, можно создать объект [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) или [`Unpickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler) соответственно.7778Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) предоставляет следующие константы:7980#### `pickle.HIGHEST_PROTOCOL`8182Целое число – наивысшая доступная [версия протокола](https://python-all.ru/3.11/library/pickle.html#pickle-protocols). Это значение можно передавать в качестве аргумента *протокола* функциям [`dump()`](https://python-all.ru/3.11/library/pickle.html#pickle.dump) и [`dumps()`](https://python-all.ru/3.11/library/pickle.html#pickle.dumps), а также конструктору [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler).8384#### `pickle.DEFAULT_PROTOCOL`8586Целое число, [версия протокола](https://python-all.ru/3.11/library/pickle.html#pickle-protocols) по умолчанию, используемая для сериализации. Может быть меньше [`HIGHEST_PROTOCOL`](https://python-all.ru/3.11/library/pickle.html#pickle.HIGHEST_PROTOCOL). В настоящее время протокол по умолчанию – 4, впервые представленный в Python 3.4 и несовместимый с предыдущими версиями.8788Изменено в версии 3.0: Протокол по умолчанию – 3.8990Изменено в версии 3.8: Протокол по умолчанию – 4.9192Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) предоставляет следующие функции для упрощения процесса упаковки:9394#### `pickle.dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)`9596Записывает упакованное представление объекта *obj* в открытый [файловый объект](https://python-all.ru/3.11/glossary.html#term-file-object) *file*. Это эквивалентно `Pickler(file, protocol).dump(obj)`.9798Аргументы *file*, *protocol*, *fix\_imports* и *buffer\_callback* имеют тот же смысл, что и в конструкторе [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler).99100Изменено в версии 3.8: Добавлен аргумент *buffer\_callback*.101102#### `pickle.dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)`103104Возвращает упакованное представление объекта *obj* в виде объекта [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), а не записывает его в файл.105106Аргументы *protocol*, *fix\_imports* и *buffer\_callback* имеют тот же смысл, что и в конструкторе [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler).107108Изменено в версии 3.8: Добавлен аргумент *buffer\_callback*.109110#### `pickle.load(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)`111112Читает упакованное представление объекта из открытого [файлового объекта](https://python-all.ru/3.11/glossary.html#term-file-object) *file* и возвращает восстановленную иерархию объектов, заданную в нём. Это эквивалентно `Unpickler(file).load()`.113114Версия протокола pickle определяется автоматически, поэтому аргумент протокол не требуется. Байты после упакованного представления объекта игнорируются.115116Аргументы *file*, *fix\_imports*, *encoding*, *errors*, *strict* и *buffers* имеют тот же смысл, что и в конструкторе [`Unpickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler).117118Изменено в версии 3.8: Добавлен аргумент *buffers*.119120#### `pickle.loads(data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)`121122Возвращает восстановленную иерархию объектов упакованного представления *data* объекта. *data* должен быть [байтоподобным объектом](https://python-all.ru/3.11/glossary.html#term-bytes-like-object).123124Версия протокола pickle определяется автоматически, поэтому аргумент протокол не требуется. Байты после упакованного представления объекта игнорируются.125126Аргументы *fix\_imports*, *encoding*, *errors*, *strict* и *buffers* имеют тот же смысл, что и в конструкторе [`Unpickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler).127128Изменено в версии 3.8: Добавлен аргумент *buffers*.129130Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) определяет три исключения:131132#### `exception pickle.PickleError`133134Общий базовый класс для остальных исключений pickle. Он наследуется от [`Exception`](https://python-all.ru/3.11/library/exceptions.html#Exception).135136#### `exception pickle.PicklingError`137138Исключение возникает, когда [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) встречает объект, который нельзя упаковать. Оно наследуется от [`PickleError`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleError).139140Обратитесь к разделу [Какие объекты можно упаковывать и распаковывать?](https://python-all.ru/3.11/library/pickle.html#pickle-picklable), чтобы узнать, какие объекты можно упаковывать.141142#### `exception pickle.UnpicklingError`143144Исключение возникает при проблемах с распаковкой объекта, например, при повреждении данных или нарушении безопасности. Оно наследуется от [`PickleError`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleError).145146Обратите внимание, что во время распаковки могут возбуждаться и другие исключения, включая (но не ограничиваясь) AttributeError, EOFError, ImportError и IndexError.147148Модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) экспортирует три класса: [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler), [`Unpickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler) и [`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer):149150#### `class pickle.Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)`151152Он принимает двоичный файл для записи потока данных pickle.153154Необязательный аргумент *протокол* – целое число, указывает упаковщику использовать заданный протокол; поддерживаются протоколы от 0 до [`HIGHEST_PROTOCOL`](https://python-all.ru/3.11/library/pickle.html#pickle.HIGHEST_PROTOCOL). Если аргумент не указан, по умолчанию используется [`DEFAULT_PROTOCOL`](https://python-all.ru/3.11/library/pickle.html#pickle.DEFAULT_PROTOCOL). Если указано отрицательное число, выбирается [`HIGHEST_PROTOCOL`](https://python-all.ru/3.11/library/pickle.html#pickle.HIGHEST_PROTOCOL).155156Аргумент *file* должен иметь метод write(), принимающий единственный аргумент типа bytes. Таким образом, это может быть файл на диске, открытый для двоичной записи, экземпляр [`io.BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO) или любой другой пользовательский объект, соответствующий этому интерфейсу.157158Если *fix\_imports* равен true и *протокол* меньше 3, pickle попытается сопоставить новые имена Python 3 со старыми именами модулей, используемыми в Python 2, чтобы поток данных pickle был читаем в Python 2.159160Если *buffer\_callback* равен None (по умолчанию), то буферные представления сериализуются в *file* как часть потока pickle.161162Если *buffer\_callback* не равен None, то он может быть вызван любое количество раз с буферным представлением. Если колбэк возвращает ложное значение (например None), переданный буфер считается [внеполосным](https://python-all.ru/3.11/library/pickle.html#pickle-oob); в противном случае буфер сериализуется внутриполосно, т.е. внутри потока pickle.163164Ошибка, если *buffer\_callback* не равен None, а *protocol* равен None или меньше 5.165166Изменено в версии 3.8: Добавлен аргумент *buffer\_callback*.167168#### `dump(obj)`169170Записывает упакованное представление *obj* в открытый файловый объект, переданный в конструкторе.171172#### `persistent_id(obj)`173174По умолчанию ничего не делает. Этот метод существует, чтобы подкласс мог его переопределить.175176Если [`persistent_id()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.persistent_id) возвращает `None`, *obj* упаковывается как обычно. Любое другое значение заставляет [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) выдать возвращённое значение в качестве постоянного идентификатора для *obj*. Значение этого постоянного идентификатора должно быть определено [`Unpickler.persistent_load()`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler.persistent_load). Обратите внимание, что значение, возвращаемое [`persistent_id()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.persistent_id), само не может иметь постоянного идентификатора.177178См. [Постоянство внешних объектов](https://python-all.ru/3.11/library/pickle.html#pickle-persistent) для подробностей и примеров использования.179180#### `dispatch_table`181182Таблица диспетчеризации (dispatch table) объекта Pickler – это реестр *функций приведения (reduction functions)*, которые можно объявить с помощью [`copyreg.pickle()`](https://python-all.ru/3.11/library/copyreg.html#copyreg.pickle). Это отображение, где ключами являются классы, а значениями – функции приведения. Функция приведения принимает единственный аргумент соответствующего класса и должна соответствовать тому же интерфейсу, что и метод [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__).183184По умолчанию объект Pickler не имеет атрибута [`dispatch_table`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.dispatch_table), а вместо этого использует глобальную таблицу диспетчеризации, управляемую модулем [`copyreg`](https://python-all.ru/3.11/library/copyreg.html#module-copyreg). Однако для настройки упаковки для конкретного объекта Pickler можно задать атрибут [`dispatch_table`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.dispatch_table) как объект, похожий на словарь. Кроме того, если подкласс [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) имеет атрибут [`dispatch_table`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.dispatch_table), то он будет использоваться в качестве таблицы диспетчеризации по умолчанию для экземпляров этого класса.185186См. [Таблицы диспетчеризации](https://python-all.ru/3.11/library/pickle.html#pickle-dispatch) в качестве примеров использования.187188Новое в версии 3.3.189190#### `reducer_override(obj)`191192Специальная функция приведения, которая может быть определена в подклассах [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler). Этот метод имеет приоритет над любой функцией приведения в [`dispatch_table`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.dispatch_table). Он должен соответствовать тому же интерфейсу, что и метод [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__), и может опционально возвращать [`NotImplemented`](https://python-all.ru/3.11/library/constants.html#NotImplemented) для перехода к функциям приведения, зарегистрированным в [`dispatch_table`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.dispatch_table), чтобы упаковать `obj`.193194Подробный пример см. в [Пользовательское приведение для типов, функций и других объектов](https://python-all.ru/3.11/library/pickle.html#reducer-override).195196Новое в версии 3.8.197198#### `fast`199200Устарело. Включает быстрый режим, если установлено в истинное значение. Быстрый режим отключает использование мемо, ускоряя процесс упаковки за счёт отсутствия лишних op-кодов PUT. Не следует использовать с самореферентными объектами, иначе [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) будет рекурсивно вызывать себя до бесконечности.201202Используйте [`pickletools.optimize()`](https://python-all.ru/3.11/library/pickletools.html#pickletools.optimize), если нужны более компактные упаковки.203204#### `class pickle.Unpickler(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)`205206Принимает бинарный файл для чтения потока данных pickle.207208Версия протокола pickle определяется автоматически, поэтому аргумент протокола не нужен.209210Аргумент *file* должен иметь три метода: read(), который принимает целочисленный аргумент, readinto(), принимающий аргумент-буфер, и readline(), не требующий аргументов, как в интерфейсе [`io.BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase). Таким образом, *file* может быть файлом на диске, открытым для бинарного чтения, объектом [`io.BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO) или любым другим пользовательским объектом, соответствующим этому интерфейсу.211212Необязательные аргументы *fix\_imports*, *encoding* и *errors* используются для управления совместимостью с потоком pickle, созданным Python 2. Если *fix\_imports* истинно, pickle попытается сопоставить старые имена Python 2 с новыми именами, используемыми в Python 3. Аргументы *encoding* и *errors* сообщают pickle, как декодировать 8-битные строковые экземпляры, упакованные Python 2; по умолчанию они равны 'ASCII' и 'strict' соответственно. *encoding* может быть 'bytes' для чтения этих 8-битных строк как байтовых объектов. Использование `encoding='latin1'` требуется для распаковки массивов NumPy и экземпляров [`datetime`](https://python-all.ru/3.11/library/datetime.html#datetime.datetime), [`date`](https://python-all.ru/3.11/library/datetime.html#datetime.date) и [`time`](https://python-all.ru/3.11/library/datetime.html#datetime.time), упакованных Python 2.213214Если *buffers* равен None (по умолчанию), то все необходимые для десериализации данные должны содержаться в потоке pickle. Это означает, что аргумент *buffer\_callback* был равен None, когда экземпляр [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) создавался (или когда вызывались [`dump()`](https://python-all.ru/3.11/library/pickle.html#pickle.dump) или [`dumps()`](https://python-all.ru/3.11/library/pickle.html#pickle.dumps)).215216Если *buffers* не равен None, это должен быть итерируемый объект из объектов с поддержкой буферов, который расходуется каждый раз, когда поток pickle ссылается на [внеполосное](https://python-all.ru/3.11/library/pickle.html#pickle-oob) буферное представление. Такие буферы были переданы по порядку в *buffer\_callback* объекта Pickler.217218Изменено в версии 3.8: Добавлен аргумент *buffers*.219220#### `load()`221222Читает упакованное представление объекта из открытого файлового объекта, переданного конструктору, и возвращает восстановленную иерархию объектов, заданную в нём. Байты после упакованного представления объекта игнорируются.223224#### `persistent_load(pid)`225226По умолчанию вызывает [`UnpicklingError`](https://python-all.ru/3.11/library/pickle.html#pickle.UnpicklingError).227228Если определено, [`persistent_load()`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler.persistent_load) должен возвращать объект, указанный постоянным идентификатором *pid*. Если встречен недопустимый постоянный идентификатор, должно быть вызвано [`UnpicklingError`](https://python-all.ru/3.11/library/pickle.html#pickle.UnpicklingError).229230См. [Постоянство внешних объектов](https://python-all.ru/3.11/library/pickle.html#pickle-persistent) для подробностей и примеров использования.231232#### `find_class(module, name)`233234Импортирует *module* при необходимости и возвращает объект с именем *name* из него, где аргументы *module* и *name* являются объектами [`str`](https://python-all.ru/3.11/library/stdtypes.html#str). Обратите внимание: вопреки названию, [`find_class()`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler.find_class) также используется для поиска функций.235236Подклассы могут переопределить этот метод для получения контроля над тем, объекты какого типа и каким образом могут быть загружены, что потенциально снижает риски безопасности. См. [Ограничение глобальных объектов](https://python-all.ru/3.11/library/pickle.html#pickle-restrict) для подробностей.237238Возбуждает [событие аудита](https://python-all.ru/3.11/library/sys.html#auditing) `pickle.find_class` с аргументами `module`, `name`.239240#### `class pickle.PickleBuffer(buffer)`241242Обёртка для буфера, представляющего данные, которые можно упаковать. *buffer* должен быть объектом, [предоставляющим буфер](https://python-all.ru/3.11/c-api/buffer.html#bufferobjects), например [байтово-подобным объектом](https://python-all.ru/3.11/glossary.html#term-bytes-like-object) или N-мерным массивом.243244[`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer) сам является поставщиком буфера, поэтому его можно передавать другим API, ожидающим объект, предоставляющий буфер, например [`memoryview`](https://python-all.ru/3.11/library/stdtypes.html#memoryview).245246Объекты [`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer) могут быть сериализованы только с использованием протокола pickle 5 или выше. Они подходят для [внеполосной сериализации](https://python-all.ru/3.11/library/pickle.html#pickle-oob).247248Новое в версии 3.8.249250#### `raw()`251252Возвращает [`memoryview`](https://python-all.ru/3.11/library/stdtypes.html#memoryview) области памяти, лежащей в основе этого буфера. Возвращаемый объект представляет собой одномерный, C-непрерывный memoryview с форматом `B` (беззнаковые байты). [`BufferError`](https://python-all.ru/3.11/library/exceptions.html#BufferError) возникает, если буфер не является ни C-, ни Fortran-непрерывным.253254#### `release()`255256Освобождает базовый буфер, предоставленный объектом PickleBuffer.257258## Какие объекты можно сериализовать и десериализовать?259260Следующие типы можно сериализовать:261262- встроенные константы (`None`, `True`, `False`, `Ellipsis` и [`NotImplemented`](https://python-all.ru/3.11/library/constants.html#NotImplemented));263- целые числа, числа с плавающей запятой, комплексные числа;264- строки, байты, байтовые массивы;265- кортежи, списки, множества и словари, содержащие только сериализуемые объекты;266- функции (встроенные и определённые пользователем), доступные на верхнем уровне модуля (через [`def`](https://python-all.ru/3.11/reference/compound_stmts.html#def), а не [`lambda`](https://python-all.ru/3.11/reference/expressions.html#lambda));267- классы, доступные на верхнем уровне модуля;268- экземпляры таких классов, результат вызова [`__getstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__getstate__) которых является упаковываемым (подробнее см. раздел [Упаковка экземпляров классов](https://python-all.ru/3.11/library/pickle.html#pickle-inst)).269270Попытки сериализовать несериализуемые объекты приведут к возникновению исключения [`PicklingError`](https://python-all.ru/3.11/library/pickle.html#pickle.PicklingError); при этом на диск может быть уже записано неизвестное количество байтов. Попытка сериализовать сильно рекурсивную структуру данных может превысить максимальную глубину рекурсии – в этом случае будет возбуждено [`RecursionError`](https://python-all.ru/3.11/library/exceptions.html#RecursionError). Можно аккуратно увеличить этот лимит с помощью [`sys.setrecursionlimit()`](https://python-all.ru/3.11/library/sys.html#sys.setrecursionlimit).271272Обратите внимание, что функции (встроенные и определённые пользователем) сериализуются по полностью [квалифицированному имени](https://python-all.ru/3.11/glossary.html#term-qualified-name), а не по значению. [\[2\]](https://python-all.ru/3.11/library/pickle.html#id8) Это означает, что сериализуется только имя функции, а также имя содержащего модуля и классов. Ни код функции, ни её атрибуты не сериализуются. Поэтому модуль, в котором определена функция, должен быть импортируемым в среде десериализации, и модуль должен содержать указанный объект, иначе будет возбуждено исключение. [\[3\]](https://python-all.ru/3.11/library/pickle.html#id9)273274Аналогичным образом классы сериализуются по полностью квалифицированному имени, поэтому на среду десериализации накладываются те же ограничения. Обратите внимание, что ни код класса, ни его данные не сериализуются, поэтому в следующем примере атрибут класса `attr` не восстанавливается в среде десериализации:275276```python277class Foo:278 attr = 'A class attribute'279280picklestring = pickle.dumps(Foo)281```282283Именно из-за этих ограничений сериализуемые функции и классы должны быть определены на верхнем уровне модуля.284285Аналогично, при сериализации экземпляров классов код и данные самого класса не сериализуются вместе с ними. Сериализуются только данные экземпляра. Это сделано намеренно, чтобы можно было исправить ошибки в классе или добавить в него методы и по-прежнему загружать объекты, созданные с помощью более старой версии класса. Если планируется использовать долгоживущие объекты, которые переживут множество версий класса, будет разумно добавить в объекты номер версии, чтобы можно было выполнять соответствующие преобразования с помощью метода [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__) класса.286287## Сериализация экземпляров классов288289В этом разделе описываются общие механизмы, позволяющие определять, настраивать и контролировать процесс сериализации и десериализации экземпляров классов.290291В большинстве случаев для того, чтобы экземпляры стали сериализуемыми, не требуется дополнительного кода. По умолчанию pickle получает класс и атрибуты экземпляра через интроспекцию. При десериализации экземпляра класса его метод [`__init__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__init__) обычно *не* вызывается. Поведение по умолчанию сначала создаёт неинициализированный экземпляр, а затем восстанавливает сохранённые атрибуты. Следующий код демонстрирует реализацию такого поведения:292293```python294def save(obj):295 return (obj.__class__, obj.__dict__)296297def restore(cls, attributes):298 obj = cls.__new__(cls)299 obj.__dict__.update(attributes)300 return obj301```302303Классы могут изменить поведение по умолчанию, предоставив один или несколько специальных методов:304305#### `object.__getnewargs_ex__()`306307В протоколах 2 и выше классы, реализующие метод [`__getnewargs_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs_ex__), могут задавать значения, передаваемые методу [`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__) при распаковке. Метод должен возвращать пару `(args, kwargs)`, где *args* – кортеж позиционных аргументов, а *kwargs* – словарь именованных аргументов для конструирования объекта. Эти значения будут переданы методу [`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__) при распаковке.308309Этот метод следует реализовать, если метод [`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__) вашего класса требует только именованных аргументов (keyword-only). В противном случае для обеспечения совместимости рекомендуется реализовать [`__getnewargs__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs__).310311Изменено в версии 3.6: [`__getnewargs_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs_ex__) теперь используется в протоколах 2 и 3.312313#### `object.__getnewargs__()`314315Этот метод служит той же цели, что и [`__getnewargs_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs_ex__), но поддерживает только позиционные аргументы. Он должен возвращать кортеж аргументов `args`, который будет передан методу [`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__) при десериализации.316317[`__getnewargs__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs__) не будет вызываться, если определён [`__getnewargs_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs_ex__).318319Изменено в версии 3.6: До Python 3.6 в протоколах 2 и 3 вместо [`__getnewargs_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs_ex__) вызывался [`__getnewargs__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs__).320321#### `object.__getstate__()`322323Классы могут дополнительно влиять на то, как сериализуются их экземпляры, переопределяя метод [`__getstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__getstate__). Этот метод вызывается, и возвращаемый объект сериализуется как содержимое экземпляра вместо состояния по умолчанию. Имеется несколько случаев:324325- Для класса, у которого нет экземпляра [`__dict__`](https://python-all.ru/3.11/library/stdtypes.html#object.__dict__) и нет [`__slots__`](https://python-all.ru/3.11/reference/datamodel.html#object.__slots__), состоянием по умолчанию является `None`.326- Для класса, у которого есть [`__dict__`](https://python-all.ru/3.11/library/stdtypes.html#object.__dict__) экземпляра и нет [`__slots__`](https://python-all.ru/3.11/reference/datamodel.html#object.__slots__), состоянием по умолчанию является `self.__dict__`.327- Для класса, у которого есть [`__dict__`](https://python-all.ru/3.11/library/stdtypes.html#object.__dict__) экземпляра и [`__slots__`](https://python-all.ru/3.11/reference/datamodel.html#object.__slots__), состоянием по умолчанию является кортеж из двух словарей: `self.__dict__` и словаря, отображающего имена слотов в их значения. Во втором словаре присутствуют только слоты, имеющие значение.328- Для класса, у которого есть [`__slots__`](https://python-all.ru/3.11/reference/datamodel.html#object.__slots__) и нет [`__dict__`](https://python-all.ru/3.11/library/stdtypes.html#object.__dict__) экземпляра, состоянием по умолчанию является кортеж, первый элемент которого – `None`, а второй – словарь, отображающий имена слотов в их значения, как описано в предыдущем пункте.329330Изменено в версии 3.11: Добавлена реализация по умолчанию метода `__getstate__()` в классе [`object`](https://python-all.ru/3.11/library/functions.html#object).331332#### `object.__setstate__(state)`333334При распаковке, если класс определяет [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__), он вызывается с распакованным состоянием. В этом случае нет требования, чтобы объект состояния был словарём. В противном случае упакованное состояние должно быть словарём, и его элементы присваиваются словарю нового экземпляра.335336> **Примечание**337>338> Если [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__) возвращает состояние со значением `None` при упаковке, то метод [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__) не будет вызван при распаковке.339340Обратитесь к разделу [Обработка объектов с состоянием](https://python-all.ru/3.11/library/pickle.html#pickle-state) за дополнительной информацией о том, как использовать методы [`__getstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__getstate__) и [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__).341342> **Примечание**343>344> Во время распаковки для экземпляра могут вызываться некоторые методы, такие как [`__getattr__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__getattr__), [`__getattribute__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__getattribute__) или [`__setattr__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__setattr__). Если эти методы полагаются на выполнение некоторого внутреннего инварианта, тип должен реализовать [`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__) для установления такого инварианта, поскольку [`__init__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__init__) не вызывается при распаковке экземпляра.345346Как мы увидим, pickle не использует напрямую описанные выше методы. На самом деле эти методы являются частью протокола копирования, который реализует специальный метод [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__). Протокол копирования предоставляет единый интерфейс для получения данных, необходимых для упаковки и копирования объектов. [\[4\]](https://python-all.ru/3.11/library/pickle.html#id10)347348Хотя реализация [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__) непосредственно в классах является мощной, она чревата ошибками. По этой причине разработчикам классов следует использовать высокоуровневый интерфейс (т.е. [`__getnewargs_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__getnewargs_ex__), [`__getstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__getstate__) и [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__)), когда это возможно. Однако мы покажем случаи, когда использование `__reduce__()` является единственным вариантом или приводит к более эффективной упаковке, или и то и другое.349350#### `object.__reduce__()`351352В настоящее время интерфейс определён следующим образом. Метод [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__) не принимает аргументов и должен возвращать либо строку, либо, желательно, кортеж (возвращаемый объект часто называют «reduce value»).353354Если возвращается строка, она должна интерпретироваться как имя глобальной переменной. Это должно быть локальное имя объекта относительно его модуля; модуль pickle ищет объект в пространстве имён модуля. Такое поведение обычно полезно для одиночек (singletons).355356Если возвращается кортеж, он должен содержать от двух до шести элементов. Необязательные элементы можно опустить или указать в качестве их значения `None`. Семантика каждого элемента следующая (по порядку):357358- Вызываемый объект, который будет вызван для создания начальной версии объекта.359- Кортеж аргументов для вызываемого объекта. Если вызываемый объект не принимает ни одного аргумента, должен быть передан пустой кортеж.360- Необязательно: состояние объекта, которое будет передано методу [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__) объекта, как описано ранее. Если у объекта нет такого метода, то значение должно быть словарём, и оно будет добавлено в атрибут [`__dict__`](https://python-all.ru/3.11/library/stdtypes.html#object.__dict__) объекта.361- Опционально, итератор (не последовательность), выдающий последовательные элементы. Эти элементы будут добавлены к объекту либо с помощью `obj.append(item)`, либо пакетно через `obj.extend(list_of_items)`. В основном это используется для подклассов списка, но может применяться и другими классами, если у них есть [методы append и extend](https://python-all.ru/3.11/library/stdtypes.html#typesseq-common) с соответствующей сигнатурой. (Какой из методов `append()` или `extend()` будет использован, зависит от версии протокола pickle и количества добавляемых элементов, поэтому оба должны поддерживаться.)362- Необязательно: итератор (не последовательность), возвращающий последовательные пары ключ-значение. Эти элементы будут сохранены в объекте с помощью `obj[key] = value`. В основном это используется для подклассов словаря, но может использоваться и другими классами, если они реализуют [`__setitem__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__setitem__).363- Необязательно: вызываемый объект с сигнатурой `(obj, state)`. Этот вызываемый объект позволяет пользователю программно управлять поведением обновления состояния конкретного объекта, вместо использования статического метода [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__) объекта `obj`. Если не указан `None`, этот вызываемый объект будет иметь приоритет над [`__setstate__()`](https://python-all.ru/3.11/library/pickle.html#object.__setstate__) метода `obj`.364365 Новое в версии 3.8: Добавлен необязательный шестой элемент кортежа, `(obj, state)`.366367#### `object.__reduce_ex__(protocol)`368369В качестве альтернативы может быть определён метод [`__reduce_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce_ex__). Единственное отличие состоит в том, что этот метод должен принимать один целочисленный аргумент – версию протокола. Если он определён, pickle будет предпочитать его методу [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__). Кроме того, [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__) автоматически становится синонимом расширенной версии. Основное назначение этого метода – предоставлять обратно совместимые reduce-значения для старых версий Python.370371### Персистентность внешних объектов372373Для обеспечения персистентности объектов модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) поддерживает понятие ссылки на объект вне упакованного потока данных. Такие объекты идентифицируются по постоянному идентификатору (persistent ID), который должен быть либо строкой из буквенно-цифровых символов (для протокола 0), [\[5\]](https://python-all.ru/3.11/library/pickle.html#id11) либо просто произвольным объектом (для любого более нового протокола).374375Разрешение таких постоянных идентификаторов не определяется модулем [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle); он делегирует это разрешение определённым пользователем методам упаковщика и распаковщика, соответственно [`persistent_id()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.persistent_id) и [`persistent_load()`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler.persistent_load).376377Чтобы упаковать объекты, имеющие внешний постоянный идентификатор, упаковщик должен иметь пользовательский метод [`persistent_id()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.persistent_id), который принимает объект в качестве аргумента и возвращает либо `None`, либо постоянный идентификатор для этого объекта. Когда возвращается `None`, упаковщик просто упаковывает объект как обычно. Когда возвращается строка постоянного идентификатора, упаковщик упаковывает этот объект вместе с маркером, чтобы распаковщик распознал его как постоянный идентификатор.378379Чтобы распаковать внешние объекты, распаковщик должен иметь пользовательский метод [`persistent_load()`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler.persistent_load), который принимает объект постоянного идентификатора и возвращает ссылочный объект.380381Вот исчерпывающий пример, показывающий, как постоянный идентификатор может использоваться для упаковки внешних объектов по ссылке.382383```python384# Простой пример, показывающий, как с помощью persistent ID можно упаковать внешние объекты по ссылке.385# внешние объекты по ссылке.386387import pickle388import sqlite3389from collections import namedtuple390391# Простой класс, представляющий запись в нашей базе данных.392MemoRecord = namedtuple("MemoRecord", "key, task")393394class DBPickler(pickle.Pickler):395396 def persistent_id(self, obj):397 # Вместо упаковки MemoRecord как обычного экземпляра класса, мы выводим398 # постоянный идентификатор.399 if isinstance(obj, MemoRecord):400 # Здесь наш постоянный идентификатор – это просто кортеж, содержащий метку и ключ, который ссылается на определённую запись в базе данных.401 # ключ, который ссылается на определённую запись в базе данных.402 return ("MemoRecord", obj.key)403 else:404 # Этот метод вызывается при каждом обнаружении постоянного идентификатора.405 # требуется упаковать как обычно.406 return None407408class DBUnpickler(pickle.Unpickler):409410 def __init__(self, file, connection):411 super().__init__(file)412 self.connection = connection413414 def persistent_load(self, pid):415 # Извлеките запись из базы данных по ссылке и верните её.416 # Всегда возбуждает исключение, если невозможно вернуть правильный объект.417 cursor = self.connection.cursor()418 type_tag, key_id = pid419 if type_tag == "MemoRecord":420 # Извлеките указанную запись из базы данных и верните её.421 cursor.execute("SELECT * FROM memos WHERE key=?", (str(key_id),))422 key, task = cursor.fetchone()423 return MemoRecord(key, task)424 else:425 # Инициализируйте и наполните базу данных.426 # Извлеките записи для упаковки.427 # по постоянному идентификатору.428 raise pickle.UnpicklingError("unsupported persistent object")429430def main():431 import io432 import pprint433434 # Обновите запись для надёжности.435 conn = sqlite3.connect(":memory:")436 cursor = conn.cursor()437 cursor.execute("CREATE TABLE memos(key INTEGER PRIMARY KEY, task TEXT)")438 tasks = (439 'give food to fish',440 'prepare group meeting',441 'fight with a zebra',442 )443 for task in tasks:444 cursor.execute("INSERT INTO memos VALUES(NULL, ?)", (task,))445446 # Извлеките записи, которые требуется упаковать.447 cursor.execute("SELECT * FROM memos")448 memos = [MemoRecord(key, task) for key, task in cursor]449 # Выводит и нумерует строки в текстовом файле.450 file = io.BytesIO()451 DBPickler(file).dump(memos)452453 print("Pickled records:")454 pprint.pprint(memos)455456 # Обновите запись, для верности.457 cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")458459 # Удаляет не подлежащие упаковке записи.460 file.seek(0)461 memos = DBUnpickler(file, conn).load()462463 print("Unpickled records:")464 pprint.pprint(memos)465466if __name__ == '__main__':467 main()468```469470### Диспетчерские таблицы471472Если требуется настроить упаковку некоторых классов, не затрагивая другой код, зависящий от упаковки, можно создать упаковщик с частной диспетчерской таблицей.473474Глобальная диспетчерская таблица, управляемая модулем [`copyreg`](https://python-all.ru/3.11/library/copyreg.html#module-copyreg), доступна как `copyreg.dispatch_table`. Поэтому можно использовать модифицированную копию `copyreg.dispatch_table` в качестве частной диспетчерской таблицы.475476Например477478```python479f = io.BytesIO()480p = pickle.Pickler(f)481p.dispatch_table = copyreg.dispatch_table.copy()482p.dispatch_table[SomeClass] = reduce_SomeClass483```484485создаёт экземпляр [`pickle.Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) с частной диспетчерской таблицей, которая обрабатывает класс `SomeClass` особым образом. В качестве альтернативы код486487```python488class MyPickler(pickle.Pickler):489 dispatch_table = copyreg.dispatch_table.copy()490 dispatch_table[SomeClass] = reduce_SomeClass491f = io.BytesIO()492p = MyPickler(f)493```494495делает то же самое, но все экземпляры `MyPickler` по умолчанию будут использовать общую частную диспетчерскую таблицу. С другой стороны, код496497```python498copyreg.pickle(SomeClass, reduce_SomeClass)499f = io.BytesIO()500p = pickle.Pickler(f)501```502503изменяет глобальную диспетчерскую таблицу, общую для всех пользователей модуля [`copyreg`](https://python-all.ru/3.11/library/copyreg.html#module-copyreg).504505### Обработка объектов с состоянием506507Вот пример, показывающий, как изменить поведение упаковки (pickling) для класса. Класс `TextReader` ниже открывает текстовый файл и возвращает номер строки и содержимое строки каждый раз, когда вызывается его метод `readline()`. Если экземпляр `TextReader` упаковывается, сохраняются все атрибуты, *кроме* члена-файлового объекта. При распаковке экземпляра файл открывается заново и чтение продолжается с последней позиции. Методы `__setstate__()` и `__getstate__()` используются для реализации этого поведения.508509```python510class TextReader:511 """Вывести и пронумеровать строки в текстовом файле."""512513 def __init__(self, filename):514 self.filename = filename515 self.file = open(filename)516 self.lineno = 0517518 def readline(self):519 self.lineno += 1520 line = self.file.readline()521 if not line:522 return None523 if line.endswith('\n'):524 line = line[:-1]525 return "%i: %s" % (self.lineno, line)526527 def __getstate__(self):528 # Восстанавливает состояние ранее открытого файла. Для этого необходимо открыть его заново и читать, пока не будет восстановлено количество строк.529 # Наконец, сохраняет файл.530 # метод, чтобы избежать изменения исходного состояния.531 state = self.__dict__.copy()532 # Для любого другого объекта используйте обычную редукцию.533 del state['file']534 return state535536 def __setstate__(self, state):537 # Восстановить атрибуты экземпляра (например, filename и lineno).538 self.__dict__.update(state)539 # Получить дескриптор исходного буферного объекта.540 # открыть его заново и читать, пока количество строк не восстановится.541 file = open(self.filename)542 for _ in range(self.lineno):543 file.readline()544 # Наконец, сохраните файл.545 self.file = file546```547548Пример использования может выглядеть так:549550```python551>>> reader = TextReader("hello.txt")552>>> reader.readline()553'1: Hello world!'554>>> reader.readline()555'2: I am line number two.'556>>> new_reader = pickle.loads(pickle.dumps(reader))557>>> new_reader.readline()558'3: Goodbye!'559```560561## Настраиваемая редукция для типов, функций и других объектов562563Новое в версии 3.8.564565Иногда [`dispatch_table`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.dispatch_table) может быть недостаточно гибким. В частности, может потребоваться настроить упаковку на основе другого критерия, а не только типа объекта, или настроить упаковку функций и классов.566567Для таких случаев можно создать подкласс класса [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) и реализовать метод [`reducer_override()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.reducer_override). Этот метод может возвращать произвольный кортеж редукции (см. [`__reduce__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce__)). Кроме того, он может возвращать [`NotImplemented`](https://python-all.ru/3.11/library/constants.html#NotImplemented) для возврата к традиционному поведению.568569Если определены оба метода [`dispatch_table`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.dispatch_table) и [`reducer_override()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.reducer_override), то приоритет имеет метод [`reducer_override()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.reducer_override).570571> **Примечание**572>573> Из соображений производительности [`reducer_override()`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler.reducer_override) может не вызываться для следующих объектов: `None`, `True`, `False`, а также для точных экземпляров [`int`](https://python-all.ru/3.11/library/functions.html#int), [`float`](https://python-all.ru/3.11/library/functions.html#float), [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), [`dict`](https://python-all.ru/3.11/library/stdtypes.html#dict), [`set`](https://python-all.ru/3.11/library/stdtypes.html#set), [`frozenset`](https://python-all.ru/3.11/library/stdtypes.html#frozenset), [`list`](https://python-all.ru/3.11/library/stdtypes.html#list) и [`tuple`](https://python-all.ru/3.11/library/stdtypes.html#tuple).574575Вот простой пример, где разрешается упаковка и восстановление заданного класса:576577```python578import io579import pickle580581class MyClass:582 my_attribute = 1583584class MyPickler(pickle.Pickler):585 def reducer_override(self, obj):586 """Пользовательский редуктор для MyClass."""587 if getattr(obj, "__name__", None) == "MyClass":588 return type, (obj.__name__, obj.__bases__,589 {'my_attribute': obj.my_attribute})590 else:591 # Для любого другого объекта используется обычная редукция.592 return NotImplemented593594f = io.BytesIO()595p = MyPickler(f)596p.dump(MyClass)597598del MyClass599600unpickled_class = pickle.loads(f.getvalue())601602assert isinstance(unpickled_class, type)603assert unpickled_class.__name__ == "MyClass"604assert unpickled_class.my_attribute == 1605```606607## Буферы внеполосной передачи608609Новое в версии 3.8.610611В некоторых контекстах модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) используется для передачи больших объёмов данных. Поэтому может быть важно минимизировать количество копирований памяти, чтобы сохранить производительность и расход ресурсов. Однако нормальная работа модуля [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle), преобразующего графоподобную структуру объектов в последовательный поток байтов, по своей сути включает копирование данных в поток pickle и из него.612613Этого ограничения можно избежать, если и *поставщик* (реализация типов объектов для передачи), и *потребитель* (реализация системы связи) поддерживают механизмы внеполосной передачи, предоставляемые протоколом pickle версии 5 и выше.614615### API поставщика616617Крупные объекты данных, подлежащие упаковке, должны реализовывать метод [`__reduce_ex__()`](https://python-all.ru/3.11/library/pickle.html#object.__reduce_ex__), специализированный для протокола 5 и выше, который возвращает экземпляр [`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer) (вместо, например, объекта [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes)) для любых больших данных.618619Объект [`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer) *сигнализирует*, что соответствующий буфер пригоден для внеполосной передачи данных. Эти объекты остаются совместимыми с обычным использованием модуля [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle). Однако потребители также могут согласиться сообщить [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle), что они будут обрабатывать эти буферы самостоятельно.620621### API потребителя622623Система связи может включить настраиваемую обработку объектов [`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer), создаваемых при сериализации графа объектов.624625На стороне отправителя необходимо передать аргумент *buffer\_callback* в [`Pickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Pickler) (или в функцию [`dump()`](https://python-all.ru/3.11/library/pickle.html#pickle.dump) или [`dumps()`](https://python-all.ru/3.11/library/pickle.html#pickle.dumps)), который будет вызываться для каждого [`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer), генерируемого при упаковке графа объектов. Буферы, накопленные *buffer\_callback*, не будут скопированы в поток pickle – будет вставлен только дешёвый маркер.626627На стороне получателя необходимо передать аргумент *buffers* в [`Unpickler`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler) (или в функцию [`load()`](https://python-all.ru/3.11/library/pickle.html#pickle.load) или [`loads()`](https://python-all.ru/3.11/library/pickle.html#pickle.loads)), который является итерируемым объектом с буферами, переданными в *buffer\_callback*. Этот итерируемый объект должен выдавать буферы в том же порядке, в котором они были переданы в *buffer\_callback*. Эти буферы предоставят данные, ожидаемые восстановителями объектов, чья упаковка породила исходные объекты [`PickleBuffer`](https://python-all.ru/3.11/library/pickle.html#pickle.PickleBuffer).628629Между отправляющей и принимающей сторонами система связи может реализовать собственный механизм передачи для внеполосных буферов. Потенциальные оптимизации включают использование общей памяти или сжатия, зависящего от типа данных.630631### Пример632633Вот тривиальный пример, где мы реализуем подкласс [`bytearray`](https://python-all.ru/3.11/library/stdtypes.html#bytearray), способный участвовать во внеполосной упаковке буферов:634635```python636class ZeroCopyByteArray(bytearray):637638 def __reduce_ex__(self, protocol):639 if protocol >= 5:640 return type(self)._reconstruct, (PickleBuffer(self),), None641 else:642 # PickleBuffer запрещён для протоколов pickle <= 4.643 return type(self)._reconstruct, (bytearray(self),)644645 @classmethod646 def _reconstruct(cls, obj):647 with memoryview(obj) as m:648 # Получить дескриптор исходного буферного объекта.649 obj = m.obj650 if type(obj) is cls:651 # Исходный буферный объект – это ZeroCopyByteArray, вернуть его.652 # как есть.653 return obj654 else:655 return cls(obj)656```657658Восстановитель (метод класса `_reconstruct`) возвращает объект, предоставляющий буфер, если он имеет правильный тип. Это простой способ имитировать поведение с нулевым копированием в этом игрушечном примере.659660На стороне потребителя мы можем упаковать эти объекты обычным способом, который при десериализации даст нам копию исходного объекта:661662```python663b = ZeroCopyByteArray(b"abc")664data = pickle.dumps(b, protocol=5)665new_b = pickle.loads(data)666print(b == new_b) # True667print(b is new_b) # False: создана копия668```669670Но если мы передадим *buffer\_callback*, а затем вернём накопленные буферы при десериализации, мы сможем получить обратно исходный объект:671672```python673b = ZeroCopyByteArray(b"abc")674buffers = []675data = pickle.dumps(b, protocol=5, buffer_callback=buffers.append)676new_b = pickle.loads(data, buffers=buffers)677print(b == new_b) # True678print(b is new_b) # True: копия не создана679```680681Этот пример ограничен тем, что [`bytearray`](https://python-all.ru/3.11/library/stdtypes.html#bytearray) выделяет свою собственную память: нельзя создать экземпляр [`bytearray`](https://python-all.ru/3.11/library/stdtypes.html#bytearray), основанный на памяти другого объекта. Однако сторонние типы данных, такие как массивы NumPy, не имеют этого ограничения и позволяют использовать упаковку с нулевым копированием (или с минимальным количеством копий) при передаче между разными процессами или системами.682683> **См. также**684>685> [**PEP 574**](https://python-all.ru/3.11/library/pickle.html) – Протокол pickle 5 с внеполосными данными686687## Ограничение глобалов688689По умолчанию распаковщик импортирует любой класс или функцию, найденные в данных pickle. Для многих приложений такое поведение неприемлемо, поскольку оно позволяет распаковщику импортировать и вызывать произвольный код. Просто подумайте, что делает этот вручную созданный поток данных pickle при загрузке:690691```python692>>> import pickle693>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")694hello world6950696```697698В этом примере распаковщик импортирует функцию [`os.system()`](https://python-all.ru/3.11/library/os.html#os.system), а затем применяет строковый аргумент «echo hello world». Хотя этот пример безобиден, нетрудно представить такой, который может нанести вред вашей системе.699700По этой причине может потребоваться контролировать, что распаковывается, с помощью настройки [`Unpickler.find_class()`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler.find_class). Вопреки своему названию, [`Unpickler.find_class()`](https://python-all.ru/3.11/library/pickle.html#pickle.Unpickler.find_class) вызывается всякий раз, когда запрашивается глобальный объект (т.е. класс или функция). Таким образом, можно либо полностью запретить глобалы, либо ограничить их безопасным подмножеством.701702Вот пример распаковщика, который разрешает загрузку только нескольких безопасных классов из модуля [`builtins`](https://python-all.ru/3.11/library/builtins.html#module-builtins):703704```python705import builtins706import io707import pickle708709safe_builtins = {710 'range',711 'complex',712 'set',713 'frozenset',714 'slice',715}716717class RestrictedUnpickler(pickle.Unpickler):718719 def find_class(self, module, name):720 # Разрешать только безопасные классы из builtins.721 if module == "builtins" and name in safe_builtins:722 return getattr(builtins, name)723 # Запрещать всё остальное.724 raise pickle.UnpicklingError("global '%s.%s' is forbidden" %725 (module, name))726727def restricted_loads(s):728 """Вспомогательная функция, аналогичная pickle.loads()."""729 return RestrictedUnpickler(io.BytesIO(s)).load()730```731732Пример использования нашего распаковщика, работающего как задумано:733734```python735>>> restricted_loads(pickle.dumps([1, 2, range(15)]))736[1, 2, range(0, 15)]737>>> restricted_loads(b"cos\nsystem\n(S'echo hello world'\ntR.")738Traceback (most recent call last):739 ...740pickle.UnpicklingError: global 'os.system' is forbidden741>>> restricted_loads(b'cbuiltins\neval\n'742... b'(S\'getattr(__import__("os"), "system")'743... b'("echo hello world")\'\ntR.')744Traceback (most recent call last):745 ...746pickle.UnpicklingError: global 'builtins.eval' is forbidden747```748749Как показывают наши примеры, нужно быть осторожным с тем, что разрешается распаковывать. Поэтому если безопасность важна, стоит рассмотреть альтернативы, такие как marshalling API в модуле [`xmlrpc.client`](https://python-all.ru/3.11/library/xmlrpc.client.html#module-xmlrpc.client) или сторонние решения.750751## Производительность752753Последние версии протокола pickle (начиная с протокола 2) поддерживают эффективное бинарное кодирование для ряда распространённых возможностей и встроенных типов. Кроме того, модуль [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle) имеет прозрачный оптимизатор, написанный на C.754755## Примеры756757Для простейшего кода используйте функции [`dump()`](https://python-all.ru/3.11/library/pickle.html#pickle.dump) и [`load()`](https://python-all.ru/3.11/library/pickle.html#pickle.load).758759```python760import pickle761762# Произвольный набор объектов, поддерживаемых pickle.763data = {764 'a': [1, 2.0, 3+4j],765 'b': ("character string", b"byte string"),766 'c': {None, True, False}767}768769with open('data.pickle', 'wb') as f:770 # Запаковать словарь 'data', используя самый высокий доступный протокол.771 pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)772```773774Следующий пример читает полученные сериализованные данные.775776```python777import pickle778779with open('data.pickle', 'rb') as f:780 # Версия используемого протокола определяется автоматически, поэтому781 # указывать её не нужно.782 data = pickle.load(f)783```784785> **См. также**786>787> **Модуль [`copyreg`](https://python-all.ru/3.11/library/copyreg.html#module-copyreg)**788>789> Регистрация конструктора интерфейса pickle для расширенных типов.790>791> **Модуль [`pickletools`](https://python-all.ru/3.11/library/pickletools.html#module-pickletools)**792>793> Инструменты для работы и анализа сериализованных данных.794>795> **Модуль [`shelve`](https://python-all.ru/3.11/library/shelve.html#module-shelve)**796>797> Индексированные базы данных объектов; использует [`pickle`](https://python-all.ru/3.11/library/pickle.html#module-pickle).798>799> **Модуль [`copy`](https://python-all.ru/3.11/library/copy.html#module-copy)**800>801> Поверхностное и глубокое копирование объектов.802>803> **Модуль [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal)**804>805> Высокопроизводительная сериализация встроенных типов.806807Сноски808809\[[1](https://python-all.ru/3.11/library/pickle.html#id1)\]810811Не путайте это с модулем [`marshal`](https://python-all.ru/3.11/library/marshal.html#module-marshal)812813\[[2](https://python-all.ru/3.11/library/pickle.html#id3)\]814815Вот почему функции [`lambda`](https://python-all.ru/3.11/reference/expressions.html#lambda) нельзя сериализовать: все функции `lambda` имеют одно и то же имя: `<lambda>`.816817\[[3](https://python-all.ru/3.11/library/pickle.html#id4)\]818819Возникающее исключение, скорее всего, будет [`ImportError`](https://python-all.ru/3.11/library/exceptions.html#ImportError) или [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError), но может быть и другим.820821\[[4](https://python-all.ru/3.11/library/pickle.html#id5)\]822823Модуль [`copy`](https://python-all.ru/3.11/library/copy.html#module-copy) использует этот протокол для операций поверхностного и глубокого копирования.824825\[[5](https://python-all.ru/3.11/library/pickle.html#id6)\]826827Ограничение на буквенно-цифровые символы связано с тем, что постоянные идентификаторы в протоколе 0 разделяются символом новой строки. Поэтому если в постоянных идентификаторах встречаются символы новой строки, результирующие сериализованные данные станут нечитаемыми.828