Overview

pickle module provides serializing and de-serializing functionality for python objects. Serializing also referred to as pickling, marshaling, flattening. Pickling is byte serialization whereas JSON is text serialization.

Serialized data generated by pickle is python-specific. Hence other languages won't be able to de-serialize pickled data by python pickle.

Warning: This module is not secure against malicious unstructured data. Never unpickle data from untrusted sources.

import pickle

Dumping pickled data to file and reading it:

• pickle.dump(obj,file,protocol=None,fix_imports=True) - It writes serialized/pickled version of obj to file object. Default protocol is 3 and if negative number is given for protocol then it selects HIGHEST_PROTOCOL. If fix_imports is True then it maps new Python 3 module names to Python 2 to avoid failure during read by Python 2.
• pickle.load(file,fix_imports=True,encoding="ASCII",errors="strict") - It reads data from file object. fix_imports has same use as above method. encoding can be bytes to read 8-bit string as byte objects, latin1 to read numpy array, datetime, date and time instances.

Note: File should be opened in binary mode to write pickled byte stream data to it. File should have write() and read() methods to be used by dump() and load() methods.

with open('pickle_data.dat', 'wb') as f:
    pickle.dump('Writing String data to file', f)
    pickle.dump({'Key':'Value'},f)
    pickle.dump([1,9,4,7,3,5],f)

with open('pickle_data.dat','rb') as f:
    unpickled_string = pickle.load(f)
    unpickled_dict = pickle.load(f)
    unpickled_list = pickle.load(f)
    print(unpickled_string)
    print(unpickled_dict)
    print(unpickled_list)

Writing String data to file
{'Key': 'Value'}
[1, 9, 4, 7, 3, 5]

Generating pickled data as bytes and reading from it:

• dumps(obj,protocol=None,fix_imports=True) - Same as dump() method but instead of writing pickled data to file, it returns it.
• loads(bytes_obj,fix_imports=True,encoding='ASCII',errors='strict') - Reads data from bytes object and returns in original format. Other parameters have same meaning as load().

pickled_string = pickle.dumps('Generating pickled text data')
print(type(pickled_string),pickled_string)
pickled_dict = pickle.dumps({'some_key':'some_value'})
print(type(pickled_dict),pickled_dict)
pickled_list = pickle.dumps([4,6,8,9,10])
print(type(pickled_list),pickled_list)

<class 'bytes'> b'\x80\x03X\x1c\x00\x00\x00Generating pickled text dataq\x00.'
<class 'bytes'> b'\x80\x03}q\x00X\x08\x00\x00\x00some_keyq\x01X\n\x00\x00\x00some_valueq\x02s.'
<class 'bytes'> b'\x80\x03]q\x00(K\x04K\x06K\x08K\tK\ne.'

unpickled_text = pickle.loads(pickle.dumps('Generating pickled text data'))
print(unpickled_text, type(unpickled_text))
unpickled_dict = pickle.loads(pickle.dumps({'some_key':'some_value'}))
print(unpickled_dict, type(unpickled_dict))
unpickled_range = pickle.loads(pickle.dumps(range(10)))
print(unpickled_range, type(unpickled_range))
unpickled_list = pickle.loads(pickle.dumps([10,9,8,7,6,5,4,3,2,1]))
print(unpickled_list, type(unpickled_list))

Generating pickled text data <class 'str'>
{'some_key': 'some_value'} <class 'dict'>
range(0, 10) <class 'range'>
[10, 9, 8, 7, 6, 5, 4, 3, 2, 1] <class 'list'>

Pickle Protocol Version available currently:

• Version 0: It's original human-readable protocol and backward compatible with old python versions.
• Version 1: Old binary format compatible with previous python versions
• Version 2: Introduced in Python 2.3. Supports efficient pickling of new-style python classes.
• Version 3: Introduced in Python 3.0. Default protocol. It cannot be unpickled by Python 2.x. Explicitly support for bytes objects.
• Version 4: Introduced in Python 3.4. Supports pickling for very large objects, different kinds of objects and different data formats optimizations.

Protocol Constants:

• pickle.HIGHEST_PROTOCOL - Highest protocol available
• pickle.DEFAULT_PROTOCOL - Default protocol is version 3 currently.

Pickle module exceptions:

• pickle.PickleError - Common base class for other Pickling Exceptions. Extends Exception class.
• pickle.PicklingError - Raised when an unpickable object is encountered by a module. Extends PickleError.
• pickle.UnpicklingError - Raised when unpickling fails due to corrupt data or security violations. Extends PickleError.