higher-order-functions-and-decorators.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Higher-Order Functions and Decorators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Suppose you are maintaining a module, package, or data structure that has an API with many methods and you want to add the ability to log every API call. Furthermore, you need to enable or disable the logging feature using a single flag. Do you manually add a block of logging code to every method definition? Do you write a wrapper API? How do you ensure the logging feature is modular in its implementation, remains compatible as the API evolves, and is easy to maintain?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python's concrete syntax includes support for something called *decorators*. This is a syntactic feature that acts as a convenient and concise tool for modifying, analyzing, or associating functions and methods *at the point at which they are defined*. This can reduce redundancy and clutter in code. Importantly, it leverages Python's native support for a functional programming paradigm to offer you a different kind of modularity and composability that can help you add the logging feature in a relatively quick, concise, and elegant way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Functions as Values and Arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To understand decorators, it is necessary to at least be aware of higher-order functions. In Python, functions can be defined and used just like values. This is a characteristic feature of the [functional programming paradigm](https://en.wikipedia.org/wiki/Functional_programming), which Python supports. Consider the following example in which a function `f` is defined and then passed as an argument to another function `twice`. Note that when `twice` receives the argument `f` it is assigned to the local variable `g`. Then this yields `g(g(y))` = `f(f(y))` = `f(y + y)` = `(y + y) + (y + y)`. If you assign `2` to `y`, this will yield `g(g(2))` = `f(f(2))` = `f(2 + 2)` = `(2 + 2) + (2 + 2)` = `8`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def f(x):\n",
    "    return x + x\n",
    "\n",
    "def twice(g, y):\n",
    "    return g(g(y))\n",
    "\n",
    "twice(f, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Just as functions can be arguments, they can also be results. In the example below, a different variant of `twice` takes a function as its sole input and returns a *new* function that behaves like its input function but is applied twice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.twice.<locals>.h(y)>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def f(x):\n",
    "    return x + x\n",
    "\n",
    "def twice(g):\n",
    "\n",
    "    # Define a new function locally.\n",
    "    def h(y):\n",
    "        return g(g(y))\n",
    "\n",
    "    # Return the local function as the result.\n",
    "    return h\n",
    "\n",
    "twice(f)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Because `twice(f)` is a function, you can apply it to an argument and it will return a result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "twice(f)(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Decorators and Function Definitions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "As a slightly simpler variant of the motivating example described in the introduction, suppose you want to modify some existing functions so that they display their results using `print` (in addition to returning their results as they normally would). To do this in a reusable way, you can write a higher-order function that takes the original function as an input and returns a *new* function that also prints the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def displays(f):\n",
    "    \n",
    "    # This is the new variant of the function `f`.\n",
    "    def f_displays(x):\n",
    "        r = f(x)\n",
    "        print('The result is:', r)\n",
    "        return r\n",
    "\n",
    "    return f_displays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "This transformer function `displays` can then be applied to any existing function to give you a new version that also prints its result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The result is: 4\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def double(x):\n",
    "    return x + x\n",
    "\n",
    "double = displays(double)\n",
    "\n",
    "double(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python's concrete syntax lets you do exactly the same thing using a more concise notation: prepend the `@` symbol before your higher-order function and place it immediately before the definition of the function you want to transform. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "@displays\n",
    "def triple(x):\n",
    "    return x + x + x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "In the example above, the variable `triple` (after the decorated definition is executed) refers to the transformed version of the function in the definition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The result is: 6\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "triple(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Because the higher-order function used as a decorator is itself just a function, it can *also* be the result of a function. Thus, you can create a function that creates decorators! Below, the function `displays_with` returns a decorator that prints a custom message rather than the hard-coded one in the examples above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def displays_with(message):\n",
    "\n",
    "    # Create the function that converts a function\n",
    "    # into a function that display (i.e., our old\n",
    "    # decorator).\n",
    "    def displays(f):\n",
    "\n",
    "        # This is the new variant of the function `f`.\n",
    "        def f_displays(x):\n",
    "            r = f(x)\n",
    "            print(message, r)\n",
    "            return r\n",
    "\n",
    "        return f_displays\n",
    "    \n",
    "    # Return the function created above.\n",
    "    return displays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The decorator syntax allows you to supply the argument to the function that creates a decorator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The function returned: 6\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@displays_with('The function returned:')\n",
    "def triple(x):\n",
    "    return x + x + x\n",
    "\n",
    "triple(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To clarify what is happening, a code block that is functionally equivalent to code above is presented below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The function returned: 6\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def triple(x):\n",
    "    return x + x + x\n",
    "\n",
    "triple = displays_with('The function returned:')(triple)\n",
    "\n",
    "triple(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Decorators can also be stacked. Suppose you create a decorator that also adds the decorated function to a running list of functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "functions = []\n",
    "\n",
    "def function(f):\n",
    "    functions.append(f)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "You can now decorate a function with both decorators."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<function __main__.triple(x)>]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@displays_with('The function returned:')\n",
    "@function\n",
    "def triple(x):\n",
    "    return x + x + x\n",
    "\n",
    "functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Note that order *does* matter: if you place the `function` decorator *above* the `displays_with`, the function added to the list using `function` will be the one already modified by `displays_with`. Thus, when multiple decorators are present they are applied *from the bottom up* (or, in other words, decorators are *right-associative*). In the example below, the *transformed* function `triple` is added to the list of functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The function returned: 6\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "functions = []\n",
    "\n",
    "@function\n",
    "@displays_with('The function returned:')\n",
    "def triple(x):\n",
    "    return x + x + x\n",
    "\n",
    "functions[0](2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "In the example below, on the other hand, the *original* version of `triple` is added to the list of functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "functions = []\n",
    "\n",
    "@displays_with('The function returned:')\n",
    "@function\n",
    "def triple(x):\n",
    "    return x + x + x\n",
    "\n",
    "functions[0](2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Decorators and Class Definitions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Just as functions in Python can be used as values, so can classes. This article will not go into much depth on this subject. It is enough to see that the same examples presented involving function definitions have corresponding examples involving class definitions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "First, note that you can define a function that takes a class (*not* an object of the class, but the class itself) as an input. The function `check` below takes a class as an input and checks if it has a method called `method`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(False, True)"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "class C:\n",
    "    def __init__(self, attr):\n",
    "        self.attr = attr\n",
    "\n",
    "class D:\n",
    "    def method(self):\n",
    "        pass\n",
    "\n",
    "def check(cls):\n",
    "    return callable(getattr(cls, 'method', None))\n",
    "\n",
    "check(C), check(D)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Decorators can be added to a class definition in the same way that they can be added to a function definition. In the examples below, the decorator `displayable` checks whether a class definition includes a method called `display` and raises an exception if it does not."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def displayable(cls):\n",
    "    if not callable(getattr(cls, 'display', None)):\n",
    "        raise Exception('objects of this class are not displayable')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "@displayable\n",
    "class C:\n",
    "    def display(self):\n",
    "        return 'C'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The expected behavior can be seen in the example below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "objects of this class are not displayable\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    @displayable\n",
    "    class D:\n",
    "        def method(self):\n",
    "            pass\n",
    "except Exception as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Use Cases"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "As illustrated above, decorators are a reusable way to analyze, log, associate, or transform a function, method, or class by adding just one line to their definition. The original motivating use case, as well as a few others, are reviewed below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Adding Logging to an API"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Logging is a compelling use case for decorators because it illustrates how they can save significant time and effort. To review: you have a large API and need to log the inputs and outputs of every API call. The simple API below can act as a placeholder or this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "class Database:\n",
    "    def __init__(self):\n",
    "        self.data = []\n",
    "    \n",
    "    def insert(self, entry):\n",
    "        data.append(entry)\n",
    "        return True\n",
    "\n",
    "    def find(self, entry):\n",
    "        return entry in self.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " One approach you can take is to implement a single decorator that you will reuse for every method in the API implementation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "log = []\n",
    "\n",
    "def logged(f):\n",
    "\n",
    "    def logged_f(db, inp):\n",
    "        outp = f(db, inp)\n",
    "        log.append({'method':f.__name__, 'in':inp, 'out':outp})\n",
    "        return outp\n",
    "\n",
    "    return logged_f"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "You can add the decorator before every public method definition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "class Database:\n",
    "    def __init__(self):\n",
    "        self.data = []\n",
    "\n",
    "    @logged\n",
    "    def insert(self, entry):\n",
    "        self.data.append(entry)\n",
    "        return True\n",
    "\n",
    "    @logged\n",
    "    def find(self, entry):\n",
    "        return entry in self.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Below is what you might see in the log after a few API calls are made."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'method': 'insert', 'in': 'alice', 'out': True},\n",
       " {'method': 'find', 'in': 'alice', 'out': True},\n",
       " {'method': 'find', 'in': 'bob', 'out': False}]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db = Database()\n",
    "db.insert('alice')\n",
    "db.find('alice')\n",
    "db.find('bob')\n",
    "\n",
    "log"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "As an exercise, you may want to try writing a *single* decorator for an entire class definition in order to avoid adding a decorator to every function. You may find the [built-in function `dir`](https://docs.python.org/3/library/functions.html#dir) useful for this purpose."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Defining Hooks, Extensions, and Event Handlers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Decorators are used in a number of popular libraries, such as [Flask](https://flask.palletsprojects.com/). In the example below drawn from the Flask documentation, Flask is used to set up an HTTP server with a single route. The function that handles processing of a requests and the construction of a response is associated with that event using a decorator provided by the Flask API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from flask import Flask\n",
    "app = Flask(__name__)\n",
    "\n",
    "@app.route('/')\n",
    "def hello_world():\n",
    "    return 'Hello, World!'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Note that the decorator is itself a method, and also that it is technically higher-order (in that it takes an argument consisting of the route path and returns a decorator that is then applied to the function being defined)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Analyzing or Measuring Functions/Methods"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "As illustrated in the example with the class decorator `displayable`, decorators can be used to implement static or dynamic analyses of functions, methods, and classes. A static analysis might only examine its input function/class (or the code inside it) at the time of the definition *without* actually running the code or modifying the function/class itself. A dynamic analysis might run the code itself or it might modify the code to measure its own operation in some way. Because you have already seen an example of the former, examples of the latter are presented below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "For the first example, suppose you want to test that a method always returns positive outputs in a range of inputs. The decorator definition below illustrates one way that this can be accomplished."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def check(f):\n",
    "\n",
    "    # Run some tests on `f`.\n",
    "    for x in range(-10,11):\n",
    "        if f(x) < 0:\n",
    "            raise ValueError('incorrect negative output')\n",
    "\n",
    "    # Do not modify the original function.\n",
    "    return f\n",
    "\n",
    "@check\n",
    "def square(x):\n",
    "    return x * x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "For the second example, consider a situation in which you want to check the running time of various methods. You can use decorators in conjunction with the built-in `time` package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def timed(f):\n",
    "\n",
    "    from time import time\n",
    "    def time_f():\n",
    "        ts = time()\n",
    "        result = f()\n",
    "        te = time()\n",
    "        print(f.__name__ + ':', te-ts, 'seconds')\n",
    "        return result\n",
    "\n",
    "    return time_f"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The example below demonstrates how the `timed` decorator defined above might be used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "work: 1.0003864765167236 seconds\n"
     ]
    }
   ],
   "source": [
    "@timed\n",
    "def work():\n",
    "    from time import sleep\n",
    "    sleep(1)\n",
    "work()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "One issue that might arise when an analyzing functions in this way, especially when you are stacking decorators, is that the decorated function will not preserve the original function's metadata."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'time_f'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "work.__name__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To avoid this, you can use the built-in high-order function [`wraps`](https://docs.python.org/3/library/functools.html#functools.wraps) function (which can itself be used as a decorator) found in the built-in [functools](https://docs.python.org/3/library/functools.html) library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def decorated(f):\n",
    "\n",
    "    from functools import wraps\n",
    "    @wraps(f)\n",
    "    def decorated_f():\n",
    "        return f()\n",
    "\n",
    "    return decorated_f"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Using `wraps` as in the above example ensures the metadata of the original function is preserved."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'f'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@decorated\n",
    "def f():\n",
    "    pass\n",
    "\n",
    "f.__name__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Further Reading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Hopefully, this article leaves you with a better understanding of how decorators are a syntactically convenient way to use higher-order functions and helps you recognize some of the situations for which they may be well-suited in your own work. There are many other compelling use cases for both higher-order functions and decorators, some of which may be covered in future articles. For a more comprehensive resource on decorators, you may want to look at the [Python Wiki](https://wiki.python.org/moin/PythonDecorators3). To learn more about the history of the feature, you can review the [Python Enhancement Proposal](https://www.python.org/dev/peps/pep-0318/) for this feature."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}