L2_PythonClassesAndWritingFiles/L2_PythonClassesAndWritingFiles.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "518a832f",
   "metadata": {},
   "source": [
    "# `L2`: Lecture 2: Python basics: Modules, Classes, and Methods\n",
    "\n",
    "In this lecture, we discuss how to make and use our own modules. We also discuss how Python implements *object orientation*, which allows programs to be structured into classes, each responsible for its own behavior. This helps to keep a check on the\n",
    "complexity of our programs and generally makes them easier to manage. The main mechanisms for doing this are classes and methods. You have already used built-in classes and methods without necessarily knowing it.\n",
    "\n",
    "__Outline:__\n",
    "  * [1. Modules ](#Ch1)\n",
    "      * [1.1 Using modules ](#Ch11)\n",
    "      * [1.2 Useful Python libraries ](#Ch12)\n",
    "      * [1.3 Test yourself ](#Ch13)\n",
    "  * [2. Object Oriented](#Ch2)\n",
    "  * [3. Defining Classes](#Ch3)\n",
    "      * [3.1 Inheritance](#Ch31)\n",
    "      * [3.2 Summary](#Ch32)\n",
    "  * [4. Reading files](#Ch4)\n",
    "      * [4.1 Files](#Ch41)\n",
    "          * [4.1.1 Reading files](#Ch411)\n",
    "          * [4.1.2 Reading big files](#Ch412)\n",
    "          * [4.1.3 Writing files](#Ch413)\n",
    "          * [4.1.4 The file system](#Ch414)\n",
    "          * [4.1.5 Pickling](#Ch415)\n",
    "          * [4.1.6 JSON ](#Ch416)        \n",
    "  * [5. Internet](#Ch5)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "718596d2",
   "metadata": {},
   "source": [
    "## 1. Modules <a class=\"anchor\" id=\"Ch1\"></a>\n",
    "\n",
    "Most computer languages have a concept like modules that allows you to create a group of functions that are in a convenient form for others to use—or even for yourself to use on different projects. Python does this grouping of functions in a very simple and elegant way. Essentially, any file with Python code in it can be thought of as a module with the same name as the file. However, before we get into writing our own modules, let’s look at how we use the modules already installed with Python.\n",
    "\n",
    "### 1.1 Using Modules<a class=\"anchor\" id=\"Ch11\"></a>\n",
    "\n",
    "For example, to take a random number from a range of numbers, we can use the module `random`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d760608",
   "metadata": {},
   "outputs": [],
   "source": [
    "import random\n",
    "\n",
    "random.randint(1,6)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40dca504",
   "metadata": {},
   "source": [
    "The first thing we do here is tell Python that we want to use the random module by using the `import` command. Somewhere in the Python installation is a file called `random.py` that contains a `randint` function as well as some other functions. With so many modules available to us, there is a real danger that different modules might have functions with the same name. In such a case, how would Python know which one to use? \n",
    "\n",
    "Fortunately, we do not have to worry about this happening because we have imported the module, and none of the functions in the module are visible unless we use the `module_name` and then put a dot onto the front of the function name (as in `random.randint()`).\n",
    "\n",
    "When we do not do this right, we will get an error. Here, try omitting the module name, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f4a6bf8f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import random\n",
    "\n",
    "randint(1,6)  # error: `randint` is not defined"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffa27f34",
   "metadata": {},
   "source": [
    "Having to put the module name in front of every call to a function that’s used a lot can get tedious. Fortunately, we can make this a little easier by adding `as` to the import command as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14180efd",
   "metadata": {},
   "outputs": [],
   "source": [
    "import random as r\n",
    "\n",
    "r.randint(1,6)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47037010",
   "metadata": {},
   "source": [
    "This gives the module a local name within our program of just `r` rather than `random`, which saves us a bit of typing.\n",
    "If you are certain a function you want to use from a library is not going to conflict with anything in your program, you can take things a stage further and import the function specifically, as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "164379a1",
   "metadata": {},
   "outputs": [],
   "source": [
    "from random import randint\n",
    "\n",
    "randint(1,6)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26c4f6b9",
   "metadata": {},
   "source": [
    "To go even further, you can import *everything* from the module in one fell swoop. Unless you know exactly what is in the module, however, **this is not normally a good idea**, but you can do it as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27b04026",
   "metadata": {},
   "outputs": [],
   "source": [
    "from random import *\n",
    "\n",
    "randint(1,6)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6bd4d34d",
   "metadata": {},
   "source": [
    "In this case the `*` means \"everything\".\n",
    "\n",
    "### 1.2 Useful Python Libraries <a class=\"anchor\" id=\"Ch12\"></a>\n",
    "\n",
    "So far we have used the `random` module, but other modules are included in Python. These modules are often called Python’s standard library. There are too many of these modules to list in full. However, you can always find a complete list of Python modules at https://docs.python.org/3/library/.\n",
    "\n",
    "Here are some of the most useful modules you\n",
    "should take a look at:\n",
    "\n",
    "• `string` String utilities\n",
    "\n",
    "• `datetime` For manipulating dates and times\n",
    "\n",
    "• `pickle` For saving and restoring data structures on file \n",
    "\n",
    "• `urllib.request` For reading web pages \n",
    "\n",
    "• `tkinter` For creating graphical user interfaces \n",
    "\n",
    "• `numpy` For mathematics, arrays and matrices  (useful guide for Matlab users: https://numpy.org/doc/stable/user/numpy-for-matlab-users.html)\n",
    "\n",
    "• `matplotlib` For data visualisation\n",
    "\n",
    "\n",
    "##### 1.2.1 Example Using `matplotlib` and `numpy`\n",
    "\n",
    "Find an example of plotting a curve below.\n",
    "\n",
    "> ❓**Test Yourself**: see whether you understand the elements that are used in the example below: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f1acd010",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "# generate (x, y, y2) datapoints\n",
    "x = np.linspace(0, 10, 100)\n",
    "y = 4 + 2 * np.sin(2 * x)\n",
    "y2 = 4*np.cos(2*x)\n",
    "\n",
    "# plot the (x, y) series\n",
    "ax = plt.subplot(2, 1, 1)\n",
    "ax.plot(x, y, linewidth=2.0)\n",
    "\n",
    "ax.set(xlim=(0, 8), xticks=np.arange(1, 8),\n",
    "       ylim=(0, 8), yticks=np.arange(1, 8))\n",
    "\n",
    "plt.xlabel('time (s)')\n",
    "plt.ylabel('sway (mm)')\n",
    "plt.title('Synthetic data to demonstrate plot functions')\n",
    "plt.grid(True)\n",
    "\n",
    "# plot the (x, y2) series\n",
    "ax =plt.subplot(2, 1, 2)\n",
    "ax.plot(x, y2, linewidth=2.0)\n",
    "ax.set(xlim=(0, 8), xticks=np.arange(1, 8)) \n",
    "plt.xlabel('time (s)')\n",
    "plt.ylabel('CoP (mm)')\n",
    "plt.grid(True)\n",
    "\n",
    "plt.tight_layout()\n",
    "\n",
    "# show the plot\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05f5d973",
   "metadata": {},
   "source": [
    "### 1.3 ❓Test Yourself <a class=\"anchor\" id=\"Ch13\"></a>\n",
    "\n",
    "A dataset--`time`, `y1`, and `y2`--is given below. Plot both series (`(time, y1)` and `(time, y2)`) in the same plot. Provide a legend (containing the `data1`, `data2` series). Don't forget the labels on the axes. You can find more information [on the matplotlib website](https://matplotlib.org/3.5.0/tutorials/introductory/pyplot.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "36d9aa47",
   "metadata": {},
   "outputs": [],
   "source": [
    "y1 = [2, 3, 5, 2, 4, 8, 4]  # plot this with a red dashed line\n",
    "y2 = [5, 5, 5, 6, 1, 1, 1]  # plot this with green triangles\n",
    "time = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7]\n",
    "\n",
    "# Example: test yourself\n",
    "\n",
    "## Put your own code here ##\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe8348af",
   "metadata": {},
   "source": [
    "## 2. Object Oriented Programming <a class=\"anchor\" id=\"Ch2\"></a>\n",
    "\n",
    "Object orientation has much in common with modules. It shares the same goals of trying to group related items together so that they are easy to maintain and find. As the name suggests, object orientation is about *objects*. We have been unobtrusively using objects already. A string is an object, for example. Thus, when we type: \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5eb4b29",
   "metadata": {},
   "outputs": [],
   "source": [
    "'abc'.upper()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "442e560f",
   "metadata": {},
   "source": [
    "We are telling the string `'abc'` that we want a copy of it, but in uppercase. In object-oriented terms, `abc` is an _instance_ of the built-in _class_ `str`, and `upper` is a _method_ on the _class_ `str`. We can actually find out the class of an object, as shown here (note double underscores before and after the word class):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6abd6fdc",
   "metadata": {},
   "outputs": [],
   "source": [
    "'abc'.__class__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f02c4cca",
   "metadata": {},
   "outputs": [],
   "source": [
    "[1].__class__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "05588ad4",
   "metadata": {},
   "outputs": [],
   "source": [
    "12.34.__class__"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3111593b",
   "metadata": {},
   "source": [
    "## 3. Defining Classes <a class=\"anchor\" id=\"Ch3\"></a>\n",
    "\n",
    "We are now going to create a class that does the job of converting measurements from one unit to another by multiplying a value by a scale factor. We will give the class the name `ScaleConverter`. Here is the listing for the whole class, plus a few lines of code to test it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e2fbc63",
   "metadata": {},
   "outputs": [],
   "source": [
    "class ScaleConverter:\n",
    "    \n",
    "    def __init__(self, units_from, units_to, factor):\n",
    "        self.units_from = units_from\n",
    "        self.units_to = units_to\n",
    "        self.factor = factor\n",
    "        \n",
    "    def description(self):\n",
    "        return 'Convert ' + self.units_from + ' to ' + self.units_to\n",
    "    \n",
    "    def convert(self,value):\n",
    "        return value*self.factor\n",
    "    \n",
    "c1 = ScaleConverter('inches','mm',25) #creating an \"instance\" of the class ScaleConverter\n",
    "print(c1.description())\n",
    "print('converting 2 inches')\n",
    "print(str(c1.convert(2))+ c1.units_to)  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c8ba521",
   "metadata": {},
   "source": [
    "The first line is fairly obvious: It states that we are beginning the definition of a class called `ScaleConverter`. The colon (`:`) on the end indicates that all that follows is part of the *class definition* until we get back to an indent level of the left margin again. Inside the `ScaleConverter`, we can see what looks like three *function definitions*. These functions\n",
    "belong to the *class*; they cannot be used except via an *instance* of the class. These kinds of functions that belong to a class are called *methods*.\n",
    "\n",
    "The first method, `__init__`, looks a bit strange—its name has two underscore characters on either side. When Python is creating a new instance of a class, it automatically calls the method `__init__`. The number of parameters that `__init__` should have depends on how many parameters are supplied when an instance of the class is made. To unravel that, we need to look at this line at the end of the file:\n",
    "\n",
    "```python\n",
    "        c1 = ScaleConverter('inches','mm',25)\n",
    "```\n",
    "\n",
    "This line creates a new instance of the `ScaleConverter`, specifying what the units being converted from and to are, as well as the scaling factor. The `__init__` method must have all these parameters, but it must also have a parameter called `self` as the first parameter:\n",
    "\n",
    "```python\n",
    "        def __init__(self, units_from, units_to, factor):\n",
    "```\n",
    "\n",
    "The parameter `self` refers to the object itself. Now, looking at the body of the `__init__` method, we see some assignments:\n",
    "\n",
    "```python\n",
    "        self.units_from = units_from\n",
    "        self.units_to = units_to\n",
    "        self.factor = factor\n",
    "```\n",
    "\n",
    "Each of these assignments creates a variable that belongs to the object and has its initial value set from the parameters passed in to `__init__`. To recap, when we create a new `ScaleConverter` by typing something like:\n",
    "\n",
    "```python\n",
    "          c1 = ScaleConverter('inches','mm',25)\n",
    "```\n",
    "\n",
    "Python creates a new instance of `ScaleConverter` and assigns the values `'inches'`, `'mm'`, and `25` to its three variables: `self.units_from`, `self.units_to`, and `self.factor`.\n",
    "\n",
    "The term _encapsulation_ is often used in discussions of classes. It is the job of a class to encapsulate everything to do with the class. That means storing data (like the three variables) and things that you might want to do with the data in the form of the `description` and `convert` methods. The first of these (`description`) takes the information that the ScaleConverter knows about its units and creates a string that describes it. As with `__init__`, all methods must have a first parameter of `self`. The method will probably need it to access the data of the class to which it belongs. \n",
    "\n",
    "To demonstrate:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fa342fb4",
   "metadata": {},
   "outputs": [],
   "source": [
    "silly_converter = ScaleConverter('apples','grapes',74)\n",
    "silly_converter.description()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1f693248",
   "metadata": {},
   "outputs": [],
   "source": [
    "silly_converter.convert(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "50754fc6",
   "metadata": {},
   "source": [
    "### 3.1 Inheritance <a class=\"anchor\" id=\"Ch31\"></a>\n",
    "\n",
    "The `ScaleConverter` class is okay for units of length and things like that; however, it would not work for something like converting temperature from degrees Celsius (C) to degrees Fahrenheit (F). The formula for this is `F = 1.8*C + 32`. There is both a scale factor (`1.8`) and an offset (`32`). Let’s create a class called `ScaleAndOffsetConverter` that is just like `ScaleConverter`, but with a factor as well as an offset.\n",
    "\n",
    "One way to do this would simply be to copy the whole of the code for `ScaleConverter` and change it a bit by adding the extra variable. It might, in fact, look something like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "482f9bcd",
   "metadata": {},
   "outputs": [],
   "source": [
    "class ScaleAndOffsetConverter:\n",
    "\n",
    "    def __init__(self, units_from, units_to, factor, offset):\n",
    "        self.units_from = units_from\n",
    "        self.units_to = units_to\n",
    "        self.factor = factor\n",
    "        self.offset = offset\n",
    "        \n",
    "    def description(self):\n",
    "        return 'Convert ' + self.units_from + ' to ' + self.units_to\n",
    "    \n",
    "    def convert(self,value):\n",
    "        return value*self.factor + self.offset\n",
    "    \n",
    "c2 = ScaleAndOffsetConverter('C', 'F', 1.8, 32)\n",
    "print(c2.description())\n",
    "print('converting 20C')\n",
    "print(str(c2.convert(20))+ c2.units_to)  "
   ]
  },
  {
   "attachments": {
    "image.png": {
     "image/png": "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"
    }
   },
   "cell_type": "markdown",
   "id": "638df635",
   "metadata": {},
   "source": [
    "Assuming we want both types of converters in the program we are writing, then this is a bad way of doing it. It’s bad because we are repeating code. The description method is actually identical, and `__init__` is almost the same. A much better way is to use something called _inheritance_.\n",
    "\n",
    "The idea behind inheritance in classes is that when you want a specialized version of a class that already exists, you inherit all the parent class’s variables and methods and just add new ones or override the ones that are different. Below shows a class diagram for the two classes, indicating how `ScaleAndOffsetConverter` inherits from `ScaleConverter`, adds a new variable (`offset`), and overrides the method `convert` (because it will work a bit differently).\n",
    "\n",
    "![image.png](attachment:image.png)\n",
    "\n",
    "Here is the class definition for `ScaleAndOffsetConverter` using inheritance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "78fd78fb",
   "metadata": {},
   "outputs": [],
   "source": [
    "class ScaleAndOffsetConverter(ScaleConverter):\n",
    "\n",
    "    def __init__(self, units_from, units_to, factor, offset):\n",
    "        ScaleConverter.__init__(self, units_from, units_to, factor)\n",
    "        self.offset = offset\n",
    "        \n",
    "    def convert(self,value):\n",
    "        return value*self.factor + self.offset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d5cf6b68",
   "metadata": {},
   "source": [
    "The first thing to notice is that the class definition for `ScaleAndOffsetConverter` has `ScaleConverter` in parentheses immediately after it. That is how you specify the parent class for a class.\n",
    "The `__init__` method for the new “subclass” of `ScaleConverter` first invokes the `__init__` method of ScaleConverter before defining the new variable `offset`. The `convert` method will override the `convert` method in the parent class because we need to add on the `offset` for this kind of converter. You can run and experiment with the two classes together:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68f4d658",
   "metadata": {},
   "outputs": [],
   "source": [
    "c1 = ScaleConverter('inches','mm',25)\n",
    "print(c1.description())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08557bea",
   "metadata": {},
   "outputs": [],
   "source": [
    "print('converting 2 inches')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c878c190",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(str(c1.convert(2))+c1.units_to)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37e4c0c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "c2 =ScaleAndOffsetConverter('C','F', 1.8, 32)\n",
    "print(c2.description())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68940520",
   "metadata": {},
   "outputs": [],
   "source": [
    "print('converting 20C')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bdff5205",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(str(c2.convert(20))+c2.units_to)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5525bc3f",
   "metadata": {},
   "source": [
    "It’s a simple matter to convert these two classes into a module that we can use in other programs. In fact, __we will use this \n",
    "module in the next lecture where we attach a graphical user interface to it.__\n",
    "\n",
    "\n",
    "__To turn this file into a module, we should first take the test code at the end off and then save it under a sensible name. Let’s call it `converters.py`. The module must be in the same directory as any program that wants to use it. So, save this file in the same folder as the next lecture.__\n",
    "To use the module you use the command:\n",
    "\n",
    "```python\n",
    "        import converters\n",
    "```\n",
    "        \n",
    "### 3.2 Summary <a class=\"anchor\" id=\"Ch32\"></a>\n",
    "\n",
    "Lots of modules are available for Python, and some are specifically for the Raspberry Pi, such as the `RPi.GPIO` library for controlling the GPIO pins. As you work through this course, you will encounter various modules. You will also find that as the programs you write get more complex, the benefits of an object-oriented approach to designing and coding your projects will keep everything more manageable."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0ec4a07",
   "metadata": {},
   "source": [
    "## 4. Reading files  <a class=\"anchor\" id=\"Ch4\"></a>\n",
    "\n",
    "Python makes it easy for your programs to use saved files and connect to the Internet. You can read data from files, write data to files, and fetch content from the Internet. You can even check for new mail and tweets—all from your program.\n",
    "\n",
    "### 4.1 Files <a class=\"anchor\" id=\"Ch41\"></a>\n",
    "\n",
    "When you run a Python program, any values you have in variables will be lost. For your experiments it is therefore important that you can save your values in a file, and read data from files.\n",
    "\n",
    "#### 4.1.1 Reading Files <a class=\"anchor\" id=\"Ch411\"></a>\n",
    "\n",
    "Python makes reading the contents of a file extremely easy. As an example, create a text file (e.g. with your notepad) and save the following list of data names. Save the file as `participants_data.txt` in the same folder as this lecture:\n",
    "\n",
    "    P01_01042022_1215\n",
    "    P02_01042022_1240\n",
    "    P03_01042022_1315\n",
    "    P04_01042022_1400\n",
    "    P05_02042022_0900\n",
    "\n",
    "If you now want to read this file with Python:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b20ec481",
   "metadata": {},
   "outputs": [],
   "source": [
    "# if this file is not in the same folder as this lecture notebook, then put the foldername in front: folder/file\n",
    "file = 'participants_data.txt' \n",
    "\n",
    "f = open(file)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1fee2651",
   "metadata": {},
   "outputs": [],
   "source": [
    "data_names = f.read()\n",
    "data_names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f9c2b1c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "data_names.splitlines()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1001194a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# we can combine these last two lines as follows:\n",
    "data_names = f.read().splitlines()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84f47b20",
   "metadata": {},
   "source": [
    "You should always call the **close** command when you are done with a file to free up operating system resources. **Leaving a file open can lead to problems.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "afd161c8",
   "metadata": {},
   "outputs": [],
   "source": [
    "f.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39937254",
   "metadata": {},
   "source": [
    "It can sometimes be difficult to remember to close files after finishing with them. An alternative to the above is Python's `with` block. `with` blocks are used to automatically perform some kind of \"cleanup\" on exiting them. Here, it is called with `open` to automatically manage calling `close` at the end:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e157c25d",
   "metadata": {},
   "outputs": [],
   "source": [
    "with open('participants_data.txt') as f2:\n",
    "    some_data = f2.read()\n",
    "    # f2.close() is automatically called here, at the end of the 'with' block"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "029b5911",
   "metadata": {},
   "source": [
    "If a file isn't found, we can get an error like:\n",
    "\n",
    "    FileNotFoundError                         Traceback (most recent call last)\n",
    "    C:\\607243182.py in <module>\n",
    "          2 file = 'participants_data.txt'\n",
    "          3 \n",
    "    ----> 4 f = open(file)\n",
    "\n",
    "    FileNotFoundError: [Errno 2] No such file or directory: 'participants_data.txt'\n",
    "    \n",
    " To make this a bit more user friendly, the file-reading code needs to be inside a `try` command, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5e8fbc7",
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    f = open(file)\n",
    "    data_names = f.read().splitlines()\n",
    "    f.close()\n",
    "except IOError:\n",
    "    print(\"Cannot find file: \" + file)\n",
    "    exit()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19532134",
   "metadata": {},
   "source": [
    "To test the code above, add an error to your _file_ variable above (where you define the `file = 'participants_data.txt'` variable) and see if you get the right error message."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "72582cf7",
   "metadata": {},
   "source": [
    "#### 4.1.2 Reading big files <a class=\"anchor\" id=\"Ch412\"></a>\n",
    "\n",
    "The way we did things in the previous section is fine for a small file containing some strings. However, if we were reading a really huge file (say, several megabytes), then two things would happen. First, it would take a significant amount of time for Python to read all the data. Second, because all the data is read at once, at least as much memory as the file size would be used, and for truly enormous files, that might result in Python running out of memory.\n",
    "\n",
    "If you find yourself in the situation where you are reading a big file, you need to think about how you are going to handle it. For example, if you were *searching a file* for a particular string, you could just read one line of the file at a time, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aa137cb5",
   "metadata": {},
   "outputs": [],
   "source": [
    "file = 'participants_data.txt' \n",
    "find_file = 'P04_01042022_1400\\n'\n",
    "\n",
    "try:\n",
    "    f = open(file)\n",
    "    line = f.readline()\n",
    "    while line != '':\n",
    "        if line == find_file:\n",
    "            print('participant is in this file')\n",
    "            break\n",
    "        line = f.readline()\n",
    "    f.close()\n",
    "except IOError:\n",
    "    print(\"Cannot find file: \" + file)\n",
    "    exit()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b6247ca0",
   "metadata": {},
   "source": [
    "When the function `readline` gets to the last line of the file, it returns an empty string (`''`). Otherwise, it returns the contents of the line, including the end-of-line character (`\\n`) . If it reads a blank line that is actually just a gap between lines and not the end of the file, it will return just the end-of-line character (`\\n`). By the program only reading one line at a time, the memory being used is only ever equivalent to one full line.\n",
    "\n",
    "If the file is not broken into convenient lines, you can specify an input argument in `read` that limits the number of characters read. For example, the following will just read the first 20 characters of a file:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "96ccebaa",
   "metadata": {},
   "outputs": [],
   "source": [
    "f = open(file)\n",
    "f.read(21)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6b8ef2c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "f.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c5441b5",
   "metadata": {},
   "source": [
    "#### 4.1.3 Writing files <a class=\"anchor\" id=\"Ch413\"></a>\n",
    "\n",
    "Writing files is almost as simple. When a file is opened, as well as specifying the name of the file to `open`, you can also specify the mode in which to open the file. The mode is represented by a character, and if no mode is specified it is assumed to be `r` for `read`. The modes are as follows:\n",
    "\n",
    "• `r` (read).\n",
    "\n",
    "• `w` (write) Replaces the contents of any existing file with that name.\n",
    "\n",
    "• `a` (append) Appends anything to be written onto the end of an existing file.\n",
    "\n",
    "• `r+` Opens the file for both reading and writing (not often used).\n",
    "\n",
    "To write a file, you open it with a second parameter of `'w'`, `'a'`, or `'r+'`. Here’s an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d7c3dc7b",
   "metadata": {},
   "outputs": [],
   "source": [
    "f = open('test.txt','w')\n",
    "f.write('This file is not empty')\n",
    "f.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d20cfbb",
   "metadata": {},
   "source": [
    "Try finding the file using the file manager just to check it's there. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c1c009ee",
   "metadata": {},
   "source": [
    "#### 4.1.4 The File System <a class=\"anchor\" id=\"Ch414\"></a>\n",
    "\n",
    "Occasionally, you will need to do some file-system-type operations on files (moving them, copying them, and so on). Python uses the operating system to perform these actions, but provides a nice Python-style way of doing them. Many of these functions are in the `shutil` (shell utility) package. There’s a number of subtle variations on the basic copy and move features that deal with file permissions and metadata. In this section, we just deal with the basic operations. You can refer to the official Python documentation for any other functions (https://docs.python.org/3/library/).\n",
    "\n",
    "Here’s how to copy a file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "321a6ea9",
   "metadata": {},
   "outputs": [],
   "source": [
    "import shutil\n",
    "\n",
    "shutil.copy('test.txt','test_copy.txt')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be2783dc",
   "metadata": {},
   "source": [
    "Check in the file manager that you now have a copy of the `test.txt` file\n",
    "\n",
    "To move a file, either to change its name or move it to a different directory:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bcc4c52e",
   "metadata": {},
   "outputs": [],
   "source": [
    "shutil.move('test_copy.txt','test_dup.txt')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40f9a447",
   "metadata": {},
   "source": [
    "This works on directories as well as files. If you want to copy an entire folder—including all its contents and its content’s contents—you can use the function `copytree`. The rather dangerous function `rmtree`, on the other hand, will recursively *remove* a directory and all its contents — ⚠️ __exercise extreme caution with this one!__\n",
    "\n",
    "The nicest way of finding out what is in a directory is via _globbing_. The package `glob` allows you to create a list of files in a directory by specifying a wildcard (e.g. `*`). Here’s an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8edb8b83",
   "metadata": {},
   "outputs": [],
   "source": [
    "import glob\n",
    "\n",
    "glob.glob('*.txt')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b79cf020",
   "metadata": {},
   "source": [
    "If you just want all the files in the folder, you could use this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bc875743",
   "metadata": {},
   "outputs": [],
   "source": [
    "glob.glob('*')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f9b3c30",
   "metadata": {},
   "source": [
    "#### 4.1.5 Pickling <a class=\"anchor\" id=\"Ch415\"></a>\n",
    "\n",
    "Pickling involves saving the *contents of a variable* to a file in such a way that the file can be later loaded to get the *original value* back. The most common reason for wanting to do this is to save data between runs of a program. As an example, we can create a complex list containing another list and various other data objects and then pickle it into a file called `mylist.pickle`, like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bd35d176",
   "metadata": {},
   "outputs": [],
   "source": [
    "mylist = ['a', 123, [4, 5, True]]\n",
    "mylist"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "97ad97d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pickle\n",
    "\n",
    "f = open('mylist.pickle','wb')\n",
    "pickle.dump(mylist,f)\n",
    "f.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af1e4723",
   "metadata": {},
   "source": [
    "If you find the file and open it in an editor to have a look, you will see something cryptic. That is to be expected; it is text, but it is not meant to be in human-readable form. The pickle file is binary (that's why you open the file in `'wb'` mode). \n",
    "\n",
    "To reconstruct a pickle file into an object, here is what you do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2f05f3d7",
   "metadata": {},
   "outputs": [],
   "source": [
    "f = open('mylist.pickle','rb')\n",
    "other_array = pickle.load(f)\n",
    "f.close()\n",
    "\n",
    "other_array"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e338750",
   "metadata": {},
   "source": [
    "#### 4.1.6 JSON  <a class=\"anchor\" id=\"Ch416\"></a>\n",
    "\n",
    "JSON is a text format for representing data. It is used both in files and in web services using JSON as a common interchange format for data. Python makes it really easy to use JSON by creating lists and dictionaries from JSON text retrieved from a file or from the internet.\n",
    "\n",
    "As an example, create the following JSON file and save it as `'data_experiments.json'`:\n",
    "\n",
    "```json\n",
    "{\"participants\":[\n",
    "    {\"name\": \"P01_01042022_1215\", \"age\": 23, \"weight\": 63},\n",
    "    {\"name\": \"P02_01042022_1240\", \"age\": 56, \"weight\": 83},\n",
    "    {\"name\": \"P03_01042022_1315\", \"age\": 76, \"weight\": 58},\n",
    "    {\"name\": \"P04_01042022_1400\", \"age\": 33, \"weight\": 100},\n",
    "    {\"name\": \"P05_02042022_0900\", \"age\": 20, \"weight\": 87}\n",
    "]}\n",
    "```\n",
    "     \n",
    "When it comes to JSON, think of `{` and `}` as enclosing a Python directory. In this case, the directory has a *key* of `\"participants\"` and *value* that is a list contained by `[` and `]`. There are 5 values in that list, all of which are themselves dictionaries containing information about the participants.\n",
    "\n",
    "Each particiant dictionary has keys of `\"name\"`, `\"age\"`, and `\"weight\"`. The name token is a string enclosed within quotes and the age and weight are numbers (and so do not have quotes around them). \n",
    "\n",
    "Now let's try to import your saved JSON file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7ba4c559",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "\n",
    "f = open('data_experiments.json')\n",
    "j = json.load(f)\n",
    "f.close()\n",
    "\n",
    "print(j['participants'][1]['name'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4456665e",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(j['participants'][1]['age'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c693f79",
   "metadata": {},
   "source": [
    "The first thing we do is import the `json` library. We then open the file `data_experiments.json`, and because json is in a text format, unlike the pickle file, we do not have to open it as a binary file.\n",
    "\n",
    "The `json` method `load` reads the contents of the files and converts it into a dictionary. This is assigned to the variable `j`. The files are then closed, as we have read what we need from it.\n",
    "\n",
    "The final line of the program shows how you can use the `[key]` notation to navigate into the structure of dictionaries and lists that have been created in variable `j`. This first uses the *key* `['participants']` to retrieve the corresponding *value*, being the list of (dictionaries of) participants. It then uses `[1]` to select item `1` in the list (the second item/participant dictionary). Then, the usage of the *key* `['name']` selects the corresponding *value*, which is the participant name of the second participant."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2ea2807",
   "metadata": {},
   "source": [
    "## 5. Internet <a class=\"anchor\" id=\"Ch5\"></a>\n",
    "\n",
    "As well as being full of webpages, the internet is also a source of information for your programs rather than viewing them in the browser. Such web services are available for pretty much anything, from currency rates and stock prices to weather forecasts. The software on the server for such web services is called API (Application Programming Interface) and APIs generally use JSON as a way to communicate with your programs.\n",
    "\n",
    "As an example, we are going to use the service called `wheatherstack.com`. This service is for __free__, as long as you don't make too many demands on it. Therefore, it wants to track your use and so you need to register an account. Go to https://weatherstack.com and register an account. Then, find your key by clicking on the Dashboard button.\n",
    "\n",
    "You need to copy this key and past it into the `'key='` line of the program:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b747f8a6",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "import urllib.parse, urllib.request\n",
    "\n",
    "\n",
    "url = 'http://api.weatherstack.com/current'\n",
    "city = urllib.parse.quote('Delft')\n",
    "key =  \"\" # paste your key here!\n",
    "\n",
    "\n",
    "response = urllib.request.urlopen(url+ '?access_key=' + key + '&query='+ city)\n",
    "j = json.load(response)\n",
    "\n",
    "print(j)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1afc8f3",
   "metadata": {},
   "source": [
    "As you can see, we have received a whole load of information back from the API that we could make use of in our programs.\n",
    "The program uses the `urllib` library to perform the web request, contacting weatherstack's API, so this library has to be imported.\n",
    "\n",
    "Three variables are used, which will be assembled into the full URL to be sent to the API. They are the base URL, the city, and the API key. The base URL defines the website we want to receive information from. The city defines the location we want to know the weather in. URLs cannot have spaces in them, but some city names (like Den Haag) do. So, the method `urllib.parse.quote` is used to convert spaces into the `%20` escape characters expected in a URL. \n",
    "\n",
    "After defining these variables, `urllib.request.urlopen` opens a connection to the API as if you were opening a file  on your machine, and `json.load` converts this information into the JSON strcuture.\n",
    "\n",
    "To extract the current weather:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "74cf8389",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(j['current']['weather_descriptions'][0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0596e936",
   "metadata": {},
   "source": [
    "Sources:\n",
    "* Monk,Simon, Programming the Raspberry Pi, Getting Started with Python"
   ]
  }
 ],
 "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.11.5"
  },
  "vscode": {
   "interpreter": {
    "hash": "3e45daf00863230a827a161a48bb6a07fa17f2de93398243aa637230796bd1af"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}