Optional arguments decorator (Python recipe) by Maxime H Lapointe

ActiveState Code (http://code.activestate.com/recipes/578435/)

When you create a decorator, it will happen that you need to pass parameters to it. Frequently, those parameters will also be optionnal. Usually, this problem is solved by adding logic in the decorator, making itmuch more complicated to read and forcing you to repeat similar code elsewhere if the need arises again. This code defines a decorator opt_arg_dec to apply to your decorator to allow them to receive arguments (required or not) automatically. You don't even need to tell opt_arg_dec about them, the parameters received will be passed to your decorator. Using this decorator is very simple. @opt_arg_dec def call_logger(func, include_args=False, include_return=False): def call_logging_func(params, *kwargs): print("Calling", func.__name__, include_args, include_return) # Do your logging ret = func(params, *kwargs) return ret return call_logging_func

# You can now use the decorator in the following ways:
@call_logger
def hello1(arg1, arg2="!"):
    print("hello", arg1, arg2)

@call_logger()
def hello2(arg1, arg2="!"):
    print("hello", arg1, arg2)

@call_logger(True, False)
def hello3(arg1, arg2="!"):
    print("hello", arg1, arg2)

@call_logger(include_return=True)
def hello4(arg1, arg2="!"):
    print("hello", arg1, arg2)

def hello5(arg1, arg2="!"):
    print("hello", arg1, arg2)
hello5 = call_logger(True, True)(hello5)

def hello6(arg1, arg2="!"):
    print("hello", arg1, arg2)
hello6 = call_logger(hello6, True)


>>> hello1("world")
Calling hello1 with False and False
hello world !

>>> hello2(arg1="world")
Calling hello2 with False and False
hello world !

>>> hello3("world", arg2="!!!!!!")
Calling hello3 with True and False
hello world !!!!!!

>>> hello4("guys")
Calling hello4 with False and True
hello guys !

>>> hello5("everybody", ":)")
Calling hello5 with True and True
hello everybody :)

>>> hello6("sir")
Calling hello6 with True and False
hello sir !

This basically allows you do decorate things the way you want. However, there is a little catch created by allowing you do only call the decorator once. (as used in the example hello1 and hello6). In order to know your decorator should be called on the first argument of the first call(hello1 and hello6) or wait for a second call (hello2, hello3, hello4, hello5), the decorator needs to do checks on the first parameter sent to it. So if you send something that is a valid target as first argument, you will have a problem:

def should_i_include_args():
    pass

# Won't work!
@call_logger(should_i_include_args)
def hello7(arg1, arg2="!"):
    print("hello", arg1, arg2)

This will fail. You passed a function as first argument, so the decorator accepts it as the function to be decorated. It will then call this function with hello7. Same thing happens if you do this:

# Won't work!
def hello8(arg1, arg2="!"):
    print("hello", arg1, arg2)
hello8 = call_logger(should_i_include_args)(hello8)

The solution is to pass in Ellipsis as first argument. The opt_arg_dec will automatically remove it (only when first argument) and understand that this means that there will be another call to receive the real target of the decorator. You can have more control on this behavior, see further down.

def should_i_include_args():
    pass

# This works!
@call_logger(Ellipsis, should_i_include_args)
def hello7(arg1, arg2="!"):
    print("hello", arg1, arg2)

# This works! but really, why are you using this form?
def hello8(arg1, arg2="!"):
    print("hello", arg1, arg2)
hello8 = call_logger(Ellipsis, should_i_include_args)(hello8)

If you are using Python 3, then be happy to know that Ellipsis has a shortcut. You can simply write ... and python will recognize it as Ellipsis. The result is much simpler to read.

@call_logger(..., should_i_include_args)
def hello7(arg1, arg2="!"):
    print("hello", arg1, arg2)

# This works! but really, why are you using this form?
def hello8(arg1, arg2="!"):
    print("hello", arg1, arg2)
hello8 = call_logger(..., should_i_include_args)(hello8)

Another thing to be careful about is that if you want a method or a classmethod to be an opt_arg_dec, then you need to pass an optionnal parameter (is_method=True) to opt_arg_dec so that it handle the self or cls correctly. Do not do this for staticmethod as they do not add an additionnal argument.

class call_logger(object):

    @opt_arg_dec(is_method=True)
    def log_call(self, func, include_args=False, include_return=False):
        def call_logging_func(*params, **kwargs):
            print("Calling", func.__name__, include_args, include_return)
            return func(*params, **kwargs)
        return call_logging_func

    @classmethod
    @opt_arg_dec(is_method=True)
    def log_call_everywhere(self, func, include_args=False, include_return=False):
        def call_logging_func(*params, **kwargs):
            print("Calling", func.__name__, include_args, include_return)
            return func(*params, **kwargs)
        return call_logging_func


    @staticmethod
    @opt_arg_dec
    def log_call_default(self, func, include_args=False, include_return=False):
        def call_logging_func(*params, **kwargs):
            print("Calling", func.__name__, include_args, include_return)
            return func(*params, **kwargs)
        return call_logging_func

These work the exact same way as when used on a function. There is simply some added logic to deal with the additionnal paremeter. Also keep in mind when using staticmethod or classmethod on a decorator, they must be the last one called, so they must be the first decorator written.

If you want a class to be useable as an opt_arg_dec, then simply decorate it with it.

# Couldn't think of a context where this was necessary...
@opt_arg_dec
class call_log(object):
    def __new__(cls, func, include_args=False, include_return=False):
        def call_logging_func(*params, **kwargs):
            print("Calling", func.__name__, include_args, include_return)
            return func(*params, **kwargs)
        return call_logging_func

If you want a class instance to be useable as an opt_arg_dec, then decorate the __call__ function with it. Don't forget the is_method=True.

class call_logger(object):
    @opt_arg_dec(is_method=True)
    def __call__(self, func, include_args=False, include_return=False):
        def call_logging_func(*params, **kwargs):
            print("Calling", func.__name__, include_args, include_return)
            return func(*params, **kwargs)
        return call_logging_func

In order to support being called only once and detecting that the first argument should be used as target of the decorator instead of waiting for a second call, opt_arg_dec does some check on the first argument when it is not Ellipsis. You can control those checks depending on what is likely to be used with your decorator. Keep in mind; those checks are only used in the first call to the decorator. The second call will accept anything. Meaning:

@opt_arg_dec
def my_decorator(func, p1=None, p2=None):
    return func # Doesn't do anything.

def test1():
    pass

# "hi" will be checked to see if it's a valid target. It's not, so it will wait
# for the next call.
my_decorator("hi", "you")
def test1(): pass

# "hi" is checked again, wait for second call again. "world" is not checked and
# just goes through. Meaning your decorator would receive ("world", "hi", "you")
# as argument, no function or callable.
my_decorator("hi", "you")("world")

The control you have over what you say is a valid target for your decorator is by using the parameters valid_target and allow_non_callable that you can pass to opt_arg_dec when creating your decorator. valid_target: A callable receiving a single object and returning True if it is a valid target for the decorator to decorate. This is not used as error validation. This is to detect when the decorator will only be called once (when no initial call to set arguments is made or when it is not used in the form of a decorator.) If arguments were previously passed, the target will be sent through without any form of checking. You must still to error validation in your decorator if you need it. The target must be callable unless allow_non_callable is True. Special values:

• None (default): the target must not be a type/class (but it can be an instance of a type/class). Use this for function decorator, unless you want to pass in a function to be more specific and only allow certain specific types.
• "class": the target must be a class (not an instance of a class).However, builtin classes that are global to python will not be accepted. Meaning (int, float, str, set, dict, list, tuple and maybe a few more) since it is unlikely to want to decorate those. Use this for class decorators.
• "type": same as "class", but builtin classes are also accepted.
• "any": anything is allowed. (Must still be callable unless allow_non_callable is True)
• "never": nothing will ever be accepted as target. This means the decorator must always be called before being applied to the real target, even if it means with no arguments.

allow_non_callable: If False (the default), then the target to be decorated must be callable! See valid_target for more details, this check is done in the same conditions. Setting this to True means that valid_target must do more advanced check, otherwise almost anything will be considered a valid target and the first call to the function will be treated as a full call.

Basically, the special values should cover most common cases. If you want your decorator to be applicable to classes only, so a class decorator, then use valid_target="class". Note that opt_arg_dec itself is an opt_arg_dec with valid_target="any", that’s why you can use it on a function or a class.

# a class decorator
@opt_arg_dec(valid_target="class")
def my_class_decorator(cls, arg1=None):
    pass

In order to help with problems related to this target validation, a debugging function is provided: get_misused_opt_arg_dec()

Used to help developpers find places where an optionnal argument decorator was misused. It returns a list of (decorator, params, kwargs).

Basically, once you have created all of your opt_arg_dec, or simply at the end of your application. get_misused_opt_arg_dec() doesn't return an empty list, it means that somewhere, something is not defined properly. The first value of params should normally be the wrong target, and should help you find where you did the mistake. Things appear in this list when a opt_arg_dec is called without a valid target and never called again. Example:

# my_function_decorator is expecting something that is not a class (the default)
# but receives a class
@my_function_decorator
class Foo(object):
    pass

# Right now, Foo is not the class, it's a function waiting to receive anything,
# which will return Foo. Probably not what you want.

The decorator was expecting to receive a function, but received a class in the first call. If this was really what was desired, then you must call the decorator first to skip this validation:

@my_function_decorator()
class Foo(object):
    pass

Thats pretty much it. Hope this becomes the standard answer to "how to make a decorator with (optional) arguments".