pickle

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

Модуль может работать с большинством разновидностей обычных объектов Python, включая:

  • None
  • Числа и строки
  • Кортежи, списки и словари, содержащие объекты только тех типов, которые поддерживаются модулем pickle
  • Экземпляры пользовательских классов, объявленных в модуле на верхнем уровне

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

Соответствующее определение класса не сохраняется, вместо этого сохраненные данные просто содержат имя соответствующего класса и имя модуля, где этот класс объявлен.

Когда происходит восстановление такого экземпляра, автоматически выполняется импортирование модуля, в котором находится объявление класса, для получения доступа к определению класса при воссоздании экземпляра.

Следует также отметить, что при восстановлении экземпляра метод __init__() класса не вызывается.

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

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

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

Обычно не требуется делать что-то особенное с пользовательскими классами, чтобы обеспечить их совместимость с модулем pickle.

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

Метод __getstate__() должен возвращать объект, пригодный для сохранения (такой как строка или кортеж), представляющий состояние оригинального объекта.

Метод __setstate__() должен принимать сохраненный объект и на его основе восстанавливать оригинальный объект.

Если эти методы не определены, по умолчанию сохраняется атрибут __dict__ экземпляра.

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

Примечание

  • В Python 2 имеется модуль cPickle, содержащий реализацию функций модуля pickle на языке C.

    Он обладает гораздо более высокой производительностью по сравнению с модулем pickle, но ограничивает возможность создания производных классов от Pickler и Unpickler.

    В Python 3 также имеется модуль, содержащий реализацию на языке C, но он не используется непосредственно (модуль pickle использует его автоматически).

  • Формат данных, используемый модулем pickle, характерен для языка Python и не должен рассматриваться как совместимый с какими-либо внешними стандартами, такими как XML.

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

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

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

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

    В частности, с особенностями реализации специальных методов __reduce__() и __reduce_ex__(), которые используются модулем pickle для создания последовательности байтов.

HIGHEST_PROTOCOL

pickle.HIGHEST_PROTOCOL

Атрибут, хранит идентификатор современного протокола

dump()

pickle.dump(object, file_obj[, protokol-0][, fix_imports-True])
  • obj - сохраняемый объект

  • file_obj - файловый объект

  • fix_imports - введена в python 3

  • protokol - число, формат выводимых данных

    Если в аргументе protocol передается отрицательное значение, выбирается наиболее современный протокол.

    Самая последняя версия протокола хранится в переменной pickle.HIGHEST_PROTOCOL.

    Если объект не поддерживает возможность сериализации, возбуждается исключение pickle.PicklingError.

    • 0 - текстовый формат, обратно совместимый с более ранними версиями Python.
    • 1 – двоичный формат, который также совместим с большинством предыдущих версий Python.
    • 2 – новый формат, который обеспечивает наиболее эффективный способ сохранения классов и экземпляров.
    • 3 - используется в Python 3 и несовместим с предыдущими версиями интерпретатора.

Выводит сериализованное представление объекта в файловый объект.

Вызывает __getstate__() объекта

dump("123", open("file.txt", 'w'))

dumps()

pickle.dumps(object [, protocol][, fix_imports-True])
  • obj - сохраняемый объект
  • protokol - протокол сохранения (1, ...)
  • fix_imports - возможно введена в третьем питоне

То же, что и функция dump(), но возвращает строку (в 3 питоне байты), содержащую сериализованные данные

dumps([1, 2, 3, 4, 5])
# b'\x80\x03]q\x00(K\x01K\x02K\x03K\x04K\x05e.'

load()

pickle.load(file_obj[, fix_imports-True][, encoding-"ASCII"][, errors-"strict"])
  • file_obj - файловый объект
  • encoding - кодировка файла, добавлена в третьем питоне
  • fix_imports - добавлена в третьем питоне
  • errors - добавлена в третьем питоне

Загружает сериализованное представление объекта из файлового объекта и возвращает готовый объект.

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

По достижении конца файла возбуждается исключение EOFError.

d - load(open("file.txt"))

loads()

pickle.loads(string, [ , fix_imports-True][ , encoding-'ASCII'][ , errors-'strict'])
  • str - строка (в 3 питоне последовательность байтов)
  • fix_imports - возможно введена в третьем питоне
  • encoding - возможно введена в третьем питоне
  • errors - возможно введена в третьем питоне

То же, что и функция load(), но сериализованное представление объекта из строки.

loads(b'\x80\x03]q\x00(K\x01K\x02K\x03K\x04K\x05e. ')
# [1, 2, 3, 4, 5]

loads(b'\x80\x03(K\x06K\x07K\x08K\tK\ntq\x00. ')
# (6, 7, 8, 9, 10)

Pickler()

class pickle.Pickler(file [, protocol][, fix_imports-True])

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

dump(x)

Записывает объект в файл.

При сохранении объекта запоминается его идентичность.

Если впоследствии повторно будет выполнена попытка сохранить объект с помощью метода dump(), вместо новой копии в файл будет записана ссылка на объект, сохраненный ранее.

clear_memo()

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

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

Unpickler()

class pickle.Unpickler(file[, fix_imports-True][, encoding-'ASCII'][, errors-'strict'])

Создает объект, который читает данные из файлового объекта.

load()

загружает данные из файла и возвращает новый объект.

Объект Unpickler запоминает объекты, которые он возвращал, потому что исходный файл может содержать ссылки на объекты, сохраненные объектом Pickler.

В этом случае метод load() возвращает ссылку на ранее загруженный объект.