Before / After Execution

Either prior to the wrapped function being executed, or afterwards, another function can be called. The most simplistic use case for this is logging the beginning and ending of execution of a function.

@attach(on_before=lambda: logging.info('Execution began'), on_after=lambda: logging.info('Execution ended'))
def func():
    ...

If an exception is raised by the wrapped function (or the on_before function), the on_after function isn’t called.

More complex usage comes from digesting the parameters meant for the wrapped function and transforming them in some way. This is accomplished by simply returning an object from the on_before function and the values will be used instead of the ones passed in.

def sanitize(string):
    # Do some stuff
    return new_string

@attach(on_before=lambda x: sanitize(x))
def func(string):
    ...

If an iterable is returned, it is used as the args of the wrapped function. The before_with_kwargs argument can be set to True to specify that the return value be used as the kwargs of the wrapped function (which means it should be a dictionary. If an iterable is returned and this parameter is set, the last value is used as the kwargs, and the rest as the args.

def sanitize(string):
    # Do some stuff
    return new_string

@attach(on_before=lambda x: sanitize(x), {'use_ssl': True})
def func(string):
    ...

Error Handling

The on_error can be used to execute a function if an exception is raised. By default, the original exception is still raised after the on_error callback is called. This can be changed by setting override_error to True. This can be used to instead return a value or raise a different exception.

def on_error(e):
    print('Caught error: ' + str(e))
    if isinstance(e, TypeError):
        return -1
    raise

@attach(on_error=on_error, override_error=True)
def func():
    raise TypeError

# -1 is returned instead of raising TypeError

Return Value Handling

Like raised exception, return values can consumed by a on_return function in a similar manner. By default, the original return value is still returned after the on_return callback is called. This can be changed by setting override_return to True. A common use case for this is when interacting with functions that yield a return value that indicates a failed state (like -1 or None), while other values indicate a successful state (like 0 or an object). This behavior can be transformed into a simple bool True or False return value instead.

def on_return(val):
    if val in (-1, None):
        return False
    return True

@attach(on_return=on_return, override_return=True)
def func()
    return -1

# False is returned instead of -1

If an exception is raised by the wrapped function (or the on_before or on_after functions), the on_return function isn’t called.