| \section{\module{functools} --- |
| Higher order functions and operations on callable objects.} |
| |
| \declaremodule{standard}{functools} % standard library, in Python |
| |
| \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.} |
| |
| \versionadded{2.5} |
| |
| The \module{functools} module is for higher-order functions: functions |
| that act on or return other functions. In general, any callable object can |
| be treated as a function for the purposes of this module. |
| |
| |
| The \module{functools} module defines the following function: |
| |
| \begin{funcdesc}{partial}{func\optional{,*args}\optional{, **keywords}} |
| Return a new \class{partial} object which when called will behave like |
| \var{func} called with the positional arguments \var{args} and keyword |
| arguments \var{keywords}. If more arguments are supplied to the call, they |
| are appended to \var{args}. If additional keyword arguments are supplied, |
| they extend and override \var{keywords}. Roughly equivalent to: |
| \begin{verbatim} |
| def partial(func, *args, **keywords): |
| def newfunc(*fargs, **fkeywords): |
| newkeywords = keywords.copy() |
| newkeywords.update(fkeywords) |
| return func(*(args + fargs), **newkeywords) |
| newfunc.func = func |
| newfunc.args = args |
| newfunc.keywords = keywords |
| return newfunc |
| \end{verbatim} |
| |
| The \function{partial} is used for partial function application which |
| ``freezes'' some portion of a function's arguments and/or keywords |
| resulting in a new object with a simplified signature. For example, |
| \function{partial} can be used to create a callable that behaves like |
| the \function{int} function where the \var{base} argument defaults to |
| two: |
| \begin{verbatim} |
| >>> basetwo = partial(int, base=2) |
| >>> basetwo.__doc__ = 'Convert base 2 string to an int.' |
| >>> basetwo('10010') |
| 18 |
| \end{verbatim} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{reduce}{function, sequence\optional{, initializer}} |
| Apply \var{function} of two arguments cumulatively to the items of |
| \var{sequence}, from left to right, so as to reduce the sequence to |
| a single value. For example, \code{reduce(lambda x, y: x+y, [1, 2, |
| 3, 4, 5])} calculates \code{((((1+2)+3)+4)+5)}. The left argument, |
| \var{x}, is the accumulated value and the right argument, \var{y}, |
| is the update value from the \var{sequence}. If the optional |
| \var{initializer} is present, it is placed before the items of the |
| sequence in the calculation, and serves as a default when the |
| sequence is empty. If \var{initializer} is not given and |
| \var{sequence} contains only one item, the first item is returned. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{update_wrapper} |
| {wrapper, wrapped\optional{, assigned}\optional{, updated}} |
| Update a \var{wrapper} function to look like the \var{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 |
| \var{__name__}, \var{__module__} and \var{__doc__}, the documentation string) |
| and \var{WRAPPER_UPDATES} (which updates the wrapper function's \var{__dict__}, |
| i.e. the 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(): |
| ... """Docstring""" |
| ... print 'Called example function' |
| ... |
| >>> example() |
| Calling decorated function |
| Called example function |
| >>> example.__name__ |
| 'example' |
| >>> example.__doc__ |
| 'Docstring' |
| \end{verbatim} |
| Without the use of this decorator factory, the name of the example |
| function would have been \code{'wrapper'}, and the docstring of the |
| original \function{example()} would have been lost. |
| \end{funcdesc} |
| |
| |
| \subsection{\class{partial} Objects \label{partial-objects}} |
| |
| |
| \class{partial} objects are callable objects created by \function{partial()}. |
| They have three read-only attributes: |
| |
| \begin{memberdesc}[callable]{func}{} |
| A callable object or function. Calls to the \class{partial} object will |
| be forwarded to \member{func} with new arguments and keywords. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[tuple]{args}{} |
| The leftmost positional arguments that will be prepended to the |
| positional arguments provided to a \class{partial} object call. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[dict]{keywords}{} |
| The keyword arguments that will be supplied when the \class{partial} object |
| is called. |
| \end{memberdesc} |
| |
| \class{partial} objects are like \class{function} objects in that they are |
| callable, weak referencable, and can have attributes. There are some |
| important differences. For instance, the \member{__name__} and |
| \member{__doc__} attributes are not created automatically. Also, |
| \class{partial} objects defined in classes behave like static methods and |
| do not transform into bound methods during instance attribute look-up. |