Python Topics : Decorators
Python Functions
First-Class Objects
functions are objects
greeters.py 
def say_hello(name):
    return f"Hello {name}"

def be_awesome(name):
    return f"Yo {name}, together we're the awesomest!"

def greet_bob(greeter_func):
    return greeter_func("Bob")
say_hello() and be_awesome() are regular functions that expect a name given as a string
the greet_bob() function expects a function as its argument
can pass it the say_hello() or the be_awesome() function 
>>> greet_bob(say_hello)
'Hello Bob'

>>> greet_bob(be_awesome)
'Yo Bob, together we're the awesomest!'
Inner Functions
can define functions inside other functions
these functions are called inner functions
inner_functions.py 
def parent():
    print("Printing from parent()")

    def first_child():
        print("Printing from first_child()")

    def second_child():
        print("Printing from second_child()")

    second_child()
    first_child()
output 
>>> parent()
Printing from parent()
Printing from second_child()
Printing from first_child()
the inner functions aren't defined until the parent function is called
inner functions are locally scoped to parent()
only exist inside the parent() function as local variables

Functions as Return Values
can return functions from functions
inner_functions.py 
def parent(num):
    def first_child():
        return "Hi, I'm Elias"

    def second_child():
        return "Call me Ester"

    if num == 1:
        return first_child
    else:
        return second_child
the function returns a reference to an inner function 
>>> first = parent(1)
>>> second = parent(2)

>>> first
<function parent.<locals>.first_child at 0x7f599f1e2e18>

>>> second
<function parent.<locals>.second_child at 0x7f599dad5268>
    
>>> first()
'Hi, I'm Elias'

>>> second()
'Call me Ester'
Simple Decorators in Python

a decorator wraps a function, modifying its behavior
hello_decorator.py 
def decorator(func):
    def wrapper():
        print("Something is happening before the function is called.")
        func()
        print("Something is happening after the function is called.")
    return wrapper

def say_whee():
    print("Whee!")

say_whee = decorator(say_whee)
output 
>>> from hello_decorator import say_whee

>>> say_whee()
Something is happening before the function is called.
Whee!
Something is happening after the function is called.
Adding Syntactic Sugar
the examples above are somewhat convoluted
say_whee shows no indication of a decorator
have to call the decorator function to get the reference to the function being decorated

can use decorators in a simpler way with the @ symbol
sometimes called the pie syntax
hello_decorator.py 

def decorator(func):
    def wrapper():
        print("Something is happening before the function is called.")
        func()
        print("Something is happening after the function is called.")
    return wrapper

@decorator
def say_whee():
    print("Whee!")
@decorator is just a shorter way of saying say_whee = decorator(say_whee)

Reusing Decorators
create a module where decorators are stored
decorators.py 
def do_twice(func):
    def wrapper_do_twice():
        func()
        func()
    return wrapper_do_twice
can now use the decorator in other files by doing a regular import 
>>> from decorators import do_twice

>>> @do_twice
... def say_whee():
...     print("Whee!")
...
>>> say_whee()
Whee!
Whee!
Decorating Functions With Arguments
below the decorator fails 
>>> from decorators import do_twice

>>> @do_twice
... def greet(name):
...     print(f"Hello {name}")
...
test with REPL 
>>> greet(name="World")
Traceback (most recent call last):
  ...
TypeError: wrapper_do_twice() takes 0 positional arguments but 1 was given
the decorator's inner function wrapper_do_twice() takes no arguments
the decorator's inner function will only work when the decorated method takes no arguments such as say_whee()

use *args and **kwargs in the inner wrapper function
the function will then accept an arbitrary number of positional and keyword arguments
decorators.py 

def do_twice(func):
    def wrapper_do_twice(*args, **kwargs):
        func(*args, **kwargs)
        func(*args, **kwargs)
    return wrapper_do_twice
the decorator now works with whee and greet functions 
>>> from decorators import do_twice

>>> @do_twice
... def say_whee():
...     print("Whee!")
...

>>> say_whee()
Whee!
Whee!

>>> @do_twice
... def greet(name):
...     print(f"Hello {name}")
...

>>> greet("World")
Hello World
Hello World
Returning Values From Decorated Functions
the decorator determines the values, if any, to be returned 
>>> from decorators import do_twice

>>> @do_twice
... def return_greeting(name):
...     print("Creating greeting")
...     return f"Hi {name}"
...
output 
>>> hi_adam = return_greeting("Adam")
Creating greeting
Creating greeting

>>> print(hi_adam)
None
the call to return_greeting("Adam") return None
each call to the wrappered function returns a populated f-string
the do_twice_wrapper() doesn't explicitly return a value from the wrappered function calls

decorators need to make sure the wrapper function returns the return value of the decorated function
change decorators.py to 

def do_twice(func):
    def wrapper_do_twice(*args, **kwargs):
        func(*args, **kwargs)
        return func(*args, **kwargs)
    return wrapper_do_twice
using the decorator 
>>> hi_adam = return_greeting("Adam")
Creating greeting
Creating greeting

>>> print(hi_adam)
'Hi Adam'
Finding Yourself
introspection is the ability of an object to know about its own attributes at runtime
a function knows its own name and documentation 
>>> print
<built-in function print>

>>> print.__name__
'print'

>>> help(print)
Help on built-in function print in module builtins:

print(...)
    <full help message>
with a decorated function what does the function know about itself vs its decorated self?
to preserve the function's undecorated introspection decorators should use the @functools.wraps decorator
the @functools.wraps decorator will preserve information about the original function
decorators.py 
import functools

def do_twice(func):
    @functools.wraps(func)
    def wrapper_do_twice(*args, **kwargs):
        func(*args, **kwargs)
        return func(*args, **kwargs)
    return wrapper_do_twice
A Few Real World Examples

boilerplate for decorators 
import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper_decorator(*args, **kwargs):
        # Do something before
        value = func(*args, **kwargs)
        # Do something after
        return value
    return wrapper_decorator
Timing Functions
create a @timer decorator in decorators.py
decorator will measure the time a function takes to execute and then print the duration to the console 
import functools
import time

# ...

def timer(func):
    """Print the runtime of the decorated function"""
    @functools.wraps(func)
    def wrapper_timer(*args, **kwargs):
        start_time = time.perf_counter()
        value = func(*args, **kwargs)
        end_time = time.perf_counter()
        run_time = end_time - start_time
        print(f"Finished {func.__name__}() in {run_time:.4f} secs")
        return value
    return wrapper_timer
test the @timer decorator 
>>> from decorators import timer

>>> @timer
... def waste_some_time(num_times):
...     for _ in range(num_times):
...         sum([number**2 for number in range(10_000)])
...

>>> waste_some_time(1)
Finished waste_some_time() in 0.0010 secs

>>> waste_some_time(999)
Finished waste_some_time() in 0.3260 secs
Debugging Code
the @debug decorator will print a function's arguments and its return value every time it's called
add to decorators.py 
def debug(func):
    """Print the function signature and return value"""
    @functools.wraps(func)
    def wrapper_debug(*args, **kwargs):
        # unwrap args
        args_repr = [repr(a) for a in args]
        kwargs_repr = [f"{k}={repr(v)}" for k, v in kwargs.items()]
        signature = ", ".join(args_repr + kwargs_repr)
        # print the function name and args
        print(f"Calling {func.__name__}({signature})")
        # actually call the function
        value = func(*args, **kwargs)
        # print the function name and return value
        print(f"{func.__name__}() returned {repr(value)}")
        return value
    return wrapper_debug
function to test @debug decorator 
>>> from decorators import debug

>>> @debug
... def make_greeting(name, age=None):
...     if age is None:
...         return f"Howdy {name}!"
...     else:
...         return f"Whoa {name}! {age} already, you're growing up!"
...
test the @debug decorator 
>>> from decorators import debug

>>> @debug
... def make_greeting(name, age=None):
...     if age is None:
...         return f"Howdy {name}!"
...     else:
...         return f"Whoa {name}! {age} already, you're growing up!"
...
@debug is more powerful when applied to small convenience functions which aren't called directly
calculate an approximation of the mathematical constant e 
#calculate_e.py

import math
from decorators import debug

math.factorial = debug(math.factorial)

def approximate_e(terms=18):
    return sum(1 / math.factorial(n) for n in range(terms))
a decorator is applied to a function which has already been defined
the output 
>>> from calculate_e import approximate_e

>>> approximate_e(terms=5)
Calling factorial(0)
factorial() returned 1
Calling factorial(1)
factorial() returned 1
Calling factorial(2)
factorial() returned 2
Calling factorial(3)
factorial() returned 6
Calling factorial(4)
factorial() returned 24
2.708333333333333
Slowing Down Code
create a decorator that slows down code
the most common use case is to rate-limit a function that continuously checks whether a resource has changed
@slow_down decorator will sleep one second before it calls the decorated function 
# decorators.py

def slow_down(func):
    """Sleep 1 second before calling the function"""
    @functools.wraps(func)
    def wrapper_slow_down(*args, **kwargs):
        time.sleep(1)
        return func(*args, **kwargs)
    return wrapper_slow_down
@slow_down in use 
>>> from decorators import slow_down

>>> @slow_down
... def countdown(from_number):
...     if from_number < 1:
...         print("Liftoff!")
...     else:
...         print(from_number)
...         countdown(from_number - 1)
...

>>> countdown(3)
3
2
1
Liftoff!
note countdown() recursion

Registering Plugins
decorators don't have to wrap the function that they're decorating
decorators can also simply register that a function exists and return it unwrapped
example : can use this to create a lightweight plugin architecture 
# decorators.py

PLUGINS = dict()

def register(func):
    """Register a function as a plug-in"""
    PLUGINS[func.__name__] = func
    return func
the @register decorator only stores a reference to the decorated function in the global PLUGINS dictionary
example : can now register functions 
>>> from decorators import register, PLUGINS

>>> @register
... def say_hello(name):
...     return f"Hello {name}"
...

>>> @register
... def be_awesome(name):
...     return f"Yo {name}, together we're the awesomest!"
...
Python applies decorators when a function defined
say_hello() and be_awesome() are registered immediately
use PLUGINS to call these functions 
>>> import random

>>> def randomly_greet(name):
...     greeter, greeter_func = random.choice(list(PLUGINS.items()))
...     print(f"Using {greeter!r}")
...     return greeter_func(name)
...

>>> randomly_greet("Alice")
Using 'say_hello'
'Hello Alice'
in the above f-string the !r flag has the same effect as calling repr(greeter)

main benefit of this simple plugin architecture is that no need to maintain a list of which plugins exist
the list is created when the plugins register themselves
trivial to add a new plugin, just define the function and decorate it with @register

globals() provides a listingof all global variables in the current scope including plugins 

>>> globals()
{..., # Many variables that aren't not shown here.
 'say_hello': ,
 'be_awesome': ,
 'randomly_greet': }
Authenticating Users
example is commonly used when working with a web framework
this example uses Flask to set up a /secret web page that should only be visible to users which are logged in or otherwise authenticated 
import functools
from flask import Flask, g, request, redirect, url_for

app = Flask(__name__)

def login_required(func):
    """Make sure user is logged in before proceeding"""
    @functools.wraps(func)
    def wrapper_login_required(*args, **kwargs):
        if g.user is None:
            return redirect(url_for("login", next=request.url))
        return func(*args, **kwargs)
    return wrapper_login_required

@app.route("/secret")
@login_required
def secret():
    ...
Fancy Decorators
Decorating Classes
two different ways to use decorators on classes
first way is to decorate the methods of a class
second way is to decorate the class itself
was one of the motivations for introducing decorators

some commonly used decorators are built-ins in Python

  • @classmethod
  • @staticmethod
  • @property
the @classmethod and @staticmethod decorators are used to define methods inside a class namespace which aren't connected to a particular instance of that class
the @property decorator is used to customize getters and setters for class attributes

a class where some of its methods are decorated using the @debug and @timer decorators 

from decorators import debug, timer

class TimeWaster:
    @debug
    def __init__(self, max_num):
        self.max_num = max_num

    @timer
    def waste_time(self, num_times):
        for _ in range(num_times):
            sum([number**2 for number in range(self.max_num)])
using the TimeWaster class 
>>> from class_decorators import TimeWaster

>>> tw = TimeWaster(1000)
Calling __init__(<time_waster.TimeWaster object at 0x7efccce03908>, 1000)
__init__() returned None

>>> tw.waste_time(999)
Finished waste_time() in 0.3376 secs
use decorators on classes is to decorate the whole class
done in the dataclasses module to decorate the whole class 
>>> from dataclasses import dataclass

>>> @dataclass
... class PlayingCard:
...     rank: str
...     suit: str
...
syntax is similar to function decorators
can also decorate a class as shown below 
PlayingCard = dataclass(PlayingCard)
a common use of class decorators is to be a simpler alternative to some use cases of metaclasses
in both cases the definition of a class changes dynamically

writing a class decorator is very similar to writing a function decorator
only difference is that the decorator will receive a class and not a function as an argument
all the decorators that above will work as class decorators
when using them on a class instead of a function, the effect might not be what is desired
the @timer decorator is applied to a class 

from decorators import timer

@timer
class TimeWaster:
    def __init__(self, max_num):
        self.max_num = max_num

    def waste_time(self, num_times):
        for _ in range(num_times):
            sum([i**2 for i in range(self.max_num)])
decorating a class doesn't decorate its methods
@timer is just shorthand for TimeWaster = timer(TimeWaster)
@timer only measures the time that it takes to instantiate the class 
>>> from class_decorators import TimeWaster

>>> tw = TimeWaster(1000)
Finished TimeWaster() in 0.0000 secs

>>> tw.waste_time(999)
Nesting Decorators
can apply several decorators to a function at once by stacking them on top of each other 
>>> from decorators import debug, do_twice

>>> @debug
... @do_twice
... def greet(name):
...     print(f"Hello {name}")
...
output shows the decorators being executed in the order they're listed. 
>>> greet("Yadi")
Calling greet('Yadi')
Hello Yadi
Hello Yadi
greet() returned None
changing the order of decorators changes the output 
>>> from decorators import debug, do_twice

>>> @do_twice
... @debug
... def greet(name):
...     print(f"Hello {name}")
...

>>> greet("Yadi")
Calling greet('Yadi')
Hello Yadi
greet() returned None
Calling greet('Yadi')
Hello Yadi
greet() returned None
both calls to greet() are annotated with debugging information

Defining Decorators With Arguments
sometimes a decorator needs to receive arguments
@do_twice could be extended to a @repeat(num_times) decorator
the number of times to execute the decorated function can be given as an argument with @repeat defined, the decorator might be used as 
>>> from decorators import repeat

>>> @repeat(num_times=4)
... def greet(name):
...     print(f"Hello {name}")
...

>>> greet("World")
Hello World
Hello World
Hello World
Hello World
name after @ refers to a function which can be called by another function
for consistency need a repeat(num_times=4) function to return a function object which can act as a decorator
decorator_repeat is a container for repeat(num_times=4) 
def repeat(num_times):
    def decorator_repeat(func):
        ...  # Create and return a wrapper function for repeat(num_times=4)
    return decorator_repeat
with the wrapper function added 
# decorators.py

def repeat(num_times):
    def decorator_repeat(func):
        @functools.wraps(func)
        # wrapper function
        def wrapper_repeat(*args, **kwargs):
            for _ in range(num_times):
                value = func(*args, **kwargs)
            return value
        return wrapper_repeat
        # end wrapper function
    return decorator_repeat
things to note
  • a function with an inner function with an inner function
    the outer-most function returns a reference to the decorated function
    defining decorator_repeat() as an inner function means that repeat() will refer to a function object - decorator_repeat
    need to add parentheses when setting up the decorator, as in @repeat()
    parentheses are necessary in order to add arguments
  • the num_times argument is seemingly not used in repeat() itself
    by passing num_times, a closure is created where the value is stored until wrapper_repeat() uses it later
Creating Decorators With Optional Arguments
can also define decorators which can be used both with and 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
the decorator arguments must all be specified by keyword
can enforce this with the special asterisk (*) syntax meaning all the following parameters are keyword-only 

def name(_func=None, *, key1=value1, key2=value2, ...):
    def decorator_name(func):
        ...  # Create and return a wrapper function.

    if _func is None:
        return decorator_name
    else:
        return decorator_name(_func)
if @name is called without arguments, then the decorated function will be passed in as _func
if @name is called with arguments, then _func will be None
some of the keyword arguments may have been changed from their default values
the asterisk in the argument list means the remaining arguments can't be positional arguments 
# decorators.py

def repeat(_func=None, *, num_times=2):
    def decorator_repeat(func):
        @functools.wraps(func)
        def wrapper_repeat(*args, **kwargs):
            for _ in range(num_times):
                value = func(*args, **kwargs)
            return value
        return wrapper_repeat

    if _func is None:
        return decorator_repeat
    else:
        return decorator_repeat(_func)
testing the decorators with different functions 
>>> from decorators import repeat

>>> @repeat
... def say_whee():
...     print("Whee!")
...

>>> @repeat(num_times=3)
... def greet(name):
...     print(f"Hello {name}")
...

>>> say_whee()
Whee!
Whee!

>>> greet("Penny")
Hello Penny
Hello Penny
Hello Penny
Tracking State in Decorators
sometimes need a decorator that can keep track of state
create a decorator which counts the number of times a function is called 
# decorators.py

def count_calls(func):
    @functools.wraps(func)
    def wrapper_count_calls(*args, **kwargs):
        wrapper_count_calls.num_calls += 1
        print(f"Call {wrapper_count_calls.num_calls} of {func.__name__}()")
        return func(*args, **kwargs)
    wrapper_count_calls.num_calls = 0
    return wrapper_count_calls
the state is the number of calls to the function
the number is stored in the function attribute .num_calls 
>>> from decorators import count_calls

>>> @count_calls
... def say_whee():
...     print("Whee!")
...

>>> @count_calls
... def say_whoa():
...     print("Whoa!")
...

>>> say_whee()
Call 1 of say_whee()
Whee!
>>> say_whee()
Call 2 of say_whee()
Whee!
>>> say_whoa()
Call 1 of say_whoa()
Whoa!
>>> say_whee()
Call 3 of say_whee()
Whee!
>>> say_whee.num_calls
3
>>> say_whoa.num_calls
1
the .num_calls attribute is assigned to the decorated function

Using Classes as Decorators
typical way to maintain state in Python is by using classes
rewrite the @count_calls example to use a class as a decorator

for a function the decorator syntax is 

func = decorator(func)
if decorator is a class it needs to take func as an argument in its .__init__() initializer
the class instance needs to be callable so that it can stand in for the decorated function
for a class instance to be callable implement the dunder .__call__() 
>>> class Counter:
...     def __init__(self, start=0):
...         self.count = start
...     def __call__(self):
...         self.count += 1
...         print(f"Current count is {self.count}")
...
the .__call__() method is executed each time a call to an instance of the class 
>>> counter = Counter()
>>> counter()
Current count is 1

>>> counter()
Current count is 2

>>> counter.count
2
each instance of Counter has its own count attribute

using a class as a decorator to maintain state 

# decorators.py

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.num_calls = 0

    def __call__(self, *args, **kwargs):
        self.num_calls += 1
        print(f"Call {self.num_calls} of {self.func.__name__}()")
        return self.func(*args, **kwargs)
More Real-World Examples
Slowing Down Code, Revisited
add a rate parameter to the decorator 
import functools
import time

def slow_down(_func=None, *, rate=1):
    """Sleep given amount of seconds before calling the function"""
    def decorator_slow_down(func):
        @functools.wraps(func)
        def wrapper_slow_down(*args, **kwargs):
            time.sleep(rate)
            return func(*args, **kwargs)
        return wrapper_slow_down

    if _func is None:
        return decorator_slow_down
    else:
        return decorator_slow_down(_func)
uses the boilerplate code shown earlier for passing arguments
same recursive countdown() method 
from decorators import slow_down

@slow_down(rate=2)
def countdown(from_number):
    if from_number < 1:
        print("Liftoff!")
    else:
        print(from_number)
        countdown(from_number - 1)
with the same output as before 
>>> countdown(3)
3
2
1
Liftoff!
Creating Singletons
a singleton is a class with only one instance 
# decorators.py

def singleton(cls):
    """Make a class a Singleton class (only one instance)"""
    @functools.wraps(cls)
    def wrapper_singleton(*args, **kwargs):
        if wrapper_singleton.instance is None:
            wrapper_singleton.instance = cls(*args, **kwargs)
        return wrapper_singleton.instance
    wrapper_singleton.instance = None
    return wrapper_singleton
a class decorator follows the same format as a function decorator 
>>> from decorators import singleton

>>> @singleton
... class TheOne:
...     pass
...

>>> first_one = TheOne()
>>> another_one = TheOne()

>>> id(first_one)
140094218762310

>>> id(another_one)
140094218762310

>>> first_one is another_one
True
Caching Return Values
decorators can provide a nice mechanism for caching and memoization
a recursive definition of the Fibonacci sequence 
>>> from decorators import count_calls

>>> @count_calls
... def fibonacci(num):
...     if num < 2:
...         return num
...     return fibonacci(num - 1) + fibonacci(num - 2)
...
the performance is horrible
implemention takes 177 calls

usual solution is to implement Fibonacci numbers using a for loop and a lookup table
caching the calculations will also work
a @cache decorator 

# decorators.py

def cache(func):
    """Keep a cache of previous function calls"""
    @functools.wraps(func)
    def wrapper_cache(*args, **kwargs):
        cache_key = args + tuple(kwargs.items())
        if cache_key not in wrapper_cache.cache:
            wrapper_cache.cache[cache_key] = func(*args, **kwargs)
        return wrapper_cache.cache[cache_key]
    wrapper_cache.cache = {}
    return wrapper_cache
cache works as a lookup table
stores calculations in a dictionary
example usage 
>>> from decorators import cache, count_calls

>>> @cache
... @count_calls
... def fibonacci(num):
...     if num < 2:
...         return num
...     return fibonacci(num - 1) + fibonacci(num - 2)
...
>>> fibonacci(10)
Call 1 of fibonacci()
Call 2 of fibonacci()
Call 3 of fibonacci()
Call 4 of fibonacci()
Call 5 of fibonacci()
Call 6 of fibonacci()
Call 7 of fibonacci()
Call 8 of fibonacci()
Call 9 of fibonacci()
Call 10 of fibonacci()
Call 11 of fibonacci()
55

>>> fibonacci(8)
21
the second call to fibonacci() makes no calls to the @count_calls decorator
the @cache decorator returns the value from its dictionary

the @cache decorator reinvents the wheel
functools module contains

  • @functools.lru_cache
  • @functools.cache
functools' decorators have more features

built-in cache example 

>>> import functools

>>> @functools.lru_cache(maxsize=4)
... def fibonacci(num):
...     if num < 2:
...         value = num
...     else:
...         value = fibonacci(num - 1) + fibonacci(num - 2)
...     print(f"Calculated fibonacci({num}) = {value}")
...     return value
...
the maxsize parameter specifies how many recent calls are cached
default value is 128
can specify maxsize=None to cache all function calls
using @functools.cache has the same effect as maxsize=None
can cause memory problems if many large objects are being cached

can use the .cache_info() method to see how the cache performs
example 

>>> fibonacci(10)
Calculated fibonacci(1) = 1
Calculated fibonacci(0) = 0
Calculated fibonacci(2) = 1
Calculated fibonacci(3) = 2
Calculated fibonacci(4) = 3
Calculated fibonacci(5) = 5
Calculated fibonacci(6) = 8
Calculated fibonacci(7) = 13
Calculated fibonacci(8) = 21
Calculated fibonacci(9) = 34
Calculated fibonacci(10) = 55
55

>>> fibonacci(8)
21

>>> fibonacci(5)
Calculated fibonacci(1) = 1
Calculated fibonacci(0) = 0
Calculated fibonacci(2) = 1
Calculated fibonacci(3) = 2
Calculated fibonacci(4) = 3
Calculated fibonacci(5) = 5
5

>>> fibonacci(8)
Calculated fibonacci(6) = 8
Calculated fibonacci(7) = 13
Calculated fibonacci(8) = 21
21

>>> fibonacci(5)
5

>>> fibonacci.cache_info()
CacheInfo(hits=17, misses=20, maxsize=4, currsize=4)
Adding Information About Units
decorator adds unit as a function attribute 
#decorators.py

def set_unit(unit):
    """Register a unit on a function"""
    def decorator_set_unit(func):
        func.unit = unit
        return func
    return decorator_set_unit
example calculates the volume of a cylinder based on its radius and height in centimeters 
>>> import math
>>> from decorators import set_unit

>>> @set_unit("cm^3")
... def volume(radius, height):
...     return math.pi * radius**2 * height
...
to see the attribute 
>>> volume(3, 5)
141.3716694115407

>>> volume.unit
'cm^3'
units become even more powerful with a library which can convert between units
pint is such a library
to install pint in a venv 
python -m pip install Pint
example converts the volume to cubic inches or gallons 
>>> import pint
>>> ureg = pint.UnitRegistry()
>>> vol = volume(3, 5) * ureg(volume.unit)

>>> vol
<Quantity(141.3716694115407, 'centimeter ** 3')>

>>> vol.to("cubic inches")
<Quantity(8.627028576414954, 'inch ** 3')>

>>> vol.to("gallons").m  # Magnitude
0.0373464440537444
use pint to create a quantity which has both a magnitude and a unit
use .to() to convert to other units

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

# decorators.py

import pint
# ...
def use_unit(unit):
    """Have a function return a Quantity with given unit"""
    use_unit.ureg = pint.UnitRegistry()
    def decorator_use_unit(func):
        @functools.wraps(func)
        def wrapper_use_unit(*args, **kwargs):
            value = func(*args, **kwargs)
            return value * use_unit.ureg(unit)
        return wrapper_use_unit
    return decorator_use_unit
the @use_unit decorator simplifies converting units 
>>> from decorators import use_unit

>>> @use_unit("meters per second")
... def average_speed(distance, duration):
...     return distance / duration
...

>>> bolt = average_speed(100, 9.58)
>>> bolt
<Quantity(10.438413361169102, 'meter / second')>

>>> bolt.to("km per hour")
<Quantity(37.578288100208766, 'kilometer / hour')>

>>> bolt.to("mph").m  # Magnitude
23.350065679064745
index