Decorators are one of the nicest features of Python, yet for the beginner Python programmer, they can seem like magic. The purpose of this article is to understand, in depth, the mechanism behind Python decorators.
Here's what you'll learn:
- what are Python decorators and what they are good for
- how to define our own decorators
- examples of real-world decorators and how they work
- how to write better code using decorators
Introduction
In case you haven't seen one yet (or perhaps you didn't know you were dealing with one), decorators look like this:
@decorator
def function_to_decorate():
pass
You usually encounter them above the definition of a function, and they're prefixed by @. Decorators are especially good for keeping your code DRY (Don't Repeat Yourself), and they do that while also improving the readability of your code.
Still fuzzy? Don't be, since decorators are just Python functions. That's right! You already know how to create one. In fact, the fundamental principle behind decorators is function composition. Let's take an example:
def x_plus_2(x):
return x + 2
print(x_plus_2(2)) # 2 + 2 == 4
def x_squared(x):
return x * x
print(x_squared(3)) # 3 ^ 2 == 9
# Let's compose the two functions for x=2
print(x_squared(x_plus_2(2))) # (2 + 2) ^ 2 == 16
print(x_squared(x_plus_2(3))) # (3 + 2) ^ 2 == 25
print(x_squared(x_plus_2(4))) # (4 + 2) ^ 2 == 36
What if we wanted to create another function, x_plus_2_squared? Trying to compose the functions would be futile:
x_squared(x_plus_2) # TypeError: unsupported operand type(s) for *: 'function' and 'function'
You cannot compose functions in this way because both functions take numbers as arguments. However, this will work:
# Let's now create a proper function composition without actually applying the function x_plus_2_squared = lambda x: x_squared(x_plus_2(x)) print(x_plus_2_squared(2)) # (2 + 2) ^ 2 == 16 print(x_plus_2_squared(3)) # (3 + 2) ^ 2 == 25 print(x_plus_2_squared(4)) # (4 + 2) ^ 2 == 36
Let's redefine how x_squared works. If we want x_squared to be composable by default, it should:
- Accept a function as an argument
- Return another function
We'll name the composable version of x_squared simply squared.
def squared(func):
return lambda x: func(x) * func(x)
print(squared(x_plus_2)(2)) # (2 + 2) ^ 2 == 16
print(squared(x_plus_2)(3)) # (3 + 2) ^ 2 == 25
print(squared(x_plus_2)(4)) # (4 + 2) ^ 2 == 36
Now that we've defined the squared function in a way that makes it composable, we can use it with any other function. Here are some examples:
def x_plus_3(x):
return x + 3
def x_times_2(x):
return x * 2
print(squared(x_plus_3)(2)) # (2 + 3) ^ 2 == 25
print(squared(x_times_2)(2)) # (2 * 2) ^ 2 == 16
We can say that squared decorates the functions x_plus_2, x_plus_3, and x_times_2. We are very close to achieving the standard decorator notation. Check this out:
x_plus_2 = squared(x_plus_2) # We decorated x_plus_2 with squared print(x_plus_2(2)) # x_plus_2 now returns the decorated squared result: (2 + 2) ^ 2
That's it! x_plus_2 is a proper Python decorated function. Here's where the @ notation comes into place:
def x_plus_2(x):
return x + 2
x_plus_2 = squared(x_plus_2)
# ^ This is completely equivalent with:
@squared
def x_plus_2(x):
return x + 2
In fact, the @ notation is a form of syntactic sugar. Let's try that out:
@squared
def x_times_3(x):
return 3 * x
print(x_times_3(2)) # (3 * 2) ^ 2 = 36.
# It might be a bit confusing, but by decorating it with squared, x_times_3 became in fact (3 * x) * (3 * x)
@squared
def x_minus_1(x):
return x - 1
print(x_minus_1(3)) # (3 - 1) ^ 2 = 4
If squared is the first decorator you've ever written, give yourself a big pat on the back. You've grasped one of the most complex concepts in Python. Along the way, you learned another fundamental feature of functional programming languages: function composition.
Build Your Own Decorator
A decorator is a function that takes a function as an argument and returns another function. That being said, the generic template for defining a decorator is:
def decorator(function_to_decorate):
# ...
return decorated_function
In case you didn't know, you can define functions inside functions. In most cases, the decorated_function will be defined inside decorator.
def decorator(function_to_decorate):
def decorated_function(*args, **kwargs):
# ... Since we decorate `function_to_decorate`, we should use it somewhere inside here
return decorated_function
Let's look at a more practical example:
import pytz
from datetime import datetime
def to_utc(function_to_decorate):
def decorated_function():
# Get the result of function_to_decorate and transform the result to UTC
return function_to_decorate().astimezone(pytz.utc)
return decorated_function
@to_utc
def package_pickup_time():
""" This can come from a database or from an API """
tz = pytz.timezone('US/Pacific')
return tz.localize(datetime(2017, 8, 2, 12, 30, 0, 0))
@to_utc
def package_delivery_time():
""" This can come from a database or from an API """
tz = pytz.timezone('US/Eastern')
return tz.localize(datetime(2017, 8, 2, 12, 30, 0, 0)) # What a coincidence, same time different timezone!
print("PICKUP: ", package_pickup_time()) # '2017-08-02 19:30:00+00:00'
print("DELIVERY: ", package_delivery_time()) # '2017-08-02 16:30:00+00:00'
Sweet! Now you can be sure that everything inside your app is standardised for the UTC timezone.
A Practical Example
Another really popular and classic use-case for decorators is caching the result of a function:
import time
def cached(function_to_decorate):
_cache = {} # Where we keep the results
def decorated_function(*args):
start_time = time.time()
print('_cache:', _cache)
if args not in _cache:
_cache[args] = function_to_decorate(*args) # Perform the computation and store it in cache
print('Compute time: %ss' % round(time.time() - start_time, 2))
return _cache[args]
return decorated_function
@cached
def complex_computation(x, y):
print('Processing ...')
time.sleep(2)
return x + y
print(complex_computation(1, 2)) # 3, Performing the expensive operation
print(complex_computation(1, 2)) # 3, SKIP performing the expensive operation
print(complex_computation(4, 5)) # 9, Performing the expensive operation
print(complex_computation(4, 5)) # 9, SKIP performing the expensive operation
print(complex_computation(1, 2)) # 3, SKIP performing the expensive operation
If you look at the code shallowly, you might object. The decorator isn't reusable! If we decorate another function (say another_complex_computation) and call it with the same parameters then we'll get the cached results from the complex_computation function. This won't happen. The decorator is reusable, and here's why:
@cached
def another_complex_computation(x, y):
print('Processing ...')
time.sleep(2)
return x * y
print(another_complex_computation(1, 2)) # 2, Performing the expensive operation
print(another_complex_computation(1, 2)) # 2, SKIP performing the expensive operation
print(another_complex_computation(1, 2)) # 2, SKIP performing the expensive operation
The cached function is called once for every function it decorates, so a different _cache variable is instantiated every time and lives in that context. Let's test this out:
print(complex_computation(10, 20)) # -> 30 print(another_complex_computation(10, 20)) # -> 200
Decorators in the Wild
The decorator we just coded, as you may have noticed, is very useful. It's so useful that a more complex and robust version already exists in the standard functools module. It is named lru_cache. LRU is the abbreviation of Least Recently Used, a caching strategy.
from functools import lru_cache
@lru_cache()
def complex_computation(x, y):
print('Processing ...')
time.sleep(2)
return x + y
print(complex_computation(1, 2)) # Processing ... 3
print(complex_computation(1, 2)) # 3
print(complex_computation(2, 3)) # Processing ... 5
print(complex_computation(1, 2)) # 3
print(complex_computation(2, 3)) # 5
One of my favourite uses of decorators is in the Flask web framework. It is so neat that this code snippet is the first thing you see on the Flask website. Here's the snippet:
from flask import Flask
app = Flask(__name__)
@app.route("/")
def hello():
return "Hello World!"
if __name__ == "__main__":
app.run()
The app.route decorator assigns the function hello as the request handler for the route "/". The simplicity is amazing.
Another neat use of decorators is inside Django. Usually, web applications have two types of pages:
- pages you can view without being authenticated (front page, landing page, blog post, login, register)
- pages you need to be authenticated to view (profile settings, inbox, dashboard)
If you try to view a page of the latter type, you'll usually get redirected to a login page. Here's how to implement that in Django:
from django.http import HttpResponse
from django.contrib.auth.decorators import login_required
# Public Pages
def home(request):
return HttpResponse("<b>Home</b>")
def landing(request):
return HttpResponse("<b>Landing</b>")
# Authenticated Pages
@login_required(login_url='/login')
def dashboard(request):
return HttpResponse("<b>Dashboard</b>")
@login_required(login_url='/login')
def profile_settings(request):
return HttpResponse("<b>Profile Settings</b>")
Observe how neatly the private views are marked with login_required. While going through the code, it is very clear to the reader which pages require the user to log in and which pages do not.
Conclusions
I hope you had fun learning about decorators because they represent a very neat Python feature. Here are some things to remember:
- Correctly using and designing decorators can make your code better, cleaner, and more beautiful.
- Using decorators can help you DRY up your code—move identical code from inside functions to decorators.
- As you use decorators more, you'll find better, more complex ways to use them.
Remember to check out what we have available for sale and for study on Envato Market, and don't hesitate to ask any questions and provide your valuable feedback using the feed below.
Well, that's that about decorators. Happy decorating!
Comments