OOP_000_First_Steps_of_a_Class.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://www.hydroffice.org/epom/\"><img src=\"images/000_000_epom_logo.png\" alt=\"ePOM\" title=\"Open ePOM home page\" align=\"center\" width=\"12%\" alt=\"Python logo\\\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://piazza.com/class/jtn9igrguw476h\"><img src=\"images/help.png\" alt=\"ePOM\" title=\"Ask questions on Piazza.com\" align=\"right\" width=\"10%\" alt=\"Piazza.com\\\"></a>\n",
    "# Object-Oriented Programming"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Object-Oriented Programming (OOP)](https://en.wikipedia.org/wiki/Object-oriented_programming) is a powerful and popular approach adopted to organize code for short programs (scripts), libraries, and applications."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "OOP is based on the concept of **objects**. An object is an instance of a **class**. A class is used to define all the required data structures as well as the functions (**methods**) that can be applied to the class data."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Class and Object](images/OOP_000_000_class_and_object.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the [*A Class as a Data Container*](../python_basics/008_A_Class_as_a_Data_Container.ipynb) notebook, you have already learned how to create your own type using a **class** as a data container. This notebook will describe how to extend a data container class with methods."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "To review the concept of the data type of a variable in Python, read the [*Variable and Types*](../python_basics/001_Variables_and_Types.ipynb#Dynamic-Nature-of-a-Variable-Type) notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "You will be asked to write your OOP code in separated `.py` files, each of them represents a Python module containing the class definition. \n",
    "**This is different from the approach adopted in [*Programming Basics for Python* notebooks](https://github.com/hydroffice/python_basics) where all the code is written in the notebook itself!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The adopted approach imports the class code contained in modules, and then creates instances of such a class in the body of this notebook (and in the following ones)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "To review the concept of module in Python, read the [*Read and Write Text Files*](../python_basics/006_Read_and_Write_Text_Files.ipynb#Read-and-Write-Text-Files) notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code cell performs two preliminary **required** operations:\n",
    "\n",
    "* Load the `autoreload` [extension](https://jupyter-notebook.readthedocs.io/en/stable/extending/) to avoid to have to manually reload the classes when changes are applied. \n",
    "* Instruct Python (using `sys.path.append()`) to look in the `code` folder for local Python modules."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "\n",
    "import sys\n",
    "import os\n",
    "\n",
    "sys.path.append(os.getcwd())  # add the current folder to the list of paths where Python looks for modules "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "Any time that you restart this notebook, remember to execute the above cell!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Class Definition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly to what is described in the [*Class Definition*](../python_basics/008_A_Class_as_a_Data_Container.ipynb#Class-Definition) notebook, we start by creating a class definition. In this case, the class will be named `WaterLevel` and will have a `\"\"\"A Class for Water Level Data\"\"\"` docstring."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Modify the empty `waterlevel.py` file located in the `mycode` folder to successfully execute the following code.\n",
    "<br><br>\n",
    "*The solution code imports the `WaterLevel` class from the `waterlevel_definition` module located in the `solutions` folder.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "from solutions.waterlevel_definition import WaterLevel\n",
    "\n",
    "wl = WaterLevel()\n",
    "print(\"The object type is %s\" % (type(wl)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mycode.waterlevel import WaterLevel\n",
    "\n",
    "wl = WaterLevel()\n",
    "print(\"The object type is %s\" % (type(wl)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Class Initialization and Attributes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now add a few attributes to the previously defined `WaterLevel` class:\n",
    "\n",
    "* Two lists (named `times` and `water_levels`, respectively)\n",
    "* A `metadata` dictionary with the following pairs of key and value:\n",
    "  *  `\"uom\"`: `\"m\"` for the unit of measure of the water level values.\n",
    "  * `\"count\"`: `0` for the number of records stored in the object.\n",
    "\n",
    "As described in [*Class Initialization and Attributes*](../python_basics/008_A_Class_as_a_Data_Container.ipynb#Class-Initialization-and-Attributes), the initialization of the class attributes happens in the *magic* `__init__(self)` method. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Extend the `WaterLevel` class in the `waterlevel.py` file (located in the `mycode` folder) to successfully execute the following code.\n",
    "<br><br>\n",
    "*The solution code imports the `WaterLevel` class from the `waterlevel_attributes` module located in the `solutions` folder.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "from solutions.waterlevel_attributes import WaterLevel\n",
    "\n",
    "wl = WaterLevel()\n",
    "print(\"Times: %s, %s\" % (wl.times, wl.water_levels))\n",
    "print(\"Metadata: %s\" % (wl.metadata))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mycode.waterlevel import WaterLevel\n",
    "\n",
    "wl = WaterLevel()\n",
    "print(\"Times: %s, %s\" % (wl.times, wl.water_levels))\n",
    "print(\"Metadata: %s\" % (wl.metadata))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialization Parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is often the case that you want to pass some parameters to the class constructor. Those parameters are the ones that you define in the `__init__()` method."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Extend the `WaterLevel` class in the `waterlevel.py` file to be able to take a `data_path` parameter for the location of the data file.\n",
    "<br><br>\n",
    "*The solution code imports the `WaterLevel` class from the `waterlevel_initialization` module located in the `solutions` folder.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "from solutions.waterlevel_initialization import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"tide.txt\")  # the 'tide.txt' file is located under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(\"Data path: %s\" % (wl.data_path))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mycode.waterlevel import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"tide.txt\")  # the 'tide.txt' file is located under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(\"Data path: %s\" % (wl.data_path))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What happen if the passed data path does not exist?\n",
    "\n",
    "Currently, nothing!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from solutions.waterlevel_initialization import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"missing.txt\")  # this file does not exist under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(\"Data path: %s\" % (wl.data_path))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Extend the `__init__` method in the `WaterLevel` class in the `waterlevel.py` file to throw a meaningful error when the passed `data_path` does not actually exist.\n",
    "<br><br>\n",
    "*The solution code imports the `WaterLevel` class from the `waterlevel_initialization_check` module located in the `solutions` folder.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "import os\n",
    "from solutions.waterlevel_initialization_check import WaterLevel\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"missing.txt\")  # this file does not exist under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(\"Data path: %s\" % (wl.data_path))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from mycode.waterlevel import WaterLevel\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"missing.txt\")  # this file does not exist under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(\"Data path: %s\" % (wl.data_path))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The String Representation Method"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another special method that may be explicitly added to a class is `__str__(self)`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The `__str__(self)` method is called each time that you pass an object to the `print()` function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you don't explicitly write it, Python will provide a default implementation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from solutions.waterlevel_initialization import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"tide.txt\")  # the 'tide.txt' file is located under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(wl)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see after executing the above **Code** cell, the default solution is to simply provide the name and the [memory address](https://en.wikipedia.org/wiki/Memory_address) of the object.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Extend the `WaterLevel` class in the `waterlevel.py` file with a `__str__(self)` method that returns a `str` with some meaningful information about the status of the object.\n",
    "<br><br>\n",
    "*The solution code imports the `WaterLevel` class from the `waterlevel_str` module located in the `solutions` folder.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "from solutions.waterlevel_str import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"tide.txt\")  # the 'tide.txt' file is located under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(wl)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mycode.waterlevel import WaterLevel\n",
    "import os\n",
    "\n",
    "wl_path = os.path.join(os.getcwd(), \"data\", \"tide.txt\")  # the 'tide.txt' file is located under the `data` folder\n",
    "wl = WaterLevel(data_path=wl_path)\n",
    "print(wl)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "There are not fixed rules of what to return as `str`. Based on the official Python documentation, the only requirement is that it should be an [*\"informal or nicely printable string representation of an object\"*](https://docs.python.org/3.6/library/stdtypes.html#str)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px; padding-top:10px;\" src=\"images/refs.png\">\n",
    "\n",
    "## Useful References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Introduction to Ocean Data Science - Object-Oriented Programming slides](https://bitbucket.org/hydroffice/hyo_epom/downloads/ePOM.Intro_to_Ocean_Data_Science.Object_Oriented_Programming.pdf)\n",
    "* [The official Python 3.6 documentation](https://docs.python.org/3.6/index.html)\n",
    "  * [Classes](https://docs.python.org/3.6/tutorial/classes.html)\n",
    "  * [String Representation Method](https://docs.python.org/3.6/reference/datamodel.html?highlight=repr#object.__str__)\n",
    "* [Memory address](https://en.wikipedia.org/wiki/Memory_address)\n",
    "* [Programming Basics with Python](https://github.com/hydroffice/python_basics)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"5%\" style=\"padding-right:10px;\" src=\"images/email.png\">\n",
    "\n",
    "*For issues or suggestions related to this notebook, write to: epom@ccom.unh.edu*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "| [Contents](index.ipynb) | [More About Classes >](OOP_001_More_About_Classes.ipynb)"
   ]
  }
 ],
 "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}