decorators-tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copyright 2016 Google Inc. All Rights Reserved.\n",
    "\n",
    "Licensed under the Apache License, Version 2.0 (the \"License\");\n",
    "you may not use this file except in compliance with the License.\n",
    "You may obtain a copy of the License at\n",
    "\n",
    "    http://www.apache.org/licenses/LICENSE-2.0\n",
    "\n",
    "Unless required by applicable law or agreed to in writing, software\n",
    "distributed under the License is distributed on an \"AS IS\" BASIS,\n",
    "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
    "See the License for the specific language governing permissions and\n",
    "limitations under the License."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h1 id=\"tocheading\">Table of Contents</h1>\n",
    "<div id=\"toc\"></div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "// From https://github.com/kmahelona/ipython_notebook_goodies\n",
       "$.getScript('https://kmahelona.github.io/ipython_notebook_goodies/ipython_notebook_toc.js')"
      ],
      "text/plain": [
       "<IPython.core.display.Javascript object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%javascript\n",
    "// From https://github.com/kmahelona/ipython_notebook_goodies\n",
    "$.getScript('https://kmahelona.github.io/ipython_notebook_goodies/ipython_notebook_toc.js')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Basics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There's lots of guides out there on decorators ([this](http://thecodeship.com/patterns/guide-to-python-function-decorators/) one is good), but I was never really sure when I would need to use decorators. Hopefully this will help motivate them a little more. Here I hope to show you:\n",
    "\n",
    "* When decorators might come in handy\n",
    "* How to write one\n",
    "* How to generalize using `*args` and `**kwargs` sorcery. \n",
    "\n",
    "You should read this if:\n",
    "\n",
    "* You've heard of decorators and want to know more about them, and/or\n",
    "* You want to know what `*args` and `**kwargs` mean.\n",
    "\n",
    "If you're here just for `*args` and `**kwargs`, start reading [here](#args)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Motivation\n",
    "\n",
    "Let's say you're defining methods on numbers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def add(n1, n2):\n",
    "    return n1 + n2\n",
    "\n",
    "def multiply(n1, n2):\n",
    "    return n1 * n2\n",
    "\n",
    "def exponentiate(n1, n2):\n",
    "    \"\"\"Raise n1 to the power of n2\"\"\"\n",
    "    import math\n",
    "    return math.pow(n1, n2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well, we only want these functions to work if both inputs are numbers. So we could do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def is_number(n):\n",
    "    \"\"\"Return True iff n is a number.\"\"\"\n",
    "    # A number can always be converted to a float\n",
    "    try:\n",
    "        float(n)\n",
    "        return True\n",
    "    except ValueError:\n",
    "        return False\n",
    "    \n",
    "def add(n1, n2):\n",
    "    if not (is_number(n1) and is_number(n2)):\n",
    "        print(\"Arguments must be numbers!\")\n",
    "        return\n",
    "    return n1 + n2\n",
    "\n",
    "def multiply(n1, n2):\n",
    "    if not (is_number(n1) and is_number(n2)):\n",
    "        print(\"Arguments must be numbers!\")\n",
    "        return\n",
    "    return n1 * n2\n",
    "\n",
    "def exponentiate(n1, n2):\n",
    "    \"\"\"Raise n1 to the power of n2\"\"\"\n",
    "    if not (is_number(n1) and is_number(n2)):\n",
    "        print(\"Arguments must be numbers!\")\n",
    "        return\n",
    "    import math\n",
    "    return math.pow(n1, n2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But this is yucky: we had to copy and paste code. This should always make you sad! For example, what if you wanted to change the message slightly? Or to return an error instead? You'd have to change it everywhere it appears... \n",
    "\n",
    "We want the copy & pasted code to live in just one place, so any changes just go there (DRY code: Don't Repeat Yourself). So let's **refactor**. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def validate_two_arguments(n1, n2):\n",
    "    \"\"\"\n",
    "    Returns True if n1 and n2 are both numbers.\n",
    "    \"\"\"\n",
    "    if not (is_number(n1) and is_number(n2)):\n",
    "        return False\n",
    "    return True\n",
    "\n",
    "def add(n1, n2):\n",
    "    if validate_two_arguments(n1, n2):\n",
    "        return n1 + n2\n",
    "\n",
    "def multiply(n1, n2):\n",
    "    if validate_two_arguments(n1, n2):\n",
    "        return n1 * n2\n",
    "\n",
    "def exponentiate(n1, n2):\n",
    "    \"\"\"Raise n1 to the power of n2\"\"\"\n",
    "    if validate_two_arguments(n1, n2):\n",
    "        import math\n",
    "        return math.pow(n1, n2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is definitely better. But there's still some repeated logic. Like, what if we want to return an error if we don't get numbers, or print something before running the code? We'd still have to make the changes in multiple places. The code isn't DRY. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic decorators\n",
    "\n",
    "We can refactor further with the **decorator pattern**.\n",
    "\n",
    "We want to write something that looks like\n",
    "    \n",
    "    @decorator\n",
    "    def add(n1, n2):\n",
    "        return n1 + n2\n",
    "\n",
    "so that all the logic about validating `n1` and `n2` lives in one place, and the functions just do what we want them to do. \n",
    "        \n",
    "Since the @ syntax just means `add = decorator(add)`, we know the decorator needs to take a function as an argument, and it needs to return a function. (This should be confusing at first. Functions returning functions are scary, but think about it until that doesn't seem outlandish to you.)\n",
    "\n",
    "This returned function should act the same way as `add`, so it should take two arguments. And within this returned function, we want to first check that the arguments are numbers. If they are, we want to call the original function that we decorated (in this case, `add`). If not, we don't want to do anything. Here's what that looks like (there's a lot here, so use the comments to understand what's happening):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# The decorator: takes a function.\n",
    "def validate_arguments(func):\n",
    "    # The decorator will be returning wrapped_func, a function that has the \n",
    "    # same signature as add, multiply, etc.\n",
    "    def wrapped_func(n1, n2):\n",
    "        # If we don't have two numbers, we don't want to run the function. \n",
    "        # Best practice (\"be explicit\") is to raise an error here \n",
    "        # instead of just returning None.\n",
    "        if not validate_two_arguments(n1, n2):\n",
    "            raise Exception(\"Arguments must be numbers!\")\n",
    "        # We've passed our checks, so we can call the function with the passed in arguments.\n",
    "        # If you like, think of this as\n",
    "        #   result = func(n1, n2)\n",
    "        #   return result\n",
    "        # to distinguish it from the outer return where we're returning a function.\n",
    "        return func(n1, n2)\n",
    "    # This is where we return the function that has the same signature.\n",
    "    return wrapped_func"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "4\n",
      "Caught Exception: Arguments must be numbers!\n"
     ]
    }
   ],
   "source": [
    "@validate_arguments\n",
    "def add(n1, n2):\n",
    "    return n1 + n2\n",
    "# Don't forget, the @ syntax just means\n",
    "# add = validate_decorator(add)\n",
    "\n",
    "print(add(1, 3))\n",
    "try:\n",
    "    add(2, 'hi')\n",
    "except Exception as e:\n",
    "    print(\"Caught Exception: {}\".format(e))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This pattern is nice because we've even refactored out all the validation logic (even the \"if blah then blah\" part) into the decorator. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generalizing with \\*args and \\**kwargs\n",
    "\n",
    "What if we want to validate a function that has a different number of arguments?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "wrapped_func() takes exactly 2 arguments (3 given)",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-7-81f3a3cf6ada>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      3\u001b[0m     \u001b[0;32mreturn\u001b[0m \u001b[0mn1\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mn2\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mn3\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      4\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 5\u001b[0;31m \u001b[0madd3\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m2\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m3\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m: wrapped_func() takes exactly 2 arguments (3 given)"
     ]
    }
   ],
   "source": [
    "@validate_arguments  # Won't work!\n",
    "def add3(n1, n2, n3):\n",
    "    return n1 + n2 + n3\n",
    "\n",
    "add3(1, 2, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can't decorate this because the wrapped function expects 2 arguments. \n",
    "\n",
    "Here's where we use the `*` symbol. I'll write out the code so you can see how it looks, and we'll look at what `*args` is doing below. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# The decorator: takes a function.\n",
    "def validate_arguments(func):\n",
    "    # Note the *args! Think of this as representing \"as many arguments as you want\". \n",
    "    # So this function will take an arbitrary number of arguments.\n",
    "    def wrapped_func(*args):\n",
    "        # We just want to apply the check to each argument.\n",
    "        for arg in args:\n",
    "            if not is_number(arg):\n",
    "                raise Exception(\"Arguments must be numbers!\")\n",
    "        # We also want to make sure there's at least two arguments.\n",
    "        if len(args) < 2:\n",
    "            raise Exception(\"Must specify at least 2 arguments!\")\n",
    "        \n",
    "        # We've passed our checks, so we can call the function with the \n",
    "        # passed-in arguments.\n",
    "        # Right now, args is a tuple of all the different arguments passed in \n",
    "        # (more explanation below), so we want to expand them back out when \n",
    "        # calling the function.\n",
    "        return func(*args)\n",
    "    return wrapped_func"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@validate_arguments  # This works\n",
    "def add3(n1, n2, n3):\n",
    "    return n1 + n2 + n3\n",
    "\n",
    "add3(1, 2, 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "15\n",
      "45\n"
     ]
    }
   ],
   "source": [
    "@validate_arguments  # And so does this\n",
    "def addn(*args):\n",
    "    \"\"\"Add an arbitrary number of numbers together\"\"\"\n",
    "    cumu = 0\n",
    "    for arg in args:\n",
    "        cumu += arg\n",
    "    return cumu\n",
    "print(addn(1, 2, 3, 4, 5))\n",
    "# range(n) gives a list, so we expand the list into positional arguments...\n",
    "print(addn(*range(10)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='args'>`*args`</a>\n",
    "What is this `*` nonsense?\n",
    "\n",
    "You've probably seen `*args` and `**kwargs` in documentation before. Here's what they mean:\n",
    "\n",
    "* When calling a function, `*` **expands an iterable** into **positional arguments**. \n",
    "    * Terminology note: in a call like `bing(1, 'hi', name='fig')`, `1` is the first positional argument, `'hi'` is the second positional argument, and there's a keyword argument `'name'` with the value `'fig'`.\n",
    "* When defining a signature, `*args` represents an **arbitrary number of positional arguments**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First call:\n",
      "foo args: (1, 2, 'a', 3, True)\n",
      "foo args type: <type 'tuple'>\n",
      "\n",
      "Second call:\n",
      "foo args: (1, 2, 'a', 3, True)\n",
      "foo args type: <type 'tuple'>\n"
     ]
    }
   ],
   "source": [
    "def foo(*args):\n",
    "    print(\"foo args: {}\".format(args))\n",
    "    print(\"foo args type: {}\".format(type(args)))\n",
    "    \n",
    "# So foo can take an arbitrary number of arguments\n",
    "print(\"First call:\")\n",
    "foo(1, 2, 'a', 3, True)\n",
    "\n",
    "# Which can be written using the * syntax to expand an iterable\n",
    "print(\"\\nSecond call:\")\n",
    "l = [1, 2, 'a', 3, True]\n",
    "foo(*l)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Back to the decorator\n",
    "(If you're just here for \\*args and \\*\\*kwargs, skip down to [here](#kwargs))\n",
    "\n",
    "So let's look at the decorator code again, minus the comments:\n",
    "\n",
    "    def validate_decorator(func):\n",
    "        def wrapped_func(*args):\n",
    "            for arg in args:\n",
    "                if not is_number(arg):\n",
    "                    print(\"arguments must be numbers!\")\n",
    "                    return\n",
    "            return func(*args)\n",
    "        return wrapped_func\n",
    "        \n",
    "* `def wrapped_func(*args)` says that `wrapped_func` can take an arbitrary number of arguments.\n",
    "* Within `wrapped_func`, we interact with `args` as a tuple containing all the (positional) arguments passed in. \n",
    "* If all the arguments are numbers, we call `func`, the function we decorated, by **expanding** the `args` tuple back out into positional arguments: `func(*args)`.\n",
    "* Finally the decorator needs to return a function (remember that the `@` syntax is just sugar for `add = decorator(add)`.\n",
    "\n",
    "Congrats, you now understand decorators! You can do tons of other stuff with them, but hopefully now you're equipped to read the other guides online. \n",
    "\n",
    "---\n",
    "\n",
    "### <a id='kwargs'>As for `**kwargs`:</a> \n",
    "* When calling a function, `**` **expands a dict** into **keyword arguments**.\n",
    "* When defining a signature, `**kwargs` represents an **arbitrary number of keyword arguments**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First call:\n",
      "bar kwargs: {'age': None, 'location': 'US-PAO', 'ldap': 'awan'}\n",
      "\n",
      "Second call:\n",
      "bar kwargs: {'age': None, 'location': 'US-PAO', 'ldap': 'awan'}\n"
     ]
    }
   ],
   "source": [
    "def bar(**kwargs):\n",
    "    print(\"bar kwargs: {}\".format(kwargs))\n",
    "\n",
    "# bar takes an arbitrary number of keyword arguments\n",
    "print(\"First call:\")\n",
    "bar(location='US-PAO', ldap='awan', age=None)\n",
    "\n",
    "# Which can also be written using the ** syntax to expand a dict\n",
    "print(\"\\nSecond call:\")\n",
    "d = {'location': 'US-PAO', 'ldap': 'awan', 'age': None}\n",
    "bar(**d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And in case your head doesn't hurt yet, we can do both together:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First call:\n",
      "baz args: (1, 3, 'hi'). kwargs: {'age': 37, 'name': 'Joe', 'occupation': 'Engineer'}\n",
      "\n",
      "Second call:\n",
      "baz args: (1, 3, 'hi'). kwargs: {'age': 37, 'name': 'Joe', 'occupation': 'Engineer'}\n"
     ]
    }
   ],
   "source": [
    "def baz(*args, **kwargs):\n",
    "    print(\"baz args: {}. kwargs: {}\".format(args, kwargs))\n",
    "    \n",
    "# Calling baz with a mixture of positional and keyword arguments\n",
    "print(\"First call:\")\n",
    "baz(1, 3, 'hi', name='Joe', age=37, occupation='Engineer')\n",
    "\n",
    "# Which is the same as\n",
    "print(\"\\nSecond call:\")\n",
    "l = [1, 3, 'hi']\n",
    "d = {'name': 'Joe', 'age': 37, 'occupation': 'Engineer'}\n",
    "baz(*l, **d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# Advanced decorators\n",
    "\n",
    "This section will introduce some of the many other useful ways you can use decorators. We'll talk about\n",
    "* Passing arguments into decorators\n",
    "* `functools.wraps`\n",
    "* Returning a different function\n",
    "* Decorators and objects.\n",
    "\n",
    "Use the [table of contents](#toc) at the top to make it easier to look around.\n",
    "\n",
    "## Decorators with arguments\n",
    "\n",
    "A common thing to want to do is to do some kind of configuration in a decorator. For example, let's say we want to define a `divide_n` method, and to make it easy to use we want to hide the existence of integer division. Let's define a decorator that converts arguments into floats."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def convert_arguments(func):\n",
    "    \"\"\"\n",
    "    Convert func arguments to floats.\n",
    "    \"\"\"\n",
    "    # Introducing the leading underscore: (weakly) marks a private \n",
    "    # method/property that should not be accessed outside the defining\n",
    "    # scope. Look up PEP 8 for more. \n",
    "    def _wrapped_func(*args):\n",
    "        new_args = [float(arg) for arg in args]\n",
    "        return func(*new_args)\n",
    "    return _wrapped_func\n",
    "\n",
    "@convert_arguments\n",
    "@validate_arguments\n",
    "def divide_n(*args):\n",
    "    cumu = args[0]\n",
    "    for arg in args[1:]:\n",
    "        cumu = cumu / arg\n",
    "    return cumu"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6.4375"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# The user doesn't need to think about integer division!\n",
    "divide_n(103, 2, 8)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But now let's say we want to define a `divide_n_as_integers` function. We could write a new decorator, or we could alter our decorator so that we can specify what we want to convert the arguments to. Let's try the latter. \n",
    "\n",
    "(For you smart alecks out there: yes you could use the `//` operator, but you'd still have to replicate the logic in `divide_n`. Nice try.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.33333333333\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "def convert_arguments_to(to_type=float):\n",
    "    \"\"\"\n",
    "    Convert arguments to the given to_type by casting them.\n",
    "    \"\"\"\n",
    "    def _wrapper(func):\n",
    "        def _wrapped_func(*args):\n",
    "            new_args = [to_type(arg) for arg in args]\n",
    "            return func(*new_args)\n",
    "        return _wrapped_func\n",
    "    return _wrapper\n",
    "\n",
    "\n",
    "@validate_arguments\n",
    "def divide_n(*args):\n",
    "    cumu = args[0]\n",
    "    for arg in args[1:]:\n",
    "        cumu = cumu / arg\n",
    "    return cumu\n",
    "\n",
    "\n",
    "@convert_arguments_to(to_type=int)\n",
    "def divide_n_as_integers(*args):\n",
    "    return divide_n(*args)\n",
    "\n",
    "\n",
    "@convert_arguments_to(to_type=float)\n",
    "def divide_n_as_float(*args):\n",
    "    return divide_n(*args)\n",
    "\n",
    "\n",
    "print(divide_n_as_float(7, 3))\n",
    "print(divide_n_as_integers(7, 3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Did you notice the tricky thing about creating a decorator that takes arguments? **We had to create a function to \"return a decorator\".** The outermost function, `convert_arguments_to`, returns a function that takes a function, which is what we've been calling a \"decorator\". \n",
    "\n",
    "To think about why this is necessary, let's start from the form that we wanted to write, and unpack from there. We wanted to be able to do:\n",
    "\n",
    "    @decorator(decorator_arg)\n",
    "    def myfunc(*func_args):\n",
    "        pass\n",
    "        \n",
    "Unpacking the syntactic sugar gives us\n",
    "\n",
    "    def myfunc(*func_args): \n",
    "       pass\n",
    "    myfunc = decorator(decorator_arg)(myfunc)\n",
    "      \n",
    "Written this way, it should immediately be clear that `decorator(decorator_arg)` **returns a function that takes a function**. \n",
    "\n",
    "So that's how you write a decorator that takes an argument: it actually has to be a function that takes your decorator arguments, and returns a function that takes a function. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## functools.wraps\n",
    "If you've played around with the examples above, you might've seen that the name of the wrapped function changes after you apply a decorator... And perhaps more importantly, the docstring of the wrapped function changes too (this is important for when generating documentation, e.g. with Sphinx). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "wrapped_func\n",
      "None\n"
     ]
    }
   ],
   "source": [
    "@validate_arguments\n",
    "def foo(*args):\n",
    "    \"\"\"foo frobs bar\"\"\"\n",
    "    pass\n",
    "\n",
    "\n",
    "print(foo.__name__)\n",
    "print(foo.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[`functools.wraps`](https://docs.python.org/2/library/functools.html#functools.wraps) solves this problem. Use it as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "bar\n",
      "bar frobs foo\n"
     ]
    }
   ],
   "source": [
    "from functools import wraps\n",
    "\n",
    "def better_validate_arguments(func):\n",
    "    @wraps(func)\n",
    "    def wrapped_func(*args):\n",
    "        for arg in args:\n",
    "            if not is_number(arg):\n",
    "                raise Exception(\"Arguments must be numbers!\")\n",
    "        if len(args) < 2:\n",
    "            raise Exception(\"Must specify at least 2 arguments!\")\n",
    "        return func(*args)\n",
    "    return wrapped_func\n",
    "\n",
    "\n",
    "@better_validate_arguments\n",
    "def bar(*args):\n",
    "    \"\"\"bar frobs foo\"\"\"\n",
    "    pass\n",
    "\n",
    "\n",
    "print(bar.__name__)\n",
    "print(bar.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Think of the `@wraps` decorator making it so that `wrapped_func` knows what function it originally wrapped. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Returning a different function\n",
    "\n",
    "Decorators don't even have to return the function that's passed in. You can have some fun with this..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\"Not the droid you're looking for\""
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def jedi_mind_trick(func):\n",
    "    def _jedi_func():\n",
    "        return \"Not the droid you're looking for\"\n",
    "    return _jedi_func\n",
    "\n",
    "    \n",
    "@jedi_mind_trick\n",
    "def get_droid():\n",
    "    return \"Found the droid!\"\n",
    "\n",
    "\n",
    "get_droid()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But more seriously, this can be useful for things like\n",
    "\n",
    "* Authentication: you don't want to return the function if the user isn't recognized, instead redirecting to a login page (e.g. you could check an environment variable)\n",
    "* Disabling test methods when deployed to a production environment\n",
    "\n",
    "This is also how `@unittest.skip` works, if you've ever used it to skip functions that weren't ready for testing or couldn't be tested on a particular operating system. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Objects\n",
    "### Decorators that alter \"self\"\n",
    "### Decorating a class"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}