The session package defines class Session. A Session object may be used to save the state of an object and its sub-objects (e.g., object attributes, sequence elements, dictionary items) to a file object in XML format. A Session object may also be used to reconstruct a previously saved object from a file object. (Note that the XML specification requires that there be only one root element per document, so saving multiple objects to the same file object may not work properly.)

Session does not save a representation of Python objects; it saves the Python object types and states, which may be used to reconstruct the objects. Python objects are divided into four groups:

• primitive data type (string, int, float)

  Object type is type(obj).__name__. Object state is its value.

• standard container (list, tuple, dictionary)

  Object type is type(obj).__name__. Object state is the combined states of its contents.

• class instances

  Object type is (obj.__class__.__module__, obj.__class__.__name__). Object state is obtained in the same way as pickle. Object reconstruction follows the same procedure as pickle. (Details and exceptions described below.)

• type instances

  Object type is obj.__getfactory__(). Object state is obj.__getstate__(). During object reconstruction, the object type is used to locate a callable object which is invoked with the object state and is expected to return the reconstructed object. (Details and exceptions described below.)

The save procedure is divided into the following phases:

• identify all referenced objects - remove referenced objects that cannot be saved - construct map of objects to unique identifiers - write object types and states into XML to output

The reconstruction procedure is divided into the following phases:

• read in XML tree - convert nodes into objects - construct map of unique identifiers to objects - convert unique identifiers in objects into references - return root object

Unique Identifiers

The unique identifiers are to handle object references. For example, if an attribute A of object X is object Y, then there are two options:

• attribute A can be saved as the type and state of object Y, or - object Y can be saved separately, tagged with a unique identifier, and attribute A is saved as the unique identifier.

The former approach has an important drawback: it cannot handle objects that are referenced by more than one object. Session uses the latter approach. Generating unique identifiers is non-trivial because some objects may be saved implicitly (e.g., atoms in may be saved as part of a molecule). For all saved objects, the unique identifier may simply be the string id(obj). Implicitly saved objects must also supply their own factory method (function used to create the objects) and initialization arguments information (see below).

Class and Type Instances

While primitive data types and standard containers can be handled by Session with no help from the objects themselves, class and type instances are more complex. Class instances contain enough information so that Session can save those which do not require special processing; however, some class instances may need to do more things when they are restored (e.g., rebuild a graphical user interface). Session provides several mechanisms to provide sufficient control to reconstructed instances:

• Normally, an instance is recreated without calling its __init__ method (by creating an instance of a dummy class and then setting its __class__ attribute to the real class). If an instance has an __getinitargs__ method, then the return value from the method (which must be a tuple) is saved as part of the object state and the reconstructed instance is created by 'apply'ing the class factory method to the __getinitargs__ tuple. - Normally, an the __dict__ attribute of an instance is saved as its state, and the contents of the dictionary is used to set attributes of the reconstructed object. If an instance has a __getstate__ method, then the return value from the method is saved as the state instead. If the class has a __setstate__ method, then it is invoked with the saved state to restore the object state.

Type instances contain much less information (accessible via Python introspection) than class instances:

• They do not contain information about its factory method (the function used to create the instance). - They do not necessarily have an __dict__ attribute, so it is difficult to identify which objects they reference and to construct object state automatically. - They cannot be created without using a factory method.

These differences require that type instances provide additional methods to supply the necessary information. In keeping with the class instance interface style, Session uses __getstate__, __setstate__, and __getinitargs__ methods for type instances. In addition, Session uses the __getfactory__ method to obtain the factory information and saves it along with the object state. For completeness, Session checks for the __getfactory__ method for class instances as well as type instances.

If an instance does not provide special methods (__getfactory__, __getstate__, __getinitargs__, __setstate__), Session checks for registered class/type handlers. These handlers may be registered using the register method in Session with the appropriate keyword arguments.

• Identify Objects to Save *

Once the object state has been obtained, either via __dict__ or __getstate__(), it is used to find other referenced objects. Objects that do not contain sufficient information.