Alexandre Vassalotti | f7fa63d | 2008-05-11 08:55:36 +0000 | [diff] [blame] | 1 | :mod:`copyreg` --- Register :mod:`pickle` support functions |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 2 | =========================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
Alexandre Vassalotti | f7fa63d | 2008-05-11 08:55:36 +0000 | [diff] [blame] | 4 | .. module:: copyreg |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 5 | :synopsis: Register pickle support functions. |
| 6 | |
| 7 | |
| 8 | .. index:: |
| 9 | module: pickle |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | module: copy |
| 11 | |
Ezio Melotti | 78b18d4 | 2012-11-08 11:04:57 +0200 | [diff] [blame] | 12 | The :mod:`copyreg` module offers a way to define fuctions used while pickling |
| 13 | specific objects. The :mod:`pickle` and :mod:`copy` modules use those functions |
| 14 | when pickling/copying those objects. The module provides configuration |
| 15 | information about object constructors which are not classes. |
Benjamin Peterson | b5314c6 | 2009-12-13 21:04:16 +0000 | [diff] [blame] | 16 | Such constructors may be factory functions or class instances. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | |
| 18 | |
| 19 | .. function:: constructor(object) |
| 20 | |
| 21 | Declares *object* to be a valid constructor. If *object* is not callable (and |
| 22 | hence not valid as a constructor), raises :exc:`TypeError`. |
| 23 | |
| 24 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 25 | .. function:: pickle(type, function, constructor=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
Georg Brandl | 23e8db5 | 2008-04-07 19:17:06 +0000 | [diff] [blame] | 27 | Declares that *function* should be used as a "reduction" function for objects |
| 28 | of type *type*. *function* should return either a string or a tuple |
| 29 | containing two or three elements. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
| 31 | The optional *constructor* parameter, if provided, is a callable object which |
| 32 | can be used to reconstruct the object when called with the tuple of arguments |
| 33 | returned by *function* at pickling time. :exc:`TypeError` will be raised if |
| 34 | *object* is a class or *constructor* is not callable. |
| 35 | |
Antoine Pitrou | 8d3c290 | 2012-03-04 18:31:48 +0100 | [diff] [blame] | 36 | See the :mod:`pickle` module for more details on the interface |
| 37 | expected of *function* and *constructor*. Note that the |
| 38 | :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. |
Ezio Melotti | 78b18d4 | 2012-11-08 11:04:57 +0200 | [diff] [blame] | 41 | |
| 42 | Example |
| 43 | ------- |
| 44 | |
| 45 | The example below would like to show how to register a pickle function and how |
| 46 | it will be used: |
| 47 | |
| 48 | >>> import copyreg, copy, pickle |
| 49 | >>> class C(object): |
| 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) |
| 60 | pickling a C instance... |
| 61 | >>> p = pickle.dumps(c) |
| 62 | pickling a C instance... |