/Doc/library/functools.rst

  1:mod:`functools` --- Higher order functions and operations on callable objects
  2==============================================================================
  3
  4.. module:: functools
  5   :synopsis: Higher order functions and operations on callable objects.
  6.. moduleauthor:: Peter Harris <scav@blueyonder.co.uk>
  7.. moduleauthor:: Raymond Hettinger <python@rcn.com>
  8.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
  9.. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
 10
 11
 12.. versionadded:: 2.5
 13
 14The :mod:`functools` module is for higher-order functions: functions that act on
 15or return other functions. In general, any callable object can be treated as a
 16function for the purposes of this module.
 17
 18The :mod:`functools` module defines the following functions:
 19
 20
 21.. function:: reduce(function, iterable[, initializer])
 22
 23   This is the same function as :func:`reduce`.  It is made available in this module
 24   to allow writing code more forward-compatible with Python 3.
 25
 26   .. versionadded:: 2.6
 27
 28
 29.. function:: partial(func[,*args][, **keywords])
 30
 31   Return a new :class:`partial` object which when called will behave like *func*
 32   called with the positional arguments *args* and keyword arguments *keywords*. If
 33   more arguments are supplied to the call, they are appended to *args*. If
 34   additional keyword arguments are supplied, they extend and override *keywords*.
 35   Roughly equivalent to::
 36
 37      def partial(func, *args, **keywords):
 38          def newfunc(*fargs, **fkeywords):
 39              newkeywords = keywords.copy()
 40              newkeywords.update(fkeywords)
 41              return func(*(args + fargs), **newkeywords)
 42          newfunc.func = func
 43          newfunc.args = args
 44          newfunc.keywords = keywords
 45          return newfunc
 46
 47   The :func:`partial` is used for partial function application which "freezes"
 48   some portion of a function's arguments and/or keywords resulting in a new object
 49   with a simplified signature.  For example, :func:`partial` can be used to create
 50   a callable that behaves like the :func:`int` function where the *base* argument
 51   defaults to two:
 52
 53      >>> from functools import partial
 54      >>> basetwo = partial(int, base=2)
 55      >>> basetwo.__doc__ = 'Convert base 2 string to an int.'
 56      >>> basetwo('10010')
 57      18
 58
 59
 60.. function:: update_wrapper(wrapper, wrapped[, assigned][, updated])
 61
 62   Update a *wrapper* function to look like the *wrapped* function. The optional
 63   arguments are tuples to specify which attributes of the original function are
 64   assigned directly to the matching attributes on the wrapper function and which
 65   attributes of the wrapper function are updated with the corresponding attributes
 66   from the original function. The default values for these arguments are the
 67   module level constants *WRAPPER_ASSIGNMENTS* (which assigns to the wrapper
 68   function's *__name__*, *__module__* and *__doc__*, the documentation string) and
 69   *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
 70   instance dictionary).
 71
 72   The main intended use for this function is in :term:`decorator` functions which
 73   wrap the decorated function and return the wrapper. If the wrapper function is
 74   not updated, the metadata of the returned function will reflect the wrapper
 75   definition rather than the original function definition, which is typically less
 76   than helpful.
 77
 78
 79.. function:: wraps(wrapped[, assigned][, updated])
 80
 81   This is a convenience function for invoking ``partial(update_wrapper,
 82   wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator
 83   when defining a wrapper function. For example:
 84
 85      >>> from functools import wraps
 86      >>> def my_decorator(f):
 87      ...     @wraps(f)
 88      ...     def wrapper(*args, **kwds):
 89      ...         print 'Calling decorated function'
 90      ...         return f(*args, **kwds)
 91      ...     return wrapper
 92      ...
 93      >>> @my_decorator
 94      ... def example():
 95      ...     """Docstring"""
 96      ...     print 'Called example function'
 97      ...
 98      >>> example()
 99      Calling decorated function
100      Called example function
101      >>> example.__name__
102      'example'
103      >>> example.__doc__
104      'Docstring'
105
106   Without the use of this decorator factory, the name of the example function
107   would have been ``'wrapper'``, and the docstring of the original :func:`example`
108   would have been lost.
109
110
111.. _partial-objects:
112
113:class:`partial` Objects
114------------------------
115
116:class:`partial` objects are callable objects created by :func:`partial`. They
117have three read-only attributes:
118
119
120.. attribute:: partial.func
121
122   A callable object or function.  Calls to the :class:`partial` object will be
123   forwarded to :attr:`func` with new arguments and keywords.
124
125
126.. attribute:: partial.args
127
128   The leftmost positional arguments that will be prepended to the positional
129   arguments provided to a :class:`partial` object call.
130
131
132.. attribute:: partial.keywords
133
134   The keyword arguments that will be supplied when the :class:`partial` object is
135   called.
136
137:class:`partial` objects are like :class:`function` objects in that they are
138callable, weak referencable, and can have attributes.  There are some important
139differences.  For instance, the :attr:`__name__` and :attr:`__doc__` attributes
140are not created automatically.  Also, :class:`partial` objects defined in
141classes behave like static methods and do not transform into bound methods
142during instance attribute look-up.
143