12 Object-oriented design.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Object-oriented design\n",
    "\n",
    "## Introduction\n",
    "\n",
    "Object-oriented programming and design is an approach that is based around 'objects'. \n",
    "You have already been working\n",
    "regularly with objects such as lists, tuples, dictionaries, and NumPy arrays.\n",
    "\n",
    "The topic of object-oriented programming is a whole lecture course on its own, so in this notebook \n",
    "we will focus on:\n",
    "\n",
    "- Classes\n",
    "- Attributes of objects\n",
    "- Class methods\n",
    "\n",
    "We will do this primarily by example. We will not discuss [inheritance](https://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming)) and [polymorphism](https://en.wikipedia.org/wiki/Polymorphism_(computer_science)).\n",
    "\n",
    "Python supports the object-oriented programming paradigm; in fact, everything in Python is an object.\n",
    "You have been using concepts from object-oriented computing throughout this course.\n",
    "\n",
    "\n",
    "### Objectives\n",
    "\n",
    "- Appreciate objects as instantiations of classes\n",
    "- Understanding of attributes and methods of classes\n",
    "- Learn to create simple classes\n",
    "- Implement and use class methods"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will be using NumPy, so we import it here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: Numpy array objects\n",
    "\n",
    "Consider a NumPy array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[ 1 -4  7]\n",
      " [ 2  6 -1]]\n"
     ]
    }
   ],
   "source": [
    "A = np.array([[1, -4, 7], [2, 6, -1]])\n",
    "print(A)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We already know how to check the type of an object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'numpy.ndarray'>\n"
     ]
    }
   ],
   "source": [
    "print(type(A))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This says that `A` is an *instantiation* of the class `numpy.ndarray`. You can read this as '`A` is a `numpy.ndarray`'.\n",
    "\n",
    "So what is a `numpy.ndarray`? It is a class that has *attributes* and *member functions*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Attributes\n",
    "\n",
    "Attributes are *data* that belong to an object. The array `A` has a number of attributes. An attribute we have seen already is `shape`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 3)\n"
     ]
    }
   ],
   "source": [
    "s = A.shape\n",
    "print(s)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Every object of type `numpy.ndarray` has the attribute `shape` which describes the number of entries in the array in each direction. Other attributes are `size`, which is the total number of entries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "6\n"
     ]
    }
   ],
   "source": [
    "s = A.size\n",
    "print(s)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and `ndim`, which is the number of array dimensions (i.e. 1 for a vector, 2 for a matrix): "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2\n"
     ]
    }
   ],
   "source": [
    "d = A.ndim\n",
    "print(d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that after an attribute name there are no braces, i.e. no `()`. This is a feature of attributes - we are\n",
    "just accessing some data that belongs to an object. We are not calling a function or doing any computational work."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Methods\n",
    "\n",
    "Methods are *functions* that are associated with a class, and perform operations on the data associated with an instantiation of a class. A `numpy.ndarray` object has a method '`min`', which returns the minimum entry in \n",
    "the array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-4\n"
     ]
    }
   ],
   "source": [
    "print(A.min())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Methods are functions, and as functions can take arguments. For example, we can use the method `sort` to sort the rows of an array: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[-4  1  7]\n",
      " [-1  2  6]]\n"
     ]
    }
   ],
   "source": [
    "A.sort(kind='quicksort')\n",
    "print(A)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "where we have called the `sort` method that belongs to `numpy.ndarray`, and we have passed an argument that specifies that it should use quicksort."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Object methods can take other objects as arguments. Given a two-dimensional array (matrix) $A$ and\n",
    "a one-dimensional array (vector) $x$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1. 1. 1.]\n"
     ]
    }
   ],
   "source": [
    "A = np.array([[1, -4, 7], [2, 6, -1]])\n",
    "\n",
    "x = np.ones(A.shape[1])\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can compute $b = Ax$ using the `dot` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[4. 7.]\n"
     ]
    }
   ],
   "source": [
    "b = A.dot(x)\n",
    "print(b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finding class attributes and methods\n",
    "\n",
    "Class attributes and methods are usually listed in documentation. For `numpy.ndarray`, all attributes and methods are listed and explained at https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html.\n",
    "\n",
    "Using Jupyter (or IPython) you can use 'tab-completion' to see the available attributes and methods. You will often know from the name which one you need."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating classes\n",
    "\n",
    "Sometimes we cannot find a class (object type) that suits our problem. In this case we can make our own.\n",
    "As a simple example, consider a class that holds a person's surname and forename:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "class PersonName:\n",
    "    def __init__(self, surname, forename):\n",
    "        self.surname = surname  # Attribute\n",
    "        self.forename = forename  # Attribute\n",
    "        \n",
    "    # This is a method\n",
    "    def full_name(self):\n",
    "        \"Return full name (forename surname)\"\n",
    "        return self.forename + \" \" + self.surname\n",
    "\n",
    "    # This is a method\n",
    "    def surname_forename(self, sep=\",\"):\n",
    "        \"Return 'surname, forename', with option to specify separator\"\n",
    "        return self.surname + sep + \" \" + self.forename"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before dissecting the syntax of this class, we will use it. \n",
    "We first create an object (an instantiation) of type `PersonName`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class '__main__.PersonName'>\n"
     ]
    }
   ],
   "source": [
    "name_entry = PersonName(\"Bloggs\", \"Joanna\")\n",
    "print(type(name_entry))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We first test the attributes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Bloggs\n",
      "Joanna\n"
     ]
    }
   ],
   "source": [
    "print(name_entry.surname)\n",
    "print(name_entry.forename)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we test the class methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Joanna Bloggs\n",
      "Bloggs, Joanna\n",
      "Bloggs; Joanna\n"
     ]
    }
   ],
   "source": [
    "name = name_entry.full_name()\n",
    "print(name)\n",
    "\n",
    "name = name_entry.surname_forename()\n",
    "print(name)\n",
    "\n",
    "name = name_entry.surname_forename(\";\")\n",
    "print(name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dissecting the class, it is declared by\n",
    "```python\n",
    "class PersonName:\n",
    "```\n",
    "We then have what is known as the *intialiser*:\n",
    "```python\n",
    "    def __init__(self, surname, forename):\n",
    "        self.surname = surname\n",
    "        self.forename = forename\n",
    "```\n",
    "This is the 'function' that is called when we create an object, i.e. when we use `name_entry = PersonName(\"Bloggs\", \"Joanna\")`. The keyword '`self`' refers to the object itself - it can take time to \n",
    "develop an understanding of `self`. The initialiser in this case stores the surname and forename of the person (attributes). You can test when the initialiser is called by inserting a print statement.\n",
    "\n",
    "This class has two methods:\n",
    "```python\n",
    "    def full_name(self):\n",
    "        \"Return full name (forname surname)\"\n",
    "        return self.forename + \" \" + self.surname\n",
    "\n",
    "    def surname_forename(self, sep=\",\"):\n",
    "        \"Return 'surname, forname', with option to specify separator\"\n",
    "        return self.surname + sep + \" \" + self.forename\n",
    "```\n",
    "These methods are functions that do something with the class data. In this case, from the forename and surname\n",
    "they return the full name of the person, formatted in different ways."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Operators\n",
    "\n",
    "Operators like `+`, `-`, `*` and `/` are actually functions - in Python they are shorthand for functions with \n",
    "the names `__add__`, `__sub__`, `__mul__` and `__truediv__`, respectively. By\n",
    "adding these methods to a class, we can define what the mathematical operators should do."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Mixed-up maths\n",
    "\n",
    "Say we want to create our own numbers with their own operations. As a simple (and very silly) example, \n",
    "we decide we want to change notation such that '`*`' means division and '`/`' means multiplication.\n",
    "\n",
    "To switch '`*`' and '`/`' for our special numbers, we create a class to represent our special numbers, and\n",
    "provide it with its own `__mul__` and `__truediv__` functions.\n",
    "We will also provide the method `__str__(self)` - this is called when we use the `print` function. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "class crazynumber:\n",
    "    \"A crazy number class that switches the mutliplcation and division operations\"\n",
    "    \n",
    "    # Initialiser\n",
    "    def __init__(self, x):\n",
    "        self.x = x  # This is an attribute\n",
    "\n",
    "    # Define multiplication (*) (this is a method)\n",
    "    def __mul__(self, y):\n",
    "        return crazynumber(self.x/y.x)\n",
    "\n",
    "    # Define the division (/) (this is a method)\n",
    "    def __truediv__(self, y):\n",
    "        return crazynumber(self.x*y.x)\n",
    "    \n",
    "    # This is called when we use 'print' (this is a method)\n",
    "    def __str__(self):\n",
    "        return str(self.x)  # Convert type to a string and return"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> *Note:* the method names `__mul__`, ` __truediv__`, `__str__`, etc, should not be called directly. They \n",
    "> are mapped by Python to operators (`*` and `/` in the first two cases). The method `__str__` is called behind the scenes when using `print`.\n",
    "\n",
    "We now create two `crazynumber` objects:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "u = crazynumber(10)\n",
    "v = crazynumber(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since we have defined `*` to be division, we expect u\\*v to be equal to 5:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5.0\n"
     ]
    }
   ],
   "source": [
    "a = u*v  # This will call '__mul__(self, y)'\n",
    "print(a)  # This will call '__str__(self)'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Testing '`/`':"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "20\n"
     ]
    }
   ],
   "source": [
    "b = u/v\n",
    "print(b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By providing methods, we have defined how the mathematical operators should be interpreted."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Equality testing\n",
    "\n",
    "We have previously used library versions of sorting functions, and seen that they are much faster than our own implementations. What if we have a list of our own objects that we want to sort? For example,\n",
    "we might have a `StudentEntry` class, and then have a list with a `StudentEntry` object for each student.\n",
    "The built-in sort functions cannot know how we want to sort our list.\n",
    "\n",
    "Another case is if we have a list of numbers, and we we want to sort according to a custom rule.\n",
    "\n",
    "The built-in sort functions do not care about the details of our data. All they rely on\n",
    "are *comparisons*, e.g. the `<`, `>`, and `==` operators. If we equip our class with comparison operators,\n",
    "we can use built-in sorting functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Custom sorting\n",
    "\n",
    "Say we want to sort a list of numbers such that all even numbers appear before odd numbers, but otherwise the usual ordering rule applies. We do not want to write our own sorting function. We can do this custom sorting by creating our own class for holding a number and equipping it with `<`, `>`, and `==` operators.\n",
    "The functions corresponding to the operators are:\n",
    "\n",
    "- `__lt__(self, other)` (less than `other`, `<`)\n",
    "- `__gt__(self, other)` (greater than `other`, `>`)\n",
    "- `__eq__(self, other)` (equal to `other`, `==`)\n",
    "\n",
    "The functions return `True` or `False`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below is a class for storing a number which obeys our custom ordering rules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyNumber:\n",
    "\n",
    "    def __init__(self, x):\n",
    "        self.x = x  # Store value (attribute)\n",
    "        \n",
    "    # Custom '<' operator (method)\n",
    "    def __lt__(self, other):\n",
    "        if self.x % 2 == 0 and other.x % 2 != 0:  # I am even, other is odd, so I am less than                   \n",
    "            return True\n",
    "        elif self.x % 2 != 0 and other.x % 2 == 0:  # I am odd, other is even, so I am not less than \n",
    "            return False\n",
    "        else:\n",
    "            return self.x < other.x  # Use usual ordering of numbers\n",
    "\n",
    "    # Custom '==' operator (method)\n",
    "    def __eq__(self, other):\n",
    "        return self.x == other.x\n",
    "\n",
    "    # Custom '>' operator (method)\n",
    "    def __gt__(self, other):\n",
    "        if self.x % 2 == 0 and other.x % 2 != 0:  # I am even, other is odd, so I am not greater                    \n",
    "            return False\n",
    "        elif self.x % 2 != 0 and other.x % 2 == 0:  # I am odd, other is even, so I am greater                    \n",
    "            return True\n",
    "        else:\n",
    "            return self.x > other.x  # Use usual ordering of numbers\n",
    "\n",
    "    # This function is called by Python when we try to print something   \n",
    "    def __repr__(self):\n",
    "        return str(self.x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can perform some simple tests on the operators (insert print statements into the methods if you want\n",
    "to verify which function is called)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "x = MyNumber(4)\n",
    "y = MyNumber(3)\n",
    "print(x < y)  # Expect True (since x is even and y is odd)\n",
    "print(y < x)  # Expect False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now try applying the built-in list sort function to check that the sorted list obeys our \n",
    "custom sorting rule:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[2, 20, 44, 3, 23, 85, 105, 109, 135, 149]\n"
     ]
    }
   ],
   "source": [
    "# Create an array of random integers\n",
    "x = np.random.randint(0, 200, 10)\n",
    "\n",
    "# Create a list of 'MyNumber' from x (using list comprehension)\n",
    "y = [MyNumber(v) for v in x]\n",
    "\n",
    "# This is the long-hand for building y\n",
    "#y = []\n",
    "#for v in x:\n",
    "#    y.append(MyNumber(v))\n",
    "\n",
    "# Use the built-in list sort method to sort the list of 'MyNumber' objects\n",
    "y.sort()\n",
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Without modifying the sort algorithm, we have applied our own ordering. Approaches like this are a feature of \n",
    "object-oriented computing. The sort algorithms sort *objects*, and the objects simply need\n",
    "the comparison operators. The sort algorithms do not need to know the details of the objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using the magic methods\n",
    "\n",
    "The special Python methods that begin and end with double underscore (`__`) are *magic* methods. They map to special operators, typically mathematical operators such as `*`, `/`, `<`, `==`, etc.\n",
    "\n",
    "They are standard methods in that they can be called directly on an object, but this is not their intended use.\n",
    "Use operators instead. Below is an example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "class SomePair:\n",
    "    def __init__(self, x, y):\n",
    "        self.x = x  # Store value (attribute)\n",
    "        self.y = y  # Store value (attribute)\n",
    "\n",
    "    # '==' operator (note that it has a return value)\n",
    "    def __eq__(self, other):\n",
    "        return self.x == other.x and self.y == other.y\n",
    "    \n",
    "a = SomePair(23, 2)\n",
    "b = SomePair(23, 4)\n",
    "\n",
    "# Check for equality using ==\n",
    "print(a == b)\n",
    "\n",
    "# Check for equality using __eq__ (not recommended)\n",
    "print(a.__eq__(b))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An object does not need to have all the magic functions defined - just the ones you intend to use. If you try to use\n",
    "and operator that is not defined you will get an error."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercises\n",
    "\n",
    "Complete now the [12 Exercises](Exercises/12%20Exercises.ipynb) notebook."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}