1.7.3_class_and_magic_functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Make it classy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Hey there, this lesson is about **Object Oriented Programming**. Here I wanna give you an intuition about what it is and the way to use it in Python.\n",
    "\n",
    "You are already familiar with functions, are you ?\n",
    "Functions are meant create **blocks of code** in order to use it many times at different places in your code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def say_hello(*names):\n",
    "    for name in names:\n",
    "        print (\"Hello {}\".format(name))\n",
    "        \n",
    "say_hello(\"Anne-Sophie\", \"Bob\", \"Wang Xiaoming\", \"Mohammed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions are difficult to design because you need to make many decisions:\n",
    "- What should be their return value\n",
    "- What should be their parameters\n",
    "- What should be inside or outside the function\n",
    "- What do I want to do anyway ? (yes, yes, sometimes you end up not being able to answer that question in a \"not confusing way\") \n",
    "\n",
    "\n",
    "It takes a lot of thinking and experience to have a good *intuition* about these questions.\n",
    "\n",
    "There is no shortcut to that, good software engineering requires practice trials and a lot of errors before one can make things all right.\n",
    "\n",
    "As a matter of fact, \"object oriented programming\" is actually very likely to make things even more *complicated* if you don't use it right.\n",
    "\n",
    "However, if you do understand the right way to design your code. It is a very powerful tool.\n",
    "\n",
    "Let me give you a \"bonus advise\": \n",
    "\n",
    "*When facing a topic that seems complicated ensure you clearly set up in your mind what is the problem we are trying to solve.*\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Classify your code\n",
    "\n",
    "As a newbie, you may not feel like you need that. But...\n",
    "\n",
    "When you do coding, you may spend a lot of time writing **tens of functions**. You *re-write correct and move* your functions *so many times* that you end up *forgetting* about \"*big picture*\" of what you are trying to do.\n",
    "\n",
    "First step to understand object oriented programming is to *feel the need* to **classify** your functions.\n",
    "This is (partly) what classes are about.\n",
    "\n",
    "*(You may argue that you can do the same with \"modules\" (write code in different files... you know...). You make a point, but as you will see classes do more than that, and even if not, sometimes modules get so big that they need to be subdivided...)\n",
    "\n",
    "Example:\n",
    "In few weeks (or months) you may wanna start coding a machine learning project, even before starting to code here is how I would **classify** my functions:"
   ]
  },
  {
   "attachments": {
    "class_in_python.png": {
     "image/png": "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"
    }
   },
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![class_in_python.png](attachment:class_in_python.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class CustomData:\n",
    "    \"\"\"Some class that represent structured the data we may want to put in our database\"\"\"\n",
    "    pass\n",
    "\n",
    "class DataBaseAccess:\n",
    "    \"\"\"Group all the functions that \"access\" your database here\n",
    "    Many existing tools are able to query a database, \n",
    "    but here you will \"pre-write\" the requests you will often need in your application\n",
    "    \"\"\"\n",
    "    # Write a lot of smartly designed code here[...]\n",
    "    pass\n",
    "\n",
    "class DataMining:\n",
    "    \"\"\"Group all the functions that \"mine data\" here.\n",
    "    data mining means filtering and transforming raw data downloaded on the web into valuable information\n",
    "    \"\"\"\n",
    "    # Write a lot of smartly designed code here[...]\n",
    "    pass\n",
    "\n",
    "\n",
    "class DataPreprocessing:\n",
    "    \"\"\"Group all the functions that do your preprocessing here.\n",
    "    preprocessing means transforming your \"mined data\" into inputs for your neural network\n",
    "    \"\"\"\n",
    "    # Write a lot of smartly designed code here[...]\n",
    "    pass\n",
    "\n",
    "\n",
    "class NeuralNetwork:\n",
    "    \"\"\"Group all the functions that do your machine learning here.\n",
    "    follow the rest of this course carefully to understand this part\n",
    "    \"\"\"\n",
    "    # Write a lot of smartly designed code here[...]\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you have carefully designed your classes and functions that do \"the specialized jobs\", well designed code should allow you to write a short code that contains \"**the big picture**\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# construct an \"object\" of class DataBaseAccess (don't worry I will explain it later)\n",
    "databaseAccessor = DataBaseAccess()\n",
    "\n",
    "if (databaseAccessor.doIhaveNewData() is True): # read the data to see if I need to read you data\n",
    "    # use the \"databaseAccessor\" to download freshly processed data \n",
    "    my_new_data = databaseAccessor.readTheNewData()\n",
    "\n",
    "#create a miner and use it to mine new data\n",
    "dataMiner = DataMining()\n",
    "mined_data = dataMiner.mineData(my_new_data)\n",
    "\n",
    "#store the mined data so I don't have to re-mine it again later (mining data is a long operation)\n",
    "databaseAccessor.storedMinedData(mined_data)\n",
    "\n",
    "#preprocess that new data\n",
    "dataPreprocessor = DataPreprocessing()\n",
    "preprocessed_data = dataPreprocessor.mineData(mined_data)\n",
    "\n",
    "\n",
    "neuralNetwork = NeuralNetwork()\n",
    "neuralNetwork.configure() #TODO configure your neural network setting the number of neurons and layers for instance\n",
    "\n",
    "neuralNetwork.train(preprocessed_data)\n",
    "\n",
    "#now the model is trained ! "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This quick piece of code may look confusing to you if you are not familiar with \"classes\" and \"objects\". But keep reading you are soon gonna be an expert at this !\n",
    "\n",
    "But that's cool is it ? It just took me few lines to write \"the big picture\" of some bad ass project (I recommend you spend a minute reading it, it's actually not that bad...).\n",
    "\n",
    "Don't celebrate too quickly however : I have good and bad news.\n",
    "- Bad news is: the big picture is always the **easiest** thing to design, because it is the way our mind thinks. You are gonna spend most of your time and efforts writing the code inside the classes that make the \"big picture look easy\".\n",
    "- Good news is: if your *design is good* you may ask *someone else* to write one of the classes for you. It also helps you find the right search terms for google ;)\n",
    "- Other good news: it is alright to do easy things first, actually good software design requires that your code stay tidy in your mind and in the mind of people who mayread your code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Classes contain functions, but also variables"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Let's go back to the example of the class DataBaseAccess. This class is a \"toolbox\" or a \"*list of functions*\" we use to read and write some database.\n",
    "\n",
    "But these functions have some \"common information\" to share such as:\n",
    "- database name\n",
    "- database ip address\n",
    "\n",
    "We gave the example of the functions: \"doIhaveNewData\", \"readTheNewData\", \"storedMinedData\".\n",
    "These three functions read/write the data on the same database.\n",
    "\n",
    "The may be structured like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class DataBaseAccess:\n",
    "    \"\"\"Group all the functions that \"access\" your database here\n",
    "    Many existing tools are able to query a database, \n",
    "    but here you will \"pre-write\" the requests you will often need in your application\n",
    "    \"\"\"\n",
    "    def __init__(self):\n",
    "        self.__database_name = \"MyOverkillMachineLearning\"\n",
    "        self.__database_ipadress = \"localhost\"\n",
    "        self.__database_accessPort = 1521 \n",
    "        #If you don't know why a database have an IP address + port, don't worry about that...\n",
    "        #Focus on the code design, keep having the \"big picture\"\n",
    "    \n",
    "    def doIhaveNewData(self):\n",
    "        pass\n",
    "    \n",
    "    def readTheNewData(self):\n",
    "        pass\n",
    "    \n",
    "    def storedMinedData(self, mined_data):\n",
    "        pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "databaseAccessor.doIhaveNewData()\n",
    "databaseAccessor.storedMinedData(mined_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice we see that mysterious \"**self**\" many times in this code. I'll explain it later, for now act as if it did not exist.\n",
    "\n",
    "Notice also I have a function \\__init__ that \"initialises\" my class with the information I want to provide. The values of the variables (we give to \"self\") are stored *inside the class instance*.\n",
    "\n",
    "\n",
    "The point here is to understand that we want some \"**shared information**\" we set up \"**once**\" in such way that all the functions *inside the class* can access it.\n",
    "\n",
    "If you don't see why do you need that. Imagine would it look like otherwise. Everytime you call your function:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "doIhaveNewData(\"MyOverkillMachineLearning\", \"localhost\", 1521)\n",
    "#[...]\n",
    "storedMinedData(\"MyOverkillMachineLearning\", \"localhost\", 1521, mined_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How do you like it ?\n",
    "\n",
    "Even if you like coding I am pretty sure you won't like *repeating* the typing of the same values again and again. \n",
    "\n",
    "Even if you copy paste and spend few effort on that repetition I do believe that it is easier to read when there is less text."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code with classes is **simpler and makes more sense**.\n",
    "\n",
    "Classes are a set of functions grouped together.\n",
    "\n",
    "But these \"grouped\" functions may share some information. We usually store this information in **variables**.\n",
    "\n",
    "So the variables you write inside your class are **owned** by your class (instance). These variables belong to the functions of the class and only to them. Classes give a **context** to your functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Classes vs Objects"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "That's good, we have a class DataBaseAccessor that contains functions to read and write functions like it was easy (from the point of view of the \"big picture\").\n",
    "\n",
    "All the complicated stuff about database are wrapped inside that class.\n",
    "\n",
    "But what if I had many databases and I want to use these same functions to access them? The only thing I want to change is the databases name ip and access port.\n",
    "\n",
    "I don't want to modify my existing class I still need my first database *I want both*.\n",
    "\n",
    "This is how you understand the difference between class and object. \n",
    "\n",
    "Creating an object of class DataBaseAccessor consists in using its **same functions**, with the **same variables**, but **having different values**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class DataBaseAccess:\n",
    "    def __init__(self):\n",
    "        \"\"\"Configure with some default parameters\"\"\"\n",
    "        self.__database_name = \"MyOverkillMachineLearning\"\n",
    "        self.__database_ipadress = \"localhost\"\n",
    "        self.__database_accessPort = 1521\n",
    "        pass\n",
    "    \n",
    "    def __init__(self, databaseName, ipadress, accessPort):\n",
    "        \"\"\"Configure with some other parameters\"\"\"\n",
    "        self.__database_name = databaseName\n",
    "        self.__database_ipadress = ipadress\n",
    "        self.__database_accessPort = accessPort\n",
    "\n",
    "# Here is how it looks when we use that class\n",
    "\n",
    "my_default_database = DataBaseAccess() #variable that access default database MyOverkillMachineLearning\n",
    "my_other_database = DataBaseAccess(\"MySecretDatabase\", \"localhost\", 1522) #variable accessing MySecretDatabase\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we go, we have code two variables of \"type\" DataBaseAccess (yes a class is in some way a variable type). \n",
    "\n",
    "If you want to sound like a true developper you can say: **my_default_database** and **my_other_database** are \"**instances**\" of class DataBaseAccess (which actually means exactly the same).\n",
    "\n",
    "We can also say **my_default_database** and **my_other_database** are **objects** of **class** DataBaseAccess.\n",
    "They share the same functions, but when you call a function from on object it will automatically pass the parameter of that object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "my_default_database.readTheNewData() # read the data from database \"MyOverkillMachineLearning\"\n",
    "my_other_database.readTheNewData() # read the data from database \"MySecretDatabase\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Some important vocabulary:\n",
    "\n",
    "A **class** is a **type** while **objects** are **variables** of that **type**.\n",
    "\n",
    "Now you know why it is called \"**Object** Oriented Programming\"\n",
    "\n",
    "Just a quick remark: you may have noticed that we've got \"two \\__init\\__ functions\". They have the **exact same name** but they differ by the number of parameters you pass them. \n",
    "\n",
    "Python is able to recognize which function you mean to call just by counting the number of parameters. \n",
    "Declaring many functions with the same name but with a different number of parameters is called **overloading**.\n",
    "\n",
    "The **\\__init__** function is a **python reserved function name** that (almost) always appears in class declaration. **It is automatically called just after an \"instance\" of that class is created**. \n",
    "\n",
    "Now it's time to talk about that \"mysterious **self keyword**\"."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Point to my **self**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Maybe you already guessed what is that \"self\" that appears so many times in the class definition. If you pay a close look you may even notice that it is the first parameter of every function. \n",
    "\n",
    "And if you look even more careful you may also notice that this \"self\" has dissapeared when we call the function."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "#doIhaveNewData(self): becomes \n",
    "databaseAccessor.doIhaveNewData() #when we call it\n",
    "\n",
    "#storedMinedData(self, mined_data): becomes \n",
    "databaseAccessor.storedMinedData(mined_data) #when we call it"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a way it hasn't really disapeared, it **transformed** ! Have a look !\n",
    "It is actually the **\"databaseAccessor\" that became \"self\"**!\n",
    "\n",
    "Let's have a better intuition on this.\n",
    "You remember the objects databaseAccessor and my_other_database are both instances of the same class called DataBaseAccess do you ?\n",
    "\n",
    "They have the same functions but inside the functions the values of \\__database_name is different.\n",
    "\n",
    "When python is inside your function doIhaveNewData, it kind of need some help \"to remember\" which object it is dealing with. The \"self\" is that reminder. It is some sort of \"pointer\", pointing to the memory containing the values of the variables for the current object.\n",
    "\n",
    "The very fact of writing \"**[your object name].**\" just before the name of the function is gonna give a value to \"self\", and that value is [your object]."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Make it magic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How would you do it if you were asked to add that feature on your class : \"I want to be able to add new data on that database.\"\n",
    "\n",
    "There is the obvious way and the magic way.\n",
    "\n",
    "## The obvious way\n",
    "\n",
    "I hope it is obvious to you. The right way to do that, is of course to add a new function to the class DataBaseAccess "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class CustomData:\n",
    "    \"\"\"Some class that structures the data we may want to put in our database\"\"\"\n",
    "    pass\n",
    "\n",
    "\n",
    "class DataBaseAccess:\n",
    "    \"\"\"Same as above\"\"\"\n",
    "    # all the functions I mentioned before have not changed\n",
    "    def addData(self, newData):\n",
    "        #write code to add newData in the database\n",
    "        pass\n",
    "        \n",
    "#Now let's show how to use it.\n",
    "newData = CustomData() # for now no data, it is just an example...\n",
    "my_database = DataBaseAccess()\n",
    "my_database.addData(newData)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pretty straightforward is it ?\n",
    "(I am talking about the code design of course, you may still spend a lot of effort writing a class to \"contain\" data and put it in the variable \"newData\" instead of the \"empty CustomData class\"...)\n",
    "\n",
    "But how would you like to write that: "
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "my_database = my_database + newData"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course for now it does not work. Python do not know what does that mean to add a CustomData into a DataBaseAccess.\n",
    "You need to be aware that this is what this statement is asking.\n",
    "\n",
    "But python offers some magic feature to make it work:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The magic way"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class CustomData:\n",
    "    \"\"\"Some class that structures the data we may want to put in our database\"\"\"\n",
    "    pass\n",
    "\n",
    "\n",
    "class DataBaseAccess:\n",
    "    \"\"\"Same as above\"\"\"\n",
    "    # instead of addData I want to write this\n",
    "    def __add__(self, newData):\n",
    "        # If I try to add something that is not a CustomData make the program crash\n",
    "        if isinstance(newData, CustomData) is False:\n",
    "            raise Exception(\"type {} does not fit, expect a CustomData\".format(type(newData)))\n",
    "        #write code to add newData in the database\n",
    "\n",
    "# And now you can do magic !\n",
    "my_database = my_database + newData #calls the function __add__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The only thing that had changed between this example and the previous is the name of the function: it is *\\__add\\__* instead of *addData*.\n",
    "\n",
    "The name \\__add\\__ is a *reserved* name, that means that giving that name to a function inside a class has a *special meaning*, and that *special meaning* is what we call **magic**.\n",
    "\n",
    "The magic here is that you are telling the python interpreter what is the way to add something to your object.\n",
    "In other terms, if you define that function python will replace this:\n",
    "* my_database = my_database + newData\n",
    "\n",
    "By this:\n",
    "* my_database.\\__add\\__(newData)\n",
    "\n",
    "I am not making the whole list of every magic function there is. There are magic functions for most operators you can imagine: '=', '-', '[]', '*', etc... Just google it if you need it. \n",
    "\n",
    "But do never forget to keep in mind that you only want to do things that **have some meaning** to you and your colleagues. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Be careful with magic\n",
    "\n",
    "But there are few things I want to warn you about:\n",
    "- magic functions create an implicit way of calling a function. Implicit means that **your function call does not look like calling a function**. **It is up to you to master what your code is doing**. Otherwise you will have painful time debugging problems.\n",
    "- the magic function does not care if you try to add a number a string or anything else. But does that mean anything to \"add 5\" into your database like this: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "my_database = my_database + 5 # seriously ?!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**If you are not able to tell the meaning of something, the code is not gonna make the meaning for you**. You are the smart humain brain, don't rely on the machine to make meaning of things instead of yourself, otherwise you will be disapointed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Crash my code on purpose\n",
    "That is actually the reason why I added that code: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# If I try to add something that is not a CustomData make the program crash\n",
    "if isinstance(newData, CustomData) is False:\n",
    "    raise Exception(\"type {} does not fit, expect a CustomData\".format(type(newData)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When I write the function \\__add\\__ I mean to add proper data in my database, I don't want to pollute it with nonsense ! \n",
    "On that point I plan to design a class CustomData who is responsible for data quality and format, and I want to add only that verified data in my database.\n",
    "\n",
    "If me or someone else try to add something wrong, on purpose or not, I raise an Exception, which will probably cause the program to crash.\n",
    "\n",
    "I do want you to wonder: **Why do I crash my program on purpose ?** I though the job is to avoid the program crashing...\n",
    "\n",
    "That's a great question !\n",
    "When you do a lot of programming you realize that a program who crashes is actually \"easy to debug\" because there are many ways to find the exact place where it crashed, and fix it !\n",
    "Of course it is better if everything is fine and work good... \n",
    "\n",
    "But there is something that is way **much worse** than a program which crashes: a program that look like it work but that is actually having a wrong behaviour.\n",
    "\n",
    "If someone trys to add \"5\" in my database, that does not mean anything to me. So I want it to crash, so that we find out quickly that there is something wrong."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "isinstance(newData, CustomData)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is what this code is doing: it checks that my data has the right format that I defined in CustomData. \n",
    "I want the newData to be an object of type CustomData and nothing else."
   ]
  }
 ],
 "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
}