pickle¶
Модуль преобразует объект в последовательность байтов, которая может быть записана в файл, а потом прочитана из файла.
Модуль может работать с большинством разновидностей обычных объектов Python, включая:
None
Числа и строки
Кортежи, списки и словари, содержащие объекты только тех типов, которые поддерживаются модулем pickle
Экземпляры пользовательских классов, объявленных в модуле на верхнем уровне
Когда сохраняются экземпляры пользовательских классов, данные об экземпляре – единственная информация, которая сохраняется.
Соответствующее определение класса не сохраняется, вместо этого сохраненные данные просто содержат имя соответствующего класса и имя модуля, где этот класс объявлен.
Когда происходит восстановление такого экземпляра, автоматически выполняется импортирование модуля, в котором находится объявление класса, для получения доступа к определению класса при воссоздании экземпляра.
Следует также отметить, что при восстановлении экземпляра метод __init__() класса не вызывается.
Воссоздание и восстановление данных в экземпляре производится другими способами.
Одно из ограничений, накладываемых на экземпляры классов, заключается в том, что соответствующие определения классов должны находиться на верхнем уровне модуля (то есть это не могут быть вложенные классы).
Кроме того, если определение класса экземпляра первоначально было выполнено в модуле __main__, оно должно быть загружено вручную, до попытки восстановления сохраненного объекта (поскольку интерпретатор не знает, как автоматически загрузить определение требуемого класса обратно в модуль __main__ в процессе восстановления).
Обычно не требуется делать что-то особенное с пользовательскими классами, чтобы обеспечить их совместимость с модулем pickle.
Однако класс может предоставлять собственные версии методов сохранения и восстановления информации о своем состоянии, реализовав специальные методы __getstate__() и __setstate__().
Метод __getstate__() должен возвращать объект, пригодный для сохранения (такой как строка или кортеж), представляющий состояние оригинального объекта.
Метод __setstate__() должен принимать сохраненный объект и на его основе восстанавливать оригинальный объект.
Если эти методы не определены, по умолчанию сохраняется атрибут __dict__ экземпляра.
Следует отметить, что если эти методы определены, они также будут использоваться модулем copy для операций поверхностного и глубокого копирования.
Note
В Python 2 имеется модуль cPickle, содержащий реализацию функций модуля pickle на языке C.
Он обладает гораздо более высокой производительностью по сравнению с модулем pickle, но ограничивает возможность создания производных классов от Pickler и Unpickler.
В Python 3 также имеется модуль, содержащий реализацию на языке C, но он не используется непосредственно (модуль pickle использует его автоматически).
Формат данных, используемый модулем pickle, характерен для языка Python и не должен рассматриваться как совместимый с какими-либо внешними стандартами, такими как XML.
Везде, где только возможно, вместо модуля marshal должен использоваться модуль pickle, потому что модуль pickle является более гибким, используемый им формат кодирования данных описан в документации и в нем выполняется проверка на наличие ошибок.
Из-за проблем, связанных с безопасностью, программы не должны восстанавливать данные из файлов, полученных из непроверенных источников.
Использование модуля pickle с типами, объявленными в модулях расширений, является намного более сложной задачей, чем было описано здесь.
Разработчики расширений обязательно должны ознакомиться с подробным описанием низкоуровневого протокола в электронной документации, чтобы обеспечить возможность сохранения объектов с помощью модуля pickle.
В частности, с особенностями реализации специальных методов __reduce__() и __reduce_ex__(), которые используются модулем pickle для создания последовательности байтов.
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() возвращает ссылку на ранее загруженный объект.
-