A Python decorator wraps a target function with another wrapper function. This wrapper function can add any behavior you might want. For example, it can track execution times, redefine how the wrapped function runs, or modify return values.

As a concrete example, the standard library’s functools.lru_cache() decorator wraps a target function to add caching behavior. If you call a wrapped function twice with the same arguments, the second call returns a cached value rather than re-executing the potentially costly inner function.

Scout's Decorators 

Scout’s Python integration uses decorators extensively for instrumenting third-party libraries. This instrumentation allows us to measure execution time and help you find hot spots in your application.

Our instrumentation uses built-in extension mechanisms where possible, such as Django’s database instrumentation. But often libraries have no such mechanisms, so we resort to wrapping third party libraries’ functions with our own decorators. For example, we instrument jinja2 ’s Template.render() function with a decorator to measure template rendering time.

We value the correctness of our instrumentation a lot so that we do not affect our users’ applications. It’s important that our decorators are as transparent as possible, so they do not break assumptions held by the library or application. Therefore, we create our decorators with the wrapt library by Graham Dumpleton.

wrapt makes writing correct, transparent decorators easy. If you are writing any kind of decorators in Python, you should consider using wrapt. Let’s look at how it helps the Scout integration.

Making a Decorator with the Function Closure Pattern

Imagine we have this simple function for generating HTML, imitating Jinja2’s Template.render() :

def render_html(title):
return f"<h1>{title}</h1>"

We’d like to instrument it with a decorator to print the execution time. We can create a decorator that does this like so:

import time

  def instrument(wrapped):
      def wrapper(*args, **kwargs):
start = time.time_ns()
result = wrapped(*args, **kwargs)
end = time.time_ns()
print(f"Took {end - start} nanoseconds") return result

      return wrapper

This uses the “function closure pattern” that is commonly used to create decorators. The outer instrument function is called with the wrapped function as, and returns wrapper . This inner wrapper function:

1. Records the start in nanoseconds with time.time_ns() .
2. Calls the wrapped function wrapped, looked up in the function closure of the outer instrument() .
3. Records the end time.
4. Prints a message about the execution time in nanoseconds.
5. Returns the result from calling wrapped.

You can imagine that in the Scout integration, rather than printing a message, we append details about the executed function to a log. This log is then shipped with extra details as a trace of a single web request. We aggregate this trace with those for similar requests and display the results in our GUI.

Using our Decorator 

We can apply our decorator like so:

@instrument
def render_html(title):
    return f"<h1>{title}</h1>"

The outer instrument() function returns our wrapper() function, bound to the name render_html.

The @ syntax is actually a shortcut added in Python 2.4. We can expand it like so:

def render_html(title):
    return f"<h1>{title}</h1>"

render_html = instrument(render_html)

In this form, we can see that render_html is effectively defined twice: first as a plain function, second as the return value of instrument(). Because our instrument() returns our new wrapper() function, it continues to be a function. Decorators can return any Python object, although it normally doesn’t make sense to return something other than a function.

We can call our decorated render_html() with a value for title :

>>> render_html("Good Dog") 
Took 1000 nanoseconds 
'<h1>Good Dog</h1>'

We see the message from our wrapper printed, as well as the returned string. So our decorator works, but unfortunately, it’s not very transparent. It replaces the inner render_html() function with the wrapper() function, and this causes several detectable differences. We can see some of the differences if we ask the interpreter for the representation of the function (its repr() ).

Decorator Transparency