|
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 |
|
14 The :mod:`functools` module is for higher-order functions: functions that act on |
|
15 or return other functions. In general, any callable object can be treated as a |
|
16 function for the purposes of this module. |
|
17 |
|
18 The :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 |
|
117 have 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 |
|
138 callable, weak referencable, and can have attributes. There are some important |
|
139 differences. For instance, the :attr:`__name__` and :attr:`__doc__` attributes |
|
140 are not created automatically. Also, :class:`partial` objects defined in |
|
141 classes behave like static methods and do not transform into bound methods |
|
142 during instance attribute look-up. |
|
143 |