pickle.md
1> **Источник:** https://python-all.ru/3.1/library/pickle.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 11.1. `pickle` – сериализация объектов Python89Модуль `pickle` реализует фундаментальный, но мощный алгоритм сериализации и десериализации структуры объектов Python. «Pickling» – это процесс преобразования иерархии объектов Python в поток байтов, а «unpickling» – обратная операция, при которой поток байтов преобразуется обратно в иерархию объектов. Pickling (и unpickling) также известен как «сериализация», «маршалинг» [\[1\]](https://python-all.ru/3.1/library/pickle.html#id5) или «уплощение», однако во избежание путаницы здесь используются термины «pickling» и «unpickling».1011> **Предупреждение**12>13> Модуль `pickle` не предназначен для защиты от ошибочных или злонамеренно сформированных данных. Никогда не распаковывайте данные, полученные из ненадёжного или неаутентифицированного источника.1415## 11.1.1. Отношение к другим модулям Python1617Модуль `pickle` имеет прозрачный оптимизатор (`_pickle`), написанный на C. Он используется, когда доступен. В противном случае используется реализация на чистом Python.1819В Python есть более примитивный модуль сериализации под названием [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal), но в целом `pickle` всегда должен быть предпочтительным способом сериализации объектов Python. [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal) существует в первую очередь для поддержки `.pyc`-файлов Python.2021Модуль `pickle` отличается от [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal) в нескольких существенных аспектах:2223- Модуль `pickle` отслеживает уже сериализованные объекты, чтобы последующие ссылки на тот же объект не сериализовались повторно. [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal) этого не делает.2425 Это влияет как на рекурсивные объекты, так и на разделение объектов. Рекурсивные объекты – это объекты, содержащие ссылки на самих себя. Они не обрабатываются marshal, и более того, попытка маршалировать рекурсивные объекты приведёт к аварийному завершению интерпретатора Python. Разделение объектов (object sharing) происходит, когда на один и тот же объект есть несколько ссылок в разных местах сериализуемой иерархии объектов. `pickle` сохраняет такие объекты только один раз и гарантирует, что все остальные ссылки указывают на главную копию. Разделяемые объекты остаются разделяемыми, что может быть очень важно для изменяемых объектов.26- [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal) нельзя использовать для сериализации пользовательских классов и их экземпляров. `pickle` может прозрачно сохранять и восстанавливать экземпляры классов, однако определение класса должно быть импортируемым и находиться в том же модуле, что и при сохранении объекта.27- Формат сериализации [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal) не гарантирует переносимости между версиями Python. Поскольку его основная задача – поддержка файлов `.pyc`, разработчики Python оставляют за собой право изменять формат сериализации несовместимым с предыдущими версиями образом, если возникнет необходимость. Формат сериализации `pickle` гарантированно обратно совместим с разными выпусками Python.2829Обратите внимание, что сериализация – это более примитивное понятие, чем сохранение (persistence); хотя `pickle` читает и записывает файловые объекты, он не решает проблему именования сохраняемых объектов, ни (ещё более сложную) проблему конкурентного доступа к сохраняемым объектам. Модуль `pickle` может преобразовать сложный объект в поток байтов и обратно – из потока байтов в объект с той же внутренней структурой. Самое очевидное, что можно сделать с этими потоками байтов – записать их в файл, но также можно передать их по сети или сохранить в базе данных. Модуль [`shelve`](https://python-all.ru/3.1/library/shelve.html#module-shelve) предоставляет простой интерфейс для упаковки (pickle) и распаковки (unpickle) объектов в файлах баз данных в стиле DBM.3031## 11.1.2. Формат потока данных3233Формат данных, используемый `pickle`, является специфичным для Python. Это даёт преимущество: отсутствуют ограничения, накладываемые внешними стандартами, такими как XDR (который не может представлять разделение указателей); однако это означает, что программы на других языках могут не смочь восстановить упакованные (pickled) объекты Python.3435По умолчанию формат данных `pickle` использует компактное двоичное представление. Модуль [`pickletools`](https://python-all.ru/3.1/library/pickletools.html#module-pickletools) содержит инструменты для анализа потоков данных, созданных `pickle`.3637В настоящее время существует 4 различных протокола для упаковки.3839- Версия протокола 0 – это исходный человекочитаемый протокол, который обратно совместим с ранними версиями Python.40- Версия протокола 1 – это старый двоичный формат, также совместимый с ранними версиями Python.41- Версия протокола 2 была представлена в Python 2.3. Она обеспечивает гораздо более эффективную упаковку (pickling) [*классов нового стиля*](https://python-all.ru/3.1/glossary.html#term-new-style-class).42- Версия протокола 3 была добавлена в Python 3.0. Она имеет явную поддержку байтов (bytes) и не может быть распакована модулями pickle Python 2.x. Это текущий рекомендуемый протокол, используйте его, когда это возможно.4344Смотрите [**PEP 307**](https://python-all.ru/3.1/library/pickle.html) для получения информации об улучшениях, внесённых протоколом 2. См. исходный код [`pickletools`](https://python-all.ru/3.1/library/pickletools.html#module-pickletools) для подробных комментариев об опкодах, используемых протоколами pickle.4546## 11.1.3. Интерфейс модуля4748Чтобы сериализовать иерархию объектов, сначала создаётся объект Pickler, затем вызывается его метод [`dump()`](https://python-all.ru/3.1/library/pickle.html#pickle.dump). Для десериализации потока данных сначала создаётся Unpickler, затем вызывается его метод [`load()`](https://python-all.ru/3.1/library/pickle.html#pickle.load). Модуль `pickle` предоставляет следующую константу:4950#### `pickle.HIGHEST_PROTOCOL`5152Самая высокая доступная версия протокола. Это значение можно передать как аргумент5354*protocol*5556.5758#### `pickle.DEFAULT_PROTOCOL`5960Протокол, используемый по умолчанию для упаковки (pickling). Может быть меньше, чем HIGHEST\_PROTOCOL. В настоящее время протокол по умолчанию – 3; это протокол, не обратно совместимый, предназначенный для Python 3.0.6162Модуль `pickle` предоставляет следующие функции для упрощения процесса упаковки (pickling):6364#### `pickle.dump(obj, file[, protocol, *, fix_imports=True])`6566Записывает упакованное (pickled) представление объекта *obj* в открытый [*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object) *file*. Это эквивалентно вызову `Pickler(file, protocol).dump(obj)`.6768Необязательный аргумент *protocol* указывает упаковщику использовать заданный протокол; поддерживаются протоколы 0, 1, 2, 3. Протокол по умолчанию – 3; это обратно несовместимый протокол, разработанный для Python 3.0.6970Указание отрицательной версии протокола выбирает самую высокую поддерживаемую версию протокола. Чем выше используемый протокол, тем более новая версия Python требуется для чтения созданного pickle.7172Аргумент *file* должен иметь метод write(), принимающий один аргумент типа bytes. Таким образом, это может быть файл на диске, открытый для бинарной записи, экземпляр [`io.BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO) или любой другой пользовательский объект, соответствующий этому интерфейсу.7374Если *fix\_imports* равен True и *протокол* меньше 3, pickle попытается отобразить новые имена Python 3.x на старые имена модулей, используемые в Python 2.x, чтобы поток данных pickle был читаем в Python 2.x.7576#### `pickle.dumps(obj[, protocol, *, fix_imports=True])`7778Возвращает сериализованное представление объекта в виде объекта [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) вместо записи в файл.7980Необязательный аргумент *protocol* указывает упаковщику использовать заданный протокол; поддерживаются протоколы 0, 1, 2, 3. Протокол по умолчанию – 3; это обратно несовместимый протокол, разработанный для Python 3.0.8182Указание отрицательной версии протокола выбирает самую высокую поддерживаемую версию протокола. Чем выше используемый протокол, тем более новая версия Python требуется для чтения созданного pickle.8384Если *fix\_imports* равен True и *протокол* меньше 3, pickle попытается отобразить новые имена Python 3.x на старые имена модулей, используемые в Python 2.x, чтобы поток данных pickle был читаем в Python 2.x.8586#### `pickle.load(file[, *, fix_imports=True, encoding="ASCII", errors="strict"])`8788Читает сериализованное представление объекта из открытого [*файлового объекта*](https://python-all.ru/3.1/glossary.html#term-file-object) *file* и возвращает восстановленную иерархию объектов, указанную в нём. Это эквивалентно `Unpickler(file).load()`.8990Версия протокола pickle определяется автоматически, поэтому аргумент protocol не требуется. Байты, следующие за представлением сериализованного объекта, игнорируются.9192Аргумент *file* должен иметь два метода: read(), принимающий целочисленный аргумент, и readline(), не требующий аргументов. Оба метода должны возвращать bytes. Таким образом, *file* может быть файлом на диске, открытым для бинарного чтения, объектом [`io.BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO) или любым другим пользовательским объектом, соответствующим этому интерфейсу.9394Необязательными именованными аргументами являются *fix\_imports*, *encoding* и *errors*, которые используются для управления совместимостью с потоками pickle, созданными Python 2.x. Если *fix\_imports* равен True, pickle попытается отобразить старые имена Python 2.x на новые имена, используемые в Python 3.x. Аргументы *encoding* и *errors* указывают pickle, как декодировать экземпляры 8-битных строк, упакованные Python 2.x; по умолчанию они равны 'ASCII' и 'strict' соответственно.9596#### `pickle.loads(bytes_object[, *, fix_imports=True, encoding="ASCII", errors="strict"])`9798Читает сериализованную иерархию объектов из объекта [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) и возвращает восстановленную иерархию объектов, содержащуюся в нём.99100Версия протокола pickle определяется автоматически, поэтому аргумент protocol не требуется. Байты, следующие за представлением сериализованного объекта, игнорируются.101102Необязательными именованными аргументами являются *fix\_imports*, *encoding* и *errors*, которые используются для управления совместимостью с потоками pickle, созданными Python 2.x. Если *fix\_imports* равен True, pickle попытается отобразить старые имена Python 2.x на новые имена, используемые в Python 3.x. Аргументы *encoding* и *errors* указывают pickle, как декодировать экземпляры 8-битных строк, упакованные Python 2.x; по умолчанию они равны 'ASCII' и 'strict' соответственно.103104Модуль `pickle` определяет три исключения:105106#### `exception pickle.PickleError`107108Общий базовый класс для других исключений при упаковке. Наследует109110[`Exception`](https://python-all.ru/3.1/library/exceptions.html#Exception)111112.113114#### `exception pickle.PicklingError`115116Исключение, возникающее при обнаружении [`Pickler`](https://python-all.ru/3.1/library/pickle.html#pickle.Pickler) объекта, который невозможно упаковать. Наследует [`PickleError`](https://python-all.ru/3.1/library/pickle.html#pickle.PickleError).117118Обратитесь к разделу [*Какие объекты можно упаковывать и распаковывать?*](https://python-all.ru/3.1/library/pickle.html#pickle-picklable), чтобы узнать, какие объекты можно упаковывать.119120#### `exception pickle.UnpicklingError`121122Исключение, возникающее при проблеме распаковки (unpickling) объекта, например, при повреждении данных или нарушении безопасности. Наследует [`PickleError`](https://python-all.ru/3.1/library/pickle.html#pickle.PickleError).123124Обратите внимание, что во время распаковки могут возбуждаться и другие исключения, включая (но не ограничиваясь) AttributeError, EOFError, ImportError и IndexError.125126Модуль `pickle` экспортирует два класса: [`Pickler`](https://python-all.ru/3.1/library/pickle.html#pickle.Pickler) и [`Unpickler`](https://python-all.ru/3.1/library/pickle.html#pickle.Unpickler):127128#### `class pickle.Pickler(file[, protocol, *, fix_imports=True])`129130Он принимает двоичный файл для записи потока данных pickle.131132Необязательный аргумент *protocol* указывает упаковщику использовать заданный протокол; поддерживаются протоколы 0, 1, 2, 3. Протокол по умолчанию – 3; это обратно несовместимый протокол, разработанный для Python 3.0.133134Указание отрицательной версии протокола выбирает самую высокую поддерживаемую версию протокола. Чем выше используемый протокол, тем более новая версия Python требуется для чтения созданного pickle.135136Аргумент *file* должен иметь метод write(), принимающий один аргумент типа bytes. Таким образом, это может быть файл на диске, открытый для бинарной записи, экземпляр [`io.BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO) или любой другой пользовательский объект, соответствующий этому интерфейсу.137138Если *fix\_imports* равен True и *протокол* меньше 3, pickle попытается отобразить новые имена Python 3.x на старые имена модулей, используемые в Python 2.x, чтобы поток данных pickle был читаем в Python 2.x.139140#### `dump(obj)`141142Записывает представление143144*obj*145146в виде pickle в открытый объект файла, переданный в конструкторе.147148#### `persistent_id(obj)`149150По умолчанию ничего не делает. Этот метод существует, чтобы подкласс мог его переопределить.151152Если [`persistent_id()`](https://python-all.ru/3.1/library/pickle.html#pickle.Pickler.persistent_id) возвращает `None`, *obj* упаковывается обычным образом. Любое другое значение заставляет [`Pickler`](https://python-all.ru/3.1/library/pickle.html#pickle.Pickler) выдать это значение как постоянный идентификатор для *obj*. Смысл этого постоянного идентификатора должен быть определён [`Unpickler.persistent_load()`](https://python-all.ru/3.1/library/pickle.html#pickle.Unpickler.persistent_load). Обратите внимание, что значение, возвращаемое [`persistent_id()`](https://python-all.ru/3.1/library/pickle.html#pickle.Pickler.persistent_id), само не может иметь постоянный идентификатор.153154См. [*Постоянство внешних объектов*](https://python-all.ru/3.1/library/pickle.html#pickle-persistent) для подробностей и примеров использования.155156#### `fast`157158Устарело. При установке в истинное значение включает быстрый режим. Быстрый режим отключает использование memo, тем самым ускоряя процесс упаковки за счёт отсутствия лишних кодов операций PUT. Его не следует использовать с самореферентными объектами, иначе [`Pickler`](https://python-all.ru/3.1/library/pickle.html#pickle.Pickler) будет рекурсировать бесконечно.159160Используйте [`pickletools.optimize()`](https://python-all.ru/3.1/library/pickletools.html#pickletools.optimize), если нужны более компактные упаковки.161162#### `class pickle.Unpickler(file[, *, fix_imports=True, encoding="ASCII", errors="strict"])`163164Принимает бинарный файл для чтения потока данных pickle.165166Версия протокола pickle определяется автоматически, поэтому аргумент протокола не нужен.167168Аргумент *file* должен иметь два метода: read(), принимающий целочисленный аргумент, и readline(), не требующий аргументов. Оба метода должны возвращать bytes. Таким образом, *file* может быть файловым объектом на диске, открытым для чтения в двоичном режиме, объектом [`io.BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO) или любым другим пользовательским объектом, соответствующим этому интерфейсу.169170Необязательными именованными аргументами являются *fix\_imports*, *encoding* и *errors*, которые используются для управления совместимостью с потоками pickle, созданными Python 2.x. Если *fix\_imports* равен True, pickle попытается отобразить старые имена Python 2.x на новые имена, используемые в Python 3.x. Аргументы *encoding* и *errors* указывают pickle, как декодировать экземпляры 8-битных строк, упакованные Python 2.x; по умолчанию они равны 'ASCII' и 'strict' соответственно.171172#### `load()`173174Читает представление объекта в pickle из открытого объекта файла, переданного в конструкторе, и возвращает восстановленную иерархию объектов, указанную в нём. Байты, следующие за представлением объекта в pickle, игнорируются.175176#### `persistent_load(pid)`177178По умолчанию вызывает `UnpickingError`.179180Если определена, [`persistent_load()`](https://python-all.ru/3.1/library/pickle.html#pickle.Unpickler.persistent_load) должна возвращать объект, заданный постоянным идентификатором *pid*. Если встречен недопустимый постоянный идентификатор, должно быть возбуждено `UnpickingError`.181182См. [*Постоянство внешних объектов*](https://python-all.ru/3.1/library/pickle.html#pickle-persistent) для подробностей и примеров использования.183184#### `find_class(module, name)`185186Импортирует модуль *module* при необходимости и возвращает из него объект с именем *name*. Аргументы *module* и *name* – строки (тип [`str`](https://python-all.ru/3.1/library/functions.html#str)). Обратите внимание: вопреки своему названию, [`find_class()`](https://python-all.ru/3.1/library/pickle.html#pickle.Unpickler.find_class) также используется для поиска функций.187188Подклассы могут переопределить этот метод для получения контроля над тем, объекты какого типа и каким образом могут быть загружены, что потенциально снижает риски безопасности. См. [*Ограничение глобальных объектов*](https://python-all.ru/3.1/library/pickle.html#pickle-restrict) для подробностей.189190## 11.1.4. Что можно упаковать и распаковать?191192Следующие типы можно сериализовать:193194- `None`, `True` и `False`195- целые числа, числа с плавающей запятой, комплексные числа196- строки, байты, байтовые массивы197- кортежи, списки, множества и словари, содержащие только сериализуемые объекты198- Функции, определённые на верхнем уровне модуля.199- встроенные функции, определённые на верхнем уровне модуля200- классы, определённые на верхнем уровне модуля201- экземпляры таких классов, у которых `__dict__` или `__setstate__()` могут быть упакованы (см. раздел [*Pickling Class Instances*](https://python-all.ru/3.1/library/pickle.html#pickle-inst) для подробностей)202203Попытка запакетить (pickle) непиклируемый объект вызовет исключение [`PicklingError`](https://python-all.ru/3.1/library/pickle.html#pickle.PicklingError); при этом в базовый файл может быть уже записано некоторое количество байт. Попытка запакетить сильно рекурсивную структуру данных может превысить максимальную глубину рекурсии – в этом случае будет возбуждено [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError). Можно аккуратно увеличить этот предел с помощью [`sys.setrecursionlimit()`](https://python-all.ru/3.1/library/sys.html#sys.setrecursionlimit).204205Обратите внимание, что функции (встроенные и определяемые пользователем) упаковываются по «полному имени» (fully qualified) ссылке, а не по значению. Это означает, что упаковывается только имя функции вместе с именем модуля, в котором функция определена. Ни код функции, ни её атрибуты не упаковываются. Таким образом, определяющий модуль должен быть импортируем в среде распаковки, и модуль должен содержать именованный объект, иначе будет возбуждено исключение. [\[2\]](https://python-all.ru/3.1/library/pickle.html#id6)206207Аналогично, классы пиклятся по именованной ссылке, поэтому в среде распикливания действуют те же ограничения. Обратите внимание, что ни код класса, ни его данные не пиклятся, так что в следующем примере атрибут класса `attr` не восстанавливается в среде распикливания:208209```python210class Foo:211 attr = 'A class attribute'212213picklestring = pickle.dumps(Foo)214```215216Эти ограничения объясняют, почему сериализуемые функции и классы должны быть определены на верхнем уровне модуля.217218Аналогично, при упаковке экземпляров классов код и данные класса не упаковываются вместе с ними. Упаковываются только данные экземпляра. Это сделано намеренно, чтобы можно было исправлять ошибки в классе или добавлять методы, и при этом загружать объекты, созданные более ранней версией класса. Если предполагается использовать долгоживущие объекты, которые будут существовать на протяжении многих версий класса, возможно, стоит добавить в объекты номер версии, чтобы подходящие преобразования могли быть выполнены методом `__setstate__()` класса.219220## 11.1.5. Упаковка экземпляров классов221222В этом разделе описываются общие механизмы, позволяющие определять, настраивать и контролировать процесс сериализации и десериализации экземпляров классов.223224В большинстве случаев для того, чтобы экземпляры можно было пиклить, дополнительный код не требуется. По умолчанию pickle извлекает класс и атрибуты экземпляра через интроспекцию. При распикливании экземпляра класса его метод [`__init__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__init__) обычно *не* вызывается. Стандартное поведение сначала создаёт неинициализированный экземпляр, а затем восстанавливает сохранённые атрибуты. Следующий код показывает реализацию этого поведения:225226```python227def save(obj):228 return (obj.__class__, obj.__dict__)229230def load(cls, attributes):231 obj = cls.__new__(cls)232 obj.__dict__.update(attributes)233 return obj234```235236Классы могут изменить поведение по умолчанию, предоставив один или несколько специальных методов:237238#### `object.__getnewargs__()`239240Начиная с протокола 2, классы, реализующие метод241242[`__getnewargs__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__getnewargs__)243244, могут управлять значениями, передаваемыми методу245246[`__new__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__new__)247248при распаковке. Это часто необходимо для классов, метод249250[`__new__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__new__)251252которых требует аргументов.253254#### `object.__getstate__()`255256Классы могут дополнительно влиять на то, как пиклятся их экземпляры. Если класс определяет метод257258[`__getstate__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__getstate__)259260, он вызывается, и возвращённый объект пиклится как содержимое экземпляра вместо содержимого словаря экземпляра. Если метод261262[`__getstate__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__getstate__)263264отсутствует, то265266[`__dict__`](https://python-all.ru/3.1/library/stdtypes.html#object.__dict__)267268экземпляра пиклится как обычно.269270#### `object.__setstate__(state)`271272При распикливании, если класс определяет [`__setstate__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__setstate__), он вызывается с распикленным состоянием. В этом случае объект состояния не обязан быть словарём. В противном случае распикленное состояние должно быть словарём, и его элементы присваиваются словарю нового экземпляра.273274> **Примечание**275>276> Если [`__getstate__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__getstate__) возвращает ложное значение, метод [`__setstate__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__setstate__) не будет вызываться при распикливании.277278Обратитесь к разделу [*Handling Stateful Objects*](https://python-all.ru/3.1/library/pickle.html#pickle-state) за дополнительной информацией об использовании методов `__getstate__()` и `__setstate__()`.279280> **Примечание**281>282> При распаковке некоторые методы, такие как [`__getattr__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__getattr__), [`__getattribute__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__getattribute__) или [`__setattr__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__setattr__), могут вызываться для экземпляра. Если эти методы полагаются на некоторый внутренний инвариант, тип должен реализовать `__getnewargs__()` для установки такого инварианта; в противном случае не будут вызваны ни [`__new__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__new__), ни [`__init__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__init__).283284Как мы увидим, pickle не использует напрямую описанные выше методы. На самом деле эти методы являются частью протокола копирования, который реализует специальный метод `__reduce__()`. Протокол копирования предоставляет единый интерфейс для получения данных, необходимых для упаковки и копирования объектов. [\[3\]](https://python-all.ru/3.1/library/pickle.html#id7)285286Хотя это мощный инструмент, реализация `__reduce__()` напрямую в ваших классах чревата ошибками. По этой причине разработчикам классов следует по возможности использовать высокоуровневый интерфейс (то есть `__getnewargs__()`, `__getstate__()` и `__setstate__()`). Однако мы покажем случаи, где использование `__reduce__()` является единственным вариантом, либо приводит к более эффективной упаковке или к тому и другому.287288#### `object.__reduce__()`289290Интерфейс в настоящее время определён следующим образом. Метод [`__reduce__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__reduce__) не принимает аргументов и должен возвращать либо строку, либо, предпочтительно, кортеж (возвращаемый объект часто называют «reduce-значением»).291292Если возвращается строка, она должна интерпретироваться как имя глобальной переменной. Это должно быть локальное имя объекта относительно его модуля; модуль pickle ищет объект в пространстве имён модуля. Такое поведение обычно полезно для одиночек (singletons).293294Если возвращается кортеж, он должен содержать от двух до пяти элементов. Необязательные элементы можно опустить или указать `None` в качестве их значения. Семантика каждого элемента по порядку:295296- Вызываемый объект, который будет вызван для создания начальной версии объекта.297- Кортеж аргументов для вызываемого объекта. Если вызываемый объект не принимает ни одного аргумента, должен быть передан пустой кортеж.298- Необязательно: состояние объекта, которое будет передано методу [`__setstate__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__setstate__) объекта, как описано ранее. Если у объекта нет такого метода, значение должно быть словарём, и оно будет добавлено в атрибут [`__dict__`](https://python-all.ru/3.1/library/stdtypes.html#object.__dict__) объекта.299- Необязательно: итератор (не последовательность), возвращающий последовательные элементы. Эти элементы будут добавлены к объекту с помощью `obj.append(item)` или, пакетно, с помощью `obj.extend(list_of_items)`. В основном это используется для подклассов списков, но может использоваться и другими классами, если у них есть методы `append()` и `extend()` с подходящей сигнатурой. (Используется ли `append()` или `extend()`, зависит от версии протокола pickle и количества добавляемых элементов, поэтому оба должны поддерживаться.)300- Необязательно: итератор (не последовательность), возвращающий последовательные пары «ключ-значение». Эти элементы будут сохранены в объекте с помощью `obj[key] = value`. В основном это используется для подклассов словарей, но может использоваться и другими классами, если они реализуют [`__setitem__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__setitem__).301302#### `object.__reduce_ex__(protocol)`303304В качестве альтернативы может быть определён метод305306[`__reduce_ex__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__reduce_ex__)307308. Единственное отличие в том, что этот метод должен принимать один целочисленный аргумент – версию протокола. Если он определён, pickle будет предпочитать его методу309310[`__reduce__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__reduce__)311312. Кроме того,313314[`__reduce__()`](https://python-all.ru/3.1/library/pickle.html#pickle.object.__reduce__)315316автоматически становится синонимом расширенной версии. Основное назначение этого метода – предоставление обратно совместимых reduce-значений для старых версий Python.317318### 11.1.5.1. Сохранение внешних объектов319320Для удобства сохранения объектов модуль `pickle` поддерживает концепцию ссылки на объект вне упакованного потока данных. Такие объекты обозначаются постоянным идентификатором, который должен быть либо строкой из буквенно-цифровых символов (для протокола 0) [\[4\]](https://python-all.ru/3.1/library/pickle.html#id8), либо произвольным объектом (для любого более нового протокола).321322Разрешение таких постоянных идентификаторов не определяется модулем `pickle`; он делегирует это разрешение определённым пользователем методам упаковщика и распаковщика – `persistent_id()` и `persistent_load()` соответственно.323324Для упаковки объектов, имеющих внешний постоянный идентификатор, упаковщик должен иметь пользовательский метод `persistent_id()`, который принимает объект в качестве аргумента и возвращает либо `None`, либо постоянный идентификатор для этого объекта. Когда возвращается `None`, упаковщик просто упаковывает объект как обычно. Когда возвращается строка постоянного идентификатора, упаковщик упакует этот объект вместе с маркером, чтобы распаковщик распознал его как постоянный идентификатор.325326Для распаковки внешних объектов распаковщик должен иметь пользовательский метод `persistent_load()`, который принимает объект постоянного идентификатора и возвращает объект, на который он ссылается.327328Вот исчерпывающий пример, показывающий, как постоянный идентификатор может использоваться для упаковки внешних объектов по ссылке.329330```python331# Простой пример, показывающий, как с помощью persistent ID можно упаковать внешние объекты по ссылке.332# внешние объекты по ссылке.333334import pickle335import sqlite3336from collections import namedtuple337338# Простой класс, представляющий запись в нашей базе данных.339MemoRecord = namedtuple("MemoRecord", "key, task")340341class DBPickler(pickle.Pickler):342343 def persistent_id(self, obj):344 # Вместо упаковки MemoRecord как обычного экземпляра класса, мы выводим345 # постоянный идентификатор.346 if isinstance(obj, MemoRecord):347 # Здесь наш постоянный идентификатор – это просто кортеж, содержащий метку и ключ, который ссылается на определённую запись в базе данных.348 # ключ, который ссылается на определённую запись в базе данных.349 return ("MemoRecord", obj.key)350 else:351 # Этот метод вызывается при каждом обнаружении постоянного идентификатора.352 # требуется упаковать как обычно.353 return None354355class DBUnpickler(pickle.Unpickler):356357 def __init__(self, file, connection):358 super().__init__(file)359 self.connection = connection360361 def persistent_load(self, pid):362 # Извлеките запись из базы данных по ссылке и верните её.363 # Всегда возбуждает исключение, если невозможно вернуть правильный объект.364 cursor = self.connection.cursor()365 type_tag, key_id = pid366 if type_tag == "MemoRecord":367 # Извлеките указанную запись из базы данных и верните её.368 cursor.execute("SELECT * FROM memos WHERE key=?", (str(key_id),))369 key, task = cursor.fetchone()370 return MemoRecord(key, task)371 else:372 # Инициализируйте и наполните базу данных.373 # Извлеките записи для упаковки.374 # по постоянному идентификатору.375 raise pickle.UnpicklingError("unsupported persistent object")376377def main():378 import io, pprint379380 # Обновите запись для надёжности.381 conn = sqlite3.connect(":memory:")382 cursor = conn.cursor()383 cursor.execute("CREATE TABLE memos(key INTEGER PRIMARY KEY, task TEXT)")384 tasks = (385 'give food to fish',386 'prepare group meeting',387 'fight with a zebra',388 )389 for task in tasks:390 cursor.execute("INSERT INTO memos VALUES(NULL, ?)", (task,))391392 # Извлеките записи, которые требуется упаковать.393 cursor.execute("SELECT * FROM memos")394 memos = [MemoRecord(key, task) for key, task in cursor]395 # Выводит и нумерует строки в текстовом файле.396 file = io.BytesIO()397 DBPickler(file).dump(memos)398399 print("Pickled records:")400 pprint.pprint(memos)401402 # Обновите запись, для верности.403 cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")404405 # Удаляет не подлежащие упаковке записи.406 file.seek(0)407 memos = DBUnpickler(file, conn).load()408409 print("Unpickled records:")410 pprint.pprint(memos)411412if __name__ == '__main__':413 main()414```415416### 11.1.5.2. Обработка объектов с состоянием417418Вот пример, показывающий, как изменить поведение упаковки для класса. Класс `TextReader` открывает текстовый файл и возвращает номер строки и содержимое строки каждый раз, когда вызывается его метод `readline()`. Если экземпляр `TextReader` упаковывается, все атрибуты, *кроме* файлового объекта, сохраняются. При распаковке экземпляра файл открывается заново, и чтение возобновляется с последней позиции. Для реализации этого поведения используются методы `__setstate__()` и `__getstate__()`.419420```python421class TextReader:422 """Вывести и пронумеровать строки в текстовом файле."""423424 def __init__(self, filename):425 self.filename = filename426 self.file = open(filename)427 self.lineno = 0428429 def readline(self):430 self.lineno += 1431 line = self.file.readline()432 if not line:433 return None434 if line.endswith('\n'):435 line = line[:-1]436 return "%i: %s" % (self.lineno, line)437438 def __getstate__(self):439 # Восстанавливает состояние ранее открытого файла. Для этого необходимо открыть его заново и читать, пока не будет восстановлено количество строк.440 # Наконец, сохраняет файл.441 # метод, чтобы избежать изменения исходного состояния.442 state = self.__dict__.copy()443 # Для любого другого объекта используйте обычную редукцию.444 del state['file']445 return state446447 def __setstate__(self, state):448 # Восстановить атрибуты экземпляра (например, filename и lineno).449 self.__dict__.update(state)450 # Получить дескриптор исходного буферного объекта.451 # открыть его заново и читать, пока количество строк не восстановится.452 file = open(self.filename)453 for _ in range(self.lineno):454 file.readline()455 # Наконец, сохраните файл.456 self.file = file457```458459Пример использования может выглядеть так:460461```python462>>> reader = TextReader("hello.txt")463>>> reader.readline()464'1: Hello world!'465>>> reader.readline()466'2: I am line number two.'467>>> new_reader = pickle.loads(pickle.dumps(reader))468>>> new_reader.readline()469'3: Goodbye!'470```471472## 11.1.6. Ограничение глобалов473474По умолчанию распаковщик импортирует любой класс или функцию, найденные в данных pickle. Для многих приложений такое поведение неприемлемо, поскольку оно позволяет распаковщику импортировать и вызывать произвольный код. Просто подумайте, что делает этот вручную созданный поток данных pickle при загрузке:475476```python477>>> import pickle478>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")479hello world4800481```482483В этом примере анпиклер импортирует функцию [`os.system()`](https://python-all.ru/3.1/library/os.html#os.system), а затем применяет строковый аргумент «echo hello world». Хотя этот пример безобиден, нетрудно представить такой, который может повредить систему.484485По этой причине может потребоваться контролировать, что распаковывается, путём настройки [`Unpickler.find_class()`](https://python-all.ru/3.1/library/pickle.html#pickle.Unpickler.find_class). Вопреки своему названию, `find_class()` вызывается всякий раз, когда запрашивается глобальный объект (т.е. класс или функция). Таким образом, можно либо полностью запретить глобальные объекты, либо ограничить их безопасным подмножеством.486487Вот пример анпиклера, который разрешает загрузку только нескольких безопасных классов из модуля [`builtins`](https://python-all.ru/3.1/library/builtins.html#module-builtins):488489```python490import builtins491import io492import pickle493494safe_builtins = {495 'range',496 'complex',497 'set',498 'frozenset',499 'slice',500}501502class RestrictedUnpickler(pickle.Unpickler):503504 def find_class(self, module, name):505 # Разрешать только безопасные классы из builtins.506 if module == "builtins" and name in safe_builtins:507 return getattr(builtins, name)508 # Запрещать всё остальное.509 raise pickle.UnpicklingError("global '%s.%s' is forbidden" %510 (module, name))511512def restricted_loads(s):513 """Вспомогательная функция, аналогичная pickle.loads()."""514 return RestrictedUnpickler(io.BytesIO(s)).load()515```516517Пример использования нашего десериализатора, работающего как задумано:518519```python520>>> restricted_loads(pickle.dumps([1, 2, range(15)]))521[1, 2, range(0, 15)]522>>> restricted_loads(b"cos\nsystem\n(S'echo hello world'\ntR.")523Traceback (most recent call last):524 ...525pickle.UnpicklingError: global 'os.system' is forbidden526>>> restricted_loads(b'cbuiltins\neval\n'527... b'(S\'getattr(__import__("os"), "system")'528... b'("echo hello world")\'\ntR.')529Traceback (most recent call last):530 ...531pickle.UnpicklingError: global 'builtins.eval' is forbidden532```533534Как показывают наши примеры, нужно быть осторожным с тем, что разрешается распаковывать. Поэтому если безопасность вызывает беспокойство, возможно, стоит рассмотреть альтернативы, например API маршалинга в [`xmlrpc.client`](https://python-all.ru/3.1/library/xmlrpc.client.html#module-xmlrpc.client) или сторонние решения.535536## 11.1.7. Примеры537538Для простейшего кода используйте функции [`dump()`](https://python-all.ru/3.1/library/pickle.html#pickle.dump) и [`load()`](https://python-all.ru/3.1/library/pickle.html#pickle.load).539540```python541import pickle542543# Произвольный набор объектов, поддерживаемых pickle.544data = {545 'a': [1, 2.0, 3, 4+6j],546 'b': ("character string", b"byte string"),547 'c': set([None, True, False])548}549550with open('data.pickle', 'wb') as f:551 # Запаковать словарь 'data', используя самый высокий доступный протокол.552 pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)553```554555Следующий пример читает полученные сериализованные данные.556557```python558import pickle559560with open('data.pickle', 'rb') as f:561 # Версия используемого протокола определяется автоматически, поэтому562 # указывать её не нужно.563 data = pickle.load(f)564```565566> **См. также**567>568> **Модуль [`copyreg`](https://python-all.ru/3.1/library/copyreg.html#module-copyreg)**569>570> Регистрация конструктора интерфейса pickle для расширенных типов.571>572> **Модуль [`pickletools`](https://python-all.ru/3.1/library/pickletools.html#module-pickletools)**573>574> Инструменты для работы и анализа сериализованных данных.575>576> **Модуль [`shelve`](https://python-all.ru/3.1/library/shelve.html#module-shelve)**577>578> Индексированные базы данных объектов; использует579>580> `pickle`581>582> .583>584> **Модуль [`copy`](https://python-all.ru/3.1/library/copy.html#module-copy)**585>586> Поверхностное и глубокое копирование объектов.587>588> **Модуль [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal)**589>590> Высокопроизводительная сериализация встроенных типов.591592Сноски593594| [\[1\]](https://python-all.ru/3.1/library/pickle.html#id1) | Не путайте это с модулем [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal) |595| --- | --- |596597| [\[2\]](https://python-all.ru/3.1/library/pickle.html#id2) | Возникающее исключение, скорее всего, будет [`ImportError`](https://python-all.ru/3.1/library/exceptions.html#ImportError) или [`AttributeError`](https://python-all.ru/3.1/library/exceptions.html#AttributeError), но может быть и другим. |598| --- | --- |599600| [\[3\]](https://python-all.ru/3.1/library/pickle.html#id3) | Модуль [`copy`](https://python-all.ru/3.1/library/copy.html#module-copy) использует этот протокол для операций поверхностного и глубокого копирования. |601| --- | --- |602603| [\[4\]](https://python-all.ru/3.1/library/pickle.html#id4) | Ограничение на алфавитно-цифровые символы связано с тем, что постоянные идентификаторы в протоколе 0 разделяются символом новой строки. Поэтому если в постоянных идентификаторах встречаются какие-либо символы новой строки, результирующий pickle станет нечитаемым. |604| --- | --- |605