From 78b18d4b4c82c90c3c45f0ea77c78bbfb3358218 Mon Sep 17 00:00:00 2001
From: Ezio Melotti <ezio.melotti@gmail.com>
Date: Thu, 8 Nov 2012 11:04:57 +0200
Subject: #11481: update copyreg docs and add example.

---
 Doc/library/copy.rst    |  4 ++--
 Doc/library/copyreg.rst | 29 ++++++++++++++++++++++++++---
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/Doc/library/copy.rst b/Doc/library/copy.rst
index 0c68bd9..1db5c2d 100644
--- a/Doc/library/copy.rst
+++ b/Doc/library/copy.rst
@@ -67,8 +67,8 @@ of lists by assigning a slice of the entire list, for example,
 
 Classes can use the same interfaces to control copying that they use to control
 pickling.  See the description of module :mod:`pickle` for information on these
-methods.  The :mod:`copy` module does not use the :mod:`copyreg` registration
-module.
+methods.  In fact, :mod:`copy` module uses the registered pickle functions from
+:mod:`copyreg` module.
 
 .. index::
    single: __copy__() (copy protocol)
diff --git a/Doc/library/copyreg.rst b/Doc/library/copyreg.rst
index a2d316e..f3721d1 100644
--- a/Doc/library/copyreg.rst
+++ b/Doc/library/copyreg.rst
@@ -9,9 +9,10 @@
    module: pickle
    module: copy
 
-The :mod:`copyreg` module provides support for the :mod:`pickle` module.  The
-:mod:`copy` module is likely to use this in the future as well.  It provides
-configuration information about object constructors which are not classes.
+The :mod:`copyreg` module offers a way to define fuctions used while pickling
+specific objects.  The :mod:`pickle` and :mod:`copy` modules use those functions
+when pickling/copying those objects.  The module provides configuration
+information about object constructors which are not classes.
 Such constructors may be factory functions or class instances.
 
 
@@ -35,3 +36,25 @@ Such constructors may be factory functions or class instances.
    See the :mod:`pickle` module for more details on the interface expected of
    *function* and *constructor*.
 
+
+Example
+-------
+
+The example below would like to show how to register a pickle function and how
+it will be used:
+
+   >>> import copyreg, copy, pickle
+   >>> class C(object):
+   ...     def __init__(self, a):
+   ...         self.a = a
+   ...
+   >>> def pickle_c(c):
+   ...     print("pickling a C instance...")
+   ...     return C, (c.a,)
+   ...
+   >>> copyreg.pickle(C, pickle_c)
+   >>> c = C(1)
+   >>> d = copy.copy(c)
+   pickling a C instance...
+   >>> p = pickle.dumps(c)
+   pickling a C instance...
-- 
cgit v0.12