# Decorators

make it look more attractive by adding extra items to it.

I was watching a really interesting video about buildings architecture in New York, when one of my DIT student asked me to explain to him what was happening in this piece of code. A function I have written few months ago to check for valid authentication tokens. In this post, I will try to show how decorators in Python, a powerful concept, allows us to apply new functionality without modifying the existing structure of an object. Music please. # 1. A function:

Let's suppose we want to join 2 paths:

``````In : from pathlib import Path

In : a = Path("foo")

In : a
Out: PosixPath('foo')

In : b = Path("bar")

In : a.joinpath(b)
Out: PosixPath('foo/bar')

In :
``````

Let's suppose we usually combine 2 paths together. So much that we created a function for that purpose:

``````In : path_t = str | Path

In : def jp(path1: path_t, path2: path_t) -> path_t:
...:     """Join 2 paths together"""
...:     if isinstance(path1, str):
...:         path1 = Path(path1)
...:     return path1.joinpath(path2)
...:

In : jp(b, a)
Out: PosixPath('bar/foo')

In : jp(a, b)
Out: PosixPath('foo/bar')

In : jp("corge", a)
Out: PosixPath('corge/foo')

In : jp("corge", "qux")
Out: PosixPath('corge/qux')
``````

# 2. A decorator modifying the behaviour of the function:

While it may seem confusing at first, a decorator is really just a function that takes a function and returns a function. Let me explain.

Suppose we usually combine our home path with another path. Let's suppose the first parameter is often our home path. Let's suppose we can't modify the original function. Python functions are first-class citizens. That means:

• We can pass a function as an argument of another function.
• We can assign a function to a variable.
• We can return a function as a value from another function.
``````In : def homeprefix(func: Callable[[path_t, path_t], path_t]) -> Callable[[path_t], path_t]:
...:     def wrapper(m: path_t) -> path_t:
...:         """A wrapper that takes one parameter."""
...:         return func("/home/nsukami", m)
...:     return wrapper
...:

In : f = homeprefix(jp)

In : f("bar")
Out: PosixPath('/home/nsukami/bar')

In : f(b)
Out: PosixPath('/home/nsukami/bar')

In : f(a)
Out: PosixPath('/home/nsukami/foo')

In : f("corge/qux")
Out: PosixPath('/home/nsukami/corge/qux')

In : f(Path("spam"))
Out: PosixPath('/home/nsukami/spam')

In :
``````

As strange as it may seems, we could have done the following:

``````In : jp = homeprefix(jp) # there is an alternative syntax

In : jp(a)
Out: PosixPath('/home/nsukami/foo')

In : jp(b)
Out: PosixPath('/home/nsukami/bar')

In : jp("foobar")
Out: PosixPath('/home/nsukami/foobar')

In : jp(Path("corge"))
Out: PosixPath('/home/nsukami/corge')

In :
``````

Instead of `jp = homeprefix(jp)` we could use the following syntax which better vehicle our intent: modifying the behaviour of an existing function. Simply put: decorating our original function:

``````In : def homeprefix(func):
...:     def wrapper(m):
...:     """A function that takes one parameter."""
...:         return func("/home/nsukami", m)
...:     return wrapper
...:

In : @homeprefix # here we are, decorating jp function
...: def jp(path1: path_t, path2: path_t) -> path_t:
...:     """Join 2 paths together"""
...:     if isinstance(path1, str):
...:         path1 = Path(path1)
...:     return path1.joinpath(path2)
...:

In : jp(Path("corge"))
Out: PosixPath('/home/nsukami/corge')

In : jp("corge/qux")
Out: PosixPath('/home/nsukami/corge/qux')

In : jp(a)
Out: PosixPath('/home/nsukami/foo')

In : jp(b)
Out: PosixPath('/home/nsukami/bar')

In :
``````

# 3. A decorator should keep important informations:

Now we have another problem. Because we are literally replacing one function with another, we're also losing important informations like the docstring and the name:

``````In : ?jp
Signature: jp(m)
Docstring: A function that takes one parameter.
File:      ~/GIT/nskm2/<ipython-input-59-b4f67b1e800d>
Type:      function

In : jp.__name__
Out: 'wrapper'

In :
``````

That's the reason we have functools.wraps. `Wraps` takes the decorated function and adds the functionality of copying over the function name, docstring, arguments list, etc to the returned function. And since wraps is itself a decorator:

``````In : from functools import wraps

In : def homeprefix(func):
...:     @wraps(func)
...:     def wrapper(m):
...:         """A function that takes one parameter."""
...:         return func("/home/nsukami", m)
...:     return wrapper
...:

In : @homeprefix
...: def jp(path1: path_t, path2: path_t) -> path_t:
...:     """A function that join 2 paths together."""
...:     if isinstance(path1, str):
...:         path1 = Path(path1)
...:     return path1.joinpath(path2)
...:

In : ?jp
Signature: jp(path1: str | pathlib.Path, path2: str | pathlib.Path) -> str | pathlib.Path
Docstring: A function that join 2 paths together.
File:      ~/GIT/nskm2/<ipython-input-65-1703cd8a40dc>
Type:      function

In : jp.__name__
Out: 'jp'

In :
``````

# 4. A decorator should receive a flexible number of argument:

Now, let's suppose our original function can take many arguments:

``````In : def jp(*args: path_t) -> path_t:
...:     """A function that join many paths together."""
...:     if args:
...:         path1 = Path(args)
...:         return path1.joinpath(*args[1:])
...:     else:
...:         raise ValueError("args should be longer")
...:

In : jp("bac", "abc")
Out: PosixPath('bac/abc')

In : jp("bac")
Out: PosixPath('bac')

In : jp(Path("abc"), Path("foo"), "bar")
Out: PosixPath('abc/foo/bar')
``````

The previous decorator is not flexible enough because the returned function can't take more than 1 parameter:

``````In : def homeprefix(func):
...:     @wraps(func)
...:     def wrapper(m):
...:         """A function that takes one parameter."""
...:         return func("/home/nsukami", m)
...:     return wrapper
...:

In : @homeprefix
...: def jp(*args: path_t) -> path_t:
...:     """A function that join many paths together."""
...:     if args:
...:         path1 = Path(args)
...:         return path1.joinpath(*args[1:])
...:     else:
...:         raise ValueError("args should be longer")
...:
...:

In : jp("a")
Out: PosixPath('/home/nsukami/a')

In : jp("a", "b")
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In , line 1
----> 1 jp("a", "b")

TypeError: jp() takes 1 positional argument but 2 were given

In :

``````

Let's rewrite our decorator so that the returned function can take an infinte number or arguments:

``````In : def homeprefix(func):
...:     @wraps(func)
...:     def wrapper(*args):  # here is our update: using *args
...:         return func("/home/nsukami", *args)
...:     return wrapper
...:

In : @homeprefix
...: def jp(*args: path_t) -> path_t:
...:     """A function that join many paths together."""
...:     if args:
...:         path1 = Path(args)
...:         return path1.joinpath(*args[1:])
...:     else:
...:         raise ValueError("args should be longer")
...:

In : jp()
Out: PosixPath('/home/nsukami')

In : jp("b", "c", "d")
Out: PosixPath('/home/nsukami/b/c/d')

In : jp("b", "c", "d", Path("foo"))
Out: PosixPath('/home/nsukami/b/c/d/foo')

In : jp(Path("foo"), Path("bar"))
Out: PosixPath('/home/nsukami/foo/bar')

In :

``````

With the help of the special parameters *args and **kwargs, decorators become more generic. That way if we need the same kind of decorator in different functions with different arguments, we can write just one decorator. In general, a decorator is written like this:

``````def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
func(*args, **kwargs)
return wrapper
``````

# 5. A decorator can also have parameters:

Let's suppose people using the decorator want to be able to set what should the prefix used as the first parameter of our jp function. Let's suppose we want the decorator to receive one parameter, which is the prefix:

``````In : def homeprefix(prefix): # this function builds and returns a decorator
...:     def outer(func): # this function is the decorator
...:         @wraps(func)
...:         def inner(*args, **kwargs): # the function wrapping the original function
...:             """A function that takes one parameter."""
...:             return func(prefix, *args, **kwargs)
...:         return inner
...:     return outer
...:

In : @homeprefix("/home/nsukami")
...: def jp(path1: path_t, path2: path_t) -> path_t:
...:     """A function that join 2 paths together."""
...:     if isinstance(path1, str):
...:         path1 = Path(path1)
...:     return path1.joinpath(path2)
...:

In : jp(a)
Out: PosixPath('/home/nsukami/foo')

In : jp(b)
Out: PosixPath('/home/nsukami/bar')

In : jp("corge")
Out: PosixPath('/home/nsukami/corge')

In :
``````

We understand better what's going on when we do this instead:

``````In : decorator = homeprefix("/home/patrick")  # setup a prefix

In : @decorator  # decorate
...: def jp(path1: path_t, path2: path_t) -> path_t:
...:     """A function that join 2 paths together."""
...:     if isinstance(path1, str):
...:         path1 = Path(path1)
...:     return path1.joinpath(path2)
...:

In : jp("corge")
Out: PosixPath('/home/patrick/corge')

In : jp("quux")
Out: PosixPath('/home/patrick/quux')

In :
``````

# 6. We are still able to access the decorated function:

Let's suppose for some reason we want to test the function as if it was not decorated. Let's suppose we still want to use the underlying function. To achieve that, we'll use the `__wrapped__` attribute (assuming we used the `functools.wrap` function). Somewhere in the documentation, we can read:

The original underlying function is accessible through the wrapped attribute. This is useful for introspection, for bypassing the cache, or for rewrapping the function with a different cache.

``````In : jp("foo")
Out: PosixPath('/home/nsukami/foo')

In : jp.__wrapped__("foo") # original function
Out: PosixPath('foo')

In :

``````

# 7. An interesting example:

``````#!/usr/bin/env python3

import csv
import sqlite3
import pathlib
from functools import wraps

here = pathlib.Path(__file__)
db = here.parent.parent.parent / "sqlite_stuff" / "chinook" / "chinook.db"

def connect(db):
"""A decorator to connect to an SQLite database and execute a query."""
conn = sqlite3.connect(db)
conn.isolation_level = None
def outer(f):
@wraps(f)
def inner(*args, **kwargs):
query = f(*args, **kwargs)
rset = conn.execute(query).fetchall()
return rset
return inner
return outer

def columns(*columns, limit=10):
"""A decorator to specify what columns should be retrieved."""
cols = ", ".join(columns)
def outer(f):
@wraps(f)
def inner(*args, **kwargs):
query = f(*args, **kwargs).split("*")
start, end = query.strip(), query.strip()
return f"{start} {cols} {end} limit {limit}"
return inner
return outer

def as_csv(where="./result.csv"):
"""A decorator to save the result as a csv file."""
def outer(f):
@wraps(f)
def inner(*args, **kwargs):
rset = f(*args, **kwargs)
with open(where, "w", newline="") as dest:
csv_writer = csv.writer(
dest, delimiter=",", quoting=csv.QUOTE_ALL, lineterminator=";\r\n"
)
csv_writer.writerows(rset)
return len(rset)
return inner
return outer

###

@as_csv()
@connect(db)
@columns("title", "artistId")
def run(table="albums"):
query = f"select * from {table}"
return query

if __name__ == "__main__":
print(run())
``````

# 8. Even more interesting:

``````import sqlite3
import pathlib
from functools import wraps

here = pathlib.Path(__file__)
db = here.parent.parent.parent / "sqlite_stuff" / "chinook" / "chinook.db"

def connect(cls):
conn = sqlite3.connect(db)
conn.isolation_level = None  # sqlite3.IMMEDIATE
setattr(cls, "conn", conn)
return cls

def select(cls):
def select(self):
return cls.conn.execute(f"select * from {cls.__name__}").fetchall()
setattr(cls, "select", select)
return cls

@select
@connect
class Albums:...

if __name__ == "__main__":
a = Albums()
print(a.select())
``````