05-functions-classes-modules-in-python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Programming and Data Analysis\n",
    "\n",
    "> Functions, classes, and modules in Python\n",
    "\n",
    "Kuo, Yao-Jen <yaojenkuo@ntu.edu.tw> from [DATAINPOINT](https://www.datainpoint.com/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Structuring codes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What is structuring codes?\n",
    "\n",
    ">  By \"structure\" we mean the decisions you make concerning how your codes best meet their objectives. We need to consider how to best leverage Python's features to create clean, effective code. In practical terms, \"structure\" means making clean code whose logic and dependencies are clear as well as how the files and folders are organized in the file system.\n",
    "\n",
    "Source: [The Hitchhiker’s Guide to Python](https://docs.python-guide.org/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Why structuring codes?\n",
    "\n",
    "As our codes piled up, we need a mechanism making them:\n",
    "\n",
    "- more reusable\n",
    "- more scalable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Python provides several tools for programmers organizing their codes\n",
    "\n",
    "- Functions\n",
    "- Classes\n",
    "- Modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## How do we decide which tool to adopt?\n",
    "\n",
    "Simply put, that depends on **scale** and project spec."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## These components are mixed and matched with great flexibility\n",
    "\n",
    "- A couple lines of code assembles a function\n",
    "    - A couple of functions assembles a class\n",
    "        - A couple of classes assembles a module\n",
    "            - A couple of modules assembles a larger module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What is a function\n",
    "\n",
    "> A function is a named sequence of statements that performs a computation, either mathematical, symbolic, or graphical. When we define a function, we specify the name and the sequence of statements. Later, we can call the function by name."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Besides built-in functions or library-powered functions, we sometimes need to self-define our own functions\n",
    "\n",
    "- `def` the name of our function\n",
    "- `return` the output of our function\n",
    "\n",
    "```python\n",
    "def function_name(INPUTS: type, ARGUMENTS: type, ...) -> type:\n",
    "    \"\"\"\n",
    "    docstring: print documentation when help() is called\n",
    "    \"\"\"\n",
    "    # sequence of statements\n",
    "    return OUTPUTS\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Various source of functions\n",
    "\n",
    "- Built-in functions: <https://docs.python.org/3/library/functions.html>\n",
    "- Functions defined in standard libraries: <https://docs.python.org/3/library>\n",
    "- Functions defined in third-party libraries.\n",
    "- Functions defined by ourselves."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Built-in functions\n",
    "\n",
    "<https://docs.python.org/3/library/functions.html>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "125"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pow(5, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Functions defined in standard libraries\n",
    "\n",
    "<https://docs.python.org/3/library>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from random import randint\n",
    "\n",
    "randint(1, 11)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Functions defined in third-party libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([3, 9, 5, 9, 2])"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from numpy.random import randint\n",
    "\n",
    "randint(1, 10, size=5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Functions defined by ourselves"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "125"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def power(x: int, n: int) -> int:\n",
    "    out = x**n\n",
    "    return out\n",
    "\n",
    "power(5, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The use of `def` and `return` keywords\n",
    "\n",
    "- `def` a name tag for a code block.\n",
    "- `return` the expected outputs.\n",
    "- `return` marks the end of a code block."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "# def a name tag for a code block\n",
    "def power(x: int, n: int) -> int:\n",
    "    pass\n",
    "\n",
    "power(5, 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5\n",
      "3\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "125"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# return the expected outputs\n",
    "def power(x: int, n: int) -> int:\n",
    "    print(x)\n",
    "    print(n)\n",
    "    out = x**n\n",
    "    return out\n",
    "\n",
    "power(5, 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "125"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# return marks the end of a code block.\n",
    "def power(x: int, n: int) -> int:\n",
    "    out = x**n\n",
    "    return out\n",
    "    print(x)\n",
    "    print(n)\n",
    "\n",
    "power(5, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Scope"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## When it comes to defining functions, it is vital to understand the scope of an object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What is scope?\n",
    "\n",
    "> In computer programming, the scope of a name binding, an association of a name to an entity, such as a variable, is the region of a computer program where the binding is valid.\n",
    "\n",
    "Source: <https://en.wikipedia.org/wiki/Scope_(computer_science)>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Simply put, now we have a self-defined function, so the programming environment is now split into 2:\n",
    "\n",
    "- Global\n",
    "- Local"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## An object declared within the indented block of a function is a local object, it is only valid inside the `def` block"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 is an even number.\n",
      "name 'x' is not defined\n"
     ]
    }
   ],
   "source": [
    "def check_odd_even(x: int) -> str:\n",
    "    mod = x % 2 # local object, declared inside def block\n",
    "    if mod == 0:\n",
    "        return '{} is an even number.'.format(x)\n",
    "    else:\n",
    "        return '{} is an odd number.'.format(x)\n",
    "\n",
    "print(check_odd_even(0))\n",
    "try:\n",
    "    print(x)\n",
    "except NameError as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "name 'mod' is not defined\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    print(mod)\n",
    "except NameError as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## An object declared outside of the indented block of a function is a global object, it is valid everywhere"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 is an even number.\n",
      "0\n",
      "0\n"
     ]
    }
   ],
   "source": [
    "x = 0\n",
    "mod = x % 2\n",
    "def check_odd_even() -> str:\n",
    "    if mod == 0:\n",
    "        return '{} is an even number.'.format(x)\n",
    "    else:\n",
    "        return '{} is an odd number.'.format(x)\n",
    "\n",
    "print(check_odd_even())\n",
    "print(x)\n",
    "print(mod)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Although global object looks quite convenient, it is HIGHLY recommended NOT using global object directly in a indented function block."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using global objects in functions results in naming ambiguity between parameters versus arguments\n",
    "\n",
    "- Objects used in `def` code block: parameters.\n",
    "- Objects used in calling functions: arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "16\n"
     ]
    }
   ],
   "source": [
    "def power(x: int, n: int) -> int:\n",
    "    out = x**n # Parameters\n",
    "    return out\n",
    "\n",
    "x = 5 # Argument\n",
    "n = 3 # Argument\n",
    "print(power(4, 2)) # Arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Mapping relationship"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The principle of designing of a function is about mapping the relationship between inputs and outputs\n",
    "\n",
    "- The one-on-one relationship\n",
    "- The many-on-one relationship\n",
    "- The one-on-many relationship"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The one-on-one relationship\n",
    "\n",
    "Using scalar as input and output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "def absolute(x: int) -> int:\n",
    "    \"\"\"\n",
    "    Return the absolute value of the x.\n",
    "    \"\"\"\n",
    "    if x >= 0:\n",
    "        return x\n",
    "    else:\n",
    "        return -x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Once the function is defined, call as if it is a built-in function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function absolute in module __main__:\n",
      "\n",
      "absolute(x: int) -> int\n",
      "    Return the absolute value of the x.\n",
      "\n",
      "5566\n",
      "5566\n",
      "0\n"
     ]
    }
   ],
   "source": [
    "help(absolute)\n",
    "print(absolute(-5566))\n",
    "print(absolute(5566))\n",
    "print(absolute(0))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The many-on-one relationship relationship\n",
    "\n",
    "- Using scalars or structures for fixed inputs\n",
    "- Using `*args` or `**kwargs` for flexible inputs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using scalars for fixed inputs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "30\n"
     ]
    }
   ],
   "source": [
    "def product(x: int, y: int) -> int:\n",
    "    \"\"\"\n",
    "    Return the product values of x and y.\n",
    "    \"\"\"\n",
    "    return x*y\n",
    "\n",
    "print(product(5, 6))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using structures for fixed inputs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "900\n"
     ]
    }
   ],
   "source": [
    "def product(x: list) -> int:\n",
    "    \"\"\"\n",
    "    x: an iterable.\n",
    "    Return the product values of x.\n",
    "    \"\"\"\n",
    "    prod = 1\n",
    "    for i in x:\n",
    "        prod *= i\n",
    "    return prod\n",
    "\n",
    "print(product([5, 5, 6, 6]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using `*args` for flexible inputs\n",
    "\n",
    "- As in flexible arguments\n",
    "- Getting flexible `*args` as a `tuple`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(5, 5, 6, 6)\n"
     ]
    }
   ],
   "source": [
    "def plain_return(*args) -> tuple:\n",
    "    \"\"\"\n",
    "    Return args.\n",
    "    \"\"\"\n",
    "    return args\n",
    "\n",
    "print(plain_return(5, 5, 6, 6))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using `**kwargs` for flexible inputs\n",
    "\n",
    "- AS in keyword arguments\n",
    "- Getting flexible `**kwargs` as a `dict`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'district': 'Da-an', 'city': 'Taipei', 'country': 'Taiwan'}"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def plain_return(**kwargs) -> dict:\n",
    "    \"\"\"\n",
    "    Retrun kwargs.\n",
    "    \"\"\"\n",
    "    return kwargs\n",
    "\n",
    "plain_return(district='Da-an', city='Taipei', country='Taiwan')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The one-on-many relationship\n",
    "\n",
    "- Using default `tuple` with comma\n",
    "- Using preferred data structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using default `tuple` with comma"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('luke skywalker', 'LUKE SKYWALKER', 'lUKE SKYWALKER', 'Luke Skywalker')"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def return_different_case_formats(x: str) -> tuple:\n",
    "    return x.lower(), x.upper(), x.swapcase(), x.title()\n",
    "\n",
    "return_different_case_formats(\"Luke skywalker\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using preferred data structure"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'lowerCased': 'luke skywalker',\n",
       " 'upperCased': 'LUKE SKYWALKER',\n",
       " 'swapCased': 'lUKE SKYWALKER',\n",
       " 'titleCased': 'Luke Skywalker'}"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def return_different_case_formats(x: str) -> dict:\n",
    "    out = {\n",
    "        \"lowerCased\": x.lower(),\n",
    "        \"upperCased\": x.upper(),\n",
    "        \"swapCased\": x.swapcase(),\n",
    "        \"titleCased\": x.title()\n",
    "    }\n",
    "    return out\n",
    "\n",
    "return_different_case_formats(\"Luke skywalker\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## So far, we've learned programming known as \"Procedural Programming\"\n",
    "\n",
    "In its simplest definition, procedural programming involves writing code in a number of sequential steps and sometimes we combine these steps into commands called functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Another practice adopted in software development is called \"Object-oriented Programming, OOP\"\n",
    "\n",
    "Rather than code being designed around sequential steps, it is instead defined around objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What is an object?\n",
    "\n",
    "> In Object-oriented programming, an object is an instance of a Class. Objects are an abstraction. They hold both data, and ways to manipulate the data. The data is usually not visible outside the object. It can only be changed by using a well-specified mechanism (usually called interface).\n",
    "\n",
    "Source: <https://simple.wikipedia.org/wiki/Object_(computer_science)>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Simply put, an object is instantiated via a specific class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'int'>\n"
     ]
    }
   ],
   "source": [
    "# the object favorite_integer is an instance of int class\n",
    "favorite_integer = 5566\n",
    "print(type(favorite_integer))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'str'>\n"
     ]
    }
   ],
   "source": [
    "# the object favorite_tv_character is an instance of str class\n",
    "favorite_tv_character = \"Phoebe Buffay\"\n",
    "print(type(favorite_tv_character))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What is a class?\n",
    "\n",
    "A class provides a set of behaviors in the form of member functions (also known as methods), with implementations that are common to all instances of that class. A class also serves as a **blueprint** for its instances, effectively determining the way that state information for each instance is represented in the form of attributes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The relationship between objects and classes\n",
    "\n",
    "- A class is like a blueprint designed by its creators.\n",
    "- An object is like the final product build by its users based on its blueprint."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Why implementing a class by ourselves?\n",
    "\n",
    "- We define our own functions if there is no appropriate built-in functions or module-powered functions\n",
    "- We implement our own classes if there is no appropriate built-in classes or module-powered classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## So far, we've been using these built-in classes\n",
    "\n",
    "- Data types\n",
    "    - `int`\n",
    "    - `float`\n",
    "    - `str`\n",
    "    - `bool`\n",
    "    - `NoneType`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## So far, we've been using these built-in classes(Cont'd)\n",
    "\n",
    "- Data Structures\n",
    "    - `list`\n",
    "    - `tuple`\n",
    "    - `dict`\n",
    "    - `set`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Simply put, implementing a class is binding specific functions and data onto an object."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Defining classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Let's create a class named `SimpleCalculator` with no methods"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SimpleCalculator:\n",
    "    \"\"\"\n",
    "    This class creates a simple calculator that is unable to do anything.\n",
    "    \"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class '__main__.SimpleCalculator'>\n",
      "\n",
      "    This class creates a simple calculator that is unable to do anything.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "sc = SimpleCalculator()\n",
    "print(type(sc))\n",
    "print(sc.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Defining functions inside a class makes them methods"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SimpleCalculator:\n",
    "    \"\"\"\n",
    "    This class creates a simple calculator that is able to add and subtract 2 numbers.\n",
    "    \"\"\"\n",
    "    def add(self, x: int, y: int) -> int:\n",
    "        return x + y\n",
    "    def subtract(self, x: int, y: int) -> int:\n",
    "        return x - y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What does \"self\" mean in the parenthesis?\n",
    "\n",
    "![](https://media.giphy.com/media/QBcuE4Jas6MxmTWiIn/giphy.gif)\n",
    "\n",
    "Source: <https://giphy.com/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The \"self\" actually means the not yet instantiated object\n",
    "\n",
    "Think of the behavior of whom that is gonna use our class:\n",
    "\n",
    "```python\n",
    "sc = SimpleCalculator()\n",
    "sc.add('55', '66')\n",
    "sc.subtract(55, 66)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'5566'"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sc = SimpleCalculator()\n",
    "sc.add('55', '66')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-11"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sc.subtract(55, 66)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## We not only bind functions to a class, but also bind data to a class\n",
    "\n",
    "Use the `__init__` methods to create attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "class SimpleCalculator:\n",
    "    \"\"\"\n",
    "    This class creates a simple calculator that is able to add and subtract 2 numbers.\n",
    "    This class has an attribute of Euler's number: e.\n",
    "    \"\"\"\n",
    "    def __init__(self):\n",
    "        self.e = 2.71828182846\n",
    "    def add(self, x: int, y: int) -> int:\n",
    "        return x + y\n",
    "    def subtract(self, x: int, y: int) -> int:\n",
    "        return x - y\n",
    "    def exp(self, n: int) -> float:\n",
    "        return self.e**n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.71828182846\n",
      "7.38905609893584\n"
     ]
    }
   ],
   "source": [
    "sc = SimpleCalculator()\n",
    "print(sc.e)\n",
    "print(sc.exp(2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The object instantiated by self-defined class does not have a default print layout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<__main__.SimpleCalculator object at 0x7fa8f325ac10>\n"
     ]
    }
   ],
   "source": [
    "print(sc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## If you want to give it a print layout, we can define the `__repr__` method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "class SimpleCalculator:\n",
    "    \"\"\"\n",
    "    This class creates a simple calculator that is able to add and subtract 2 numbers.\n",
    "    This class has an attribute of Euler's number: e.\n",
    "    \"\"\"\n",
    "    def __init__(self):\n",
    "        self.e = 2.71828182846\n",
    "    def __repr__(self):\n",
    "        return \"A Simple Calculator Class.\"\n",
    "    def add(self, x: int, y: int) -> int:\n",
    "        return x + y\n",
    "    def subtract(self, x: int, y: int) -> int:\n",
    "        return x - y\n",
    "    def exp(self, n: int) -> float:\n",
    "        return self.e**n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A Simple Calculator Class.\n"
     ]
    }
   ],
   "source": [
    "sc = SimpleCalculator()\n",
    "print(sc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The `SimpleCalculator` is a bit too simple, can we add more methods?\n",
    "\n",
    "- Of course! Let's implement a `IntermediateCalculator` class with other arithmetic operations; \n",
    "- But do we have to define the class from scratch?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Besides encapsulation, there is another powerful feature of implementing a class called \"Inheritance\"\n",
    "\n",
    "Inheritance enables new objects to take on the properties of existing objects.\n",
    "\n",
    "```python\n",
    "class ChildClass(ParentClass):\n",
    "    # sequence of statements\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "class IntermediateCalculator(SimpleCalculator):\n",
    "    \"\"\"\n",
    "    This class inherits from simple calculator does nothing.\n",
    "    \"\"\"\n",
    "    pass\n",
    "\n",
    "ic = IntermediateCalculator()\n",
    "print(\"e\" in dir(ic))\n",
    "print(\"exp\" in dir(ic))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What can we do when inheriting from a parent class?\n",
    "\n",
    "- Extending attributes or methods\n",
    "- Revising attributes or methods"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "# Extending attributes or methods\n",
    "class IntermediateCalculator(SimpleCalculator):\n",
    "    \"\"\"\n",
    "    This class inherits from simple calculator and add more methods to it.\n",
    "    \"\"\"\n",
    "    def mutiply(self, x: int, y: int) -> int:\n",
    "        return x*y\n",
    "    def divide(self, x: int, y: int) -> float:\n",
    "        return x / y\n",
    "    def power(self, x: int, y: int) -> int:\n",
    "        return x**y\n",
    "    def mod(self, x: int, y: int) -> int:\n",
    "        return x % y\n",
    "    def floor_divide(self, x: int, y: int) -> int:\n",
    "        return x // y"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "sc = SimpleCalculator()\n",
    "ic = IntermediateCalculator()\n",
    "print(\"power\" in dir(sc))\n",
    "print(\"power\" in dir(ic))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "# Extending attributes or methods\n",
    "class IntermediateCalculator(SimpleCalculator):\n",
    "    def __init__(self):\n",
    "        SimpleCalculator.__init__(self)\n",
    "        self.pi = 3.14159265359\n",
    "\n",
    "sc = SimpleCalculator()\n",
    "ic = IntermediateCalculator()\n",
    "print(\"pi\" in dir(sc))\n",
    "print(\"pi\" in dir(ic))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## What is a module in Python?\n",
    "\n",
    "A Python module is a file with the extension of `.py` which consists of a couple of functions or classes. A Python module can also be in the form of a folder which consists of a couple of files with the extension of `.py`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Standard modules\n",
    "\n",
    "- Modules distributed with Python are called **standard modules**.\n",
    "- We can literally **see** them in our environment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Use `__file__` attribute to find the location of a certain module\n",
    "\n",
    "Use `import` keyword to specify the module we are about to leverage.\n",
    "\n",
    "```python\n",
    "import standard_module\n",
    "\n",
    "print(standard_module.__file__)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Use `cd` to change directory\n",
    "\n",
    "- `cd` stands for change director.\n",
    "- Type `cd path/of/modules/file/location` then press Enter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Use `ls` to see some standard modules\n",
    "\n",
    "- `ls` stands for list.\n",
    "- We can literally see some of the modules."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Create a module locally\n",
    "\n",
    "- Create an empty `simple_calculator.py` in working directory.\n",
    "- Working directory refers to the path where running notebook locates."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Copy the previously defined `SimpleCalculator` class and paste onto `simple_calculator.py`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "# simple_calculator.py\n",
    "class SimpleCalculator:\n",
    "    \"\"\"\n",
    "    This class creates a simple calculator that is able to add and subtract 2 numbers.\n",
    "    This class has an attribute of Euler's number: e.\n",
    "    \"\"\"\n",
    "    def __init__(self):\n",
    "        self.e = 2.71828182846\n",
    "    def __repr__(self):\n",
    "        return \"A Simple Calculator Class.\"\n",
    "    def add(self, x: int, y: int) -> int:\n",
    "        return x + y\n",
    "    def subtract(self, x: int, y: int) -> int:\n",
    "        return x - y\n",
    "    def exp(self, n: int) -> float:\n",
    "        return self.e**n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Import pre-defined class from a module\n",
    "\n",
    "- Use `import` keyword to specify the module we are about to leverage.\n",
    "- Use `as` keyword for alias.\n",
    "\n",
    "```python\n",
    "import module_name\n",
    "import module_name as alias\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Use `.` to specify affiliations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.71828182846\n",
      "5566\n"
     ]
    }
   ],
   "source": [
    "import simple_calculator\n",
    "\n",
    "sim_calc = simple_calculator.SimpleCalculator()\n",
    "print(sim_calc.e)\n",
    "print(sim_calc.add('55', '66'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.71828182846\n",
      "5566\n"
     ]
    }
   ],
   "source": [
    "import simple_calculator as sc\n",
    "\n",
    "sim_calc = sc.SimpleCalculator()\n",
    "print(sim_calc.e)\n",
    "print(sim_calc.add('55', '66'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Import specific feature from a module\n",
    "\n",
    "- A module may consist of a couple of functions or classes.\n",
    "- Use `from` and `import` keywords to leverage a specific feature.\n",
    "\n",
    "```python\n",
    "from module_name import class_name as alias\n",
    "from module_name import function_name as alias\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.71828182846\n",
      "5566\n"
     ]
    }
   ],
   "source": [
    "from simple_calculator import SimpleCalculator\n",
    "\n",
    "sim_calc = SimpleCalculator()\n",
    "print(sim_calc.e)\n",
    "print(sim_calc.add('55', '66'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.71828182846\n",
      "5566\n"
     ]
    }
   ],
   "source": [
    "from simple_calculator import SimpleCalculator as SC\n",
    "\n",
    "sim_calc = SC()\n",
    "print(sim_calc.e)\n",
    "print(sim_calc.add('55', '66'))"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3.9",
   "language": "python",
   "name": "python39"
  },
  "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}