pickle — Сериализация объектов Python

Связь с другими модулями Python

Формат потока данных

Формат данных, используемый pickle, специфичен для Python. Это даёт преимущество отсутствия ограничений, накладываемых внешними стандартами, такими как JSON или XDR (которые не могут представлять совместное использование указателей); однако это означает, что программы, не написанные на Python, могут не быть способны восстановить закодированные Python объекты.

По умолчанию, формат данных pickle использует относительно компактное двоичное представление. Если вам необходимы оптимальные характеристики размера, вы можете эффективно сжать закодированные данные.

Модуль pickletools содержит инструменты для анализа потоков данных, генерируемых pickle. Исходный код pickletools содержит обширные комментарии об операционных кодах, используемых протоколами pickle.

В настоящее время доступны 6 различных протоколов, которые могут быть использованы для кодирования. Чем выше используемый протокол, тем более поздняя версия Python требуется для чтения сгенерированного pickle.

• Протокол версии 0 — это оригинальный «человекочитаемый» протокол и обратно совместим с более ранними версиями Python.
• Протокол версии 1 — это старый двоичный формат, также совместимый с более ранними версиями Python.
• Протокол версии 2 был представлен в Python 2.3. Он обеспечивает гораздо более эффективное кодирование классов нового стиля. Обратитесь к PEP 307 за информацией об улучшениях, принесённых протоколом 2.
• Протокол версии 3 был добавлен в Python 3.0. Он имеет явную поддержку для bytes объектов и не может быть распакован Python 2.x. Это был протокол по умолчанию в Python 3.0–3.7.
• Протокол версии 4 был добавлен в Python 3.4. Он добавляет поддержку очень больших объектов, кодирования большего количества типов объектов и некоторых оптимизаций формата данных. Это протокол по умолчанию, начиная с Python 3.8. Обратитесь к PEP 3154 за информацией об улучшениях, принесённых протоколом 4.
• Протокол версии 5 был добавлен в Python 3.8. Он добавляет поддержку данных вне зоны доступа и ускорение для данных в зоне доступа. Обратитесь к PEP 574 за информацией об улучшениях, принесённых протоколом 5.

Интерфейс модуля

Для сериализации иерархии объектов просто вызовите функцию dumps(). Аналогично, для десериализации потока данных вызовите функцию loads(). Однако, если вы хотите получить больший контроль над сериализацией и десериализацией, вы можете создать объект Pickler или Unpickler соответственно.

Модуль pickle предоставляет следующие константы:

pickle.HIGHEST_PROTOCOL

Целое число, наивысшая доступная версия протокола. Это значение может быть передано в качестве значения протокола функциям dump() и dumps(), а также конструктору Pickler.

pickle.DEFAULT_PROTOCOL

Целое число, используемая по умолчанию версия протокола для пиклирования. Может быть меньше, чем HIGHEST_PROTOCOL. В настоящее время протокол по умолчанию равен 4, впервые представлен в Python 3.4 и несовместим с предыдущими версиями.

Изменено в версии 3.0: Протокол по умолчанию — 3.

Изменено в версии 3.8: Протокол по умолчанию — 4.

Модуль pickle предоставляет следующие функции для повышения удобства процесса пиклирования:

pickle.dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)

Записать сериализованное представление объекта obj в открытый объект файла file. Это эквивалентно Pickler(file, protocol).dump(obj).

Аргументы file, protocol, fix_imports и buffer_callback имеют то же значение, что и в конструкторе Pickler.

Изменено в версии 3.8: Добавлен аргумент buffer_callback.

pickle.dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)

Вернуть сериализованное представление объекта obj как объект bytes, вместо записи в файл.

Аргументы protocol, fix_imports и buffer_callback имеют то же значение, что и в конструкторе Pickler.

Изменено в версии 3.8: Добавлен аргумент buffer_callback.

pickle.load(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Прочитать сериализованное представление объекта из открытого объекта файла file и вернуть реконструированную иерархию объектов, указанную в нем. Это эквивалентно Unpickler(file).load().

Версия протокола pickle определяется автоматически, поэтому аргумент protocol не требуется. Байты после сериализованного представления объекта игнорируются.

Аргументы file, fix_imports, encoding, errors, strict и buffers имеют то же значение, что и в конструкторе Unpickler.

Изменено в версии 3.8: Добавлен аргумент buffers.

pickle.loads(data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Вернуть реконструированную иерархию объектов из сериализованного представления data объекта. data должен быть объектом типа bytes.

Версия протокола pickle определяется автоматически, поэтому аргумент protocol не требуется. Байты после сериализованного представления объекта игнорируются.

Аргументы fix_imports, encoding, errors, strict и buffers имеют то же значение, что и в конструкторе Unpickler.

Изменено в версии 3.8: Добавлен аргумент buffers.

Модуль pickle определяет три исключения:

exception pickle.PickleError

Общий базовый класс для других исключений пиклирования. Он наследует от Exception.

exception pickle.PicklingError

Исключение, генерируемое, когда Pickler встречает несериализуемый объект. Он наследует от PickleError.

Обратитесь к Что можно сериализовать и десериализовать? чтобы узнать, какие типы объектов можно сериализовать.

exception pickle.UnpicklingError

Исключение, возникающее при проблемах с десериализацией объекта, например, при повреждении данных или нарушении безопасности. Он наследует от PickleError.

Обратите внимание, что при десериализации могут быть подняты и другие исключения, включая (но не ограничиваясь ими) AttributeError, EOFError, ImportError и IndexError.

Модуль pickle экспортирует три класса: Pickler, Unpickler и PickleBuffer.

class pickle.Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)

Это принимает двоичный файл для записи потока данных пикла.

Необязательный аргумент protocol, целое число, сообщает пиклеру использовать указанный протокол; поддерживаемые протоколы — от 0 до HIGHEST_PROTOCOL. Если не указано, по умолчанию используется DEFAULT_PROTOCOL. Если указано отрицательное число, выбирается HIGHEST_PROTOCOL.

Аргумент file должен иметь метод write(), принимающий единственный байтовый аргумент. Таким образом, это может быть файл на диске, открытый для двоичного записи, экземпляр io.BytesIO или любой другой пользовательский объект, соответствующий этому интерфейсу.

Если fix_imports истинно, а protocol меньше 3, пикл попытается сопоставить новые имена Python 3 со старыми именами модулей, используемыми в Python 2, чтобы поток данных пикла был читаем с Python 2.

Если buffer_callback равно None (по умолчанию), представления буферов сериализуются в file в качестве части потока пикла.

Если buffer_callback не равно None, то оно может вызываться любое количество раз с представлением буфера. Если обратный вызов возвращает ложное значение (например, None), данный буфер вне потока; в противном случае буфер сериализуется внутри потока, т.е. внутри потока пикла.

Ошибка, если buffer_callback не равно None, а protocol равно None или меньше 5.

Изменено в версии 3.8: Аргумент buffer_callback был добавлен.

dump(obj)

Записать сериализованное представление obj в открытый объект файла, заданный в конструкторе.

persistent_id(obj)

По умолчанию ничего не делает. Это существует, чтобы дочерний класс мог переопределить его.

Если persistent_id() возвращает None, obj сериализуется как обычно. Любое другое значение заставляет Pickler выводить возвращенное значение в качестве постоянного идентификатора для obj. Значение этого постоянного идентификатора должно быть определено Unpickler.persistent_load(). Обратите внимание, что возвращаемое значение persistent_id() само не может иметь постоянный идентификатор.

См. Сохранение внешних объектов для получения подробностей и примеров использования.

dispatch_table

Таблица диспетчеризации объекта пиклера — это реестр функций сокращения, которые можно объявить с помощью copyreg.pickle(). Это отображение, ключи которого — классы, а значения — функции сокращения. Функция сокращения принимает один аргумент соответствующего класса и должна соответствовать тому же интерфейсу, что и метод __reduce__().

По умолчанию у объекта пиклера не будет атрибута dispatch_table, и он вместо этого будет использовать глобальную таблицу диспетчеризации, управляемую модулем copyreg. Однако для настройки сериализации для конкретного объекта пиклера можно установить атрибут dispatch_table на объект типа dict. Кроме того, если у подкласса Pickler есть атрибут dispatch_table, то он будет использоваться в качестве таблицы диспетчеризации по умолчанию для экземпляров этого класса.

См. Таблицы диспетчеризации для примеров использования.

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

reducer_override(obj)

Специальный редьюсер, который может быть определен в подклассах Pickler. Этот метод имеет приоритет над любым редьюсером в dispatch_table. Он должен соответствовать тому же интерфейсу, что и метод __reduce__(), и может необязательно возвращать NotImplemented, чтобы перейти к редьюсерам, зарегистрированным в dispatch_table, для сериализации obj.

Для подробного примера см. Настройка сокращения для типов, функций и других объектов.

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

fast

Устарело. Включить быстрый режим, если значение истинно. Быстрый режим отключает использование memo, поэтому ускоряет процесс сериализации, не генерируя избыточные коды PUT. Его нельзя использовать с объектами, ссылающимися на себя, так как в противном случае Pickler будет рекурсировать бесконечно.

Используйте pickletools.optimize(), если вам нужны более компактные pickles.

class pickle.Unpickler(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Это принимает двоичный файл для чтения потока данных pickle.

Версия протокола pickle определяется автоматически, поэтому аргумент протокола не нужен.

Аргумент file должен иметь три метода: метод read() с целочисленным аргументом, метод readinto() с аргументом буфера и метод readline() без аргументов, как в интерфейсе io.BufferedIOBase. Таким образом, file может быть файлом на диске, открытым для двоичного чтения, объектом io.BytesIO или любым другим пользовательским объектом, который соответствует этому интерфейсу.

Необязательные аргументы fix_imports, encoding и errors используются для управления поддержкой совместимости для потока pickle, сгенерированного Python 2. Если fix_imports имеет значение True, pickle попытается сопоставить старые имена Python 2 с новыми именами, используемыми в Python 3. encoding и errors сообщают pickle, как декодировать 8-битные строковые экземпляры, закодированные Python 2; они по умолчанию равны ‘ASCII’ и ‘strict’ соответственно. encoding может быть ‘bytes’, чтобы читать эти 8-битные строковые экземпляры как объекты bytes. Для распаковки массивов NumPy и экземпляров datetime, date и time, закодированных Python 2, необходимо использовать encoding='latin1'.

Если buffers равно None (значение по умолчанию), то все данные, необходимые для десериализации, должны быть содержаться в потоке pickle. Это означает, что аргумент buffer_callback был None при создании Pickler (или при вызове dump() или dumps()).

Если buffers не равно None, оно должно быть итерируемым объектом с поддержкой буферов, который используется каждый раз, когда поток pickle ссылается на внешний буфер. Такие буферы были предоставлены в порядке аргументу buffer_callback объекта Pickler.

Изменено в версии 3.8: Добавлен аргумент buffers.

load()

Прочитайте закодированное представление объекта из открытого файла, указанного в конструкторе, и верните реконструированную иерархию объектов, указанную в нём. Байты после закодированного представления объекта игнорируются.

persistent_load(pid)

По умолчанию вызывает UnpicklingError.

Если определено, persistent_load() должно возвращать объект, указанный постоянным идентификатором pid. Если встречен неверный постоянный идентификатор, должно быть вызвано исключение UnpicklingError.

Подробные сведения и примеры использования см. в разделе Сохранение внешних объектов.

find_class(module, name)

Импортировать module, если необходимо, и вернуть объект, названный name из него, где аргументы module и name являются объектами str. Обратите внимание, что, вопреки своему названию, find_class() также используется для поиска функций.

Подклассы могут переопределять его, чтобы получить контроль над типами объектов и способами их загрузки, потенциально снижая риски безопасности. Подробности см. в разделе Ограничение глобальных переменных.

Вызывает событие аудита pickle.find_class с аргументами module, name.

class pickle.PickleBuffer(buffer)

Обёртка для буфера, представляющего закодируемые данные. buffer должен быть объектом, предоставляющим буфер, например, байтовый объект или N-мерный массив.

PickleBuffer сам по себе является поставщиком буфера, поэтому его можно передать другим API, ожидающим объект, предоставляющий буфер, например, memoryview.

Объекты PickleBuffer могут быть сериализованы только с помощью протокола pickle 5 или выше. Они подходят для сериализации вне области.

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

raw()

Возвращает memoryview области памяти, лежащей в основе этого буфера. Возвращаемый объект является одномерным, C-непрерывным memoryview с форматом B (неподписанные байты). BufferError возбуждается, если буфер не является ни C-, ни Fortran-непрерывным.

release()

Освободить буфер, представленный объектом PickleBuffer.

Что можно закодировать и раскодировать?

Следующие типы можно закодировать:

• None, True, и False;
• целые, вещественные и комплексные числа;
• строки, байты, массивы байтов;
• кортежи, списки, множества и словари, содержащие только закодируемые объекты;
• функции (встроенные и пользовательские) доступные из верхнего уровня модуля (с использованием def, а не lambda);
• классы, доступные с верхнего уровня модуля;
• экземпляры таких классов, чьё __dict__ или результат вызова __getstate__() закодируемы (см. раздел Кодирование экземпляров классов для подробностей).

Попытки закодировать незакодируемые объекты вызовут исключение PicklingError; в этом случае может быть записано неопределённое количество байтов в базовый файл. Попытка закодировать высокорекурсивную структуру данных может превысить максимальную глубину рекурсии, и в этом случае будет вызвано исключение RecursionError. Вы можете осторожно изменить этот предел с помощью sys.setrecursionlimit().

Обратите внимание, что функции (встроенные и пользовательские) закодируются полными полными именами, а не по значению. 2 Это означает, что закодируется только имя функции, а также имя содержащего модуля и классов. Модуль, в котором определена функция, должен быть импортируемым в среде распаковки, и в этом модуле должен находиться объект с данным именем, иначе будет возбуждено исключение. 3

Аналогично, классы кодируются по полному имени, поэтому те же ограничения применяются к среде распаковки. Обратите внимание, что ни код, ни данные класса не закодированы, поэтому в следующем примере атрибут класса attr не восстанавливается в среде распаковки:

class Foo:
    attr = 'A class attribute'

picklestring = pickle.dumps(Foo)

Эти ограничения объясняют, почему закодируемые функции и классы должны быть определены на верхнем уровне модуля.

Аналогично, при кодировании экземпляров классов их код и данные не кодируются вместе с ними. Закодированы только данные экземпляра. Это сделано намеренно, чтобы вы могли исправить ошибки в классе или добавить методы к классу и при этом загрузить объекты, созданные с более ранней версией класса. Если вы планируете иметь долгоживущие объекты, которые будут видеть множество версий класса, может быть полезно поместить номер версии в объекты, чтобы класс мог выполнить соответствующие преобразования с помощью метода __setstate__().

Сериализация экземпляров классов

В этом разделе мы описываем общие механизмы, доступные для определения, настройки и управления тем, как экземпляры классов сериализуются и десериализуются.

В большинстве случаев для сериализации экземпляров не требуется дополнительный код. По умолчанию, pickle будет извлекать класс и атрибуты экземпляра с помощью интроспекции. Когда экземпляр класса десериализуется, его __init__() метод обычно не вызывается. По умолчанию сначала создается неинициализированный экземпляр, а затем восстанавливаются сохраненные атрибуты. Следующий код демонстрирует реализацию этого поведения:

def save(obj):
    return (obj.__class__, obj.__dict__)

def restore(cls, attributes):
    obj = cls.__new__(cls)
    obj.__dict__.update(attributes)
    return obj

Классы могут изменить поведение по умолчанию, предоставив один или несколько специальных методов:

object.__getnewargs_ex__()

В протоколах 2 и выше, классы, реализующие метод __getnewargs_ex__(), могут диктовать значения, передаваемые методу __new__() при десериализации. Метод должен вернуть пару (args, kwargs) где args — кортеж позиционных аргументов, а kwargs — словарь именованных аргументов для построения объекта. Эти значения будут переданы методу __new__() при десериализации.

Этот метод следует реализовать, если методу __new__() вашего класса требуются только именованные аргументы. В противном случае, для обеспечения совместимости рекомендуется реализовать метод __getnewargs__().

Изменено в версии 3.6: __getnewargs_ex__() теперь используется в протоколах 2 и 3.

object.__getnewargs__()

Этот метод выполняет аналогичную функцию, что и __getnewargs_ex__(), но поддерживает только позиционные аргументы. Он должен вернуть кортеж аргументов args которые будут переданы методу __new__() при десериализации.

Метод __getnewargs__() не будет вызван, если определён метод __getnewargs_ex__().

Изменено в версии 3.6: До Python 3.6, __getnewargs__() вызывался вместо __getnewargs_ex__() в протоколах 2 и 3.

object.__getstate__()

Классы могут дополнительно влиять на то, как сериализуются их экземпляры; если класс определяет метод __getstate__(), он вызывается, и возвращаемый объект сериализуется как содержимое экземпляра, вместо содержимого словаря экземпляра. Если метод __getstate__() отсутствует, словарь экземпляра __dict__ сериализуется обычным образом.

object.__setstate__(state)

При десериализации, если класс определяет __setstate__(), он вызывается со состоянием, десериализованным из данных. В этом случае нет требования, чтобы объект состояния был словарем. В противном случае сохранённое состояние должно быть словарем, и его элементы присваиваются словарю нового экземпляра.

Примечание

Если __getstate__() возвращает ложное значение, метод __setstate__() не будет вызван при десериализации.

Дополнительную информацию о том, как использовать методы __getstate__() и __setstate__(), см. в разделе Обработка объектов состояния.

Как мы увидим, pickle напрямую не использует описанные выше методы. На самом деле, эти методы являются частью протокола копирования, который реализует специальный метод __reduce__(). Протокол копирования предоставляет унифицированный интерфейс для извлечения данных, необходимых для сериализации и копирования объектов.

4

Несмотря на мощь, непосредственная реализация __reduce__() в ваших классах чревата ошибками. По этой причине разработчики классов должны использовать высокоуровневый интерфейс (т.е., __getnewargs_ex__(), __getstate__() и __setstate__()) всякий раз, когда это возможно. Тем не менее, мы покажем случаи, когда использование __reduce__() является единственным вариантом или приводит к более эффективной сериализации, или и тому, и другому.

object.__reduce__()

Интерфейс в настоящее время определяется следующим образом. Метод __reduce__() не принимает аргументов и должен вернуть либо строку, либо предпочтительно кортеж (возвращаемый объект часто называют «значением уменьшения»).

Если возвращается строка, строка должна интерпретироваться как имя глобальной переменной. Она должна быть локальным именем объекта относительно его модуля; модуль pickle ищет имя объекта в пространстве имён модуля, чтобы определить модуль объекта. Это поведение обычно полезно для синглетонов.

Если возвращается кортеж, его длина должна быть от двух до шести элементов. Пропущенные элементы могут быть опущены или None может быть указан в качестве их значения. Семантика каждого элемента следующая:

• Вызываемый объект, который будет вызван для создания начальной версии объекта.
• Кортеж аргументов для вызываемого объекта. Если вызываемый объект не принимает никаких аргументов, должен быть передан пустой кортеж.
• Необязательно, состояние объекта, которое будет передано методу __setstate__() объекта, как описано ранее. Если у объекта нет такого метода, значение должно быть словарем, и оно будет добавлено к атрибуту __dict__ объекта.
• Необязательно, итератор (а не последовательность), возвращающий последовательные элементы. Эти элементы будут добавлены в объект либо с помощью obj.append(item) или, пакетно, с помощью obj.extend(list_of_items). Это используется в первую очередь для подклассов списка, но может использоваться и другими классами, если они имеют методы append() и extend() с соответствующей сигнатурой. (Использование append() или extend() зависит от версии протокола pickle, а также от количества добавляемых элементов, поэтому необходимо поддерживать оба варианта.)
• Необязательно, итератор (не последовательность), возвращающий последовательные пары ключ-значение. Эти элементы будут храниться в объекте с помощью obj[key] = value. Это используется в первую очередь для подклассов словаря, но может использоваться и другими классами, если они реализуют __setitem__().

• Необязательно, вызываемый объект с сигнатурой (obj, state). Этот вызываемый объект позволяет пользователю программно контролировать поведение обновления состояния конкретного объекта вместо использования статического метода obj объекта. Если не None, этот вызываемый объект будет иметь приоритет над методом __setstate__() объекта.

  Новое в версии 3.8: Дополнительный шестой элемент кортежа, (obj, state), был добавлен.

object.__reduce_ex__(protocol)

В качестве альтернативы, может быть определён метод __reduce_ex__(). Единственное отличие состоит в том, что этот метод должен принимать один целочисленный аргумент — версию протокола. Если он определён, pickle будет отдавать предпочтение ему методу __reduce__(). Кроме того, метод __reduce__() автоматически становится синонимом расширенной версии. Основное использование этого метода заключается в обеспечении обратной совместимости значений уменьшения для более старых версий Python.

Настройка сокращений для типов, функций и других объектов

Иногда dispatch_table может быть недостаточно гибким. В частности, мы можем захотеть настроить сериализацию, основываясь на критерии, отличной от типа объекта, или настроить сериализацию функций и классов.

В этих случаях можно создать подкласс класса Pickler и реализовать метод reducer_override(). Этот метод может вернуть произвольный кортеж сокращения (см. __reduce__()). В качестве альтернативы он может вернуть NotImplemented для возврата к традиционному поведению.

Если определены и dispatch_table, и reducer_override(), метод reducer_override() имеет приоритет.

Вот простой пример, где мы разрешаем сериализацию и реконструкцию заданного класса:

import io
import pickle

class MyClass:
    my_attribute = 1

class MyPickler(pickle.Pickler):
    def reducer_override(self, obj):
        """Custom reducer for MyClass."""
        if getattr(obj, "__name__", None) == "MyClass":
            return type, (obj.__name__, obj.__bases__,
                          {'my_attribute': obj.my_attribute})
        else:
            # For any other object, fallback to usual reduction
            return NotImplemented

f = io.BytesIO()
p = MyPickler(f)
p.dump(MyClass)

del MyClass

unpickled_class = pickle.loads(f.getvalue())

assert isinstance(unpickled_class, type)
assert unpickled_class.__name__ == "MyClass"
assert unpickled_class.my_attribute == 1

Буферы вне зоны обмена

В некоторых контекстах модуль pickle используется для передачи больших объёмов данных. Поэтому минимизация числа копий данных в памяти для сохранения производительности и потребления ресурсов может быть важна. Однако обычная работа модуля pickle, поскольку он преобразует структуру объектов в виде графа в последовательный поток байтов, неизбежно включает копирование данных в и из потока pickle.

Это ограничение можно обойти, если как поставщик (реализация типов объектов, которые должны быть переданы), так и потребитель (реализация системы связи) поддерживают средства передачи вне зоны обмена, предоставляемые протоколом pickle 5 и выше.

class ZeroCopyByteArray(bytearray):

    def __reduce_ex__(self, protocol):
        if protocol >= 5:
            return type(self)._reconstruct, (PickleBuffer(self),), None
        else:
            # PickleBuffer is forbidden with pickle protocols <= 4.
            return type(self)._reconstruct, (bytearray(self),)

    @classmethod
    def _reconstruct(cls, obj):
        with memoryview(obj) as m:
            # Get a handle over the original buffer object
            obj = m.obj
            if type(obj) is cls:
                # Original buffer object is a ZeroCopyByteArray, return it
                # as-is.
                return obj
            else:
                return cls(obj)

b = ZeroCopyByteArray(b"abc")
data = pickle.dumps(b, protocol=5)
new_b = pickle.loads(data)
print(b == new_b)  # True
print(b is new_b)  # False: a copy was made

b = ZeroCopyByteArray(b"abc")
buffers = []
data = pickle.dumps(b, protocol=5, buffer_callback=buffers.append)
new_b = pickle.loads(data, buffers=buffers)
print(b == new_b)  # True
print(b is new_b)  # True: no copy was made

Ограничение глобальных переменных

По умолчанию разсериализация импортирует любой класс или функцию, найденную в данных сериализации. Для многих приложений это поведение неприемлемо, поскольку оно позволяет разсериализатору импортировать и вызывать произвольный код. Рассмотрим, что делает этот специально созданный поток данных сериализации при загрузке:

>>> import pickle
>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
hello world
0

В этом примере разсериализатор импортирует функцию os.system(), а затем применяет строковый аргумент “echo hello world”. Хотя этот пример безопасен, нетрудно представить себе пример, который может повредить вашу систему.

По этой причине вы можете захотеть контролировать, что разсериализуется, настраивая Unpickler.find_class(). Вопреки своему названию, Unpickler.find_class() вызывается всякий раз, когда запрашивается глобальная переменная (т. е. класс или функция). Таким образом, можно либо полностью запретить глобальные переменные, либо ограничить их безопасным подмножеством.

Вот пример разсериализатора, разрешающего загрузку только нескольких безопасных классов из модуля builtins:

import builtins
import io
import pickle

safe_builtins = {
    'range',
    'complex',
    'set',
    'frozenset',
    'slice',
}

class RestrictedUnpickler(pickle.Unpickler):

    def find_class(self, module, name):
        # Only allow safe classes from builtins.
        if module == "builtins" and name in safe_builtins:
            return getattr(builtins, name)
        # Forbid everything else.
        raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
                                     (module, name))

def restricted_loads(s):
    """Helper function analogous to pickle.loads()."""
    return RestrictedUnpickler(io.BytesIO(s)).load()

Пример использования нашего разсериализатора, работающего как ожидается:

>>> restricted_loads(pickle.dumps([1, 2, range(15)]))
[1, 2, range(0, 15)]
>>> restricted_loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
Traceback (most recent call last):
  ...
pickle.UnpicklingError: global 'os.system' is forbidden
>>> restricted_loads(b'cbuiltins\neval\n'
...                  b'(S\'getattr(__import__("os"), "system")'
...                  b'("echo hello world")\'\ntR.')
Traceback (most recent call last):
  ...
pickle.UnpicklingError: global 'builtins.eval' is forbidden

Как показывают наши примеры, нужно быть осторожным с тем, что вы разрешаете разсериализовать. Поэтому, если безопасность является проблемой, вы можете рассмотреть альтернативы, такие как API маршаллирования в xmlrpc.client или сторонние решения.

Производительность

Недавние версии протокола pickle (с протокола 2 и выше) имеют эффективные двоичные кодировки для нескольких общих функций и встроенных типов. Кроме того, модуль pickle имеет прозрачный оптимизатор, написанный на C.

Примеры

Для самого простого кода используйте функции dump() и load().

import pickle

# An arbitrary collection of objects supported by pickle.
data = {
    'a': [1, 2.0, 3+4j],
    'b': ("character string", b"byte string"),
    'c': {None, True, False}
}

with open('data.pickle', 'wb') as f:
    # Pickle the 'data' dictionary using the highest protocol available.
    pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)

В следующем примере читаются данные, закодированные с помощью pickle.

import pickle

with open('data.pickle', 'rb') as f:
    # The protocol version used is detected automatically, so we do not
    # have to specify it.
    data = pickle.load(f)

Примечания

1

Не путайте это с модулем marshal

2

Вот почему функции lambda нельзя закодировать с помощью pickle: все функции lambda имеют одно и то же имя: <lambda>.

3

Возникающее исключение, скорее всего, будет ImportError или AttributeError, но это может быть что-то другое.

4

Модуль copy использует этот протокол для операций копирования поверхностно и глубоко.

5

Ограничение на символы алфавитно-цифрового типа вызвано тем, что идентификаторы в протоколе 0 разделяются символом новой строки. Поэтому если в идентификаторах присутствуют символы новой строки, то полученные закодированные данные станут нечитаемыми.