Python's Class Development Toolkit/Python's Class Development Toolkit.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python's Class Development Toolkit (Raymond Hettinger, 2013)\n",
    "\n",
    "This is a YouTube video of a talk by Raymond Hettinger at US Pycon 2013.\n",
    "\n",
    "----\n",
    "\n",
    "\n",
    "[![](http://img.youtube.com/vi/HTLu2DFOdTg/0.jpg)](http://www.youtube.com/watch?v=HTLu2DFOdTg \"Python's Class Development Toolkit\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Case Study: Circuitous, LLC\n",
    "\n",
    "\n",
    "## Docstrings\n",
    "\n",
    "```python\n",
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "```\n",
    "\n",
    "- Put at the top of the module\n",
    "- What to put in doctrings - \"your elevator pitch &mdash; what the heck it is you're trying to do\".\n",
    "\n",
    "## Start Coding: Circle Class\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "\n",
    "class Circle:\n",
    "    'An advanced circle analytic toolkit'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "❎ - Did not start with `pass`.\n",
    "\n",
    "✅ - Started with `docstring`.\n",
    "\n",
    "**Why start with the documentation?**\n",
    "\n",
    "1. Nice to be fully documented at any time\n",
    "2. Particularly nice to be able to run it through a nice tool like Sphinx and get a PDF out of it; hand it to a product manager and, before you've written your first line of code, say \"Can you go sell this?\"\n",
    "3. Or internally to a company, you make the documentation; you hand it to your users and say\"Can you use this?\"\n",
    "\n",
    "## New Style Classes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "\n",
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "**Quick note:**\n",
    "\n",
    "Since the talk is in Python 2.7, things may have been a little different for Python 3. Here's an excerpt from [Stack Overflow | Python class inherits object](https://stackoverflow.com/questions/4015417/python-class-inherits-object):\n",
    "\n",
    "**In Python 2**: always inherit from object explicitly. Get the perks.\n",
    "\n",
    "**In Python 3**: inherit from object if you are writing code that tries to be Python agnostic, that is, it needs to work both in Python 2 and in Python 3. Otherwise don't, it really makes no difference since Python inserts it for you behind the scenes.\n",
    "\n",
    "---\n",
    "\n",
    "## Initialize Instance variables\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "\n",
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius             # instance variable\n",
    "        \n",
    "# init isn't a constructor. Its job is to initialize instance variables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Regular Method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "\n",
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return 3.14 * self.radius ** 2.0\n",
    "    \n",
    "# Regular methods have \"self\" as first argument\n",
    "\n",
    "\n",
    "# Hmm, what about the 3.14?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`self` is a convention. It could be `this` or `s` but you want your Python program to look like Python to other Python programmers.\n",
    "\n",
    "**Side story:**\n",
    "\n",
    "GvR spent 3 months building the language with modules and functions and got it working fairly well but it wasn't object oriented. \"Oooh I need to add objects\" He indented all the `def`s. He took the functions that he already had and ran them in their own namespace. If you cut the code out of the class and stick it in a separate module and import it, it looks remarkably like the class dictionary.\n",
    "\n",
    "The way the class works is that definitions run as if they were in their own module. The module dictionary becomes the class dictionary.\n",
    "\n",
    "GvR simply indented the functions, stored them in a class dictionary; he need a way to get to them. The only programming that was necessary was to program the *dot* (?) &mdash; the dot would look up and reach inside other class, find the function and take the first argument and fill in `self` for you."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modules for code re-use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "\n",
    "import math\n",
    "\n",
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return math.pi * self.radius ** 2.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Why is `math.pi` better?\n",
    "\n",
    "1. It makes sure we use the same `pi` all throughout the code.\n",
    "2. Maximizing code reuse\n",
    "3. Is `pi` a constant? More like a \"*variable that never changes*\"\n",
    "\n",
    "Old version &mdash; 32-bit version of pi\n",
    "\n",
    "Modern version &mdash; 64-bit version of pi\n",
    "\n",
    "---\n",
    "\n",
    "**YAGNI** (You Ain't Gonna Need It)\n",
    "\n",
    "\"The more you throw in, the less agile you get.\"\n",
    "\n",
    "Commit. Push. Ship the product. You get the MVP (Minimum Viable Product).\n",
    "\n",
    "## Class Variables for shared data\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "\n",
    "import math\n",
    "\n",
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.1'                      # class variable\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return math.pi * self.radius ** 2.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Version number &mdash; don't use floating point numbers\n",
    "\n",
    "## Minimum Viable Product: Ship it!\n",
    "\n",
    "**Quick note**: I used Python 3 for below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuitous version 0.1\n",
      "A circle of radius 10\n",
      "has an area of 314.1592653589793\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Tutorial\n",
    "\n",
    "print('Circuitous version', Circle.version)\n",
    "c = Circle(10)\n",
    "print('A circle of radius', c.radius)\n",
    "print('has an area of', c.area())\n",
    "print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# First customer: Academia"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Using Circuitous(tm) version 0.1\n",
      "The average area of 10 random circles\n",
      "is 1.0\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from random import random, seed\n",
    "\n",
    "seed(8675309)\n",
    "print('Using Circuitous(tm) version', Circle.version)\n",
    "n = 10\n",
    "circles = [Circle(random()) for i in range(n)]\n",
    "print('The average area of', n, 'random circles')\n",
    "avg = sum([c.area() for c in circles])/len(circles)\n",
    "print(f'is {avg:.1f}')\n",
    "print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Rubber sheet company: Next customer wants a perimeter method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Circuitous, LLC - \n",
    "An Advanced Circle Analytics Company\n",
    "\n",
    "'''\n",
    "\n",
    "import math\n",
    "\n",
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.2'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return math.pi * self.radius ** 2.0\n",
    "    \n",
    "    def perimeter(self):\n",
    "        return 2 * math.pi * self.radius\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A circlet with a radius of 0.1\n",
      "has a perimeter of 0.6283185307179586\n",
      "and a cold area of 0.031415926535897934\n",
      "and a warm area of 0.038013271108436504\n",
      "\n",
      "A circlet with a radius of 0.7\n",
      "has a perimeter of 4.39822971502571\n",
      "and a cold area of 1.5393804002589984\n",
      "and a warm area of 1.8626502843133883\n",
      "\n",
      "A circlet with a radius of 0.8\n",
      "has a perimeter of 5.026548245743669\n",
      "and a cold area of 2.0106192982974678\n",
      "and a warm area of 2.4328493509399363\n",
      "\n"
     ]
    }
   ],
   "source": [
    "cuts = [0.1, 0.7, 0.8]\n",
    "circles = [Circle(r) for r in cuts]\n",
    "for c in circles:\n",
    "    print('A circlet with a radius of', c.radius)\n",
    "    print('has a perimeter of', c.perimeter())\n",
    "    print('and a cold area of', c.area())\n",
    "    c.radius *=1.1\n",
    "    print('and a warm area of', c.area())\n",
    "    print()\n",
    "\n",
    "\n",
    "    \n",
    "# Hmm, how do we feel about exposing the radius variable?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Python, exposing attributes is common and normal."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Third customer: National Tire Company"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Tire(Circle):\n",
    "    'Tires are circles with a corrected perimeter'\n",
    "    \n",
    "    def perimeter(self):\n",
    "        'Circumference corrected for perimeter'\n",
    "        return Circle.perimeter(self) * 1.25"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A tire of radius 22\n",
      "has an inner area of 1520.53084433746\n",
      "and an odometer corrected area of\n",
      "172.7875959474386\n",
      "\n"
     ]
    }
   ],
   "source": [
    "t = Tire(22)\n",
    "print('A tire of radius', t.radius)\n",
    "print('has an inner area of', t.area())\n",
    "print('and an odometer corrected area of')\n",
    "print(t.perimeter())\n",
    "print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Next customer: National Graphics Company\n",
    "\n",
    "```python\n",
    "bbd = 25.1\n",
    "c = Circle(bbd_to_radius(bbd))\n",
    "print('A circle with a bbd of 25.1')\n",
    "print('has an radius of', c.radius)\n",
    "print('and an area of', c.area())\n",
    "print()\n",
    "\n",
    "# The API is awkward. A converter function is always needed.\n",
    "# Perhaps change the constructor signature?\n",
    "```\n",
    "\n",
    "\n",
    "### Need an alternative constructor\n",
    "\n",
    "Below are examples of alternative constructors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2013-03-16 00:00:00\n",
      "2013-03-16 05:40:16\n",
      "2010-08-16 00:00:00\n",
      "2021-02-02 12:29:23.242527\n",
      "{'raymond': None, 'rachel': None, 'matthew': None}\n"
     ]
    }
   ],
   "source": [
    "from datetime import datetime\n",
    "\n",
    "print(datetime(2013,3,16))\n",
    "print(datetime.fromtimestamp(1363383616))\n",
    "print(datetime.fromordinal(734000))\n",
    "print(datetime.now())\n",
    "\n",
    "print(dict.fromkeys(['raymond', 'rachel', 'matthew']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`datetime` provides several different ways to make a `datetime` object.\n",
    "\n",
    "### Class Methods create alternative constructors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.3'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return math.pi * self.radius ** 2.0\n",
    "    \n",
    "    def perimeter(self):\n",
    "        return 2 * math.pi * self.radius\n",
    "    \n",
    "    @classmethod                  # alternative constructor\n",
    "    def from_bbd(cls, bbd):\n",
    "        'Construct a circle from a bounding box diagonal'\n",
    "        radius = bbd / 2.0 / math.sqrt(2.0)\n",
    "        return (Circle(radius))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A circle with a bbd of 25.1\n",
      "has an radius of 8.874190103891172\n",
      "and an area of 247.4043484610132\n",
      "\n"
     ]
    }
   ],
   "source": [
    "c = Circle.from_bbd(25.1)\n",
    "print('A circle with a bbd of 25.1')\n",
    "print('has an radius of', c.radius)\n",
    "print('and an area of', c.area())\n",
    "print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### It should also work for subclasses"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Tire(Circle):\n",
    "    'Tires are circles with a corrected perimeter'\n",
    "    \n",
    "    def perimeter(self):\n",
    "        'Circumference corrected for perimeter'\n",
    "        return Circle.perimeter(self) * 1.25"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A tire of radius 15.909902576697318\n",
      "has an inner area of 795.2156404399163\n",
      "and an odometer corrected area of\n",
      "99.96486610856323\n",
      "\n"
     ]
    }
   ],
   "source": [
    "t = Tire.from_bbd(45)\n",
    "print('A tire of radius', t.radius)\n",
    "print('has an inner area of', t.area())\n",
    "print('and an odometer corrected area of')\n",
    "print(t.perimeter())\n",
    "print()\n",
    "\n",
    "\n",
    "# Hmm, this code doesn't work"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`from_bbd` is hardwired to make a Circle."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "__main__.Circle"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(t)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### anticipate subclassing"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.3'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return math.pi * self.radius ** 2.0\n",
    "    \n",
    "    def perimeter(self):\n",
    "        return 2 * math.pi * self.radius\n",
    "    \n",
    "    @classmethod                  # alternative constructor\n",
    "    def from_bbd(cls, bbd):\n",
    "        'Construct a circle from a bounding box diagonal'\n",
    "        radius = bbd / 2.0 / math.sqrt(2.0)\n",
    "        return cls(radius)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## New customer request: add a function\n",
    "\n",
    "```python\n",
    "def angle_to_grade(angle):\n",
    "    'Convert angle in degree to a percentage grade'\n",
    "    return math.tan(math.radians(angle)) * 100.0\n",
    "\n",
    "# Will this also work for the Sphere class and the Hyperbolic class?\n",
    "# Can people even find this code?\n",
    "```\n",
    "\n",
    "### Move function to a regular method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.4b'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def angle_to_grade(self, angle):\n",
    "        'Convert angle in degree to a percentage grade'\n",
    "        return math.tan(math.radians(angle)) * 100.0\n",
    "        \n",
    "# Well, findability has been improved and it won't be called in the wrong context\n",
    "# Really? You have to create an instance just to call function?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Move function to a static method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.4'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    @staticmethod                          # attach functions to classes\n",
    "    def angle_to_grade(angle):\n",
    "        'Convert angle in degree to a percentage grade'\n",
    "        return math.tan(math.radians(angle)) * 100.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Government Request: ISO-11110\n",
    "\n",
    "(It's a made-up ISO, don't worry)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.5b'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        p = self.perimeter()\n",
    "        r = p / math.pi / 2.0\n",
    "        return math.pi ** r ** 2.0\n",
    "        \n",
    "    def perimeter(self):\n",
    "        return 2.0 * math.pi * self.radius"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Tire(Circle):\n",
    "    'Tires are circles with an odometer corrected perimeter'\n",
    "    \n",
    "    def perimeter(self):\n",
    "        'Circumference corrected for the rubber'\n",
    "        return Circle.perimeter(self) * 1.25"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The change in the `Circle` class breaks the `Tire` subclass perimeter. The variable `self` doesn't mean you; it means you OR your children.\n",
    "\n",
    "**There must be a better way!™**\n",
    "\n",
    "### Class Local Reference: keep a spare copy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.5b'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        p = self._perimeter()\n",
    "        r = p / math.pi / 2.0\n",
    "        return math.pi ** r ** 2.0\n",
    "        \n",
    "    def perimeter(self):\n",
    "        return 2.0 * math.pi * self.radius\n",
    "    \n",
    "    _perimeter = perimeter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Problem**: Tire company also kept their own `_perimeter` variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Tire(Circle):\n",
    "    'Tires are circles with an odometer corrected perimeter'\n",
    "    \n",
    "    def perimeter(self):\n",
    "        'Circumference corrected for the rubber'\n",
    "        return Circle.perimeter(self) * 1.25\n",
    "    \n",
    "    _perimeter = perimeter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copying game. :(\n",
    "\n",
    "**Solution**: Name should be `_tire_perimeter` and `_circle_perimeter`.\n",
    "\n",
    "This implementation should be the same as below (double underscores):\n",
    "\n",
    "### Class local reference using the double underscore"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.5b'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        p = self.__perimeter()\n",
    "        r = p / math.pi / 2.0\n",
    "        return math.pi ** r ** 2.0\n",
    "        \n",
    "    def perimeter(self):\n",
    "        return 2.0 * math.pi * self.radius"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The purpose of the double underscore is what we call a `class local reference`; we're making sure that the `self` actually refers to you. Most of the time, `self` means you or your children, but occasionally, you need it to be you.\n",
    "\n",
    "The intention is **not** about privacy."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Government Request: ISO-22220\n",
    "\n",
    "- We insist on one \"little change\"\n",
    "- You're **not** allowed to store the `radius`.\n",
    "- You must store the `diameter` instead!\n",
    "\n",
    "These requests will break the entire `Circle` class but we must keep the API the same!\n",
    "\n",
    "Java and C++ programmers would have just wished they had set up `getters` and `setters`.\n",
    "\n",
    "**There must be a better way!™**\n",
    "\n",
    "## Convert attribute access to method access: property"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.6'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    @property                         # convert dotted access to method calls\n",
    "    def radius(self):\n",
    "        'Radius of a circle'\n",
    "        return self.diameter / 2.0\n",
    "    \n",
    "    @radius.setter\n",
    "    def radius(self, radius):\n",
    "        self.diameter = radius * 2.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\"What `property` does for you is after the fact (that) without changing the rest of our code, any of our code or any client code, we can add this in and magically every time we set `radius` including in our own code, this will no longer store on the instance variable; this will call this `setter` and actually store the diameter.\n",
    "\n",
    "This is why in Python, we don't have to fear exposing your attributes. Even if you never use `property` it's a big win for you. Why? Because Python APIs are clean and beautiful. They don't have `getters` and `setters` everywhere. In fact, if you find yourself designing a `getter` and `setter`, you're probably doing it wrong. All you're doing is making it awkward for your users to access; dotted access is a lot easier. If you actually need to make a change later, after the fact, it's really easy to do by putting in a `property`.\"\n",
    "\n",
    "\n",
    "# User Request: Many Circles"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Reloading earlier version of the Circle class.\n",
    "This is not part of the slide.\n",
    "'''\n",
    "\n",
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    version = '0.1'                      # class variable\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return math.pi * self.radius ** 2.0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Using Circuitous(tm) version 0.1\n",
      "The average area of 10000000 random circles\n",
      "is 1.0\n",
      "\n"
     ]
    }
   ],
   "source": [
    "n = 10000000\n",
    "\n",
    "seed(8675309)\n",
    "print('Using Circuitous(tm) version', Circle.version)\n",
    "circles = [Circle(random()) for i in range(n)]\n",
    "print('The average area of', n, 'random circles')\n",
    "avg = sum([c.area() for c in circles])/len(circles)\n",
    "print(f'is {avg:.1f}')\n",
    "print()\n",
    "\n",
    "# I sense a major problem.\n",
    "# Circle instances are over 300 bytes each!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Flyweight Design Patterns: Slots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Circle(object):\n",
    "    'An advanced circle analytic toolkit'\n",
    "    \n",
    "    # flyweight desing pattern suppresses\n",
    "    # the instance dictionary\n",
    "    __slots__ = ['diameter']\n",
    "    version = '0.7'\n",
    "    \n",
    "    def __init__(self, radius):\n",
    "        self.radius = radius\n",
    "        \n",
    "    def area(self):\n",
    "        'Perform quadrature on a shape of uniform radius'\n",
    "        return math.pi * self.radius ** 2.0\n",
    "    \n",
    "    @property                         # convert dotted access to method calls\n",
    "    def radius(self):\n",
    "        'Radius of a circle'\n",
    "        return self.diameter / 2.0\n",
    "    \n",
    "    @radius.setter\n",
    "    def radius(self, radius):\n",
    "        self.diameter = radius * 2.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\"What slots will do is say, let's allocate just one `pointer` for the `diameter` and nothing else. No dictionary. You lose the ability to inspect the dictionary. You lose the ability to add additional attributes. This is just an optimization; you always save it for last &mdash; only when you're scaling up to bajillion instances.\"\n",
    "\n",
    "# Summary: Toolkit for New Style Classes\n",
    "\n",
    "1. Inherit from `object()`\n",
    "2. `Instance variables` for information unique to the instance.\n",
    "3. `Class variables` for data shared among all instances.\n",
    "4. `Regular methods` need \"self\" to operate on instance data.\n",
    "5. `Class methods` implement alternative constructors. They need `cls` so they can create subclasses as well.\n",
    "6. `Static methods` attach functions to classes. They don't need either \"self\" or \"cls\". Static methods improve discoverability and require context to be specified.\n",
    "7. A `property()` lets getter and setter methods be invoked automatically by attribute access. This allows Python classes to freely expose their instance variables.\n",
    "8. The \"`__slots`\" variable implements the Flyweight Design Pattern by suppressing instance dictionaries."
   ]
  }
 ],
 "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.8.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}