docs/Module4_OOP/Introduction_to_OOP.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. meta::\n",
    "   :description: Topic: Introducing object oriented programming in python, Difficulty: Easy, Category: Section\n",
    "   :keywords: class, type, creation, definition, intro, overview, basics, meaning"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to Object Oriented Programming\n",
    "\n",
    "Our first foray into the essentials of Python introduced us to the [basic object types: numbers, strings, and lists](http://www.pythonlikeyoumeanit.com/Module2_EssentialsOfPython/Basic_Objects.html). Likewise, our discussion of NumPy was centered around the [N-dimensional array](http://www.pythonlikeyoumeanit.com/Module3_IntroducingNumpy/IntroducingTheNDarray.html). These types of objects are distinguished in large part by the different functions that are bound to them. Functions bound to objects are known as **methods**. For example, where a string possesses methods designed to manipulate its sequence of characters, a NumPy array possesses methods for operating on the numerical data bound to that array.\n",
    "\n",
    "```python\n",
    "# Different types of objects can possess different methods \n",
    "\n",
    ">>> string = \"hello world\"\n",
    ">>> string.capitalize() # use the string-method `capitalize`\n",
    "'Hello world'\n",
    "\n",
    ">>> import numpy as np\n",
    ">>> array = np.array([[0, 1, 2],\n",
    "...                   [3, 4, 5]])\n",
    ">>> array.sum()  # use the array-method `sum`\n",
    "15\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More generally, an object can possess data, known as **attributes**, which summarize information about that object. For example, the array-attributes `ndim` and `shape` provide information about the indexing-layout of that array's numerical data.\n",
    "\n",
    "```python\n",
    "# accessing an object's attributes\n",
    ">>> array.ndim\n",
    "2\n",
    ">>> array.shape\n",
    "(2, 3)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this module, we will learn to define our own, customized object types with distinct collections of attributes and methods. In this way, we will be using Python as an \"objected oriented\" programming language; this will greatly expand our capabilities as Python users, and deepen our understanding of the language itself.\n",
    "\n",
    "As a sneak peek example, let's create our own class of objects known as `Rectangle`:\n",
    "\n",
    "```python\n",
    "class Rectangle:\n",
    "    \"\"\" A Python object that describes the properties of a rectangle \"\"\"\n",
    "    def __init__(self, width, height, center=(0.0, 0.0)):\n",
    "        \"\"\" Sets the attributes of a particular instance of `Rectangle`.\n",
    "\n",
    "            Parameters\n",
    "            ----------\n",
    "            width : float\n",
    "                The x-extent of this rectangle instance.\n",
    "\n",
    "            height : float\n",
    "                The y-extent of this rectangle instance.\n",
    "\n",
    "            center : Tuple[float, float], optional (default=(0, 0))\n",
    "                The (x, y) position of this rectangle's center\"\"\"\n",
    "        self.width = width    \n",
    "        self.height = height  \n",
    "        self.center = center\n",
    "    \n",
    "    def __repr__(self):\n",
    "        \"\"\" Returns a string to be used as a printable representation \n",
    "            of a given rectangle.\"\"\"\n",
    "        return \"Rectangle(width={w}, height={h}, center={c})\".format(h=self.height,\n",
    "                                                                     w=self.width,\n",
    "                                                                     c=self.center)\n",
    "\n",
    "    def compute_area(self):\n",
    "        \"\"\" Returns the area of this rectangle \n",
    "\n",
    "            Returns\n",
    "            -------\n",
    "            float\"\"\"\n",
    "        return self.width * self.height\n",
    "\n",
    "    def compute_corners(self):\n",
    "        \"\"\" Computes the (x, y) corner-locations of this rectangle, starting with the\n",
    "            'top-right' corner, and proceeding clockwise. \n",
    "\n",
    "            Returns\n",
    "            -------\n",
    "            List[Tuple[float, float], Tuple[float, float], Tuple[float, float], Tuple[float, float]]\"\"\"\n",
    "        cx, cy = self.center\n",
    "        dx = self.width / 2.0\n",
    "        dy = self.height / 2.0\n",
    "        return [(cx + x, cy + y) for x,y in ((dx, dy), (dx, -dy), (-dx, -dy), (-dx, dy))]\n",
    "```\n",
    "\n",
    "An instance of this `Rectangle` class is an individual rectangle whose *attributes* include its width, height, and center-location. Additionally, we can use the rectangle's *methods* (its attributes that are functions) to compute its area and the locations of its corners. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "# create a rectangle of width 4, height 10, centered at (0, 0)\n",
    "# here __init__ is executed and the width/height/center attributes are set\n",
    ">>> rect1 = Rectangle(4, 10)  \n",
    "\n",
    "# the __repr__ method defines how a rectangle instance will be displayed here\n",
    "# in the console\n",
    ">>> rect1  \n",
    "Rectangle(width=4, height=10, center=(0, 0))\n",
    "\n",
    "# compute the area for this particular rectangle\n",
    ">>> rect1.compute_area()      \n",
    "40\n",
    "\n",
    "# compute the corner-locations of this rectangle\n",
    ">>> rect1.compute_corners()   \n",
    "[(2.0, 5.0), (2.0, -5.0), (-2.0, -5.0), (-2.0, 5.0)]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just like any other Python object that we have encountered, we can put our `Rectangle`s in lists, store them as values in dictionaries, pass them to functions, reference them with multiple variables, and so on.\n",
    "\n",
    "Popular STEM, data analysis, and machine learning Python libraries rely heavily on the ability to define custom classes of Python objects. For example, [pandas](https://pandas.pydata.org/) defines a spreadsheet-like `DataFrame` class; [PyTorch](https://pytorch.org/), [MXNet](https://mxnet.incubator.apache.org/), and [TensorFlow](https://www.tensorflow.org/) each define tensor classes that are capable of [automatic differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation), which is critically important for training neural networks. Understanding Python's class system will greatly improve your ability to leverage libraries like these (Shameless plug: refer to [MyGrad](https://mygrad.readthedocs.io) if you are interested in seeing a simple pure-Python/NumPy implementation of an auto-differentiation library). \n",
    "\n",
    "Moving forward, we will discuss the essential *class definition*, which will permit us to  define our own class (a.k.a. type) of object. Next, we will learn about creating distinct *instances* of a given object type and about defining methods. This will lead to our first encounter with *special methods*, which enable us to affect how our object type behaves with Python's various operators. For example, we can define how the `+` operator interacts with our objects. Lastly, we will briefly discuss the concept of class inheritance. \n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Takeaway:**\n",
    "\n",
    "The goal of this module is to understand how to define and utilize our own class of Python objects. This will greatly mature our understanding of Python as an object-oriented language, and will expand our ability to fully leverage all of Python's features.  \n",
    "\n",
    "</div>\n",
    "\n",
    "## Class vs Type: An Important Note on Terminology\n",
    "Before proceeding any further, it is worthwhile to draw our attention to the fact that the terms \"type\" and \"class\" are practically synonymous in Python. Thus far, we have only encountered the term \"type\" to distinguish objects from one another, e.g. `1` belongs to the type `int` and `\"cat\"` belongs to the type `str`. However, we will soon study *class* definitions for making new types objects, and soon introduce functions like `issubclass` into our lexicon. That being said, know that *class* and *type* mean the same thing! There are historical reasons for the coexistence of these two terms, but [since Python 2.2](https://www.python.org/download/releases/2.2/descrintro/) concepts of type and class have been unified.\n",
    "\n",
    "In practice, people tend to reserve the word \"type\" to refer to built-in types (e.g. `int` and `str`) and \"class\" to refer to user-defined types. Again, in the modern versions of Python, these terms carry no practical distinction."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Takeaway:**\n",
    "\n",
    "The terms \"type\" and \"class\" are synonymous; they both refer to the encapsulating definition of a specific type/class of Python object, with all of its attributes. Although they are not treated synonymously within the Python language - we will write class definitions, not type definitions, and we will use `type` to inspect an object and not `class` - these distinctions are merely relics of versions of Python long passed.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Links to Official Documentation\n",
    "\n",
    "- [Python Tutorial: A First Look at Classes](https://docs.python.org/3/tutorial/classes.html#a-first-look-at-classes)"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "text_representation": {
    "extension": ".md",
    "format_name": "markdown",
    "format_version": "1.3",
    "jupytext_version": "1.13.6"
   }
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}