PWSHub News

Primer on Python Decorators – Real Python

Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Python Decorators 101

In this tutorial on Python decorators, you’ll learn what they are and how to create and use them. Decorators provide a simple syntax for calling higher-order functions.

By definition, a decorator is a function that takes another function and extends the behavior of the latter function without explicitly modifying it. This sounds confusing, but it’ll make more sense after you’ve seen a few examples of how decorators work.

In this tutorial, you’ll learn:

  • What it means for functions to be first-class objects
  • How to define functions so they can be used as decorators
  • Which practical use cases can be tackled with decorators
  • How to create decorators so that they follow best practices

You can find all the examples from this tutorial by downloading the accompanying materials below:

Python Functions

In order to understand decorators, you must first understand some finer points of how functions work. There are many aspects to functions, but in the context of decorators, a function returns a value based on the given arguments. Here’s a basic example:

In general, functions in Python may also have side effects rather than just turning an input into an output. The print() function is an example of this: it returns None while having the side effect of outputting something to the console. However, to understand decorators, it’s enough to think about functions as tools that turn given arguments into values.

First-Class Objects

In functional programming, you work almost entirely with pure functions that don’t have side effects. While not a purely functional language, Python supports many functional programming concepts, including treating functions as first-class objects.

This means that functions can be passed around and used as arguments, just like any other object like str, int, float, list, and so on. Consider the following three functions:

Here, say_hello() and be_awesome() are regular functions that expect a name given as a string. The greet_bob() function, however, expects a function as its argument. You can, for example, pass it the say_hello() or the be_awesome() function.

To test your functions, you can run your code in interactive mode. You do this with the -i flag. For example, if your code is in a file named, then you run python -i

Note that greet_bob(say_hello) refers to two functions, but in different ways: greet_bob() and say_hello. The say_hello function is named without parentheses. This means that only a reference to the function is passed. The function isn’t executed. The greet_bob() function, on the other hand, is written with parentheses, so it will be called as usual.

This is an important distinction that’s crucial for how functions work as first-class objects. A function name without parentheses is a reference to a function, while a function name with trailing parentheses calls the function and refers to its return value.

Inner Functions

It’s possible to define functions inside other functions. Such functions are called inner functions. Here’s an example of a function with two inner functions:


What happens when you call the parent() function? Think about this for a minute. Then run in interactive mode to try it out. The output will be as follows:

Note that the order in which the inner functions are defined does not matter. Like with any other functions, the printing only happens when the inner functions are executed.

Furthermore, the inner functions aren’t defined until the parent function is called. They’re locally scoped to parent(), meaning they only exist inside the parent() function as local variables. Try calling first_child(). You’ll get an error:

Whenever you call parent(), the inner functions first_child() and second_child() are also called. But because of their local scope, they aren’t available outside of the parent() function.

Functions as Return Values

Python also allows you to return functions from functions. In the following example, you rewrite parent() to return one of the inner functions:


Note that you’re returning first_child without the parentheses. Recall that this means that you’re returning a reference to the function first_child. In contrast, first_child() with parentheses refers to the result of evaluating the function. You can see this in the following example:

The somewhat cryptic output means that the first variable refers to the local first_child() function inside of parent(), while second points to second_child().

You can now use first and second as if they’re regular functions, even though you can’t directly access the functions they point to:

You recognize the return values of the inner functions that you defined inside of parent().

Finally, note that in the earlier example, you executed the inner functions within the parent function—for example, first_child(). However, in this last example, you didn’t add parentheses to the inner functions, such as first_child, upon returning. That way, you got a reference to each function that you could call in the future.

Simple Decorators in Python

Now that you’ve seen that functions are just like any other object in Python, you’re ready to move on and see the magical beast that is the Python decorator. You’ll start with an example:


Here, you’ve defined two regular functions, decorator() and say_whee(), and one inner wrapper() function. Then you redefined say_whee() to apply decorator() to the original say_whee().

Can you guess what happens when you call say_whee()? Try it in a REPL. Instead of running the file with the -i flag, you can also import the function manually:

To understand what’s going on here, look back at the earlier examples. You’re applying everything that you’ve learned so far.

The so-called decoration happens at the following line:

In effect, the name say_whee now points to the wrapper() inner function. Remember that you return wrapper as a function when you call decorator(say_whee):

However, wrapper() has a reference to the original say_whee() as func, and it calls that function between the two calls to print().

Put simply, a decorator wraps a function, modifying its behavior.

Before moving on, have a look at a second example. Because wrapper() is a regular Python function, the way a decorator modifies a function can change dynamically. So as not to disturb your neighbors, the following example will only run the decorated code during the day:

If you try to call say_whee() after bedtime, nothing will happen:

Here, say_whee() doesn’t print any output. That’s because the if test failed, so the wrapper didn’t call func(), the original say_whee().

Adding Syntactic Sugar

Look back at the code that you wrote in The way you decorated say_whee() is a little clunky. First of all, you end up typing the name say_whee three times. Additionally, the decoration gets hidden away below the definition of the function.

Instead, Python allows you to use decorators in a simpler way with the @ symbol, sometimes called the pie syntax. The following example does the exact same thing as the first decorator example:


So, @decorator is just a shorter way of saying say_whee = decorator(say_whee). It’s how you apply a decorator to a function.

Reusing Decorators

Recall that a decorator is just a regular Python function. All the usual tools for reusability are available. Now, you’ll create a module where you store your decorators and that you can use in many other functions.

Create a file called with the following content:

The do_twice() decorator calls the decorated function twice. You’ll soon see the effect of this in several examples.

You can now use this new decorator in other files by doing a regular import:

When you run this example, you should see that the original say_whee() is executed twice:

There are two Whee! exclamations printed, confirming that @do_twice does what it says on the tin.

Decorating Functions With Arguments

Say that you have a function that accepts some arguments. Can you still decorate it? Give it a try:

You now apply @do_twice to greet(), which expects a name. Unfortunately, calling this function raises an error:

The problem is that the inner function wrapper_do_twice() doesn’t take any arguments, but you passed name="World" to it. You could fix this by letting wrapper_do_twice() accept one argument, but then it wouldn’t work for the say_whee() function that you created earlier.

The solution is to use *args and **kwargs in the inner wrapper function. Then it’ll accept an arbitrary number of positional and keyword arguments. Rewrite as follows:

The wrapper_do_twice() inner function now accepts any number of arguments and passes them on to the function that it decorates. Now both your say_whee() and greet() examples work. Start a fresh REPL:

You use the same decorator, @do_twice, to decorate two different functions. This hints at one of the powers of decorators. They add behavior that can apply to many different functions.

Returning Values From Decorated Functions

What happens to the return value of decorated functions? Well, that’s up to the decorator to decide. Say you decorate a simple function as follows:

Try to use it:

Oops, your decorator ate the return value from the function.

Because the do_twice_wrapper() doesn’t explicitly return a value, the call return_greeting("Adam") ends up returning None.

To fix this, you need to make sure the wrapper function returns the return value of the decorated function. Change your file:

Now you return the return value of the last call of the decorated function. Check out the example again:

This time, return_greeting() returns the greeting 'Hi Adam'.

Finding Yourself

A great convenience when working with Python, especially in the interactive shell, is its powerful introspection ability. Introspection is the ability of an object to know about its own attributes at runtime. For instance, a function knows its own name and documentation:

When you inspect print(), you can see its name and documentation. The introspection works for functions that you define yourself as well:

However, after being decorated, say_whee() has gotten very confused about its identity. It now reports being the wrapper_do_twice() inner function inside the do_twice() decorator. Although technically true, this isn’t very useful information.

To fix this, decorators should use the @functools.wraps decorator, which will preserve information about the original function. Update again:

You don’t need to change anything about the decorated say_whee() function, but you need to restart your REPL to see the effect:

Much better! Now say_whee() is still itself after decoration.

You’ve now learned the basics of how to create a decorator. However, @do_twice isn’t a very exciting decorator, and there aren’t a lot of use cases for it. In the next section, you’ll implement several decorators that illustrate what you know so far and that you can use in your own code.

A Few Real World Examples

You’ll now look at a few more useful examples of decorators. You’ll notice that they’ll mainly follow the same pattern that you’ve learned so far:

This formula is a good boilerplate template for building more complex decorators.

You’ll continue to store your decorators in Recall that you can download all the examples in this tutorial:

Timing Functions

You’ll start by creating a @timer decorator. It’ll measure the time a function takes to execute and then print the duration to the console. Here’s the code:

This decorator works by storing the time just before the function starts running in line 10 and just after the function finishes in line 12. The runtime of the function is then the difference between the two, calculated in line 13. You use time.perf_counter(), which does a good job of measuring time intervals.

Now, add waste_some_time() as an example of a function that spends some time, so that you can test @timer. Here are some examples of timings:

Run it yourself. Work through the definition of @timer line by line. Make sure you understand how it works. Don’t worry if you don’t get everything, though. Decorators are advanced beings. Try to sleep on it or make a drawing of the program flow.

If you’re interested in learning more about timing functions, then have a look at Python Timer Functions: Three Ways to Monitor Your Code.

Debugging Code

The following @debug decorator will print a function’s arguments and its return value every time you call the function:

The signature is created by joining the string representations of all the argument:

  • Line 9: You create a list of the positional arguments. Use repr() to get a nice string representing each argument.
  • Line 10: You create a list of the keyword arguments. The f-string formats each argument as key=value, and again, you use repr() to represent the value.
  • Line 11: You join together the lists of positional and keyword arguments to one signature string with each argument separated by a comma.
  • Line 14: You print the return value after the function is executed.

It’s time to see how the decorator works in practice by applying it to a simple function with one positional and one keyword argument:

Note how the @debug decorator prints the signature and return value of the make_greeting() function:

This example might not seem immediately useful since the @debug decorator just repeats what you wrote. It’s more powerful when applied to small convenience functions that you don’t call directly yourself.

The following example calculates an approximation of the mathematical constant e:

Here, you also apply a decorator to a function that has already been defined. In line 4, you decorate factorial() from the math standard library. You can’t use the pie syntax, but you can still manually apply the decorator. The approximation of e is based on the following series expansion:

When calling the approximate_e() function, you can see the @debug decorator at work:

In this example, you get a decent approximation of the true value e ≈ 2.718281828, adding only five terms.

Slowing Down Code

In this section, you’ll create a decorator that slows down your code. This might not seem very useful. Why would you want to slow down your Python code?

Probably the most common use case is that you want to rate-limit a function that continuously checks whether a resource—like a web page—has changed. The @slow_down decorator will sleep one second before it calls the decorated function:

In @slow_down, you call time.sleep() to have your code take a pause before calling the decorated function. To see how the @slow_down decorator works, you create a countdown() function. To see the effect of slowing down the code, you should run the example yourself:

In countdown(), you check if from_number is smaller than one. In that case, you print Liftoff!. If not, then you print the number and keep counting.

The @slow_down decorator always sleeps for one second. Later, you’ll see how to control the rate by passing an argument to the decorator.

Registering Plugins

Decorators don’t have to wrap the function that they’re decorating. They can also simply register that a function exists and return it unwrapped. You can use this, for example, to create a lightweight plugin architecture:

The @register decorator only stores a reference to the decorated function in the global PLUGINS dictionary. Note that you don’t have to write an inner function or use @functools.wraps in this example because you’re returning the original function unmodified.

You can now register functions as follows:

Note that the PLUGINS dictionary already contains references to each function object that’s registered as a plugin:

Python applies decorators when you define a function, so say_hello() and be_awesome() are immediately registered. You can then use PLUGINS to call these functions:

The randomly_greet() function randomly chooses one of the registered functions to use. In the f-string, you use the !r flag. This has the same effect as calling repr(greeter).

The main benefit of this simple plugin architecture is that you don’t need to maintain a list of which plugins exist. That list is created when the plugins register themselves. This makes it trivial to add a new plugin: just define the function and decorate it with @register.

If you’re familiar with globals() in Python, then you might see some similarities to how the plugin architecture works. With globals(), you get access to all global variables in the current scope, including your plugins:

Using the @register decorator, you can create your own curated list of interesting names, effectively hand-picking some functions from globals().

Authenticating Users

The final example before moving on to some fancier decorators is commonly used when working with a web framework. In this example, you’ll use Flask to set up a /secret web page that should only be visible to users that are logged in or otherwise authenticated:

While this gives an idea about how to add authentication to your web framework, you should usually not write these types of decorators yourself. For Flask, you can use the Flask-Login extension instead, which adds more security and functionality.

Fancy Decorators

So far, you’ve seen how to create simple decorators. You already have a pretty good understanding of what decorators are and how they work. Feel free to take a break from this tutorial to practice everything that you’ve learned.

In the second part of this tutorial, you’ll explore more advanced features, including how to do the following:

  • Add decorators to classes
  • Add several decorators to one function
  • Create decorators with arguments
  • Create decorators that can optionally take arguments
  • Define stateful decorators
  • Define classes that act as decorators

Ready to dive in? Here you go!

Decorating Classes

There are two different ways that you can use decorators on classes. The first one is very close to what you’ve already done with functions: you can decorate the methods of a class. This was one of the motivations for introducing decorators back in the day.

Some commonly used decorators are even built-ins in Python, including @classmethod, @staticmethod, and @property. The @classmethod and @staticmethod decorators are used to define methods inside a class namespace that aren’t connected to a particular instance of that class. The @property decorator is used to customize getters and setters for class attributes. Expand the box below for an example using these decorators:

The following definition of a Circle class uses the @classmethod, @staticmethod, and @property decorators:

Inside Circle you can see several different kinds of methods. Decorators are used to distinguish them:

  • .cylinder_volume() is a regular method.
  • .radius is a mutable property. It can be set to a different value. However, by defining a setter method, you do some error testing to make sure .radius isn’t set to a nonsensical negative number. Properties are accessed as attributes without parentheses.
  • .area is an immutable property. Properties without .setter() methods can’t be changed. Even though it’s defined as a method, it can be retrieved as an attribute without parentheses.
  • .unit_circle() is a class method. It’s not bound to one particular instance of Circle. Class methods are often used as factory methods that can create specific instances of the class.
  • .pi() is a static method. It’s not really dependent on the Circle class, except that it’s part of its namespace. You can call static methods on either an instance or the class.

You can use Circle as follows:

In these examples, you explore the different methods, attributes, and properties of Circle.

Next, define a class where you decorate some of its methods using the @debug and @timer decorators from earlier:


Using this class, you can see the effect of the decorators:

When you create a new instance of TimeWaster, Python calls .__init__() under the hood, as your use of @debug reveals. The @timer decorator helps you monitor how much time is spent on .waste_time().

The other way to use decorators on classes is to decorate the whole class. This is, for example, done in the dataclasses module:

The meaning of the syntax is similar to the function decorators. In the example above, you could’ve decorated the class by writing PlayingCard = dataclass(PlayingCard).

A common use of class decorators is to be a simpler alternative to some use cases of metaclasses. In both cases, you’re changing the definition of a class dynamically.

Writing a class decorator is very similar to writing a function decorator. The only difference is that the decorator will receive a class and not a function as an argument. In fact, all the decorators that you saw above will work as class decorators. When you’re using them on a class instead of a function, their effect might not be what you want. In the following example, the @timer decorator is applied to a class:


Decorating a class doesn’t decorate its methods. Recall that @timer is just shorthand for TimeWaster = timer(TimeWaster). Here, @timer only measures the time that it takes to instantiate the class:

The output from @timer is only shown as tw is created. The call to .waste_time() isn’t timed.

Later, you’ll see an example defining a proper class decorator, namely @singleton, which ensures that there’s only one instance of a class.

Nesting Decorators

You can apply several decorators to a function at once by stacking them on top of each other:

Think about this as the decorators being executed in the order they’re listed. In other words, @debug calls @do_twice, which calls greet(), or debug(do_twice(greet())):

The greeting is printed twice because of @do_twice. However, the output from @debug is only shown once, since it’s called before the @do_twice decorator. Observe the difference if you change the order of @debug and @do_twice:

Here, @do_twice is applied to @debug as well. You can see that both calls to greet() are annotated with debugging information.

Defining Decorators With Arguments

Sometimes, it’s useful to pass arguments to your decorators. For instance, @do_twice could be extended to a @repeat(num_times) decorator. The number of times to execute the decorated function could then be given as an argument.

If you define @repeat, you could do something like this:

Think about how you’d implement @repeat.

So far, the name written after the @ has referred to a function object that can be called with another function. To be consistent, you then need repeat(num_times=4) to return a function object that can act as a decorator. Luckily, you already know how to return functions! In general, you want something like the following:

Typically, the decorator creates and returns an inner wrapper function, so writing the example out in full will give you an inner function within an inner function. While this might sound like the programming equivalent of the Inception, you’ll untangle it all in a moment:

It looks a little messy, but you’ve only put the same decorator pattern that you’ve seen many times by now inside one additional def that handles the arguments to the decorator. First, consider the innermost function:

This wrapper_repeat() function takes arbitrary arguments and returns the value of the decorated function, func(). This wrapper function also contains the loop that calls the decorated function num_times times. This is no different from the earlier wrapper functions that you’ve seen, except that it’s using the num_times parameter that must be supplied from the outside.

One step out, you’ll find the decorator function:

Again, decorator_repeat() looks exactly like the decorator functions that you’ve written earlier, except that it’s named differently. That’s because you reserve the base name—repeat()—for the outermost function, which is the one the user will call.

As you’ve already seen, the outermost function returns a reference to the decorator function:

There are a few subtle things happening in the repeat() function:

  • Defining decorator_repeat() as an inner function means that repeat() will refer to a function object, decorator_repeat. Earlier, you used decorators like @do_twice without parentheses. Now, you need to add parentheses when setting up the decorator, as in @repeat(). This is necessary in order to add arguments.
  • The num_times argument is seemingly not used in repeat() itself. But by passing num_times, a closure is created where the value of num_times is stored until wrapper_repeat() uses it later.

With everything set up, test your code to see if the results are as expected:

That’s just the result that you were aiming for.

Creating Decorators With Optional Arguments

With a little bit of care, you can also define decorators that can be used both with and without arguments. Most likely, you don’t need this, but it is nice to have the flexibility. Like Winnie-the-Pooh says:

Both—but don’t bother about the bread, please. (Source)

As you saw in the previous section, when a decorator uses arguments, you need to add an extra outer function. The challenge now is for your code to figure out if you’ve called the decorator with or without arguments.

Since the function to decorate is only passed in directly if the decorator is called without arguments, the function must be an optional argument. This means that the decorator arguments must all be specified by keyword. You can enforce this with the special asterisk (*) syntax, which means that all the following parameters are keyword-only:

Here, the _func argument acts as a marker, noting whether the decorator has been called with arguments or not:

  • Line 1: If you’ve called @name without arguments, then the decorated function will be passed in as _func. If you’ve called it with arguments, then _func will be None, and some of the keyword arguments may have been changed from their default values. The asterisk in the argument list means that you can’t call the remaining arguments as positional arguments.
  • Line 6: In this case, you called the decorator with arguments. Return a decorator function that takes a function as an argument and returns a wrapper function.
  • Line 8: In this case, you called the decorator without arguments. Apply the decorator to the function immediately.

Using this boilerplate on the @repeat decorator in the previous section, you can write the following:

Compare this with the original @repeat. The only changes are the added _func parameter and the ifelse block at the end.

Recipe 9.6 of the excellent Python Cookbook shows an alternative solution using functools.partial().

You can now apply @repeat to different functions to test that you can now use it with or without arguments:

Recall that the default value of num_times is 2, so using @repeat without any arguments is equivalent to using @do_twice:

Here, Whee! is repeated twice since that’s the default behavior of @repeat. As specified by the argument, the greeting is repeated three times.

Tracking State in Decorators

Sometimes, it’s useful to have a decorator that can keep track of state. As an example, you’ll create a decorator that counts the number of times a function is called.

In the next section, you’ll see how to use classes to keep state. But in simple cases, you can also get away with using function attributes:

The state—the number of calls to the function—is stored in the function attribute .num_calls on the wrapper function. Here’s the effect of using it:

You apply @count_calls to your old friend, say_whee(). Each time you call the function, you see that the call count increases. You can also manually query the .num_calls attribute.

Using Classes as Decorators

The typical way to maintain state in Python is by using classes. In this section, you’ll see how to rewrite the @count_calls example from the previous section to use a class as a decorator.

Recall that the decorator syntax @decorator is just a quicker way of saying func = decorator(func). Therefore, if decorator is a class, it needs to take func as an argument in its .__init__() initializer. Furthermore, the class instance needs to be callable so that it can stand in for the decorated function.

For a class instance to be callable, you implement the special .__call__() method:

The .__call__() method is executed each time you try to call an instance of the class:

Each time you call counter(), the state changes as the count increases. Therefore, a typical implementation of a decorator class should implement .__init__() and .__call__():

The .__init__() method must store a reference to the function, and it can do any other necessary initialization. The .__call__() method will be called instead of the decorated function. It does essentially the same thing as the wrapper() function in your earlier examples. Note that you need to use the functools.update_wrapper() function instead of @functools.wraps.

This @CountCalls decorator works the same as the one in the previous section:

Each call to say_whee() is counted and noted. In the next section, you’ll look at more examples of decorators.

More Real-World Examples

You’ve come a long way now, having figured out how to create all kinds of decorators. You’ll wrap it up, putting your newfound knowledge to use by creating a few more examples that might be useful in the real world.

Slowing Down Code, Revisited

As noted earlier, your previous implementation of @slow_down always sleeps for one second. Now you know how to add parameters to decorators, so you can rewrite @slow_down using an optional rate argument that controls how long it sleeps:

You’re using the boilerplate introduced in the Creating Decorators With Optional Arguments section to make @slow_down callable both with and without arguments. The same recursive countdown() function as earlier now sleeps two seconds between each count:

As before, you must run the example yourself to see the effect of the decorator:

There’ll be a two second pause between each number in the countdown.

Creating Singletons

A singleton is a class with only one instance. There are several singletons in Python that you use frequently, including None, True, and False. The fact that None is a singleton allows you to compare for None using the is keyword, like you did when creating decorators with optional arguments:

Using is returns True only for objects that are the exact same instance. The following @singleton decorator turns a class into a singleton by storing the first instance of the class as an attribute. Later attempts at creating an instance simply return the stored instance:

As you see, this class decorator follows the same template as your function decorators. The only difference is that you’re using cls instead of func as the parameter name to indicate that it’s meant to be a class decorator.

Check it out in practice:

By comparing object IDs and checking with the is keyword, you confirm that first_one is indeed the exact same instance as another_one.

Class decorators are less common than function decorators. You should document these well, so that your users know how to apply them.

Caching Return Values

Decorators can provide a nice mechanism for caching and memoization. As an example, look at a recursive definition of the Fibonacci sequence:

While this implementation is straightforward, its runtime performance is terrible:

To calculate the tenth Fibonacci number, you should only need to calculate the preceding Fibonacci numbers, but this implementation somehow needs a whopping 177 calculations. It gets worse quickly: 21,891 calculations are needed for fibonacci(20) and almost 2.7 million calculations for the thirtieth number. This is because the code keeps recalculating Fibonacci numbers that are already known.

The usual solution is to implement Fibonacci numbers using a for loop and a lookup table. However, caching the calculations will also do the trick. First add a @cache decorator to your module:

The cache works as a lookup table, as it stores calculations in a dictionary. You can add it to fibonacci():

You still use @count_calls to monitor the performance of your calculations. With the cache, fibonacci() only does the necessary calculations once:

Note that in the call to fibonacci(8), no new calculations were needed since the eighth Fibonacci number had already been calculated for fibonacci(10).

In the standard library, a Least Recently Used (LRU) cache is available as @functools.lru_cache. Additionally, you can use a regular cache with @functools.cache.

These decorators have more features than the one you saw above. You should use @functools.lru_cache or @functools.cache instead of writing your own cache decorator.

In the next example, you don’t return the result immediately. Instead, you add a call to print() to see when a result is calculated and not just retrieved from the cache:

The maxsize parameter specifies how many recent calls are cached. The default value is 128, but you can specify maxsize=None to cache all function calls. Using @functools.cache has the same effect as maxsize=None. However, be aware that this can cause memory problems if you’re caching many large objects.

You can use the .cache_info() method to see how the cache performs, and you can tune it if needed. In your example, you used an artificially small maxsize to see the effect of elements being removed from the cache:

In these examples, you calculate a few Fibonacci numbers. Your cache only holds four calculations at a time. For example, after calculating fibonacci(10), it holds the seventh, eight, ninth, and tenth number.

Therefore, you’re able to find fibonacci(8) without doing any recalculations. Then you ask for fibonacci(5), but that fifth number has been deleted from the cache. It therefore needs to be calculated from scratch.

In most applications, you don’t need to constrain your cache and can use @functools.cache directly.

Adding Information About Units

The following example is somewhat similar to the registering plugins example from earlier, in that it doesn’t really change the behavior of the decorated function. Instead, it simply adds unit as a function attribute:

The following example calculates the volume of a cylinder based on its radius and height in centimeters:

You’ve added information to volume() that the result should be interpreted as cubic centimeters. You can later access the .unit function attribute when needed:

Note that you could’ve achieved something similar using function annotations:

However, since annotations are used for type hints, it’s a bit clunky to combine such units as annotations with static type checking.

Units become even more powerful and fun when connected with a library that can convert between units. One such library is pint. With pint installed (python -m pip install Pint), you can convert the volume to cubic inches or gallons, for example:

You use pint to create a quantity that has both a magnitude and a unit. By calling .to(), you convert to other units. For example, the example cylinder is about 141 cubic centimeters, which translates to approximately 8.63 cubic inches and 0.0373 gallons.

You could also modify the decorator to return a pint Quantity directly. Such a Quantity is made by multiplying a value with the unit. In pint, units must be looked up in a UnitRegistry. You can store the registry as a function attribute on the decorator to avoid cluttering the namespace:

With the @use_unit decorator, converting units is practically effortless:

When Usain Bolt ran 100 meters in 9.58 seconds at the 2009 world championships, he had an average speed of 10.4 meters per second. This translates to about 37.6 kilometers per hour and 23.4 miles per hour.

Validating JSON

You’ll now look at one last use case. Take a quick look at the following Flask route handler:

Here you ensure that the key student_id is part of the request. Although this validation works, it doesn’t really belong in the function itself. Additionally, there may be other routes that use the same validation. So, to keep it DRY, you can abstract out any unnecessary logic with a decorator. The following @validate_json decorator will do the job:


In the above code, the decorator takes a variable-length list as an argument so that you can pass in as many string arguments as necessary, each representing a key used to validate the JSON data:

  • Line 4: The list of keys that must be present in the JSON is given as arguments to the decorator.
  • Line 9: The wrapper function validates that each expected key is present in the JSON data.

The route handler can then focus on its real job—updating grades—as it can safely assume that the JSON data are valid:


You apply @validate_json, which simplifies the logic inside update_grade().


This has been quite a journey! You started this tutorial by looking closer at functions, and particularly how you can define them inside other functions and pass them around just like any other Python object. Then you learned about decorators and how to write them such that:

  • They can be reused.
  • They can decorate functions with arguments and return values.
  • They can use @functools.wraps to look more like the decorated function.

In the second part of the tutorial, you saw more advanced decorators and learned how to:

  • Decorate classes
  • Nest decorators
  • Add arguments to decorators
  • Keep state within decorators
  • Use classes as decorators

You saw that, to define a decorator, you typically define a function returning a wrapper function. The wrapper function uses *args and **kwargs to pass on arguments to the decorated function. If you want your decorator to also take arguments, then you need to nest the wrapper function inside another function. In this case, you usually end up with three return statements.

You can download the code from this tutorial by clicking below:

Further Reading

If you’re still looking for more, the book Python Tricks has a section on decorators, as does the Python Cookbook by David Beazley and Brian K. Jones.

For a deep dive into the historical discussion on how decorators should be implemented in Python, see PEP 318 as well as the Python Decorator Wiki. You can find more examples of decorators in the Python Decorator Library. The decorator module can simplify creating your own decorators, and its documentation contains further decorator examples.

Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Python Decorators 101


Related stories
2 weeks ago - If you want to get into the field of Artificial Intelligence (AI), one of the most in-demand career paths these days, you've come to the right place. Learning Deep Learning Fundamentals is your essential first step to learning about...
3 weeks ago - Hi Folks, This newsletter comes back to a theme I love: Node.js streams. I expect more contents about the fundamentals in the future, as I'm scavenging some...
2 weeks ago - After a busy conference season, I've taken some time to catch up on reading and make a dent in the pile of books on my nightstand. Here's what I've started, finished, and picked up since re:Invent.
9 hours ago - Want to mirror your iPhone screen on your Ubuntu desktop? There's a free, open-source app you can install from the Ubuntu repos to do exactly that. If
Other stories
2 hours ago - Here's a quick set of steps from my actual experiences of using Fedora Linux as daily driver, which you can follow.
7 hours ago - Written by Contributor Opinions expressed by Twilio contributors are their own In this post, we'll learn how to build an...
8 hours ago - In the world of data science, where raw information swirls in a cacophony of numbers and variables, lies the art of harmonizing data. Like a maestro conducting a symphony, the skilled data scientist orchestrates the disparate elements of...
9 hours ago - Windows 10 allows you to create a password lock on a folder so only you can access the content within. Here are the steps to set up a password-locked folder
12 hours ago - Avid users of Varia, a modern download manager for Linux desktops, may want to check out official browser extensions. By installing the official Varia
13 hours ago - So far, all of my Alpine.js explorations have been client-side focused. But, my ultimate goal is to see if Alpine.js is a good companion framework for a ColdFusion-based multi-page application (MPA). As such, I wanted to spend some time...
13 hours ago - Mike Bostock, Announcing: Observable Framework: Today we’re launching Observable 2.0 with a bold new vision: an open-source static site generator for building fast, beautiful data apps, dashboards, and reports. Our …
14 hours ago - Windows has features to help SSDs operate to their full potential. Here is what you need to do if you have an SSD for your Windows PC.
1 day ago - Boosting your Node.js app's safety: a guide to keeping user passwords secure with bcrypt. Learn how to safeguard user accounts and data in your applications for better peace of mind.
1 day ago - If you’re screen-shopping, you’ll probably come across the “nit” unit. Find out what a nit of screen brightness is and why it is important for your screen.
1 day ago - Buying a graphics card in 2023 is tricky, with NVIDIA and AMD competing head to head across all segments. This guide can help you choose.
2 days ago - Remote Play works great for co-op gaming and streaming games. If you're facing issues with Steam Remote Play, learn how to fix it in this guide
2 days ago - In the world of network optimization, Content Delivery Networks (CDNs) and caching play a vital role in improving website performance and user experience. And while both aim to speed up website loading times, they have distinct purposes...
2 days ago - You may often need to compress files and folders for various reasons. And "Gzip" compression is a good choice for many scenarios. Recently, I have faced an issue where I needed to compress a lot of files individually, and manual...
2 days ago - In Python, lists are a cornerstones of data organization and manipulation – so I think they deserve a thorough exploration. This article delves into how to create and manipulate lists in Python, some advanced functionalities, and some...
2 days ago - Is your Fitbit not charging properly or at all? You can solve this common problem with the fixes in this guide guide.
2 days ago - An overview of SDKs The acronym SDK stands for software development kit. It contains platform-specific tools to run and develop software. Imitation or innovation? Leveraging the best parts of rival products If you think about some...
2 days ago - Linear design is a popular design trend, particularly for SaaS products, but has it peaked already? Let's find out.
2 days ago - In this week's episode of the podcast, freeCodeCamp founder Quincy Larson discusses AI and the future of education with Seth Goldin. Among other things, Seth is co-founder of College Compendium, an education charity, and studies computer...
2 days ago - Today I learned (well, technically, a few days ago, the week has been a lot), that the web platform supports a requestSubmit method. Since the...
2 days ago - Yesterday, I created a "template outlet" directive in Alpine.js. This directive allows me to take a template reference and render it at any arbitrary point within the document and provide it with local data bindings. This opens the...
2 days ago - Google Chrome has recently introduced a very useful feature for boosting productivity. You can now save and open tab groups across desktop devices when
2 days ago - 2024-03-01 1179 #agile and scrum#tools and resources 187062 102 Mar 1, 2024 ⋅ 4 min read Sara Nguyen My greatest career achievement was when I was recognized as "GIF Master" for my GIFs in the company Slack...
2 days ago - Learn how to foster digital literacy while encouraging physical play, creativity, and real-world interactions for a healthier, more rounded development.
2 days ago - Implementing OTA in-app updates in React Native apps can streamline the update process, preventing delays that hinder overall productivity.
2 days ago - A really interesting new browser capability. If you serve the following HTML: <template shadowrootmode="open"> <slot name="item-1">Loading...</slot> </template> Then later in the same page stream an element specifying that slot: <span …
2 days ago - In the realm of data analysis, SQL stands as a mighty tool, renowned for its robust capabilities in managing and querying databases. However, Python's pandas library brings SQL-like functionalities to the fingertips of analysts and data...
2 days ago - Are you looking for the right motherboard for your Ryzen 5000 or Ryzen 7000 CPU? We dive into the best AMD gaming motherboards.
2 days ago - Nested CSS support and a much cleaner client-side API for Svelte 5 This month, the Svelte maintainers made a ton of progress on Svelte 5 and Rich...
2 days ago - Next time you stop by you'll notice it has a new look. Canonical's designers have given Launchpad's landing page a lithe new look that
2 days ago - The JavaScript Registry (JSR) is a TypeScript-first, ESM-only module registry designed for the entire JavaScript ecosystem. Use JSR modules from Deno and npm-based projects. JSR is free and open source. Available today in public beta.
2 days ago - Tooltips are a very common pattern used in CSS for years. There are a lot of ways to approach tooltips in CSS, though some evoke headaches with all the magic numbers they require. In this article, Temani Afif presents modern techniques to...
2 days ago - What are the typical computer tasks you do manually every week? Could you automate those tasks with a Python script? Christopher Trudeau is back on the show this week, bringing another batch of PyCoder's Weekly articles and projects.
2 days ago - Dubai-based venture capital firm COTU Ventures has launched its first $54 million fund to invest in early-stage startups in Middle East and North Africa
3 days ago - Endatabas is "an open source immutable database" - also described as "SQL document database with full history". It uses a variant of SQL which allows you to insert data into …
3 days ago - The goal of this handbook is to provide gentle step-by-step instructions that will help you learn the key concepts of React. Instead of covering all the theories and concepts of React in their entirety, I'll be teaching you important...
3 days ago - The Apple TV remote is small and easy to get lost. If you have lost your Apple TV remote, here are a few ways to conect to your TV and remotely control it.
3 days ago - In the digital age, data security has become a paramount concern for individuals and organizations alike. With cyber threats evolving at an alarming...
3 days ago - About a week ago I noticed that the default icon for App Center (the Flutter-based software store-front that replaced Ubuntu Software in 23.10) had
3 days ago - If you are looking to play local multiplayer games online, these are some of the best games on Steam with Remote Play compatibility.
3 days ago - Vicki Boykis dives deep into the GGUF format used by llama.cpp, after starting with a detailed description of how PyTorch models work and how they are traditionally persisted using Python …
3 days ago - Google Gemini is a cutting edge AI model that is a competitor of GPT-4. We just released a course on the YouTube channel that will help you harness the power of the advanced AI technology. Developed by the popular...