diff options
Diffstat (limited to 'Doc/lib/libfunctools.tex')
| -rw-r--r-- | Doc/lib/libfunctools.tex | 145 |
1 files changed, 0 insertions, 145 deletions
diff --git a/Doc/lib/libfunctools.tex b/Doc/lib/libfunctools.tex deleted file mode 100644 index 654a5b1..0000000 --- a/Doc/lib/libfunctools.tex +++ /dev/null @@ -1,145 +0,0 @@ -\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. |