Module enthought.​persistence.​state_pickler

This module provides code that allows one to pickle the state of a Python object to a dictionary.

The motivation for this is simple. The standard Python pickler/unpickler is best used to pickle simple objects and does not work too well for complex code. Specifically, there are two major problems (1) the pickle file format is not easy to edit with a text editor and (2) when a pickle is unpickled, it creates all the necessary objects and sets the state of these objects.

Issue (2) might not appear to be a problem. However, often, the determination of the entire 'state' of an application requires the knowledge of the state of many objects that are not really in the users concern. The user would ideally like to pickle just what he thinks is relevant. Now, given that the user is not going to save the entire state of the application, the use of pickle is insufficient since the state is no longer completely known (or worth knowing). The default Unpickler recreates the objects and the typical implementation of __setstate__ is usually to simply update the object's __dict__ attribute. This is inadequate because the pickled information is taken out of the real context when it was saved.

The StatePickler basically pickles the 'state' of an object into a large dictionary. This pickled data may be easily unpickled and modified on the interpreter or edited with a text editor (pprint.saferepr is a friend). The second problem is also eliminated. When this state is unpickled using StateUnpickler, what you get is a special dictionary (a State instance). This allows one to navigate the state just like the original object. Its up to the user to create any new objects and set their states using this information. This allows for a lot of flexibility while allowing one to save and set the state of (almost) any Python object.

The StateSetter class helps set the state of a known instance. When setting the state of an instance it checks to see if there is a __set_pure_state__ method that in turn calls StateSetter.set appropriately.

Additionally, there is support for versioning. The class' version is obtain from the __version__ class attribute. This version along with the versions of the bases of a class is embedded into the metadata of the state and stored. By using version_registry.py a user may register a handler for a particular class and module. When the state of an object is set using StateSetter.set_state, then these handlers are called in reverse order of their MRO. This gives the handler an opportunity to upgrade the state depending on its version. Builtin classes are not scanned for versions. If a class has no version, then by default it is assumed to be -1.

Example:

>>> class A:
...    def __init__(self):
...        self.a = 'a'
...
>>> a = A()
>>> a.a = 100
>>> import state_pickler
>>> s = state_pickler.dumps(a)               # Dump the state of `a`.
>>> state = state_pickler.loads_state(s)     # Get the state back.
>>> b = state_pickler.create_instance(state) # Create the object.
>>> state_pickler.set_state(b, state)        # Set the object's state.
>>> assert b.a == 100