Back to Index

3.14.5.2 Pickling and unpickling extension types

When the Pickler encounters an object of a type it knows nothing about -- such as an extension type -- it looks in two places for a hint of how to pickle it. One alternative is for the object to implement a __reduce__() method. If provided, at pickling time __reduce__() will be called with no arguments, and it must return either a string or a tuple.

If a string is returned, it names a global variable whose contents are pickled as normal. When a tuple is returned, it must be of length two or three, with the following semantics:

• A callable object, which in the unpickling environment must be either a class, a callable registered as a ``safe constructor'' (see below), or it must have an attribute __safe_for_unpickling__ with a true value. Otherwise, an UnpicklingError will be raised in the unpickling environment. Note that as usual, the callable itself is pickled by name.

   

• A tuple of arguments for the callable object, or None.
  Deprecated since release 2.3. Use the tuple of arguments instead

   

• Optionally, the object's state, which will be passed to the object's __setstate__() method as described in section 3.14.5. If the object has no __setstate__() method, then, as above, the value must be a dictionary and it will be added to the object's __dict__.

   

Upon unpickling, the callable will be called (provided that it meets the above criteria), passing in the tuple of arguments; it should return the unpickled object.

If the second item was None, then instead of calling the callable directly, its __basicnew__() method is called without arguments. It should also return the unpickled object.

An alternative to implementing a __reduce__() method on the object to be pickled, is to register the callable with the copy_reg module. This module provides a way for programs to register ``reduction functions'' and constructors for user-defined types. Reduction functions have the same semantics and interface as the __reduce__() method described above, except that they are called with a single argument, the object to be pickled.

The registered constructor is deemed a ``safe constructor'' for purposes of unpickling as described above.

© 2002-2004 Active-Venture.com Webhosting Service

Disclaimer: This documentation is provided only for the benefits of our hosting customers.
For authoritative source of the documentation, please refer to http://python.org/doc/