python class demonstration.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Classes and Object-Oriented Programming in Python\n",
    "Here I demonstrate several key features of classes and object-oriented programming in Python.  These include the following\n",
    "- class inheritance\n",
    "- overriding magic methods\n",
    "- property setters and getters (using `@property` and `@<attribute>.setter` decorators)\n",
    "- composition\n",
    "\n",
    "These examples were inspired by the simple straight-forward book [\"Object-Oriented Programming in Python\"](http://python-textbok.readthedocs.io/en/stable/index.html) written for a MSc-level \n",
    "course in IT at the University of Cape Town.  The copyright of the book is held by University of Cape Town and individual contributors and has been released under the CC BY-SA 4.0 licence. Revision 8e685e710775+. \n",
    "\n",
    "Note that I will add more description as time permits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import datetime\n",
    "import time"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I will start by defining a `Person` class. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class Person(object):\n",
    "    \n",
    "    def __init__(self, name, surname, gender, birthdate, **kwargs):\n",
    "        self.name = name\n",
    "        self.surname = surname\n",
    "        self.birthdate = birthdate\n",
    "        if 'male' == gender.lower() or 'boy' == gender.lower():\n",
    "            self.gender = 'male'\n",
    "        else:\n",
    "            self.gender = 'female'\n",
    "        # accomodate other input information\n",
    "        for key, val in kwargs.iteritems():\n",
    "            self.__dict__[key] = val\n",
    "\n",
    "    @property\n",
    "    def fullname(self):\n",
    "        return '{} {}'.format(self.name, self.surname)\n",
    "\n",
    "    @property\n",
    "    def age(self):\n",
    "        today = datetime.date.today()\n",
    "        age = today.year - self.birthdate.year\n",
    "\n",
    "        if today < datetime.date(today.year, self.birthdate.month, self.birthdate.day):\n",
    "            age -= 1\n",
    "        return age\n",
    "\n",
    "    # override some magic methods\n",
    "\n",
    "    def __str__(self):\n",
    "        critical_keys = ['name', 'surname', 'gender', 'birthdate', 'fullname']\n",
    "        about = '\\n{} is a {}-y-o {}.\\n'.format(self.fullname, self.age,\n",
    "                                                self.gender)\n",
    "        additional_keys = list(set(self.__dict__.keys()) - set(critical_keys))\n",
    "        if len(additional_keys) > 0:\n",
    "            about += '--Additional info--\\n'\n",
    "            for key in additional_keys:\n",
    "                about += '{}: {}\\n'.format(key, self.__dict__[key])\n",
    "        return about\n",
    "\n",
    "    # setup comparison based on name alphabatization\n",
    "    def __eq__(self, other): # does self == other?\n",
    "        return self.name == other.name and self.surname == other.surname\n",
    "\n",
    "    def __gt__(self, other): # is self > other?\n",
    "        if self.surname == other.surname:\n",
    "            return self.name > other.name\n",
    "        return self.surname > other.surname\n",
    "\n",
    "    # now we can define all the other methods in terms of the first two\n",
    "    def __ne__(self, other): # does self != other?\n",
    "        return not self == other # this calls self.__eq__(other)\n",
    "\n",
    "    def __le__(self, other): # is self <= other?\n",
    "        return not self > other # this calls self.__gt__(other)\n",
    "\n",
    "    def __lt__(self, other): # is self < other?\n",
    "        return not (self > other or self == other)\n",
    "\n",
    "    def __ge__(self, other): # is self >= other?\n",
    "        return not self < other"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " This expects certain critical input values when intantiating a person, their first and last name, gender, and birthdate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Dawn Joe is a 33-y-o female.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "dawn = Person('Dawn', 'Joe', 'female', datetime.date(1984, 1, 13))\n",
    "print(dawn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For demonstration purposes, I set this up to accept additional keyword arguments as well.  This should be done with care as relying on these additional attributes can lead to problems if they are not populated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Jon Doe is a 33-y-o male.\n",
      "--Additional info--\n",
      "hair: red\n",
      "cell: 249.298.6690\n",
      "email: jon.doe@email.com\n",
      "address: 123 Redwood Ct\n",
      "\n"
     ]
    }
   ],
   "source": [
    "jon = Person('Jon', 'Doe', 'male', datetime.date(1983, 8, 21),\n",
    "             email='jon.doe@email.com', address='123 Redwood Ct',\n",
    "             cell='249.298.6690', hair='red')\n",
    "print(jon)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now lets define a `Child` class.  It will inherit from the `Person` class, with one added property, `nap_time`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class Child(Person):\n",
    "    \n",
    "    @property\n",
    "    def nap_time(self):\n",
    "        if self.age < 1:\n",
    "            return [9, 1]\n",
    "        elif self.age < 5:\n",
    "            return [1]\n",
    "        else:\n",
    "            return []\n",
    "\n",
    "    def __str__(self):\n",
    "        critical_keys = ['name', 'surname', 'gender', 'birthdate', 'fullname']\n",
    "        about = '{} is a {}-y-o {},\\n'.format(self.fullname, self.age,\n",
    "                                                self.gender)\n",
    "        if len(self.nap_time) > 1:\n",
    "            about += 'and takes naps at {} and {} o-clock.\\n'.format(*self.nap_time)\n",
    "        elif len(self.nap_time) > 0:\n",
    "            about += 'with a nap time at {} o-clock.\\n'.format(*self.nap_time)\n",
    "        else:\n",
    "            about += 'and is too old for naps.\\n'\n",
    "\n",
    "        additional_keys = list(set(self.__dict__.keys()) - set(critical_keys))\n",
    "        if len(additional_keys) > 0:\n",
    "            about += '--Additional info--\\n'\n",
    "            for key in additional_keys:\n",
    "                about += '{}: {}\\n'.format(key, self.__dict__[key])\n",
    "        return about"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Sussy Doe is a 5-y-o female,\n",
      "and is too old for naps.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "sussy = Child('Sussy', 'Doe', 'female', datetime.date(2011, 7, 22))\n",
    "print(sussy)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Johnny Doe is a 2-y-o male,\n",
      "with a nap time at 1 o-clock.\n",
      "--Additional info--\n",
      "hair: red\n",
      "toy: green ball\n",
      "blankie: blue\n",
      "\n"
     ]
    }
   ],
   "source": [
    "johnny = Child('Johnny', 'Doe', 'male', datetime.date(2015, 3, 1),\n",
    "               blankie='blue', hair='red', toy='green ball')\n",
    "print(johnny)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I have already been using composition, by providing a datetime object for the `birthdate` input value but I will go one step further.  Now I will define a basic family class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class Family(object):\n",
    "\n",
    "    def __init__(self, mommy, daddy, *kids):\n",
    "        self.mommy = mommy\n",
    "        self.daddy = daddy\n",
    "        self.kids = list(kids)\n",
    "        self.number_of_kids = len(self.kids)\n",
    "\n",
    "    def __str__(self):\n",
    "        about = ('\\nThe {} family is made up of {}, {}, \\n'\n",
    "                 'and their {} kids: \\n'.format(self.daddy.surname,\n",
    "                                                self.daddy.name,\n",
    "                                                self.mommy.name,\n",
    "                                                self.number_of_kids))\n",
    "        for kid in self.kids:\n",
    "            about += '{name}\\n'.format(name=kid.name)\n",
    "\n",
    "        return about"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I will use this to define a family from the four people I have already instantiated, Jon, Dawn, Sussy, and Johnny."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "The Doe family is made up of Jon, Dawn, \n",
      "and their 2 kids: \n",
      "Johnny\n",
      "Sussy\n",
      "\n"
     ]
    }
   ],
   "source": [
    "simple_family = Family(dawn, jon, johnny, sussy)\n",
    "print(simple_family)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now I will define a family that can add grow using the `add_child` method.  I will implement this two different ways to illustrate the difference between lazy and eager calculations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class LazyFamily(Family):\n",
    "\n",
    "    def __init__(self, mommy, daddy, *kids):\n",
    "        self.mommy = mommy\n",
    "        self.daddy = daddy\n",
    "        self.kids = list(kids)\n",
    "\n",
    "    @property\n",
    "    def family_size(self):\n",
    "        time.sleep(0.01)  # mimic a long calculation\n",
    "        return 2 + self.number_of_kids\n",
    "\n",
    "    @property\n",
    "    def number_of_kids(self):\n",
    "        time.sleep(0.01)  # mimic a long calculation\n",
    "        return len(self.kids)\n",
    "\n",
    "    def add_child(self, child):\n",
    "        self.kids.append(child)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "before: \n",
      "The Doe family is made up of Jon, Dawn, \n",
      "and their 2 kids: \n",
      "Johnny\n",
      "Sussy\n",
      "\n",
      "after: \n",
      "The Doe family is made up of Jon, Dawn, \n",
      "and their 3 kids: \n",
      "Johnny\n",
      "Sussy\n",
      "Alicia\n",
      "\n"
     ]
    }
   ],
   "source": [
    "alicia = Child('Alicia', 'Doe', 'female', datetime.date(2017, 7, 20))\n",
    "family_1 = LazyFamily(dawn, jon, johnny, sussy)\n",
    "print('before: {}'.format(family_1))\n",
    "\n",
    "family_1.add_child(alicia)\n",
    "print('after: {}'.format(family_1))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class EagerFamily(Family):\n",
    "\n",
    "    def __init__(self, mommy, daddy, *kids):\n",
    "        self.mommy = mommy\n",
    "        self.daddy = daddy\n",
    "        self.kids = list(kids)\n",
    "        self._number_of_kids = len(self.kids)\n",
    "        self._family_size = 2 + self.number_of_kids\n",
    "\n",
    "    @property\n",
    "    def number_of_kids(self):\n",
    "        return self._number_of_kids\n",
    "    @number_of_kids.setter\n",
    "    def number_of_kids(self, val):\n",
    "        time.sleep(0.01)  # mimic a long calculation\n",
    "        self._number_of_kids = val\n",
    "\n",
    "    @property\n",
    "    def family_size(self):\n",
    "        return self._family_size\n",
    "    @family_size.setter\n",
    "    def family_size(self, val):\n",
    "        time.sleep(0.01)  # mimic a long calculation\n",
    "        self._family_size = val\n",
    "\n",
    "    def add_child(self, child):\n",
    "        self.kids.append(child)\n",
    "        self._number_of_kids = len(self.kids)\n",
    "        self._family_size = 2 + self.number_of_kids"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "before: \n",
      "The Doe family is made up of Jon, Dawn, \n",
      "and their 2 kids: \n",
      "Johnny\n",
      "Sussy\n",
      "\n",
      "after: \n",
      "The Doe family is made up of Jon, Dawn, \n",
      "and their 3 kids: \n",
      "Johnny\n",
      "Sussy\n",
      "Rosy\n",
      "\n"
     ]
    }
   ],
   "source": [
    "family_2 = EagerFamily(dawn, jon, johnny, sussy)\n",
    "print('before: {}'.format(family_2))\n",
    "\n",
    "rosy = Child('Rosy', 'Doe', 'female', datetime.date(2017, 1, 19))\n",
    "family_2.add_child(rosy)\n",
    "print('after: {}'.format(family_2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On the surface, these two different Family definitions seems to perform the same function.  They differ in how they are calculating some of the properties, particularly `family_size` and `number_of_kids`.  In the `LazyFamily`, nothing is calculated until it is asked for.  In the `EagerFamily`, the calculations are performed as soon the information is available then cached or stored until needed.  In this example, the operations are fairly minimal, so I added a 10 ms `sleep` before the calculation in both family definitions.  This provides a clear comparison between the timing results of the two different approaches.\n",
    "\n",
    "Here I query the `family_size` five times.  In the lazy case, this means the computation to get the `family_size` must be performed five times instead of just once."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "lazy family: 0.101731061935s\n",
      "eager family: 0.000468015670776s\n",
      "eager family was 217.366785532x faster than the lazy family\n"
     ]
    }
   ],
   "source": [
    "n = 5\n",
    "\n",
    "t0 = time.time()\n",
    "for i in range(n):\n",
    "    lazy_family_size = family_1.family_size\n",
    "t_lazy = time.time() - t0\n",
    "\n",
    "t0 = time.time()\n",
    "for i in range(n):\n",
    "    eager_family_size = family_2.family_size\n",
    "t_eager = time.time() - t0\n",
    "\n",
    "print(\"lazy family: {}s\".format(t_lazy))\n",
    "print(\"eager family: {}s\".format(t_eager))\n",
    "x_faster = t_lazy / t_eager\n",
    "print(\"eager family was {}x faster than the lazy family\".format(x_faster))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice how large of a difference this was!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or I can just use the `%timeit` magic function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10 loops, best of 3: 20.2 ms per loop\n"
     ]
    }
   ],
   "source": [
    "%timeit family_1.family_size"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The slowest run took 12.12 times longer than the fastest. This could mean that an intermediate result is being cached.\n",
      "1000000 loops, best of 3: 256 ns per loop\n"
     ]
    }
   ],
   "source": [
    "%timeit family_2.family_size"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note how this confirms that for the eager case, the value only had to be computed once."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}