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 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | **Source code:** :source:`Lib/copyreg.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | .. index:: |
| 10 | module: pickle |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | module: copy |
| 12 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 13 | -------------- |
| 14 | |
Donald Stufft | 8b852f1 | 2014-05-20 12:58:38 -0400 | [diff] [blame] | 15 | The :mod:`copyreg` module offers a way to define functions used while pickling |
Ezio Melotti | 78b18d4 | 2012-11-08 11:04:57 +0200 | [diff] [blame] | 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. |
Benjamin Peterson | b5314c6 | 2009-12-13 21:04:16 +0000 | [diff] [blame] | 19 | Such constructors may be factory functions or class instances. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 28 | .. function:: pickle(type, function, constructor=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | |
Georg Brandl | 23e8db5 | 2008-04-07 19:17:06 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Antoine Pitrou | 8d3c290 | 2012-03-04 18:31:48 +0100 | [diff] [blame] | 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. |
Ezio Melotti | 78b18d4 | 2012-11-08 11:04:57 +0200 | [diff] [blame] | 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) |
Marco Buttu | b2a7c2f | 2017-03-02 12:02:43 +0100 | [diff] [blame] | 62 | >>> d = copy.copy(c) # doctest: +SKIP |
Ezio Melotti | 78b18d4 | 2012-11-08 11:04:57 +0200 | [diff] [blame] | 63 | pickling a C instance... |
Marco Buttu | b2a7c2f | 2017-03-02 12:02:43 +0100 | [diff] [blame] | 64 | >>> p = pickle.dumps(c) # doctest: +SKIP |
Ezio Melotti | 78b18d4 | 2012-11-08 11:04:57 +0200 | [diff] [blame] | 65 | pickling a C instance... |