Decorator functions without arguments

In a decorator function that doesn't receive arguments, its first and only parameter is the callable to be decorated. In the nested function is where decorated callable positional and keyword arguments are received.

This can be seen in any of previous examples.

Decorator functions with arguments

Now we'll look an example of a decorator function that receives arguments. The example will be based on our previous log_callable and will allow us to specify if we really want to count the number of calls.

log_callable with arguments example:

def log_callable(do_count):

    if not getattr(log_callable, 'count_dict', None) and do_count:
        log_callable.count_dict = {}

    if do_count:
        log_callable.count_dict.setdefault(
            callable.__name__, 0
        )

    def wrap(callable):
        def inner_wrap(*args, **kwargs):
            callable(*args, **kwargs)

            message = []

            if do_count:
                log_callable.count_dict.setdefault(
                    callable.__name__, 0
                )
                log_callable.count_dict[callable.__name__] += 1
                message.append(
                    u"""called: '{0}' '{1} times'""".format(
                        callable.__name__,
                        log_callable.count_dict[callable.__name__],
                    )
                )
            else:
                message.append(u"""called: '{0}'""".format(callable.__name__))

            message.append(u"""Arguments: {0}""".format(", ".join(args)))
            message.append(
                u"""Keyword Arguments: {0}""".format(
                    ", ".join(["{0}={1}".format(key, value) \
                               for (key, value) in kwargs.items()])
                )
            )

            logging.debug("; ".join(message))

        return inner_wrap

    return wrap

A decorator function with arguments receives the params that are passed explicitly to the decorator. The callable is received in the first nested function and finally the decorated callable arguments are received by the deeper nested function (in our case called inner_wrap)

The way to use this decorator will be as follows:

@log_callable(False)
def yes(string='y', end='\n'):
   [...]

Decorator classes without arguments

As we said before, the decorator and the callable don't need to be functions, they can be classes too.

Here is a class version of our log_callable (without arguments):

class LogCallable(object):
    """Decorates callable and logs information about it.

    Logs how many times the callable was called and the params it had.

    """

    def __init__(self, callable):
        self.callable = callable

        if not getattr(LogCallable, 'count_dict', None):
            LogCallable.count_dict = {}

        LogCallable.count_dict.setdefault(
            callable.__name__, 0
        )


    def __call__(self, *args, **kwargs):
        self.callable(*args, **kwargs)
        LogCallable.count_dict[self.callable.__name__] += 1

        message = []

        message.append(
            """called: '{0}' '{1} times'""".format(
                self.callable.__name__,
                LogCallable.count_dict[self.callable.__name__]
            )
        )
        message.append(
            """Arguments: {0}""".format(
                ", ".join(map(str, args))
            )
        )
        message.append(
            """Keyword Arguments: {0}""".format(
                ", ".join(["{0}={1}".format(key, value) \
                           for (key, value) in kwargs.items()])
            )
        )

        logging.debug("; ".join(message))

In a decorator class that doesn't receive parameters, the first param of __init__ method is the callable to be decorated. The __call__ method receives the arguments of the decorated callable.

The most interesting difference with the function version is that by using a class decorator we have avoided the need of a nested function.

The way to use this decorator is the same as we do with decorator functions:

@LogCallable
def yes(string='y', end='\n'):
    [...]

Decorator classes with arguments

Understanding the 3 previous cases it is possible to guess how a decorator class with arguments should be.

LogCallable with params example:

class LogCallable(object):
    """Decorates callable and logs information about it.

    Logs how many times the callable was called and the params it had.

    """

    def __init__(self, do_count):
        self.do_count = do_count

        if not getattr(LogCallable, 'count_dict', None) and do_count:
            LogCallable.count_dict = {}

    def __call__(self, callable):

        def wrap(*args, **kwargs):
            callable(*args, **kwargs)

            message = []

            if self.do_count:
                LogCallable.count_dict.setdefault(
                    callable.__name__, 0
                )
                LogCallable.count_dict[callable.__name__] += 1
                message.append(
                    u"""called: '{0}' '{1} times'""".format(
                        callable.__name__,
                        LogCallable.count_dict[callable.__name__],
                    )
                )
            else:
                message.append(u"""called: '{0}'""".format(callable.__name__))

            message.append(
                u"""Arguments: {0}""".format(
                    ", ".join(map(str, args))
                )
            )
            message.append(
                u"""Keyword Arguments: {0}""".format(
                    ", ".join(["{0}={1}".format(key, value) \
                               for (key, value) in kwargs.items()])
                )
            )

            logging.debug("; ".join(message))

        return wrap

In a decorator class with parameters, these are passed to the __init__ method. The decorated callable is received by the __call__ method and the arguments of it are received by the nested function (called wrap in our example).

The way to use it is exactly the same as in the case of decorator functions with params:

@LogCallable(False)
def yes(string='y', end='\n'):
    [...]