Unable to understand this python decorator

Question

I am new to python decorators. I have understood the basic concepts with the help of simple examples. But when I tried to read this more practical decorator, I feel lost. Given below is the code followed by my questions:

class countcalls(object):
   "Decorator that keeps track of the number of times a function is called."

   __instances = {}

   def __init__(self, f):
      self.__f = f
      self.__numcalls = 0
      countcalls.__instances[f] = self

   def __call__(self, *args, **kwargs):
      self.__numcalls += 1
      return self.__f(*args, **kwargs)

   def count(self):
      "Return the number of times the function f was called."
      return countcalls.__instances[self.__f].__numcalls

@countcalls
def f():
   print 'f called'

f()
f()
f()
print f.count() # prints 3

My doubts:

1. When we prefix the decorator to a function, does that mean that we are creating an object of the decorator class right there? In our case, when it says:

   @countcalls def f(): print 'f called'

Is @countcalls equivalent to creating a countcalls object and passing the function below to its __init__ method?

1. The __call__ is taking three arguments. self is fine as far as the question above is answered. What the hell are the two other arguments: *args, **kwargs and what are they achieving?

2. How can I get better at decorators?

Answer 1

This code seems to have some oddness. Let's talk about the slightly-simpler code

class countcalls(object):

    def __init__(self, f):
        self._f = f
        self._numcalls = 0

    def __call__(self, *args, **kwargs):
        self._numcalls += 1
        return self._f(*args, **kwargs)

    def count(self):
        return self._numcalls

@countcalls
def f():
    print 'f called'

f()
f()
f()
print f.count() 

# output:
#   f called
#   f called
#   f called
#   3

Remember

@countcalls
def f():
    print 'f called'

is the same thing as

def f():
    print 'f called'
f = countcalls(f)

so when we use the decorator, the function is stored using the _f attribute.

So f is a countcalls instance. When you do f(...) you call f.__call__(...)—that's how you implement () syntax for your own instances. So when you call f, what happens?

    def __call__(self, *args, **kwargs):
        self._numcalls += 1
        return self._f(*args, **kwargs)

First, you use *args and **kwargs, which in the definition condense all positional and keyword arguments into a tuple and dict, and later in the call expand a sequence and a dict into arguments (see 4.7.4 in the official tutorial for more information). Here's a partial example

>>> def f(*args): print args
... 
>>> f(1, 2)
(1, 2)
>>> f()
()
>>> def add(a, b): return a + b
... 
>>> add(*[4, 3])
7
>>> add(**{'b': 5, 'a': 9})
14

so def f(*args, **kwargs): return g(*args, **kwargs) just does a passthrough on all arguments.

Aside from that, you're just keeping track of how many times you've been in __call__ for this instance (how many times you've called f).

Just remember that @dec def f(...): ... is the same as def f(...): ... f = dec(f) and you should be able to figure out most decorators fine, given enough time. Like all things, practice will help you do this quicker and easier.

Answer 2

When we prefix the decorator to a function, does that mean that we are creating an object of the decorator class right there?

There's a very easy way to find out.

>>> @countcalls
... def f(): pass
>>> f
<a.countcalls object at 0x3175310>
>>> isinstance(f, countcalls)
True

So, yes.

Is @countcalls equivalent to creating a countcalls object and passing the function below to its init method?

Almost. It's equivalent to that and then assigning the result to the function's name, i.e.

def f():
    print 'f called'
f = countcalls(f)

How can I get better at decorators?

1. Practice
2. Read other people's code that uses them
3. Study the relevant PEPs

Answer 3

1. It is equivalent to the following:

   f = countcalls(f)

   In other words: yes, we are creating a countcalls object and passing f to its constructor.

2. These are the function arguments. In your case, f takes no arguments but suppose f was called like this:

   f(3, 4, keyword=5)

   then *args would contain 3 and 4 and **kwargs would contain the key/value pair keyword=5. For more information about *args and **kwargs, see this question.

3. Practice makes perfect.

Answer 4

1. Yes, with the caveat that it also binds that object to the name given in the def.

2. Read about them, read examples, play with some.