PyMOTW: functools
The functools module includes tools for wrapping functions and other callable objects.
Module: functools
Purpose: Tools for making decorators and other function wrappers.
Python Version: new in 2.5
Description:
The primary tool supplied by the functools module is the class partial, which can be used to "wrap" a callable with default arguments. The resulting object is itself callable and can be treated as though it is the original function. It takes all of the same arguments as the original callable and can be invoked with extra positional or named arguments as well.
partial:
This example shows two simple partial objects for the function myfunc(). Notice that show_details() prints the func, args, and keywords attributes of the partial object.
import functools
def myfunc(a, b=2):
"""Docstring for myfunc()."""
print '\tcalled myfunc with:', (a, b)
return
def show_details(name, f, is_partial=False):
"""Show details of a callable object."""
print '%s:' % name
print '\tobject:', f
if not is_partial:
print '\t__name__:', f.__name__
print '\t__doc__', repr(f.__doc__)
if is_partial:
print '\tfunc:', f.func
print '\targs:', f.args
print '\tkeywords:', f.keywords
return
show_details('myfunc', myfunc)
myfunc('a', 3)
p1 = functools.partial(myfunc, b=4)
show_details('partial with named default', p1, True)
p1('default a')
p1('override b', b=5)
p2 = functools.partial(myfunc, 'default a', b=99)
show_details('partial with defaults', p2, True)
p2()
p2(b='override b')
print 'Insufficient arguments:'
p1()
At the end of the example, the first partial created is invoked without passing a value for
a, causing an exception.
$ python functools_partial.py
myfunc:
object: <function myfunc at 0x7cbf0>
__name__: myfunc
__doc__ 'Docstring for myfunc().'
called myfunc with: ('a', 3)
partial with named default:
object: <functools.partial object at 0x74ea0>
__doc__ 'partial(func, *args, **keywords) - new function with partial application\n\tof the given arguments and keywords.\n'
func: <function myfunc at 0x7cbf0>
args: ()
keywords: {'b': 4}
called myfunc with: ('default a', 4)
called myfunc with: ('override b', 5)
partial with defaults:
object: <functools.partial object at 0x74ed0>
__doc__ 'partial(func, *args, **keywords) - new function with partial application\n\tof the given arguments and keywords.\n'
func: <function myfunc at 0x7cbf0>
args: ('default a',)
keywords: {'b': 99}
called myfunc with: ('default a', 99)
called myfunc with: ('default a', 'override b')
Insufficient arguments:
Traceback (most recent call last):
File "/Users/dhellmann/Documents/PyMOTW/in_progress/functools/functools_partial.py", line 48, in <module>
p1()
TypeError: myfunc() takes at least 1 non-keyword argument (0 given)
update_wrapper:
As illustrated in the previous example, the
partial object does not have a __name__ or __doc__ attributes by default. Losing those attributes for decorated functions makes them more difficult to debug. By using update_wrapper, you can copy or add attributes from the original function to the partial object.import functools
def myfunc(a, b=2):
"""Docstring for myfunc()."""
print '\tcalled myfunc with:', (a, b)
return
def show_details(name, f):
"""Show details of a callable object."""
print '%s:' % name
print '\tobject:', f
print '\t__name__:',
try:
print f.__name__
except AttributeError:
print '(no __name__)'
print '\t__doc__', repr(f.__doc__)
return
show_details('myfunc', myfunc)
p1 = functools.partial(myfunc, b=4)
show_details('raw wrapper', p1)
print 'Updating wrapper:'
print '\tassign:', functools.WRAPPER_ASSIGNMENTS
print '\tupdate:', functools.WRAPPER_UPDATES
functools.update_wrapper(p1, myfunc)
show_details('updated wrapper', p1)
The attributes added to the wrapper are defined in functools.WRAPPER_ASSIGNMENTS, while functools.WRAPPER_UPDATES lists values to be modified.
$ python functools_update_wrapper.py
myfunc:
object: <function myfunc at 0x7cb30>
__name__: myfunc
__doc__ 'Docstring for myfunc().'
raw wrapper:
object: <functools.partial object at 0x74f30>
__name__: (no __name__)
__doc__ 'partial(func, *args, **keywords) - new function with partial application\n\tof the given arguments and keywords.\n'
Updating wrapper:
assign: ('__module__', '__name__', '__doc__')
update: ('__dict__',)
updated wrapper:
object: <functools.partial object at 0x74f30>
__name__: myfunc
__doc__ 'Docstring for myfunc().'
Methods and Other Callables:
Partials work with any callable object, including methods and instances.
import functools
class MyClass(object):
"""Demonstration class for functools"""
def meth1(self, a, b=2):
"""Docstring for meth1()."""
print '\tcalled meth1 with:', (self, a, b)
return
def meth2(self, c, d=5):
"""Docstring for meth2"""
print '\tcalled meth2 with:', (self, c, d)
return
wrapped_meth2 = functools.partial(meth2, 'wrapped c')
functools.update_wrapper(wrapped_meth2, meth2)
def __call__(self, e, f=6):
"""Docstring for MyClass.__call__"""
print '\tcalled object with:', (self, e, f)
return
def show_details(name, f):
"""Show details of a callable object."""
print '%s:' % name
print '\tobject:', f
print '\t__name__:',
try:
print f.__name__
except AttributeError:
print '(no __name__)'
print '\t__doc__', repr(f.__doc__)
return
o = MyClass()
show_details('meth1 straight', o.meth1)
o.meth1('no default for a', b=3)
p1 = functools.partial(o.meth1, b=4)
functools.update_wrapper(p1, o.meth1)
show_details('meth1 wrapper', p1)
p1('a goes here')
show_details('meth2', o.meth2)
o.meth2('no default for c', d=6)
show_details('wrapped meth2', o.wrapped_meth2)
o.wrapped_meth2('no default for c', d=6)
show_details('instance', o)
o('no default for e')
p2 = functools.partial(o, f=7)
show_details('instance wrapper', p2)
p2('e goes here')
$ python functools_method.py
meth1 straight:
object: <bound method MyClass.meth1 of <__main__.MyClass object at 0x7ecd0>>
__name__: meth1
__doc__ 'Docstring for meth1().'
called meth1 with: (<__main__.MyClass object at 0x7ecd0>, 'no default for a', 3)
meth1 wrapper:
object: <functools.partial object at 0x81060>
__name__: meth1
__doc__ 'Docstring for meth1().'
called meth1 with: (<__main__.MyClass object at 0x7ecd0>, 'a goes here', 4)
meth2:
object: <bound method MyClass.meth2 of <__main__.MyClass object at 0x7ecd0>>
__name__: meth2
__doc__ 'Docstring for meth2'
called meth2 with: (<__main__.MyClass object at 0x7ecd0>, 'no default for c', 6)
wrapped meth2:
object: <functools.partial object at 0x74f90>
__name__: meth2
__doc__ 'Docstring for meth2'
called meth2 with: ('wrapped c', 'no default for c', 6)
instance:
object: <__main__.MyClass object at 0x7ecd0>
__name__: (no __name__)
__doc__ 'Demonstration class for functools'
called object with: (<__main__.MyClass object at 0x7ecd0>, 'no default for e', 6)
instance wrapper:
object: <functools.partial object at 0x81090>
__name__: (no __name__)
__doc__ 'partial(func, *args, **keywords) - new function with partial application\n\tof the given arguments and keywords.\n'
called object with: (<__main__.MyClass object at 0x7ecd0>, 'e goes here', 7)
wraps:
As mentioned earlier, these capabilities are especially useful when used in decorators, since the decorated function ends up with properties of the original, "raw", function.
functools provides a convenience function, wraps(), to be used as a decorator itself and to apply update_wrapper() automatically.import functools
def show_details(name, f):
"""Show details of a callable object."""
print '%s:' % name
print '\tobject:', f
print '\t__name__:',
try:
print f.__name__
except AttributeError:
print '(no __name__)'
print '\t__doc__', repr(f.__doc__)
return
def simple_decorator(f):
@functools.wraps(f)
def decorated(a='decorated defaults', b=1):
print '\tdecorated:', (a, b)
print '\t',
f(a, b=b)
return
return decorated
def myfunc(a, b=2):
print '\tmyfunc:', (a,b)
return
show_details('myfunc', myfunc)
myfunc('unwrapped, default b')
myfunc('unwrapped, passing b', 3)
wrapped_myfunc = simple_decorator(myfunc)
show_details('wrapped_myfunc', wrapped_myfunc)
wrapped_myfunc()
wrapped_myfunc('args to decorated', 4)
$ python functools_wraps.py
myfunc:
object: <function myfunc at 0x7cc70>
__name__: myfunc
__doc__ None
myfunc: ('unwrapped, default b', 2)
myfunc: ('unwrapped, passing b', 3)
wrapped_myfunc:
object: <function myfunc at 0x7ccb0>
__name__: myfunc
__doc__ None
decorated: ('decorated defaults', 1)
myfunc: ('decorated defaults', 1)
decorated: ('args to decorated', 4)
myfunc: ('args to decorated', 4)
References:
Python Module of the Week Home
Download Sample Code
Technorati Tags:
python, PyMOTW
