Add entry for reprlib.

3 files changed, 30 insertions, 3 deletions

diff --git a/Doc/library/reprlib.rst b/Doc/library/reprlib.rst
index c794a8d..0e870da 100644
--- a/Doc/library/reprlib.rst
+++ b/Doc/library/reprlib.rst
@@ -5,6 +5,9 @@
    :synopsis: Alternate repr() implementation with size limits.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
+**Source code:** :source:`Lib/reprlib.py`
+
+--------------
 
 The :mod:`reprlib` module provides a means for producing object representations
 with limits on the size of the resulting strings. This is used in the Python
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index 3c1da9f..c680d31 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -987,6 +987,32 @@ implemented::
 
 (Patch submitted by Daniel Urban; :issue:`5867`.)
 
+reprlib
+-------
+
+When writing a :meth:`__repr__` method for a custom container, it is easy to
+forget to handle the case where a member refers back to the container itself.
+Python's builtin objects such as :class:`list` and :class:`set` handle
+self-reference by displaying "..." in the recursive part of the representation
+string.
+
+To help write such :meth:`__repr__` methods, the :mod:`reprlib` module has a new
+decorator, :func:`reprlib.recursive_repr`, for detecting recursive calls to
+:meth:`__repr__` and substituting a placeholder string instead:
+
+        >>> class MyList(list):
+                @recursive_repr()
+                def __repr__(self):
+                    return '<' + '|'.join(map(repr, self)) + '>'
+
+        >>> m = MyList('abc')
+        >>> m.append(m)
+        >>> m.append('x')
+        >>> print(m)
+        <'a'|'b'|'c'|...|'x'>
+
+(Contributed by Raymond Hettinger.)
+
 contextlib
 ----------
 
@@ -1697,9 +1723,6 @@ reading directly from dictionaries and strings.
             - non-UTF8 percent encoding of non-ASCII characters
           Issue 2987 for IPv6 (RFC2732) support in urlparse
 
-.. XXX reprlib.recursive_repr
-
-
 Multi-threading
 ===============
 
diff --git a/Lib/reprlib.py b/Lib/reprlib.py
index 7b5c436..9fee304 100644
--- a/Lib/reprlib.py
+++ b/Lib/reprlib.py
@@ -30,6 +30,7 @@ def recursive_repr(fillvalue='...'):
         wrapper.__module__ = getattr(user_function, '__module__')
         wrapper.__doc__ = getattr(user_function, '__doc__')
         wrapper.__name__ = getattr(user_function, '__name__')
+        wrapper.__name__ = getattr(user_function, '__annotations__', {})
         return wrapper
 
     return decorating_function