A decorator is a function that takes another function and extends the behavior of the latter function without explicitly modifying it. In what follows, I demonstrate a practical use case for parameterized decorators focusing on units conversion.

To illustrate, we refer to the `getspeed` function used to estimate the spped of the International Space Station w.r.t. the surface of the Earth. `getspeed` returns a scalar representing the average speed of the ISS over a given time differential. The result is returned in kilometers per hour, with no parameter available to apply a change of units. To incorporate this functionality, we can either (1) add a units parameter to change the units of the calculated speed prior to `getspeed` returning, or (2) implement a decorator
specifying the units of the calculated value fully outside of `getspeed`. The declarations for `haverdist`, `getiss` and `getspeed` are provided below:

``````import datetime
import math
import os
import sys
import time
import requests

def haverdist(coords1, coords2):
"""
Compute distance between geographic coordinate pairs.

Parameters
----------
coords1: tuple or list;
(lat1, lon1) of first geolocation.

coords2: tuple or list
(lat2, lon2) of second geolocation.

Returns
-------
float
Distance in kilometers between coords1 and coords2.
"""
# Convert degrees to radians then compute differences.
R = 6367
rlat1, rlon1 = [ii * math.pi / 180 for ii in coords1]
rlat2, rlon2 = [ii * math.pi / 180 for ii in coords2]
drlat, drlon = (rlat2 - rlat1), (rlon2 - rlon1)
inner = (math.sin(drlat / 2.))**2 + (math.cos(rlat1)) * \
(math.cos(rlat2)) * (math.sin(drlon /2.))**2
return(2.0 * R * math.asin(min(1., math.sqrt(inner))))

def getiss():
"""
Get timestamped geo-coordinates of International Space Station.

Returns
-------
dict
Dictionary with keys "latitude", "longitude" and
"timestamp" indicating time and position of ISS.
"""
dpos = dict()
resp = requests.get("http://api.open-notify.org/iss-now.json").json()
if resp["message"] != "success":
raise RuntimeError("Unable to access Open Notify API.")
dpos["timestamp"] = resp["timestamp"]
dpos["latitude"]  = float(resp["iss_position"]["latitude"])
dpos["longitude"] = float(resp["iss_position"]["longitude"])
return(dpos)

def getspeed(dloc1, dloc2):
"""
Compute speed of ISS relative to Earth's surface using a pair of coordinates
retrieved via `getiss`.

Parameters
----------
dloc1: dict
Dictionary with keys "latitude", "longitude" "timestamp"
associated with the first positional snapshot.
dloc2: dict
Dictionary with keys "latitude", "longitude" "timestamp"
associated with the second positional snapshot.

Returns
-------
float
Scalar value representing the average speed in km/s of the
International Space Station relative to the Earth in translation
from `dloc1` to `dloc2`.
"""
# Convert unix epochs to timestamp datetime objects.
ts1  = datetime.datetime.fromtimestamp(dloc1['timestamp'])
ts2  = datetime.datetime.fromtimestamp(dloc2['timestamp'])
secs = abs((ts2-ts1).total_seconds())
loc1 = (dloc1["latitude"], dloc1["longitude"])
loc2 = (dloc2["latitude"], dloc2["longitude"])
dist = haverdist(loc1, loc2)
return((dist / secs) * 3600)
``````

In this case, the first option seems like a good choice. But instead of a simple function like `getspeed`, imagine a different function (we’ll call it `legacyfunc`) that we didn’t author, which has been in production for a very long time, which has lots of unfamiliar optional parameters and many more lines of code than `getspeed`, is responsible for returning the value, and this value is the one requiring a change of units. In this case, leaving `legacyfunc` unmodified and wrapping it’s result with logic to handle the change of units would be preferable.

We’ll implement a function to handle the change of units conversion. This will result in a parameterized decorator, the parameter indicating which units the final result should be converted to. For this example, the only options will be kilometers per hour or miles per hour, but the decorator can be extended to facilitate any number of additional distance or time conversions.

``````"""
Demonstration of parameterized decorator to facilitate change of units conversion.
"""
import functools

def units(spec):
"""
Specify the units to represent orbital speed. `spec` can be either "kmph"
(kilometer per hour) or "mph" (miles per hour). Defaults to "kmph".
"""
def decorator(function):
@functools.wraps(function)
def wrapper(*args, **kwargs):
result_init = function(*args, **kwargs)
# result_init is result returned by original function.
if spec=="mph":
result = result_init * 0.62137119
else:
result = result_init
return(result)
return(wrapper)
return(decorator)
``````

Next, we modify `getspeed` by referencing the `units` decorator as follows:

``````import functools

@units("mph")
def getspeed(dloc1, dloc2):
"""
Compute speed of ISS relative to Earth's surface using

Parameters
----------
dloc1: dict
Dictionary with keys "latitude", "longitude" "timestamp"
associated with the first positional snapshot.
dloc2: dict
Dictionary with keys "latitude", "longitude" "timestamp"
associated with the second positional snapshot.

Returns
-------
float
Scalar value representing the average speed of the International
Space Station relative to the Earth going from ``dloc1`` to
``dloc2``.
"""
# Convert unix epochs to timestamp datetime objects.
ts1   = datetime.datetime.fromtimestamp(dloc1['timestamp'])
ts2   = datetime.datetime.fromtimestamp(dloc2['timestamp'])
secs  = abs((ts2-ts1).total_seconds())
loc1  = (dloc1["latitude"], dloc1["longitude"])
loc2  = (dloc2["latitude"], dloc2["longitude"])
dist  = haverdist(geoloc1=loc1, geoloc2=loc2)
vinit = (dist / secs) # kilometers per second
return(vinit * 3600)
``````

With this change, the scalar representing kilometers per hour returned by `getspeed` will be converted to miles per hour. Calling this can be confirmed by calling `getspeed`.

``````In [2]: dpos1 = getiss(); time.sleep(5); dpos2 = getiss()
In [3]: getspeed(dpos1, dpos2)
Out[2]: 16126.21
``````

A speed of 16126mph equates to ~26,000km/h, right around what we’d expected (Wikipedia puts the ISS average orbital velocity at ~27,000km/h).