1.7.2_decorators.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python decorators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This course is about a feature in python called \"decorators\". We use it to \"decorate\" functions or classes (we will see what that means).\n",
    "\n",
    "They can be very convenient, but use them with care because they can also make your code less readable. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Function decorators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### A misleading name\n",
    "\n",
    "The name \"decorator\" is a bit misleading.\n",
    "\n",
    "Decorating a function means: \"**adding a feature to that function**\". \n",
    "\n",
    "Let's see how it looks with a basic example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calling function whose name is : my_function\n",
      "Calling my function\n"
     ]
    }
   ],
   "source": [
    "def print_function_name(decorated_function): #decorator that just prints the name of the decorated function\n",
    "    print (\"Calling function whose name is : \" + decorated_function.__name__)\n",
    "    return decorated_function\n",
    "\n",
    "@print_function_name #tell python to decorate \"my_function\" using the decorator \"print_function_name\"\n",
    "def my_function():  #declaring a function that just prints a log\n",
    "    print \"Calling my function\"\n",
    "    \n",
    "\n",
    "my_function()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Explanation\n",
    "\n",
    "Pretty simple is it ?\n",
    "\n",
    "Let's just say few words about what just happened:\n",
    "\n",
    "1. A decorator just look like a function, actually *it is a function*. But to be decorator able to \"decorate\" another function there are two requirements:\n",
    "    - A decorator **take a function as input parameter** (it is the function it is decorating)\n",
    "    - A decorator **returns a function**\n",
    "\n",
    "2. The syntax **\"@\" + \"decorator_name\"** is **the** python syntax to **decorate** a function. \n",
    "Writing that syntax before a function declaration basically means : **Replace \"my_function()\"** by **decorator_name(my_function)()**.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercises:\n",
    "- See what happens when you decorate a function with parameters\n",
    "- See what happens when the decorator do not return a function\n",
    "- See what happens when the decorator do not have input parameters\n",
    "- See what happens when the decorator has got many input parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### When using it\n",
    "\n",
    "As you just noticed, the consequence of \"decorating\" a function is: \"every time you call that function,  there is another function implicitly called behind the scene\".\n",
    "\n",
    "And we've just seen a very convenient use case: \"printing a log\". Yes that's right, sometimes when you debug a huge code, you know where and when and where the function is used at \"run time\".\n",
    "\n",
    "In that use case, you want to limit the impact in the source code, (you don't want to find and replace every call of your function by a call to another function that prints a log, trust me you don't...).\n",
    "\n",
    "You could also write the log *inside* the function to get the same result. But that means you have to make the same in every function you want to trace.\n",
    "I find decorating every function I want to trace much more convenient."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bonus code\n",
    "\n",
    "Here is a decorator that prints the function name and the parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calling function: my_function_with_parameters\n",
      "With parameters: \n",
      "('a', 'b', 'c') {}\n",
      "Inside my_function_with_parameters\n",
      "\n",
      "Calling function: my_other_function_with_parameters\n",
      "With parameters: \n",
      "('a', 'b', 'c', 'd', 'e') {}\n",
      "Inside my_other_function_with_parameters\n"
     ]
    }
   ],
   "source": [
    "def print_function_and_parameters(decorated_function): \n",
    "    def print_parameters(*args, **kwargs):\n",
    "        print (\"Calling function: \" + decorated_function.__name__)\n",
    "        print (\"With parameters: \")\n",
    "        print args, kwargs\n",
    "        decorated_function(*args, **kwargs)\n",
    "    return print_parameters\n",
    "\n",
    "@print_function_and_parameters\n",
    "def my_function_with_parameters(a, b, c):\n",
    "    print \"Inside my_function_with_parameters\"\n",
    "    \n",
    "@print_function_and_parameters\n",
    "def my_other_function_with_parameters(a, b, c, d, e):\n",
    "    print \"Inside my_other_function_with_parameters\"\n",
    "\n",
    "    \n",
    "my_function_with_parameters(\"a\", \"b\", \"c\")\n",
    "print \"\"\n",
    "my_other_function_with_parameters(\"a\", \"b\", \"c\", \"d\", \"e\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### When NOT using decorators\n",
    "\n",
    "As we just see, the implicit call of *another decorating function* behind the scenes, can be very convenient. But the sideback is: \"*it implicitly calling another function behind the scenes*\".\n",
    "\n",
    "Yes you are not getting me wrong: the sideback is the same sentence as the advantage.\n",
    "\n",
    "The point is: don't use decorators to implement treatments that you don't want to make \"invisible\" from the point of view of the code that is calling the function.\n",
    "\n",
    "For instance, if you want the the decorator to \"*modify variables*\" or \"make a *big computation*\", this is **usually a bad idea** because that makes a code that is difficult to debug, and whose behavious is difficult to predict.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### One more use case: \n",
    "\n",
    "This is an exercise for you:\n",
    "Make a decorator that counts the time a function needed to execute.\n",
    "\n",
    "I provide you some timing functions you might want to use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.00239300728\n"
     ]
    }
   ],
   "source": [
    "from time import *\n",
    "\n",
    "current_time = time()\n",
    "sleep(2)\n",
    "time_after_computation = time()\n",
    "print (time_after_computation - current_time)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Going further: class decorators\n",
    "\n",
    "This is considered as an advanced feature of python. In my experience, you can find on the internet code samples for almost any of the good use cases you might need.\n",
    "\n",
    "Just \"*fly with your own wings*\". For example, if you know what is a \"Singleton\" you can find a very elegant implementation of that design pattern using \"class decorators\".\n",
    "\n",
    "You might want to execute all the functions of a class in a separate thread etc...\n",
    "\n",
    "It is not that I am being lazy, I just believe that if you are a skilled enough coder to consider doing these things, I trust you, you can find everything you need by yourself on the internet !\n",
    "\n",
    "Enjoy your coding !"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}