notebooks/018_Running_Python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img alt='UCL' src=\"images/ucl_logo.png\" align='center'>\n",
    "\n",
    "\n",
    "[<img src=\"images/noun_post_2109127.svg\" width=\"50\" align='right'>](020_Python_files.ipynb)\n",
    "[<img src=\"images/noun_pre_2109128.svg\" width=\"50\" align='right'>](017_Functions.ipynb)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 018 Python codes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Whilst writing codes in Jupyter notebooks is useful and powerful, you will find over the course of GEOG0111 that you will need to develop your own codes as Python scripts. These are more portable than codes embedded in notebooks, and can also be used to develop your own code libraries. \n",
    "\n",
    "In this session, you will learn how to generate and use Python scripts from a notebook. In particular, you will learn the typical format of such scripts, and generate some simple scripts around some basic functions.\n",
    "\n",
    "At the end of the session, there is a practical exercise for you to do and submit. It does not provide part of your formal assessment, but it is important that you do the work and submit it, so we know if you are on track or need further help. If you do not submit the work, we cannot help you in this way.\n",
    "\n",
    "\n",
    "### Prerequisites\n",
    "\n",
    "You will need some understanding of the following:\n",
    "\n",
    "* [001 Using Notebooks](001_Notebook_use.ipynb)\n",
    "* [002 Unix](002_Unix.ipynb)\n",
    "* [005 Packages](005_Packages.ipynb)\n",
    "* [017 Functions](017_Functions.ipynb)\n",
    "\n",
    "In particular, you will need to recall how to use:\n",
    "\n",
    "   - [`unix` commands](002_Unix.ipynb): `ls -l; chmod`\n",
    "   - [`functions`](017_Functions.ipynb)\n",
    "   - [`import`](005_Packages.ipynb)\n",
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running Python  Code in a file\n",
    "\n",
    "We will generally use these Jupyter notebooks for running you Python codes, but you should also learn how to develop and run Python codes outside of the notebook. We provide a quick example of that here.\n",
    "\n",
    "### Running a Python script\n",
    "\n",
    "Python codes are written in files with the suffix `.py`, e.g. [`geog0111/helloWorld.py`](geog0111/helloWorld.py).\n",
    "\n",
    "If the file is defined as a Python script snd the file is executable (relevant x bit set), then we can run. it from a shell in the same way we would run any other `unix` command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "chmod +x geog0111/helloWorld.py\n",
    "#run the script\n",
    "geog0111/helloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Python script is a Python code file that contains:\n",
    "\n",
    "    #!/usr/bin/env python\n",
    "    \n",
    "as the first line in the file, and is executable. We can see if a file is executable by getting a 'long' listing using the `unix` command `ls -l`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-rwxr-xr-x@ 1 philiplewis  staff  489 12 Dec  2022 \u001b[31mgeog0111/helloWorld.py\u001b[m\u001b[m\r\n"
     ]
    }
   ],
   "source": [
    "!ls -l geog0111/helloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first field gives us the file permissions:\n",
    "\n",
    "    -rwxr-xr-x\n",
    "    \n",
    "with the `x` bit telling us that it is executable. The permissions for this file are set to `755` (`111` `101` `101` in octal) which we can set with the `unix`  command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-rwxr-xr-x@ 1 philiplewis  staff  489 12 Dec  2022 geog0111/helloWorld.py\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "chmod 755 geog0111/helloWorld.py\n",
    "ls -l geog0111/helloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Running Python code from Python\n",
    "\n",
    "We can also run the Python code contained in [`geog0111/helloWorld.py`](geog0111/helloWorld.py) from a `notebook` cell using `%run` (or from an `ipython` prompt using just `run`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "%run geog0111/helloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another thing we can do is to `import` the code from the Python file into Python:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "from geog0111.helloWorld import helloWorld\n",
    "helloWorld()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This import statement imports the module `helloWorld` from the library `geog0111` (w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Form of a Python script\n",
    "\n",
    "We will go into more details on this in later classes, but the main format of a Python file should be along the lines of the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "#!/usr/bin/env python\n",
    "# -*- coding: utf-8 -*- \n",
    "\n",
    "'''\n",
    "helloWorld\n",
    "\n",
    "  function print the string 'hello world'\n",
    "  \n",
    "'''\n",
    "\n",
    "__author__    = \"P Lewis\"\n",
    "__copyright__ = \"Copyright 2020 P Lewis\"\n",
    "__license__   = \"GPLv3\"\n",
    "__email__     = \"p.lewis@ucl.ac.uk\"\n",
    "\n",
    "def helloWorld():\n",
    "    '''function to print the string \"hello world\"'''\n",
    "    print('hello world')\n",
    "   \n",
    "   \n",
    "# example calling the function\n",
    "def main():\n",
    "    helloWorld()\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    # execute only if run as a script\n",
    "    main()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This same code is contained in the file [geog0111/helloWorld.py](geog0111/helloWorld.py). Although the amount of comments and code in there might seem a little overkill just to print out `hello world`, it is good for you to get into the habit of writing your Python codes in this way. \n",
    "\n",
    "To briefly explain the blocks of code:\n",
    "\n",
    "    #!/usr/bin/env python\n",
    "    # -*- coding: utf-8 -*- \n",
    "\n",
    "This first line of the file allows the shell to know that this file should be interpreted with Python. It is good practice for you to include this as the first line of your Python codes so they can be run as scripts. The second line here is optional, but provides information on the python file encoding.\n",
    "\n",
    "\n",
    "    '''\n",
    "    helloWorld\n",
    "\n",
    "      function print the string 'hello world'\n",
    "\n",
    "    '''\n",
    "    __author__    = \"P Lewis\"\n",
    "    __copyright__ = \"Copyright 2020 P Lewis\"\n",
    "    __license__   = \"GPLv3\"\n",
    "    __email__     = \"p.lewis@ucl.ac.uk\"\n",
    "\n",
    "We then have a document string (contained within pairs of triple quotes) describing the purpose and some features of the code in this file. We provide some further information as variables written in the form `__var__` as relevant metadata for the file.  \n",
    "\n",
    "    def helloWorld():\n",
    "        '''function to print the string \"hello world\"'''\n",
    "        print('hello world')\n",
    "\n",
    "Next, we define a *function* containing the code we want. In this case, the main body of the code is simply:\n",
    "\n",
    "    print('hello world')\n",
    "    \n",
    "as in the examples above. The syntax `def helloWorld():` defines a function called `helloWorld` with no arguments (there is nothing defined here in the brackets). The code for the function is indented (4 spaces). \n",
    "\n",
    "After defining the function, we give a document string to associate with it and give users help information:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function helloWorld in module __main__:\n",
      "\n",
      "helloWorld()\n",
      "    function to print the string \"hello world\"\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(helloWorld)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the last part of the file, we provide some utilities that allow the file to be run as a script.\n",
    "\n",
    "First, we define a function called `main()` that provides an example of calling the function we have created:\n",
    "\n",
    "    # example calling the function    \n",
    "    def main():\n",
    "        helloWorld()\n",
    "        \n",
    "\n",
    "This should be accompanied by some comments of doc-string explaining what we are doing in the code.\n",
    " \n",
    "The final part of the file contains the code that allows this file to be run as a script:\n",
    "\n",
    "    if __name__ == \"__main__\":\n",
    "        # execute only if run as a script\n",
    "        main()\n",
    "        \n",
    "This is pretty standard syntax, so we will not go into details now, other than to note that this is the mechanism by which running this file as a script makes the call to `main()`, which then calls our example code running `helloWorld()`.\n",
    "\n",
    "The final thing we need to do is to make our script executable. This involves setting some permissions on the file with the function `Path().chmod()`. The code to do this, for the file  [geog0111/helloWorld.py](geog0111/helloWorld.py) from Python is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "Path('geog0111/helloWorld.py').chmod(int('755', base=8))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes, we might use the `unix` (`bash`) shell equivalent command to do this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "chmod 755 geog0111/helloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can run the Python code from a code cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "%run geog0111/helloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that using `%run` in the code cell (or just `run` in other Python codes) allows us to run a python command from a Python file in the cell, rather than the usual Python codes.\n",
    "\n",
    "An alternative is to make the whole cell into one to run bash commands with `%%bash`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "geog0111/helloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Follow-up on doc-strings\n",
    "\n",
    "Please note that document strings are an important part of Python code. There are several helpful tutorials on the internet that will help you write better documentation that you may wish to follow up:\n",
    "\n",
    "* [PEP-0257](https://www.python.org/dev/peps/pep-0257/)\n",
    "* [Datacamp tutorial](https://www.datacamp.com/community/tutorials/docstrings-python)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Editing a file\n",
    "\n",
    "To do the task below, you will need to invoke a text editor of some sort to create the Python file. There are several ways you can do this, depending on how you are using these notebooks.\n",
    "\n",
    "\n",
    "### Jupyter notebook\n",
    "\n",
    "If you are in the GEOG0111 class, you will most likely be using the notebook server. In this case, follow these instructions:\n",
    "\n",
    "You can open a text editor from a Jupyter notebook server from the menu on the right hand side of the Jupyter homepage window:\n",
    "\n",
    "![](images/te.png)\n",
    "\n",
    "You can change file permissions using a command similar to that above (here, set for execute):\n",
    "\n",
    "        from pathlib import Path\n",
    "        Path(MYFILE).chmod(int('755', base=8))\n",
    "        \n",
    "        \n",
    "\n",
    "### From JupyterLab\n",
    "\n",
    "If you are using this notebook in JupyterLab, go to the launcher tab and you should see various tools that you can launch:\n",
    "\n",
    "![JupyterLab tools](images/jl.png)\n",
    "\n",
    "Among these you will see 'text file'. Launch a text file, write your Python code into the file, and save it (`File -> Save As`) to the Python file name you want in your `work directory` (e.g. `work/test.py`).\n",
    "\n",
    "Alternatively, use the menu item `File -> New -> Text File` to open a new text file.\n",
    "\n",
    "To change the permissions on the file from JupyterLab, open a shell (e.g. using \n",
    "`File -> New -> Terminal`) and in there, type (assuming your file is called `work/test.py`):\n",
    "\n",
    "    chmod 755 work/test.py\n",
    "    \n",
    "    \n",
    "![JupyterLab terminal](images/term.png)\n",
    "\n",
    "\n",
    "### Use a text editor\n",
    "\n",
    "To do the task below, you will need to invoke a text editor of some sort to create the Python file. \n",
    "\n",
    "### Create in bash\n",
    "\n",
    "We can simply create a file in a bash script by following the example below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "\n",
    "# code between the next line and the \n",
    "# End Of File (EOF) marker will be saved in \n",
    "# to the file work/myHelloWorld.py\n",
    "cat << EOF > work/myHelloWorld.py\n",
    "#!/usr/bin/env python\n",
    "# -*- coding: utf-8 -*- \n",
    "\n",
    "'''\n",
    "helloWorld\n",
    "\n",
    "function print the string \"hello world\"\n",
    "\n",
    "'''\n",
    "__author__    = \"P Lewis\"\n",
    "__copyright__ = \"Copyright 2020 P Lewis\"\n",
    "__license__   = \"GPLv3\"\n",
    "__email__     = \"p.lewis@ucl.ac.uk\"\n",
    "\n",
    "def helloWorld():\n",
    "    '''function to print the string \"hello world\"'''\n",
    "    print('hello world')\n",
    "    \n",
    "    \n",
    "# example calling the function    \n",
    "def main():\n",
    "    helloWorld()\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    # execute only if run as a script\n",
    "    main()\n",
    "EOF\n",
    "\n",
    "# Chmod 755 to make the file executable\n",
    "chmod 755 work/myHelloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This should have created a file called `work/myHelloWorld.py` and made it executable (using bash to call chmod, rather than doing it in Python as above). \n",
    "\n",
    "**Be aware that backquotes `` have a special meaning in `bash`, so make sure you do not copy any backquotes from the text in these documents when you use them in `bash`.**\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now run it as above:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "%run work/myHelloWorld.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should now be able to load this Python file directly in Jupyter, using `File -> Open` then click through to the Python file you generated. \n",
    "\n",
    "Once you save the file, run the Python code again (`%run work/myHelloWorld.py`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "shown",
    "solution2_first": true
   },
   "source": [
    "#### Exercise 1\n",
    "\n",
    "* Create a Python file in your [`work`](work) folder based on the example above and call it `work/myFirstCode.py`\n",
    "* Modify the code to achieve the following:\n",
    "    - make a function called `myFirstCode` that prints out a greeting message\n",
    "    - update the document strings in the file as appropriate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "solution2": "shown"
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "# ANSWER : create the Python file with the code we want\n",
    "\n",
    "# Instructions:\n",
    "#\n",
    "# Create a Python file in your work\n",
    "# folder based on the example in geog0111/helloWorld.py\n",
    "# and call it `work/myFirstCode.py`\n",
    "#\n",
    "# Modify the code to achieve the following:\n",
    "# make a function called myFirstCode that prints out a greeting message\n",
    "# update the document strings in the file as appropriate\n",
    "\n",
    "# code between the next line and the \n",
    "# End Of File (EOF) marker will be saved in \n",
    "# to the file work/myFirstCode.py\n",
    "cat << EOF > work/myFirstCode.py\n",
    "#!/usr/bin/env python\n",
    "# -*- coding: utf-8 -*- \n",
    "\n",
    "'''\n",
    "myFirstCode\n",
    "\n",
    "  function to print a greeting\n",
    "  \n",
    "'''\n",
    "__author__    = \"P Lewis\"\n",
    "__copyright__ = \"Copyright 2020 P Lewis\"\n",
    "__license__   = \"GPLv3\"\n",
    "__email__     = \"p.lewis@ucl.ac.uk\"\n",
    "\n",
    "def myFirstCode():\n",
    "    '''function to print a greeting'''\n",
    "    print('hello from me')\n",
    "    \n",
    "    \n",
    "# example calling the function    \n",
    "def main():\n",
    "    myFirstCode()\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    # execute only if run as a script\n",
    "    main()\n",
    "EOF\n",
    "\n",
    "# Chmod 755 to make the file executable\n",
    "chmod 755 work/myFirstCode.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "solution2": "shown"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello from me\n"
     ]
    }
   ],
   "source": [
    "# ANSWER\n",
    "%run work/myFirstCode.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding command line arguments\n",
    "\n",
    "We have achieved something today, in creating a Python code in a file, making it executable, and running it. However, it is a little limited in scope: it just prints out the message the we **hard wired** into it.\n",
    "\n",
    "It is better to design codes to have some more flexibility than this. Suppose we want to be able to run our code `work/myFirstCode.py` so that we can pass a name though to the script and print out, e.g.:\n",
    "\n",
    "    hello from Fred\n",
    "        \n",
    "or\n",
    "\n",
    "    hello from Hermione\n",
    "        \n",
    "How could we achieve that?\n",
    "\n",
    "The answer, as we have seen before, is to pass an argument to our function. So, instead of having:\n",
    "         \n",
    "    def helloWorld():\n",
    "        '''function to print the string \"hello from me\"'''\n",
    "        print('hello from me')\n",
    "\n",
    "we pass an argument that we might call `name`, and conveniently pass this through to the `print()` statement using an `f-string`.\n",
    "\n",
    "         \n",
    "    def helloWorld(name):\n",
    "        '''function to print the string \"hello\" from name'''\n",
    "        print(f'hello from {name}')\n",
    "\n",
    "Let's test that before going further:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello from Fred\n",
      "hello from Hermione\n"
     ]
    }
   ],
   "source": [
    "def hello(name):\n",
    "    '''function to print \"hello from {name}\"'''\n",
    "    print(f'hello from {name}')\n",
    "    \n",
    "# call the function with some argument\n",
    "hello('Fred')\n",
    "hello('Hermione')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have seen that that code operates correctly -- it is very good practice to test any small incremental developments in your code in this way.\n",
    "\n",
    "Next, let's think about how to embed that modified function in our code in our file. We will call the code `work/hello.py` and copy most of it from the previous example. We need to make sure we update any document strings, and also take care that we are calling the correct function (it is `hello()` now, not `helloWorld()` as previously).\n",
    "\n",
    "Last then, when we make the call to `hello()` from the `main()` function, we need to make sure we pass it a string that it can print out, For example:\n",
    "\n",
    "    def main():\n",
    "        hello('Fred')\n",
    "\n",
    "Otherwise, if we leave `main()` as:\n",
    "\n",
    "    def main():\n",
    "        hello()\n",
    "\n",
    "the code would not run and give a `TypeError:`\n",
    "\n",
    "    TypeError: hello() missing 1 required positional argument: 'name'\n",
    "    \n",
    " Again, this is an incremental change, so let's test the new code before going any further:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "\n",
    "# code between the next line and the \n",
    "# End Of File (EOF) marker will be saved in \n",
    "# to the file work/hello.py\n",
    "cat << EOF > work/hello.py\n",
    "#!/usr/bin/env python\n",
    "# -*- coding: utf-8 -*- \n",
    "\n",
    "'''\n",
    "hello\n",
    "\n",
    "function to print 'hello from {name}'\n",
    "  \n",
    "'''\n",
    "__author__    = \"P Lewis\"\n",
    "__copyright__ = \"Copyright 2020 P Lewis\"\n",
    "__license__   = \"GPLv3\"\n",
    "__email__     = \"p.lewis@ucl.ac.uk\"\n",
    "\n",
    "def hello(name):\n",
    "    '''function to print \"hello from {name}\"'''\n",
    "    print(f'hello from {name}')\n",
    "    \n",
    "# example calling the function    \n",
    "def main():\n",
    "    hello('Fred')\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    # execute only if run as a script\n",
    "    main()\n",
    "EOF\n",
    "\n",
    "# Chmod 755 to make the file executable\n",
    "chmod 755 work/hello.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello from Fred\n"
     ]
    }
   ],
   "source": [
    "# run code\n",
    "%run work/hello.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now have a more flexible function `hello(name)`, but when we run the script `work/hello.py` we will always be running the same code in `main()`, so we can only ever get a hello from Fred.\n",
    "\n",
    "When we write a Python script, we often will want to make that more flexible too. We can do this by passing a command-line argument through to the script. What we want to happen is that when we run:\n",
    "\n",
    "    %run work/hello.py Hermione\n",
    "    \n",
    "we get the response:\n",
    "\n",
    "    hello from Hermione\n",
    "    \n",
    "That isn't too much of a step from where we are. We simply need to pass the command line argument through the script. In a Python script, we do this using the list\n",
    "\n",
    "    sys.argv\n",
    "    \n",
    "Let's just see how that works:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['/Users/philiplewis/opt/anaconda3/envs/geog0111/lib/python3.7/site-packages/ipykernel_launcher.py', '-f', '/Users/philiplewis/Library/Jupyter/runtime/kernel-46d1f085-b39c-404a-8ddb-d59dd32b0760.json']\n"
     ]
    }
   ],
   "source": [
    "import sys\n",
    "\n",
    "print(sys.argv)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running from the notebook, we get to see the full command that is run when we launch this notebook. Since `sys` is a package, we first import it:\n",
    "\n",
    "    import sys\n",
    "    \n",
    "Then we can access the list of arguments `sys.argv`. The first item in the list, `sys.argv[0]`  is the name of the program being run (`ipykernel_launcher.py`). The other items in the list are the command line arguments for running the notebook.\n",
    "\n",
    "Lets see how this applies to running our own code. We generate a short test script:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "\n",
    "cat << EOF > work/test.py\n",
    "#!/usr/bin/env python\n",
    "# -*- coding: utf-8 -*- \n",
    "\n",
    "import sys\n",
    "\n",
    "'''\n",
    "helloWorld\n",
    "\n",
    "function print the string 'hello world'\n",
    "\n",
    "'''\n",
    "__author__    = \"P Lewis\"\n",
    "__copyright__ = \"Copyright 2020 P Lewis\"\n",
    "__license__   = \"GPLv3\"\n",
    "__email__     = \"p.lewis@ucl.ac.uk\"\n",
    "\n",
    "def hello(name):\n",
    "    '''function to print \"hello from {name}\"'''\n",
    "    print(f'hello from {name}')\n",
    "    \n",
    "# example calling the function    \n",
    "def main(name):\n",
    "    hello(name)\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    # execute only if run as a script\n",
    "    # only pass argv[1] here\n",
    "    main(sys.argv[1])\n",
    "EOF\n",
    "\n",
    "# Chmod 755 to make the file executable\n",
    "chmod 755 work/test.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello from Hermione\n"
     ]
    }
   ],
   "source": [
    "%run work/test.py Hermione"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that running the script:\n",
    "\n",
    "    work/test.py Hermione\n",
    "    \n",
    "means that `sys.argv` inside the script contains the list `['work/test.py', 'Hermione']`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Formative assessment\n",
    "\n",
    "To get some feedback on how you are doing, you should complete and submit the formative assessment [061 Script](061_Script.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this session, we have learned the usual form of a Python script, including the `#! /usr/bin/env python`  on the first line of the file to call the Python interpreter. We have seen how to include document strings telling any user how to use the codes we develop, and well as providing lots of comments with `#` lines to describe what we are doing in the code, and why. We have seen that a Python script will typically finish with something along the lines of:\n",
    "\n",
    "    def main(args):\n",
    "      # call or demonstrate our function\n",
    "      hello(args)\n",
    "\n",
    "    if __name__ == \"__main__\":\n",
    "        # execute only if run as a script\n",
    "        main(sys.argv)\n",
    "        \n",
    "the `main()` function serving to provide a call to the codes we have developed, as well as any interface to the command line. We have seen that `sys.argv` contains command line parameters (and the program name) which we can use to modify the behaviour of the script. \n",
    "\n",
    "We have also seen how we can use \n",
    "\n",
    "    cat << EOF > file.py\n",
    "    EOF\n",
    "   \n",
    "in a bash script to generate and document our Python files, though we would also typically edits the file through some text editor.\n",
    "\n",
    "We have seen how to run a Python script from a notebook, using `%run` or via a bash shell with `%%bash`. We have seen that to 'run' a Python script, we need to change the file permissions iusing `chmod`, either in `bash` or using `Path().chmod()`. We have used the octal code `755` to change the file permissions for execution.\n",
    "\n",
    "Remember:\n",
    "\n",
    "\n",
    "\n",
    "|Command| Comment| Example| Result|\n",
    "|---|---|---|---|\n",
    "|`!unix_cmd` | Run unix command `unix_cmd` from Jupyter code cell | `!geog0111/helloWorld.py`| `hello world`|\n",
    "|| | `!ls -l geog0111/helloWorld.py`| `-rwxr-xr-x 1 ucfalew ucfa 514 Oct  1 13:10 geog0111/helloWorld.py`|\n",
    "|`%%bash` | Turn Jupyter Python code cell into `bash` cell | `%%bash` | | \n",
    "| | | `chmod 755 geog0111/helloWorld.py`\n",
    "| | |`ls -l geog0111/helloWorld.py` | `-rwxr-xr-x 1 ucfalew ucfa 514 Oct  1 13:10 geog0111/helloWorld.py`|\n",
    "| `%run script.py` | Run Python script `script.py` from Jupyter code cell| `%run geog0111/helloWorld.py` | `hello world`|\n",
    "|     `cat << XX > YY; XX` | Put  marker `XX` in bash script and send text up to `XX` into file `YY` | `cat << EOF > work/file.py` |\n",
    "|||    `hello world` | `cat work/file.py`\n",
    "|||    `EOF` | `hello world`|\n",
    "\n",
    "Form of a Python script:\n",
    "\n",
    "\n",
    "            #!/usr/bin/env python\n",
    "            # -*- coding: utf-8 -*- \n",
    "\n",
    "            '''\n",
    "            helloWorld\n",
    "\n",
    "            function print the string 'hello world'\n",
    "\n",
    "            '''\n",
    "\n",
    "            __author__    = \"P Lewis\"\n",
    "            __copyright__ = \"Copyright 2020 P Lewis\"\n",
    "            __license__   = \"GPLv3\"\n",
    "            __email__     = \"p.lewis@ucl.ac.uk\"\n",
    "\n",
    "            def helloWorld():\n",
    "                '''function to print the string \"hello world\"'''\n",
    "                print('hello world')\n",
    "\n",
    "\n",
    "            # example calling the function\n",
    "            def main():\n",
    "                helloWorld()\n",
    "\n",
    "            if __name__ == \"__main__\":\n",
    "                # execute only if run as a script\n",
    "                main()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "[<img src=\"images/noun_post_2109127.svg\" width=\"50\" align='right'>](020_Python_files.ipynb)\n",
    "[<img src=\"images/noun_pre_2109128.svg\" width=\"50\" align='right'>](017_Functions.ipynb)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "conda env:geog0111-geog0111",
   "language": "python",
   "name": "conda-env-geog0111-geog0111-py"
  },
  "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.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}