pickling module

Define a class to pickle objects.

“pickling” a file comes down to saving it in binary format. It can be loaded and used again later, even with a different Python instance. This is useful when you want to study a Fault that took a long time to be compensated, or a SimulationOutput obtained by a time-consuming TraceWin multiparticle simulation.

Warning

This a very basic pickling. Do not use for long-term storage, but for debug only.

Note

Some attributes such as lambda function in FieldMap or modules in SimulationOutput cannot be pickled by the built-in pickle module. I do not plan to refactor them, so for now we stick with cloudpickle module.

Some objects have built-in pickle and unpickle methods, namely:

class MyPickler[source]

Bases: ABC

Define an object that can save/load arbitrary objects to files.

abstractmethod pickle(my_object, path, initialfile=None, initialdir=None, title=None)[source]

Pickle (“save”) the object to a binary file.

Parameters:
Return type:

Path | None

abstractmethod unpickle(path, expected=None, title=None)[source]
Overloads:

  • self, path (Path | str | None), expected (None), title (str | None) → object | None

  • self, path (Path | str | None), expected (Type[T]), title (str | None) → T | None

Parameters:
Return type:

object | None

Unpickle (“load”) the given path to recreate original object.

Parameters:
Return type:

object | None

_abc_impl = <_abc._abc_data object at 0x7318fb34bb00>
class MyCloudPickler[source]

Bases: MyPickler

A MyPickler that can handle modules and lambda functions.

This pickler should not raise errors, but all attributes may not be properly re-created.

__init__()[source]

Check that cloudpickle module can be imported.

Return type:

None

pickle(my_object, path, initialfile=None, initialdir=None, title=None)[source]

Pickle (“save”) the object to a binary file.

Parameters:

  • my_object (object) – Object to pickle.

  • path (Path | str | None) – Filepath to the pickled object. If None, a GUI dialog will prompt the user to select a file.

  • initialdir (Path | str | None, default: None) – The directory that the GUI dialog starts in, when path is None.

  • initialfile (Path | str | None, default: None) – The file selected upon opening the GUI dialog, when path is None.

  • title (str | None, default: None) – Title of the GUI window. Use this to clarify what should be pickled.

Return type:

Path | None

Returns:

  • Absolute path to the pickled object, or None if no object was

  • pickled.

_abc_impl = <_abc._abc_data object at 0x7318fb34bac0>
unpickle(path, expected=None, title=None)[source]

Unpickle (“load”) the given path to recreate original object.

Parameters:

  • path (Path | str | None) – Filepath to the pickled object. If None, a GUI dialog will prompt the user to select a file.

  • expected (type | None, default: None) – Expected type of the unpickled object. If provided, the method will check if the unpickled object is an instance of expected. If not, a TypeError is raised.

  • title (str | None, default: None) – Title of the GUI window. Use this to clarify what should be unpickled.

Return type:

object | None

Returns:

  • Unpickled object. Has type expected if this argument was provided.

  • If there was a problem, None is returned but no exception is

  • raised.

ask_pickle_filename(initialdir=None, initialfile=None, title='Choose pickle filename')[source]

Open a GUI dialog to choose the pickle filename.

Parameters:

  • initialdir (Path | str | None, default: None) – The directory that the dialog starts in.

  • initialfile (Path | str | None, default: None) – The file selected upon opening the dialog.

  • title (str, default: 'Choose pickle filename')

Return type:

Path | None

Returns:

  • Absolute filepath of pickle file to load/save. If None is returned, the

  • pickling operation will simply be skipped.