1 :mod:`copyreg` --- Register :mod:`pickle` support functions 2 =========================================================== 3 4 .. module:: copyreg 5 :synopsis: Register pickle support functions. 6 7 **Source code:** :source:`Lib/copyreg.py` 8 9 .. index:: 10 module: pickle 11 module: copy 12 13 -------------- 14 15 The :mod:`copyreg` module offers a way to define functions used while pickling 16 specific objects. The :mod:`pickle` and :mod:`copy` modules use those functions 17 when pickling/copying those objects. The module provides configuration 18 information about object constructors which are not classes. 19 Such constructors may be factory functions or class instances. 20 21 22 .. function:: constructor(object) 23 24 Declares *object* to be a valid constructor. If *object* is not callable (and 25 hence not valid as a constructor), raises :exc:`TypeError`. 26 27 28 .. function:: pickle(type, function, constructor=None) 29 30 Declares that *function* should be used as a "reduction" function for objects 31 of type *type*. *function* should return either a string or a tuple 32 containing two or three elements. 33 34 The optional *constructor* parameter, if provided, is a callable object which 35 can be used to reconstruct the object when called with the tuple of arguments 36 returned by *function* at pickling time. :exc:`TypeError` will be raised if 37 *object* is a class or *constructor* is not callable. 38 39 See the :mod:`pickle` module for more details on the interface 40 expected of *function* and *constructor*. Note that the 41 :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler 42 object or subclass of :class:`pickle.Pickler` can also be used for 43 declaring reduction functions. 44 45 Example 46 ------- 47 48 The example below would like to show how to register a pickle function and how 49 it will be used: 50 51 >>> import copyreg, copy, pickle 52 >>> class C(object): 53 ... def __init__(self, a): 54 ... self.a = a 55 ... 56 >>> def pickle_c(c): 57 ... print("pickling a C instance...") 58 ... return C, (c.a,) 59 ... 60 >>> copyreg.pickle(C, pickle_c) 61 >>> c = C(1) 62 >>> d = copy.copy(c) # doctest: +SKIP 63 pickling a C instance... 64 >>> p = pickle.dumps(c) # doctest: +SKIP 65 pickling a C instance... 66
