Book Excerpt: The Python Standard Library by Example

Acquiring Function Properties

The partial object does not have __name__ or __doc__ attributes by default, and without those attributes, decorated functions are more difficult to debug. Using update_wrapper() copies or adds attributes from the original function to the partial object.

import functools 

def myfunc(a, b=2): 
    """Docstring for myfunc()."""
    print ’ called myfunc with:’, (a, b)
    return 

def show_details(name, f): 
   """Show details of a callable object."""
   print ’%s:’ % name
   print ’ object:’,f
   print ’ __name__:’,
   try: 
      print f.__name__
   except AttributeError: 
      print ’(no __name__)’
   print ’ __doc__’, repr(f.__doc__)
   print
   return 

show_details(’myfunc’, myfunc) 

p1 = functools.partial(myfunc, b=4) 
show_details(’raw wrapper’, p1) 

print ’Updating wrapper:’
print ’ assign:’, functools.WRAPPER_ASSIGNMENTS
print ’ update:’, functools.WRAPPER_UPDATES
print 

functools.update_wrapper(p1, myfunc) 
show_details(’updated wrapper’, p1) 

The attributes added to the wrapper are defined in WRAPPER_ASSIGNMENTS, while WRAPPER_UPDATES lists values to be modified.

$ python functools_update_wrapper.py 

myfunc:
 object: <function myfunc at 0x100da2050>
 __name__: myfunc
 __doc__ ’Docstring for myfunc().’ 

raw wrapper:
 object: <functools.partial object at 0x100d993c0>
 __name__: (no __name__)
 __doc__ ’partial(func, *args, **keywords) -new function with parti 
al application\n of the given arguments and keywords.\n’ 

Updating wrapper:
 assign: (’__module__’, ’__name__’, ’__doc__’)
 update: (’__dict__’,) 

updated wrapper:
 object: <functools.partial object at 0x100d993c0>
 __name__: myfunc
 __doc__ ’Docstring for myfunc().’ 

Other Callables

Partials work with any callable object, not just with stand-alone functions.

import functools 

class MyClass(object): 
   """Demonstration class for functools""" 

   def method1(self, a, b=2): 
      """Docstring for method1().""" 
      print ’ called method1 with:’, (self, a, b)
      return 

   def method2(self, c, d=5): 
      """Docstring for method2""" 
       print ’ called method2 with:’, (self, c, d)
       return 
       wrapped_method2 = functools.partial(method2, ’wrapped c’)
       functools.update_wrapper(wrapped_method2, method2) 
  
     def __call__(self, e, f=6): 
       """Docstring for MyClass.__call__"""
        print ’ called object with:’, (self, e, f)
        return 

def show_details(name, f): 
    """Show details of a callable object."""
     print ’%s:’ % name
     print ’ object:’,f
     print ’ __name__:’,
     try: 
        print f.__name__
     except AttributeError: 
        print ’(no __name__)’
     print ’ __doc__’, repr(f.__doc__)
     return 

o = MyClass() 

show_details(’method1 straight’, o.method1)
o.method1(’no default for a’, b=3) 
print 

p1 = functools.partial(o.method1, b=4) 
functools.update_wrapper(p1, o.method1) 
show_details(’method1 wrapper’, p1) 
p1(’a goes here’) 
print 

show_details(’method2’, o.method2)
o.method2(’no default for c’, d=6) 
print 

show_details(’wrapped method2’, o.wrapped_method2) 
o.wrapped_method2(’no default for c’, d=6) 
print 

show_details(’instance’, o) 
o(’no default for e’) 
print 
p2 = functools.partial(o, f=7) 
show_details(’instance wrapper’, p2) 
p2(’e goes here’) 

This example creates partials from an instance and methods of an instance.

$ python functools_method.py 

method1 straight: 
  object: <bound method MyClass.method1 of <__main__.MyClass object
at 0x100da3550>> 
  __name__: method1 
  __doc__ ’Docstring for method1().’ 
  called method1 with: (<__main__.MyClass object at 0x100da3550>, ’n 
o default for a’, 3) 

method1 wrapper: 
  object: <functools.partial object at 0x100d99470> 
  __name__: method1 
  __doc__ ’Docstring for method1().’ 
  called method1 with: (<__main__.MyClass object at 0x100da3550>, ’a 
 goes here’, 4) 

method2: 
  object: <bound method MyClass.method2 of <__main__.MyClass object
at 0x100da3550>> 
  __name__: method2 
  __doc__ ’Docstring for method2’ 
  called method2 with: (<__main__.MyClass object at 0x100da3550>, ’n 
o default for c’, 6) 

wrapped method2: 
  object: <functools.partial object at 0x100d993c0> 
  __name__: method2 
  __doc__ ’Docstring for method2’ 
  called method2 with: (’wrapped c’, ’no default for c’, 6) 

instance: 
  object: <__main__.MyClass object at 0x100da3550> 
  __name__: (no __name__) 
  __doc__ ’Demonstration class for functools’ 
  called object with: (<__main__.MyClass object at 0x100da3550>, ’no 
    default for e’, 6) 
  instance wrapper:
    object: <functools.partial object at 0x100d994c8>
    __name__: (no __name__) 
    __doc__ ’partial(func, *args, **keywords) -new function with part 
  ial application\n of the given arguments and keywords.\n’
    called object with: (<__main__.MyClass object at 0x100da3550>, ’e
  goes here’, 7)