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   pair: module; pickle
11   pair: module; copy
12
13--------------
14
15The :mod:`copyreg` module offers a way to define functions used while pickling
16specific objects.  The :mod:`pickle` and :mod:`copy` modules use those functions
17when pickling/copying those objects.  The module provides configuration
18information about object constructors which are not classes.
19Such 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_ob=None)
29
30   Declares that *function* should be used as a "reduction" function for objects
31   of type *type*.  *function* must return either a string or a tuple
32   containing between two and six elements. See the :attr:`~pickle.Pickler.dispatch_table`
33   for more details on the interface of *function*.
34
35   The *constructor_ob* parameter is a legacy feature and is now ignored, but if
36   passed it must be a callable.
37
38   Note that the :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler
39   object or subclass of :class:`pickle.Pickler` can also be used for
40   declaring reduction functions.
41
42Example
43-------
44
45The example below would like to show how to register a pickle function and how
46it will be used:
47
48   >>> import copyreg, copy, pickle
49   >>> class C:
50   ...     def __init__(self, a):
51   ...         self.a = a
52   ...
53   >>> def pickle_c(c):
54   ...     print("pickling a C instance...")
55   ...     return C, (c.a,)
56   ...
57   >>> copyreg.pickle(C, pickle_c)
58   >>> c = C(1)
59   >>> d = copy.copy(c)  # doctest: +SKIP
60   pickling a C instance...
61   >>> p = pickle.dumps(c)  # doctest: +SKIP
62   pickling a C instance...
63