Usage#

pickle_secure implements a secure way to pickle and unpickle a python object. It offers the same interface as a pickle, but a key is also required, which encrypts and decrypts the pickle.

Everything is placed in the pickle_secure module.

Three constants are provided:

pickle_secure.API_VERSION: str#

The python version of the pickle that pickle_secure targets

pickle_secure.HIGHEST_PROTOCOL: int#

The same as the original HIGHEST_PROTOCOL from the pickle module

pickle_secure.DEFAULT_PROTOCOL: int#

The same as the original DEFAULT_PROTOCOL from the pickle module

There are also three exceptions provided, all of them are just the same as the ones in the original pickle

exception pickle_secure.PickleError#

The same as the original PickleError from the pickle module

exception pickle_secure.PicklingError#

The same as the original PicklingError from the pickle module

exception pickle_secure.UnpicklingError#

The same as the original UnpicklingError from the pickle module

Also, the dumping and loading functions present in the original module are present:

def dumps(obj, protocol=None, *, fix_imports=True, key):

Dump the object to a bytes object.

Parameters:

  • obj – The object to be pickled

  • protocol (int) – The pickle protocol to be used, or None to use the default protocol

  • fix_imports (bool) – If the protocol is < 2, it will try to fix the imports to be readable by python2

  • key (str) – The encryption key

Returns:

the encrypted pickle of the object

Return type:

bytes

def dump(obj, file, protocol=None, *, fix_imports=True, key):

Dump the obj in the file object named file.

Parameters:

  • obj – The object to be pickled

  • file – The file to use to write the pickle

  • protocol (int) – The pickle protocol to be used, or None to use the default protocol

  • fix_imports (bool) – If the protocol is < 2, it will try to fix the imports to be readable by python2

  • key (str) – The encryption key

def loads(bytes_object, *, fix_imports=True, encoding="ASCII", errors="strict", key):

Retrieve the original object from a bytes object

Parameters:

  • bytes_obj (bytes) – The encrypted bytes object to be unpickled

  • fix_imports (bool) – If the protocol is < 2, it will try to fix the imports to be readable by python2

  • encoding (str) – It is present for compatibility reasons with python2

  • errors (str) – It is present for compatibility reasons with python2

  • key (str) – The encryption key

Returns:

The object that was originally pickled

def load(file, key, *, fix_imports=True, encoding="ASCII", errors="strict"):

Retrieve the original object from a file

Parameters:

  • file – The file containing the encrypted pickle

  • fix_imports (bool) – If the protocol is < 2, it will try to fix the imports to be readable by python2

  • encoding (str) – It is present for compatibility reasons with python2

  • errors (str) – It is present for compatibility reasons with python2

  • key (str) – The encryption key

Returns:

The object that was originally pickled