12.1. pickle – сериализация объектов Python¶pickle – Python object serialization

12.1.1. Взаимосвязь с другими модулями Python¶Relationship to other Python modules

12.1.2. Формат потока данных¶Data stream format

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

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

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

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

• Протокол версии 0 – это исходный «человекочитаемый» протокол, обратно совместимый с более ранними версиями Python.

• Протокол версии 1 – это старый двоичный формат, также совместимый с более ранними версиями Python.

• Протокол версии 2 был представлен в Python 2.3. Он обеспечивает гораздо более эффективную сериализацию классов нового стиля. Дополнительную информацию об улучшениях, внесённых протоколом 2, см. в PEP 307.

• Протокол версии 3 был добавлен в Python 3.0. Он имеет явную поддержку объектов bytes и не может быть десериализован Python 2.x. Это протокол по умолчанию и рекомендуемый протокол, когда требуется совместимость с другими версиями Python 3.

• Протокол версии 4 был добавлен в Python 3.4. Он добавляет поддержку очень больших объектов, сериализацию большего числа типов объектов и некоторые оптимизации формата данных. Обратитесь к PEP 3154 для получения информации об улучшениях, внесённых протоколом 4.

12.1.3. Интерфейс модуля¶Module Interface

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

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

pickle.HIGHEST_PROTOCOL¶

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

pickle.DEFAULT_PROTOCOL¶

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

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

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

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

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

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

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

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

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

Аргументы протокол и fix_imports имеют тот же смысл, что и в dump().

pickle.load(file, *, fix_imports=True, encoding="ASCII", errors="strict")¶

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

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

Аргумент file должен иметь два метода: read(), принимающий целочисленный аргумент, и readline(), не требующий аргументов. Оба метода должны возвращать bytes. Таким образом, 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. Использование encoding='latin1' необходимо для десериализации массивов NumPy и экземпляров datetime, date и time, сериализованных Python 2.

pickle.loads(bytes_object, *, fix_imports=True, encoding="ASCII", errors="strict")¶

Читает иерархию объектов в pickle из объекта bytes и возвращает восстановленную иерархию объектов, указанную в нём.

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

Необязательными ключевыми аргументами являются 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. Использование encoding='latin1' необходимо для десериализации массивов NumPy и экземпляров datetime, date и time, сериализованных Python 2.

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

exception pickle.PickleError¶

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

exception pickle.PicklingError¶

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

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

exception pickle.UnpicklingError¶

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

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

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

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

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

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

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

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

dump(obj)¶

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

persistent_id(obj)¶

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

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

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

dispatch_table¶

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

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

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

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

fast¶

Устарело. Включает быстрый режим, если установлено в истинное значение. Быстрый режим отключает использование мемо, ускоряя процесс упаковки за счёт отсутствия лишних op-кодов PUT. Не следует использовать с самореферентными объектами, иначе Pickler будет рекурсивно вызывать себя до бесконечности.

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

class pickle.Unpickler(file, *, fix_imports=True, encoding="ASCII", errors="strict")¶

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

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

Аргумент file должен иметь два метода: read() с целочисленным аргументом и readline() без аргументов. Оба метода должны возвращать bytes. Таким образом, 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.

load()¶

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

persistent_load(pid)¶

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

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

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

find_class(module, name)¶

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

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

12.1.4. Что можно упаковать и распаковать с помощью pickle?¶What can be pickled and unpickled?

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

• 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__() класса.

12.1.5. Упаковка экземпляров классов¶Pickling Class Instances

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

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

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

def load(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__() вашего класса требует только именованных аргументов (keyword-only). В противном случае для обеспечения совместимости рекомендуется реализовать __getnewargs__().

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

object.__getnewargs__()¶

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

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

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

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__() не принимает аргументов и должен возвращать либо строку, либо, желательно, кортеж (возвращаемый объект часто называют «reduce value»).

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

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

• Вызываемый объект, который будет вызван для создания начальной версии объекта.

• Кортеж аргументов для вызываемого объекта. Если вызываемый объект не принимает ни одного аргумента, должен быть передан пустой кортеж.

• Необязательно: состояние объекта, которое будет передано методу __setstate__() объекта, как описано ранее. Если у объекта нет такого метода, то значение должно быть словарём, и оно будет добавлено в атрибут __dict__ объекта.

• Необязательно, итератор (а не последовательность), выдающий последовательные элементы. Эти элементы будут добавлены к объекту либо с помощью obj.append(item), либо пакетно с помощью obj.extend(list_of_items). В основном используется для подклассов списка, но может использоваться и другими классами, если у них есть методы append() и extend() с подходящей сигнатурой. (То, используется ли append() или extend(), зависит от используемой версии протокола pickle и количества добавляемых элементов, поэтому оба должны поддерживаться.)

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

object.__reduce_ex__(protocol)¶

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

# Простой пример, показывающий, как с помощью persistent ID можно упаковать внешние объекты по ссылке.
# внешние объекты по ссылке.

import pickle
import sqlite3
from collections import namedtuple

# Простой класс, представляющий запись в нашей базе данных.
MemoRecord = namedtuple("MemoRecord", "key, task")

class DBPickler(pickle.Pickler):

    def persistent_id(self, obj):
        # Вместо упаковки MemoRecord как обычного экземпляра класса, мы выводим
        # постоянный идентификатор.
        if isinstance(obj, MemoRecord):
            # Здесь наш постоянный идентификатор – это просто кортеж, содержащий метку и ключ, который ссылается на определённую запись в базе данных.
            # ключ, который ссылается на определённую запись в базе данных.
            return ("MemoRecord", obj.key)
        else:
            # Этот метод вызывается при каждом обнаружении постоянного идентификатора.
            # требуется упаковать как обычно.
            return None


class DBUnpickler(pickle.Unpickler):

    def __init__(self, file, connection):
        super().__init__(file)
        self.connection = connection

    def persistent_load(self, pid):
        # Извлеките запись из базы данных по ссылке и верните её.
        # Всегда возбуждает исключение, если невозможно вернуть правильный объект.
        cursor = self.connection.cursor()
        type_tag, key_id = pid
        if type_tag == "MemoRecord":
            # Извлеките указанную запись из базы данных и верните её.
            cursor.execute("SELECT * FROM memos WHERE key=?", (str(key_id),))
            key, task = cursor.fetchone()
            return MemoRecord(key, task)
        else:
            # Инициализируйте и наполните базу данных.
            # Извлеките записи для упаковки.
            # по постоянному идентификатору.
            raise pickle.UnpicklingError("unsupported persistent object")


def main():
    import io
    import pprint

    # Обновите запись для надёжности.
    conn = sqlite3.connect(":memory:")
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE memos(key INTEGER PRIMARY KEY, task TEXT)")
    tasks = (
        'give food to fish',
        'prepare group meeting',
        'fight with a zebra',
        )
    for task in tasks:
        cursor.execute("INSERT INTO memos VALUES(NULL, ?)", (task,))

    # Извлеките записи, которые требуется упаковать.
    cursor.execute("SELECT * FROM memos")
    memos = [MemoRecord(key, task) for key, task in cursor]
    # Выводит и нумерует строки в текстовом файле.
    file = io.BytesIO()
    DBPickler(file).dump(memos)

    print("Pickled records:")
    pprint.pprint(memos)

    # Обновите запись, для верности.
    cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")

    # Удаляет не подлежащие упаковке записи.
    file.seek(0)
    memos = DBUnpickler(file, conn).load()

    print("Unpickled records:")
    pprint.pprint(memos)


if __name__ == '__main__':
    main()

f = io.BytesIO()
p = pickle.Pickler(f)
p.dispatch_table = copyreg.dispatch_table.copy()
p.dispatch_table[SomeClass] = reduce_SomeClass

class MyPickler(pickle.Pickler):
    dispatch_table = copyreg.dispatch_table.copy()
    dispatch_table[SomeClass] = reduce_SomeClass
f = io.BytesIO()
p = MyPickler(f)

copyreg.pickle(SomeClass, reduce_SomeClass)
f = io.BytesIO()
p = pickle.Pickler(f)

class TextReader:
    """Вывести и пронумеровать строки в текстовом файле."""

    def __init__(self, filename):
        self.filename = filename
        self.file = open(filename)
        self.lineno = 0

    def readline(self):
        self.lineno += 1
        line = self.file.readline()
        if not line:
            return None
        if line.endswith('\n'):
            line = line[:-1]
        return "%i: %s" % (self.lineno, line)

    def __getstate__(self):
        # Восстанавливает состояние ранее открытого файла. Для этого необходимо открыть его заново и читать, пока не будет восстановлено количество строк.
        # Наконец, сохраняет файл.
        # метод, чтобы избежать изменения исходного состояния.
        state = self.__dict__.copy()
        # Для любого другого объекта используйте обычную редукцию.
        del state['file']
        return state

    def __setstate__(self, state):
        # Восстановить атрибуты экземпляра (например, filename и lineno).
        self.__dict__.update(state)
        # Получить дескриптор исходного буферного объекта.
        # открыть его заново и читать, пока количество строк не восстановится.
        file = open(self.filename)
        for _ in range(self.lineno):
            file.readline()
        # Наконец, сохраните файл.
        self.file = file

>>> reader = TextReader("hello.txt")
>>> reader.readline()
'1: Hello world!'
>>> reader.readline()
'2: I am line number two.'
>>> new_reader = pickle.loads(pickle.dumps(reader))
>>> new_reader.readline()
'3: Goodbye!'

12.1.6. Ограничение глобальных объектов¶Restricting Globals

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

>>> 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):
        # Разрешать только безопасные классы из builtins.
        if module == "builtins" and name in safe_builtins:
            return getattr(builtins, name)
        # Запрещать всё остальное.
        raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
                                     (module, name))

def restricted_loads(s):
    """Вспомогательная функция, аналогичная 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

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

12.1.7. Производительность¶Performance

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

12.1.8. Примеры¶Examples

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

import pickle

# Произвольный набор объектов, поддерживаемых pickle.
data = {
    'a': [1, 2.0, 3, 4+6j],
    'b': ("character string", b"byte string"),
    'c': {None, True, False}
}

with open('data.pickle', 'wb') as f:
    # Запаковать словарь 'data', используя самый высокий доступный протокол.
    pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)

Следующий пример читает полученные сериализованные данные.

import pickle

with open('data.pickle', 'rb') as f:
    # Версия используемого протокола определяется автоматически, поэтому
    # указывать её не нужно.
    data = pickle.load(f)

Сноски

1

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

2

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

3

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

4

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

5

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