Add functools.update_wrapper() and functools.wraps() as described in PEP 356

1 files changed, 46 insertions, 0 deletions

diff --git a/Doc/lib/libfunctools.tex b/Doc/lib/libfunctools.tex
index a25a23a..33a6f52 100644
--- a/Doc/lib/libfunctools.tex
+++ b/Doc/lib/libfunctools.tex
@@ -5,6 +5,7 @@
 
 \moduleauthor{Peter Harris}{scav@blueyonder.co.uk}
 \moduleauthor{Raymond Hettinger}{python@rcn.com}
+\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com}
 \sectionauthor{Peter Harris}{scav@blueyonder.co.uk}
 
 \modulesynopsis{Higher-order functions and operations on callable objects.}
@@ -50,6 +51,51 @@ two:
   \end{verbatim}
 \end{funcdesc}
 
+\begin{funcdesc}{update_wrapper}
+{wrapper, wrapped\optional{, assigned}\optional{, updated}}
+Update a wrapper function to look like the wrapped function. The optional
+arguments are tuples to specify which attributes of the original
+function are assigned directly to the matching attributes on the wrapper
+function and which attributes of the wrapper function are updated with
+the corresponding attributes from the original function. The default
+values for these arguments are the module level constants
+\var{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper function's name,
+module and documentation string) and \var{WRAPPER_UPDATES} (which
+updates the wrapper function's instance dictionary).
+
+The main intended use for this function is in decorator functions
+which wrap the decorated function and return the wrapper. If the
+wrapper function is not updated, the metadata of the returned function
+will reflect the wrapper definition rather than the original function
+definition, which is typically less than helpful.
+\end{funcdesc}
+
+\begin{funcdesc}{wraps}
+{wrapped\optional{, assigned}\optional{, updated}}
+This is a convenience function for invoking
+\code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)}
+as a function decorator when defining a wrapper function. For example:
+  \begin{verbatim}
+        >>> def my_decorator(f):
+        ...     @wraps(f)
+        ...     def wrapper(*args, **kwds):
+        ...         print 'Calling decorated function'
+        ...         return f(*args, **kwds)
+        ...     return wrapper
+        ...
+        >>> @my_decorator
+        ... def example():
+        ...     print 'Called example function'
+        ...
+        >>> example()
+        Calling decorated function
+        Called example function
+        >>> example.__name__
+        'example'
+  \end{verbatim}
+Without the use of this decorator factory, the name of the example
+function would have been \code{'wrapper'}.
+\end{funcdesc}
 
 
 \subsection{\class{partial} Objects \label{partial-objects}}