object_oriented_python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Why use classes?\n",
    "\n",
    "Classes facilitate the two core tenets of code design: **code re-use** and\n",
    "**encapsulation**:\n",
    "* **Code re-use** is facilitated by:\n",
    "    - Multiple instantiation. From the same class you can create multiple\n",
    "      instances that all re-use the class methods.\n",
    "    - Inheritance. One class can re-use methods from a parent class.\n",
    "* **Encapsulation**.\n",
    "    - Class methods and variables are encapsulated in the class namespace and\n",
    "      are not accessible in the global namespace.\n",
    "    - Instance methods and variables are encapsulated in an instance-specific\n",
    "      namespace and are not accessible in the class or the global namespace.\n",
    "    \n",
    "By the way, even if you don't write object-oriented code, you still use classes\n",
    "and instances all the time because under the hood, everything in python is an\n",
    "instance of the built-in class 'object'. You can check this by running\n",
    "`isinstance(x, object)` --- for any `x`, such as an integer, function, list,\n",
    "etc. that will return True."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Namespaces\n",
    "\n",
    "A namespace is a mapping from variable names to objects. You can think of it as\n",
    "a dictionary. An object can be looked up from a namespace via dot-access with\n",
    "the namespace name --- for example, `my_namespace.my_variable` refers to the\n",
    "object associated with the key `'my_variable'` in the namespace `my_namespace`.\n",
    "\n",
    "There are usually multiple namespaces when you run something. Here are some\n",
    "examples:\n",
    "* Python has a built-in namespace (this one is actually special in that it\n",
    "  doesn't need to be explicitly accessed) containing names like `return`, `for`,\n",
    "  `def`, etc.\n",
    "* Importing modules creates namespaces. For example, `import numpy as np`\n",
    "  creates a `numpy` namespace and aliases it as `np` in the current namespace in\n",
    "  which the import statement is. The `numpy` namespace contains all variables\n",
    "  defined in the `numpy` module (specifically, the variables defined in\n",
    "  `numpy`'s `__init__.py` file).\n",
    "* When a function is entered, it creates a temporary namespace that is removed\n",
    "  when the function is exited. More on this later.\n",
    "* Classes are namespaces. More on this later.\n",
    "\n",
    "Namespaces can be nested. For example, this happens for nested modules (e.g.\n",
    "`np.linalg.norm` is accessing a variable in a nested namespace) and for nested\n",
    "functions.\n",
    "\n",
    "You can think of python execution as being in a namespace at every point in\n",
    "time. This may be the namespace of the current module being run, a temporary\n",
    "function namespace (if the interpreter happens to be inside a function at the\n",
    "moment), or the namespace of some other imported module (if the interpreter is\n",
    "inside that module at the moment).\n",
    "\n",
    "In general, it is good to keep namespaces organized. That is why wildcard\n",
    "imports such as `from numpy import *` are bad practice --- they clutter the\n",
    "current module's namespace, which can make it hard to tell where variables are\n",
    "coming from."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "f() can access global_string\n",
      "Parent scope can still access global_string\n"
     ]
    }
   ],
   "source": [
    "# When the interpreter is in a nested namespace, variables in the outer\n",
    "# namespace are accesible. Here we see that the global namespace is accessible\n",
    "# when the interpreter is inside a temporary function namespace:\n",
    "\n",
    "%reset -f\n",
    "\n",
    "global_string = 'global_string'\n",
    "\n",
    "def f():\n",
    "    print('f() can access ' + global_string)\n",
    "    \n",
    "f()\n",
    "print('Parent scope can still access ' + global_string)\n",
    "\n",
    "# Consequently, nested functions create nested temporary namespaces."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "global_list in outer scope is: ['global_string']\n",
      "Now global_list in outer scope is: ['corruption']\n"
     ]
    }
   ],
   "source": [
    "# Danger: Since the outer namespace is accessible, mutable objects in the outer\n",
    "# namespace can be modified when the interpreter is in the inner namespace.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "global_list = ['global_string']\n",
    "\n",
    "def f():\n",
    "    global_list.pop()\n",
    "    global_list.append('corruption')\n",
    "    \n",
    "print('global_list in outer scope is: {}'.format(global_list))\n",
    "f()\n",
    "print('Now global_list in outer scope is: {}'.format(global_list))\n",
    "\n",
    "# For this reason, try to make sure variables in outer namespaces (e.g. a\n",
    "# module namespace) have an immutable type when possible."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "f() can access local_string\n",
      "name 'local_string' is not defined\n"
     ]
    }
   ],
   "source": [
    "# Variables in temporary function namespace are not accesible after the funtion\n",
    "# exits because the temporary function namespace is removed then.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "def f():\n",
    "    local_string = 'local_string'\n",
    "    print('f() can access ' + local_string)\n",
    "    \n",
    "f()\n",
    "\n",
    "try:\n",
    "    # This raises error because outer scope cannot access local_string\n",
    "    print(local_string)\n",
    "except Exception as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "f() sees: locally_overriden_global_string\n",
      "Parent scope sees: global_string\n"
     ]
    }
   ],
   "source": [
    "# Overriding an outer namespace's variable in an inner namespace will create a\n",
    "# new variable in the inner namespace without affecting the variable in the\n",
    "# outer namespace.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "global_string = 'global_string'\n",
    "\n",
    "def f():\n",
    "    global_string = 'locally_overriden_global_string'\n",
    "    print('f() sees: ' + global_string)\n",
    "    \n",
    "f()\n",
    "print('Parent scope sees: ' + global_string)\n",
    "\n",
    "# In general, when looking up variables, python will look in the current\n",
    "# namespace (the one that the exceution is in at the moment) first. Only if the\n",
    "# variable name is not found in the current namespace will python check the\n",
    "# containing namespace and go up from there."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "f() sees: locally_overriden_global_string\n",
      "Parent scope sees: global_string\n",
      "Parent scope sees: locally_overriden_global_string\n"
     ]
    }
   ],
   "source": [
    "# The `global` keyword can be used to prevent local overriding\n",
    "\n",
    "%reset -f\n",
    "\n",
    "global_string = 'global_string'\n",
    "\n",
    "def f():\n",
    "    global global_string\n",
    "    global_string = 'locally_overriden_global_string'\n",
    "    print('f() sees: ' + global_string)\n",
    "    \n",
    "f()\n",
    "print('Parent scope sees: ' + global_string)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Parent scope sees: local_string\n"
     ]
    }
   ],
   "source": [
    "# The `global` keyword can also be used to define a variable in the global scope\n",
    "\n",
    "%reset -f\n",
    "\n",
    "def f():\n",
    "    global local_string\n",
    "    local_string = 'local_string'\n",
    "    \n",
    "f()\n",
    "print('Parent scope sees: ' + local_string)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Classes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Module scope can access class_string as an attribute of MyClass\n",
      "Module scope can access <function MyClass.my_method at 0x10518e170> as an attribute of MyClass\n",
      "MyClass can access class_string as an attribute of MyClass\n",
      "name 'class_string' is not defined\n",
      "\n",
      "class_string\n"
     ]
    }
   ],
   "source": [
    "# Like functions, classes create namespaces contained in the module namespace of\n",
    "# the file that the class is in. However, unlike temporary function namespaces,\n",
    "# class namespaces are persistent. Hence, like modules, variables in these\n",
    "# namespaces can be dot-accessed by the class name. Also, unlike a function a\n",
    "# class is not executed itself, so the execution never enters the class\n",
    "# namespace like it does a function's temporary namespace.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    class_string = 'class_string'\n",
    "    \n",
    "    def my_method():\n",
    "        print('MyClass can access ' + MyClass.class_string +\n",
    "              ' as an attribute of MyClass')\n",
    "        \n",
    "    # Note: Methods in MyClass cannot access class_string directly because\n",
    "    # execution never enters a class's namespace. When MyClass.my_method() is\n",
    "    # run from the global namespace, execution enters a temporary function\n",
    "    # namespace that is totally separate from the MyClass namespace.\n",
    "\n",
    "print('Module scope can access ' + MyClass.class_string +\n",
    "      ' as an attribute of MyClass')\n",
    "print('Module scope can access {} as an attribute of MyClass'.format(\n",
    "      MyClass.my_method))\n",
    "MyClass.my_method()\n",
    "\n",
    "try:\n",
    "    print(class_string)\n",
    "except Exception as e:\n",
    "    print(e)\n",
    "\n",
    "# This is useful, intuitive encapsulation! Classes are namespaces, hence are\n",
    "# containers for variables/objects, which can be dot-accessed as attributes of\n",
    "# the class.\n",
    "\n",
    "print('')\n",
    "\n",
    "# Just to go through one more example, consider this function:\n",
    "def f():\n",
    "    print(MyClass.class_string)\n",
    "f()\n",
    "# What happened here is that when the f() was called, execution entered a\n",
    "# temporary namespace for f. It then encountered MyClass and looked in the\n",
    "# current temporary namespace for the 'MyClass' variable. It was not found, so\n",
    "# python looked in the parent (global) namespace. It found 'MyClass' there. Then\n",
    "# since we asked for the 'class_string' attribute of 'MyClass', python looked\n",
    "# for the 'class_string' variable within the 'MyClass' namespace it had found."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Instances"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "instance can access class_string in the class namespace\n",
      "instance can access instance_string\n",
      "type object 'MyClass' has no attribute 'instance_string'\n",
      "['class_string']\n",
      "['corruption']\n"
     ]
    }
   ],
   "source": [
    "# Instantiating a class by calling it creates a new variable, an 'instance' of\n",
    "# the class. The instance is it's own namespace. However, it is not a\n",
    "# free-floating namespace but is instead a child of the class's namespace, which\n",
    "# means that if the interpreter cannot find a variable in the instance's\n",
    "# namespace, it is then refered to the class namespace to look for it there.\n",
    "\n",
    "# This is not the same as a nested namespace. A nested namespace is a namespace\n",
    "# within a namespace, like we get with nested modules (e.g. np.linalg.norm).\n",
    "# We cannot access instance variables through the class namespace like\n",
    "# MyClass.instance.instance_variable. Instead, think of the instance's child\n",
    "# namespace as disjoint from the class namespace but with a reference to tell\n",
    "# the interpreter where to look when it can't find a variable.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    class_string = 'class_string'\n",
    "    class_list = ['class_string']\n",
    "    \n",
    "    # Note: You can put anything in a class. Most common are functions (which\n",
    "    # are then called class methods), but it's totally acceptable to put other\n",
    "    # types of variables in here (strings, arrays, dicts, etc.). Though it's\n",
    "    # generally frowned upon to put classes in a class, for readability reasons.\n",
    "\n",
    "# Under the hood, calling the class runs the constructor method __init__(), but\n",
    "# we aren't doing anything fancy in our class so we don't even bother writing\n",
    "# __init__(). By the way, all classes secretly inherit from an 'object' type\n",
    "# that has it's own __init__() constructor that is run when we don't write our\n",
    "# own __init__(), but that's getting ahead of ourselves!\n",
    "instance = MyClass()\n",
    "\n",
    "print('instance can access ' + instance.class_string +\n",
    "      ' in the class namespace')\n",
    "\n",
    "# Being a namespace, instance can also have its own variables\n",
    "instance.instance_string = 'instance_string'\n",
    "print('instance can access ' + instance.instance_string)\n",
    "\n",
    "# Variables in instance's namespace are not accessible from the parent (class)\n",
    "# namespace or grandparent (global) namespace.\n",
    "try:\n",
    "    print(MyClass.instance_string)\n",
    "except Exception as e:\n",
    "    print(e)\n",
    "\n",
    "# Danger: Since an instance namespace refers to the parent namespace when a\n",
    "# variable isn't found, we can unwittingly corrupt a mutable variable in the\n",
    "# class namespace even if it looks like we're only touching the instance.\n",
    "other_instance = MyClass()\n",
    "print(other_instance.class_list)  # Uncorrupted\n",
    "instance.class_list.pop()\n",
    "instance.class_list.append('corruption')\n",
    "print(other_instance.class_list)  # Corrupted\n",
    "\n",
    "# General opinion: Class attributes are great. In fact, oftentimes I think\n",
    "# people don't use them enough. However, for safety always make sure they're an\n",
    "# immutable type so they can't be secretly corrupted by instances."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 185,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "method without argument\n",
      "method_with_arg() missing 1 required positional argument: 'arg'\n",
      "method with argument\n",
      "method_without_arg() takes 0 positional arguments but 1 was given\n",
      "static method without argument\n",
      "static method without argument\n"
     ]
    }
   ],
   "source": [
    "# Something special happens when you call a method in an instance's namespace:\n",
    "# The instance itself is passed in as the first argument of that method. For\n",
    "# example, python interprets this:\n",
    "#     instance.some_method(*args, **kwargs)\n",
    "#   as this:\n",
    "#     instance.some_method(instance, *args, **kwargs)\n",
    "# This behavior happens even if the method is actually found in the class's\n",
    "# namespace. This is purely syntactic sugar --- you can avoid it by doing\n",
    "# Class.some_method(instance, *args, **kwargs). But the syntactic sugar is\n",
    "# useful because it means you don't have to remember the class name every time\n",
    "# you want to run a class method on an instance.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    \n",
    "    def method_without_arg():\n",
    "        print('method without argument')\n",
    "    \n",
    "    def method_with_arg(arg):\n",
    "        # Note: There is a convention of calling the instance arg 'self'\n",
    "        print('method with argument')\n",
    "    \n",
    "    # @staticmethod is a decorator to tell python not to do this special\n",
    "    # behavior of feeding the instance as the first argument.\n",
    "    @staticmethod\n",
    "    def static_method_without_arg():\n",
    "        print('static method without argument')\n",
    "\n",
    "instance = MyClass()\n",
    "        \n",
    "# Calling method_without_arg from the class's namespace is fine\n",
    "MyClass.method_without_arg()\n",
    "\n",
    "# Calling method_with_arg from the class's namespace needs an argument\n",
    "try:\n",
    "    MyClass.method_with_arg()\n",
    "except Exception as e:\n",
    "    print(e)\n",
    "\n",
    "# Calling method_with_arg from the instance namespace is fine\n",
    "instance.method_with_arg()\n",
    "\n",
    "# Calling method_without_arg from the instance namespace gets too many arguments\n",
    "try:\n",
    "    instance.method_without_arg()\n",
    "except Exception as e:\n",
    "    print(e)\n",
    "\n",
    "# Calling static_method_without_arg from the instance namespace is fine\n",
    "instance.static_method_without_arg()\n",
    "\n",
    "# Calling static_method_without_arg from the class namespace is also fine\n",
    "MyClass.static_method_without_arg()\n",
    "\n",
    "# Rule of thumb: If your method does not depend on the instance argument\n",
    "# ('self') and you want to call it from instances, use the @staticmethod\n",
    "# decorator! No need to have extra arguments if you don't need them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 186,
   "metadata": {},
   "outputs": [],
   "source": [
    "################################################################################\n",
    "# ASIDE: DECORATORS\n",
    "################################################################################\n",
    "\n",
    "# The term 'decorator' refers to a function that takes in one function and\n",
    "# returns another. For example, f() here is a decorator:\n",
    "# \n",
    "#     def f(g):\n",
    "# \n",
    "#          def _new_g(*args, **kwargs):\n",
    "#              print(args)\n",
    "#              print(kwargs)\n",
    "#              return g(*args, **kwargs)\n",
    "# \n",
    "#          return def _new_g\n",
    "#\n",
    "# You can think of a decorator as wrapping up g to make a small modification to\n",
    "# it, which in this example just prints the args and kwargs of g before running\n",
    "# g.\n",
    "# If you want to apply this decorator to a method in a class every time that\n",
    "# method is called, python has the '@' syntactic sugar, i.e.\n",
    "#\n",
    "# class MyClass():\n",
    "# \n",
    "#    @f\n",
    "#    g(*args, **kwargs):\n",
    "#        # do whatever g is suppsed to do\n",
    "#        pass\n",
    "# \n",
    "# This will cause MyClass.g(*args, **kargs) to behave like\n",
    "# f(MyClass.g)(*args, **kwargs)\n",
    "#\n",
    "# Personally, I don't often write my own decorators. In fact, I typically try to\n",
    "# avoid them for readability reasons --- if I can let the method do whatever it\n",
    "# needs to do without a decorator, that is usually more straightforward for the\n",
    "# reader to understand.\n",
    "# \n",
    "# However, in cases when you want to override default Python functionality,\n",
    "# python has some built-in decorators, like @staticmethod. Other decorators I\n",
    "# use often are @property to make a class method behave like an attribute, and\n",
    "# @abc.abstractmethod / @abc.abstractproperty when writing abstract base\n",
    "# classes.\n",
    "\n",
    "################################################################################"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(1, 2, 3)\n",
      "{'a': 4, 'b': 5}\n",
      "6\n",
      "('h', 'i')\n",
      "{'x': True, 'y': (1, 2, 3)}\n"
     ]
    }
   ],
   "source": [
    "# The great thing about instances creating child namescopes is we can create\n",
    "# lots of instance-specific variables in our class methods. The first\n",
    "# opportunity to do this is in the constructor __init__(), which is called upon\n",
    "# instance creation.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    \n",
    "    def __init__(self, *args, **kwargs):\n",
    "        # Recall, there's nothing special about using the argument name 'self'\n",
    "        # here --- it's just convention and the code will work if you use a\n",
    "        # different name.\n",
    "        self._args = args\n",
    "        self._kwargs = kwargs\n",
    "    \n",
    "    def print_args(self):\n",
    "        print(self._args)\n",
    "    \n",
    "    def print_kwargs(self):\n",
    "        print(self._kwargs)\n",
    "\n",
    "# Remember, calling a class creates a new instance namespace and calls the\n",
    "# __init__() method, feeding in that new namespace as the first argument\n",
    "instance_0 = MyClass(1, 2, 3, a=4, b=5)\n",
    "instance_0.print_args()\n",
    "instance_0.print_kwargs()\n",
    "\n",
    "# We can add new attributes to it\n",
    "instance_0.c = 6\n",
    "print(instance_0.c)\n",
    "\n",
    "# We can create lots of instances, and their variables will all be neatly\n",
    "# encapsulated in their respective namespaces\n",
    "instance_1 = MyClass('h', 'i', x=True, y=(1, 2, 3))\n",
    "instance_1.print_args()\n",
    "instance_1.print_kwargs()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Inheritance\n",
    "\n",
    "We talked about these things:\n",
    "* Classes are namespaces\n",
    "* Instances are namespaces\n",
    "* Instance namespaces are children of class namespaces, i.e. they refer to the\n",
    "  class namespace if the interpreter can't find a variable in them.\n",
    "\n",
    "These suggest that if we want one class to have access to methods from another\n",
    "class, we somehow need to make that class's namespace be a child of the other's\n",
    "namespace. Then instances of the child class will be grandchild namespaces of\n",
    "the parent class. That is what inheritance does."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 188,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "parent method\n",
      "type object 'Parent' has no attribute 'child_method'\n"
     ]
    }
   ],
   "source": [
    "# Parent/child classes, no instances here yet.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class Parent():\n",
    "    def parent_method():\n",
    "        print('parent method')\n",
    "        \n",
    "class Child(Parent):\n",
    "    def child_method():\n",
    "        print('child method')\n",
    "        \n",
    "# Now Child has access to Parent's methods:\n",
    "Child.parent_method()\n",
    "\n",
    "# But Parent does not have access to Child's methods:\n",
    "try:\n",
    "    Parent.child_method()\n",
    "except Exception as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 189,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "parent_string\n",
      "parent instance method\n",
      "I have overridden my parent\n"
     ]
    }
   ],
   "source": [
    "# Consequently, child class instances likewise inherit methods from the parent\n",
    "# class (the parent class namespace is the grandparent of the instance\n",
    "# namespace).\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class Parent():\n",
    "    parent_string = 'parent_string'\n",
    "    \n",
    "    def parent_instance_method(self):\n",
    "        print('parent instance method')\n",
    "        \n",
    "class Child(Parent): pass\n",
    "        \n",
    "child_instance = Child()\n",
    "print(child_instance.parent_string)\n",
    "child_instance.parent_instance_method()\n",
    "\n",
    "# Note: Child classes can implement variables that have the same name as\n",
    "# variables in their parents. If this is the case, the interpreter never gets\n",
    "# referred to the parent when looking these up, so that variable has been\n",
    "# effectively overridden in the child class.\n",
    "\n",
    "class UnrulyChild(Parent):\n",
    "    def parent_instance_method(self):\n",
    "        print('I have overridden my parent')\n",
    "        \n",
    "unruly_child_instance = UnrulyChild()\n",
    "unruly_child_instance.parent_instance_method()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "parent_string_0\n"
     ]
    }
   ],
   "source": [
    "# Multiple Inheritance: Python does allow multiple inheritance. In this case,\n",
    "# python searches parent namespaces left-to-right when looking up a variable.\n",
    "# This is called Method Resolution Order (MRO).\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class Parent0():\n",
    "    parent_string = 'parent string 0'\n",
    "    \n",
    "class Parent1():\n",
    "    parent_string = 'parent string 1'\n",
    "        \n",
    "class Child(Parent0, Parent1): pass\n",
    "        \n",
    "print(Child.parent_string)\n",
    "\n",
    "# Rule of thumb. Multiple inheritance is a bad idea. It requires cognitive\n",
    "# overhead for the programmer & reader to know what variables are in the\n",
    "# parents to figure out if there are duplicates, and can give rise to gnarly\n",
    "# bugs. Things get even more messy when grandparents get involved ..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 191,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "overridden grandparent string\n",
      "grandparent string\n"
     ]
    }
   ],
   "source": [
    "# Multiple Inheritance with Grandparents: A complete mess.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class GrandParent():\n",
    "    grandparent_string = 'grandparent string'\n",
    "\n",
    "class Parent0(GrandParent): pass\n",
    "\n",
    "# Let's try making Parent1 inherit from GrandParent too, so we have a\n",
    "# diamond-shaped inheritance structure. In this case, the method resolution\n",
    "# order is Child -> Parent0 -> Parent1 -> GrandParent, as we can see:\n",
    "\n",
    "class Parent1(GrandParent):\n",
    "    grandparent_string = 'overridden grandparent string'\n",
    "        \n",
    "class Child(Parent0, Parent1): pass\n",
    "        \n",
    "print(Child.grandparent_string)  # prints 'overridden grandparent string'\n",
    "\n",
    "# From this it might seem like python is doing a breadth-first search. However,\n",
    "# that is actually not quite the case:\n",
    "\n",
    "# Let's try making Parent1 not inherit from GrandParent:\n",
    "\n",
    "class Parent1():\n",
    "    grandparent_string = 'overridden grandparent string'\n",
    "        \n",
    "class Child(Parent0, Parent1): pass\n",
    "        \n",
    "print(Child.grandparent_string)  # prints 'grandparent string'\n",
    "\n",
    "# Now the method resolution order is\n",
    "#     Child -> Parent0 -> GrandParent -> Parent 1.\n",
    "# This is strange --- while the MRO looked like breadth-first search when we\n",
    "# had a diamonnd in the structure, removing one edge of that diamond makes it\n",
    "# now look like depth-first search.\n",
    "\n",
    "# You can imagine how this could cause really devious bugs in practice and be\n",
    "# really hard to keep track of as a programmer/reader.\n",
    "\n",
    "# To make matters worse, this is just one of a large number of counterintuitive\n",
    "# behaviors in python's MRO algorithm (things get even crazier when you add\n",
    "# deeper/wider inheritance structures). Moreover, python's MRO algorithm changed\n",
    "# between python2 and python3, and a lot of programmers (myself included) got\n",
    "# confused by that, in part because we didn't fully understand the MRO algorithm\n",
    "# in python2 to being with!\n",
    "\n",
    "# Bottom line: Avoid multiple inheritance whever possible. If you absolutely\n",
    "# must use multiple inheritance, be sure to check carefully for variables with\n",
    "# the name in the parent lineages and document the inheritance structure well.\n",
    "\n",
    "# Most python programmers flatly refuse to use multiple inheritance unless one \n",
    "# of the parents is a \"Mixin\" --- a parent class that has no __init__() function\n",
    "# and is very light-weight."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# super(): Invoking a parent namespace.\n",
    "\n",
    "Sometimes you may want to get a variable in a parent namespace that has the same\n",
    "name as a variable in the child namespace. In this case you can't just get the\n",
    "variable as usual because the interpreter will pick up the one in the child\n",
    "namespace. super() allows you to explicitly tell the interpreter to jump to the\n",
    "parent namespace and begin its search there."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "parent\n",
      "parent\n"
     ]
    }
   ],
   "source": [
    "# Here is basic super() usage:\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class Parent():\n",
    "    class_string = 'parent'\n",
    "    \n",
    "class Child(Parent):\n",
    "    class_string = 'child'\n",
    "    \n",
    "    def print_string(self):\n",
    "        # Within an instance method, super() returns the parent namespace\n",
    "        print(super().class_string)\n",
    "\n",
    "child_instance = Child().print_string()  # prints 'parent'\n",
    "\n",
    "# Note that we don't need super() for this --- we could invoke Parent by name,\n",
    "# like this:\n",
    "\n",
    "class Child(Parent):\n",
    "    class_string = 'child'\n",
    "    \n",
    "    def print_string(self):\n",
    "        print(Parent.class_string)\n",
    "\n",
    "Child().print_string()  # prints 'parent'\n",
    "\n",
    "# However, using super() is slightly preferable because it makes the code more\n",
    "# robust. For example, if you decide to change the name of Parent, with super()\n",
    "# you don't have to go through the entire Child implmementation changing all the\n",
    "# times Parent was invoked by name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 134,
   "metadata": {},
   "outputs": [],
   "source": [
    "# super() is only needed when you have variables that share the same name in the\n",
    "# child and parent classes (otherwise you can use normal inheritance without\n",
    "# super()). This is often used when you want the child class method to implement\n",
    "# a wrapper of the parent class method. One very common occurance is in\n",
    "# __init__(), for example:\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class Parent():\n",
    "    def __init__(self, **parent_kwargs):\n",
    "        # Does a bunch of useful stuff that you want children to do too\n",
    "        pass\n",
    "    \n",
    "    \n",
    "class Child(Parent):\n",
    "    def __init__(self, child_arg, **parent_kwargs):\n",
    "        # Do the useful stuff in Parent's constructore\n",
    "        super().__init__(**parent_kwargs)\n",
    "        \n",
    "        # Do a little extra for the child\n",
    "        self._child_arg = child_arg\n",
    "\n",
    "# As you might imagine, calling super() when there is multiple inheritance gets\n",
    "# into python's method resolution order, which is a mess and should be avoided."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 193,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "parent\n",
      "grandparent\n"
     ]
    }
   ],
   "source": [
    "# super() can optionally take two arguments:\n",
    "#     super(class, instance)\n",
    "# where 'class' is the class who's parent we want to invoke and 'instance' is an\n",
    "# instance of that class.\n",
    "\n",
    "# One situation when when you might want to use these arguments is using super()\n",
    "# outside of a class method, e.g. later on in the code, like this:\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class Parent():\n",
    "    class_string = 'parent'\n",
    "    \n",
    "class Child(Parent):\n",
    "    class_string = 'child'\n",
    "\n",
    "child_instance = Child()\n",
    "print(super(Child, child_instance).class_string)\n",
    "\n",
    "# Another is if you want to invoke a grandparent class, like this:\n",
    "\n",
    "class GrandParent():\n",
    "    class_string = 'grandparent'\n",
    "\n",
    "class Parent(GrandParent):\n",
    "    class_string = 'parent'\n",
    "\n",
    "class Child(Parent):\n",
    "    class_string = 'child'\n",
    "    \n",
    "    def print_string(self):\n",
    "        print(super(Parent, self).class_string)\n",
    "\n",
    "Child().print_string()  # prints 'grandparent'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Dunder Methods"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 152,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['__abs__', '__add__', '__and__', '__bool__', '__ceil__', '__class__', '__delattr__', '__dir__', '__divmod__', '__doc__', '__eq__', '__float__', '__floor__', '__floordiv__', '__format__', '__ge__', '__getattribute__', '__getnewargs__', '__gt__', '__hash__', '__index__', '__init__', '__init_subclass__', '__int__', '__invert__', '__le__', '__lshift__', '__lt__', '__mod__', '__mul__', '__ne__', '__neg__', '__new__', '__or__', '__pos__', '__pow__', '__radd__', '__rand__', '__rdivmod__', '__reduce__', '__reduce_ex__', '__repr__', '__rfloordiv__', '__rlshift__', '__rmod__', '__rmul__', '__ror__', '__round__', '__rpow__', '__rrshift__', '__rshift__', '__rsub__', '__rtruediv__', '__rxor__', '__setattr__', '__sizeof__', '__str__', '__sub__', '__subclasshook__', '__truediv__', '__trunc__', '__xor__']\n"
     ]
    }
   ],
   "source": [
    "# Double underscore (or \"dunder\") methods are private class methods that python\n",
    "# calls according to particular rules.\n",
    "# For example, __init__() is one, which is called when an instance is created.\n",
    "# Another example is __str__, which is called by the 'str()' python function.\n",
    "\n",
    "# There are actually a lot of dunder methods, even for an object as simple as\n",
    "# the integer 4:\n",
    "print([x for x in dir(4) if '__' in x])\n",
    "# Most of these you rarely if ever need to worry about, but they do a lot of\n",
    "# work behind the scenes. For example, when you type 3 < 4, python actually\n",
    "# calls the __lt__() dunder, i.e. 3.__lt__(4).\n",
    "\n",
    "# Always take care when implementing or overriding dunder methods --- they're\n",
    "# double-underscore protected for a reason. __init__() is by far the most common\n",
    "# to override, but sometimes you may want to override others. In the next few\n",
    "# cells are the ones I implement/override most often:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 153,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(1, 2, 3)\n"
     ]
    }
   ],
   "source": [
    "# __call__(): This method is called whenever you call something. In fact, any\n",
    "# time you create a function (e.g. def f(): ...), that function is actually an\n",
    "# object whose __call__() method is what you wrote! Unlike functions, classes\n",
    "# are not by default callable, so I sometimes make a class callable by\n",
    "# implementing __call__(). For example:\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class CallableClass():\n",
    "    \n",
    "    def __init__(self, *args):\n",
    "        self._args = args\n",
    "\n",
    "    def __call__(self):\n",
    "        print(self._args)\n",
    "        \n",
    "CallableClass(1, 2, 3)()\n",
    "\n",
    "# Making callable classes can actually be quite useful, because a callable class\n",
    "# can behave like a function, hence can fed into calling code that expects a\n",
    "# function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 195,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<__main__.CallableClass object at 0x10b9d79d0>\n",
      "<Callable with args (1, 2, 3)>\n"
     ]
    }
   ],
   "source": [
    "# __str__(): This method is called whenever you call str() on something. This\n",
    "# one is particularly useful when you want to make logging and/or error strings\n",
    "# easier to read or more informative.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class CallableClass():\n",
    "    \n",
    "    def __init__(self, *args):\n",
    "        self._args = args\n",
    "        \n",
    "\n",
    "class PrettyCallableClass():\n",
    "    \n",
    "    def __init__(self, *args):\n",
    "        self._args = args\n",
    "        \n",
    "    def __str__(self):\n",
    "        return '<Callable with args {}>'.format(self._args)\n",
    "\n",
    "\n",
    "print(CallableClass(1, 2, 3))\n",
    "print(PrettyCallableClass(1, 2, 3))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 197,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Okay I'll stop writing examples now but will just list a few others:\n",
    "\n",
    "# __len__(): This method is called whenever you call len() on something.\n",
    "\n",
    "# __hash__(): This is called whevener you call hash() on something.\n",
    "\n",
    "# __setattr__(): This sets an attribute. For example,\n",
    "#     A.name = value   does   A.__setattr__(name, value)\n",
    "\n",
    "# __setitem__(): This sets an item. For example,\n",
    "#     A[name] = value   does   A.__setitem__(name, value)\n",
    "\n",
    "# __bool__(): Called whenever you call bool() on something.\n",
    "\n",
    "# __enter__() and __exit__(): These are the dunders you have to implement for\n",
    "# context managers."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Private class attributes\n",
    "\n",
    "Python doesn't have truly private and public class attributes --- as long as you\n",
    "have an attribute name, you can look it up in the class namescope.\n",
    "\n",
    "However, there is a convention of using a single leading underscore in a class\n",
    "attribute to indicate the attribute should not be used publicly. This is not\n",
    "enforced --- it is purely convention. By the way, this applies to functions as\n",
    "well --- if you want a function to be private to a module, use a leading\n",
    "underscore in its name.\n",
    "\n",
    "There is also name mangling, which goes a step further: If a class attribute has\n",
    "two leading underscores in its name, python will alias it by a mangled version\n",
    "of its name (specifically, _ClassName__attribute_name). It still isn't truly\n",
    "private (you can still access it publicly via its mangled name), but the name\n",
    "mangling makes it very apparent that it is supposed to be private.\n",
    "\n",
    "By the way, if an attribute has both leading and trailing double underscores, it\n",
    "it exempt from name mangling (e.g. magid dunder methods like __init__ and\n",
    "__call__).\n",
    "\n",
    "Typically, I use single underscore attributes all the time but rarely use double\n",
    "underscore attributes. As long as I abide by the convention of not accessing\n",
    "single underscore attributes publicly, there isn't really a need to use name\n",
    "mangling. I'll only use double underscores if I'm going to open-source the code\n",
    "and want to really force privacy for robustness."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 199,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "private string\n",
      "private method\n"
     ]
    }
   ],
   "source": [
    "# Single underscore private method convention\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    _private_string = 'private string'\n",
    "    \n",
    "    def _private_method():\n",
    "        print('private method')\n",
    "        \n",
    "# Single underscore is just a convention --- it can still be accessed:\n",
    "print(MyClass._private_string)\n",
    "MyClass._private_method()\n",
    "\n",
    "# However, most linters will give you a warning if you try to access a single\n",
    "# underscore attribute, and you should try to avoid doing so."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 204,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "type object 'MyClass' has no attribute '__private_string'\n",
      "type object 'MyClass' has no attribute '__private_method'\n",
      "private string\n",
      "private method\n",
      "private string\n",
      "private string\n"
     ]
    }
   ],
   "source": [
    "# Double underscore name mangling\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    __private_string = 'private string'\n",
    "    \n",
    "    def __private_method():\n",
    "        print('private method')\n",
    "        \n",
    "    def print_private_string():\n",
    "        # No name mangling when accessed from within the class\n",
    "        print(MyClass.__private_string)\n",
    "        \n",
    "    def print_private_string_from_instance(self):\n",
    "        # Whether or not instances are involved:\n",
    "        print(self.__private_string)\n",
    "\n",
    "\n",
    "try:\n",
    "    print(MyClass.__private_string)\n",
    "except Exception as e:\n",
    "    print(e)\n",
    "\n",
    "try:\n",
    "    MyClass.__private_method()\n",
    "except Exception as e:\n",
    "    print(e)\n",
    "\n",
    "# Here's how the name mangling works:\n",
    "print(MyClass._MyClass__private_string)\n",
    "MyClass._MyClass__private_method()\n",
    "\n",
    "# Accessing from within the class has no name mangling\n",
    "MyClass.print_private_string()\n",
    "MyClass().print_private_string_from_instance()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# @property Decorator\n",
    "\n",
    "Oftentime you may want an attribute to be half private in the sense that you\n",
    "want it to be accessible publicly but you don't want it to be able to be\n",
    "overwritten publicly.\n",
    "\n",
    "One way to handle this is to have a private attribute but implement a public\n",
    "getter method that returns the private attribute. This is fine, but sometimes\n",
    "the calling code would be more intuitive if it didn't have to call a getter\n",
    "method.\n",
    "\n",
    "This is where the @property decorator comes into play. The @property decorator\n",
    "makes a method behave like an attribute, i.e. it allows the caller to call the\n",
    "method without actually calling it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 206,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "private string\n",
      "private string\n",
      "42\n"
     ]
    }
   ],
   "source": [
    "# Making an attribute publicly accessible by not publicly writable.\n",
    "\n",
    "%reset -f\n",
    "\n",
    "# Method 1: Make a getter method for a private attribute\n",
    "\n",
    "class MyClass():\n",
    "    _private_string = 'private string'\n",
    "    \n",
    "    def private_string_getter(self):\n",
    "        return self._private_string\n",
    "\n",
    "print(MyClass().private_string_getter())\n",
    "\n",
    "# Method 2: Use @property decorate to make getter behave like an attribute\n",
    "\n",
    "class MyClass():\n",
    "    _private_string = 'private string'\n",
    "    \n",
    "    @property\n",
    "    def private_string(self):\n",
    "        return self._private_string\n",
    "    \n",
    "    @property\n",
    "    def random_property(self):\n",
    "        return 42\n",
    "    \n",
    "print(MyClass().private_string)\n",
    "print(MyClass().random_property)\n",
    "\n",
    "# By the way, this would work similarly if you were using double underscore\n",
    "# attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 207,
   "metadata": {},
   "outputs": [],
   "source": [
    "# By the way, it is a very common to use single underscore private attributes\n",
    "# and make them publicly accessible (but not publicly writable by convention)\n",
    "# with @property methods. Those @property methods are customarily put at the\n",
    "# bottom of the class implementation, like this:\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    def __init__(self, a, b, c):\n",
    "        self._a = a\n",
    "        self._b = b\n",
    "        self._c = c\n",
    "    \n",
    "    def my_method(self):\n",
    "        return self._a + self._b\n",
    "    \n",
    "    @property\n",
    "    def a(self):\n",
    "        return self._a\n",
    "    \n",
    "    @property\n",
    "    def b(self):\n",
    "        return self._b\n",
    "    \n",
    "    @property\n",
    "    def c(self):\n",
    "        return self._c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setters\n",
    "\n",
    "The python @x.setter decorator allows you to write some functionality to be done\n",
    "whenever a variable x is set.\n",
    "\n",
    "This can be useful if you have a private attribute that you later decide should\n",
    "be publicly settable (but don't want to or can't change the private attribute's\n",
    "name everywhere).\n",
    "\n",
    "This is also just a generally useful tool --- I regularly find myself wanting to\n",
    "have a method that sets an attribute and does other things simultaneously, and\n",
    "the @x.setter syntactical sugar often makes this more intuitive for the calling\n",
    "code than making some method with a new name to do that."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 221,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "setting private_string\n",
      "getting private_string\n",
      "new\n"
     ]
    }
   ],
   "source": [
    "# Setters\n",
    "\n",
    "%reset -f\n",
    "\n",
    "class MyClass():\n",
    "    def __init__(self):\n",
    "        self._private_string = 'private string'\n",
    "\n",
    "    @property\n",
    "    def private_string(self):\n",
    "        print('getting private_string')\n",
    "        return self._private_string\n",
    "    \n",
    "    @private_string.setter\n",
    "    def private_string(self, new_value):\n",
    "        print('setting private_string')\n",
    "        self._private_string = new_value\n",
    "        \n",
    "\n",
    "instance = MyClass()\n",
    "instance.private_string = 'new'\n",
    "print(instance.private_string)"
   ]
  }
 ],
 "metadata": {
  "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.7.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}