notebooks/003_Help.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img alt='UCL' src=\"images/ucl_logo.png\" align='center'>\n",
    "\n",
    "[<img src=\"images/noun_post_2109127.svg\" width=\"50\" align='right'>](004_Accounts.ipynb)\n",
    "[<img src=\"images/noun_pre_2109128.svg\" width=\"50\" align='right'>](002_Unix.ipynb)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "hide_input": true
   },
   "source": [
    "\n",
    "# 003 Help\n",
    "\n",
    "## Introduction\n",
    "\n",
    "#### Purpose\n",
    "\n",
    "In this notebook, we will learn how to get useful information on python commands using `help()` and associated methods.\n",
    "\n",
    "We will use `help(list)` as an example to learn about the class `list` from the help material. You are not expected to learn everything about `lists` here, as we will return to it later in the course. But you should find this useful in learning how to learn.\n",
    "\n",
    "We will learn how to access some on-line resources.\n",
    "\n",
    "#### Prerequisites\n",
    "\n",
    "You will need some understanding of the following:\n",
    "\n",
    "* [001 Using Notebooks](001_Notebook_use.ipynb)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "hide_input": false
   },
   "source": [
    "## Help Method\n",
    "\n",
    "### help()\n",
    "\n",
    "You can get help on an object using the `help()` method. This will return a full manual page of the class documentation. You need to gain some experience in reading these and understanding some of the terminology. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-07-22T08:29:08.607974Z",
     "start_time": "2020-07-22T08:29:08.561456Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method_descriptor:\n",
      "\n",
      "append(self, object, /)\n",
      "    Append object to the end of the list.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "#the method help()\n",
    "help(list.append)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "#### Exercise 1\n",
    "\n",
    "* In a new code cell, type `help(list)` and look through the information provided."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "scrolled": true,
    "solution2": "hidden"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on class list in module builtins:\n",
      "\n",
      "class list(object)\n",
      " |  list(iterable=(), /)\n",
      " |  \n",
      " |  Built-in mutable sequence.\n",
      " |  \n",
      " |  If no argument is given, the constructor creates a new empty list.\n",
      " |  The argument must be an iterable if specified.\n",
      " |  \n",
      " |  Methods defined here:\n",
      " |  \n",
      " |  __add__(self, value, /)\n",
      " |      Return self+value.\n",
      " |  \n",
      " |  __contains__(self, key, /)\n",
      " |      Return key in self.\n",
      " |  \n",
      " |  __delitem__(self, key, /)\n",
      " |      Delete self[key].\n",
      " |  \n",
      " |  __eq__(self, value, /)\n",
      " |      Return self==value.\n",
      " |  \n",
      " |  __ge__(self, value, /)\n",
      " |      Return self>=value.\n",
      " |  \n",
      " |  __getattribute__(self, name, /)\n",
      " |      Return getattr(self, name).\n",
      " |  \n",
      " |  __getitem__(...)\n",
      " |      x.__getitem__(y) <==> x[y]\n",
      " |  \n",
      " |  __gt__(self, value, /)\n",
      " |      Return self>value.\n",
      " |  \n",
      " |  __iadd__(self, value, /)\n",
      " |      Implement self+=value.\n",
      " |  \n",
      " |  __imul__(self, value, /)\n",
      " |      Implement self*=value.\n",
      " |  \n",
      " |  __init__(self, /, *args, **kwargs)\n",
      " |      Initialize self.  See help(type(self)) for accurate signature.\n",
      " |  \n",
      " |  __iter__(self, /)\n",
      " |      Implement iter(self).\n",
      " |  \n",
      " |  __le__(self, value, /)\n",
      " |      Return self<=value.\n",
      " |  \n",
      " |  __len__(self, /)\n",
      " |      Return len(self).\n",
      " |  \n",
      " |  __lt__(self, value, /)\n",
      " |      Return self<value.\n",
      " |  \n",
      " |  __mul__(self, value, /)\n",
      " |      Return self*value.\n",
      " |  \n",
      " |  __ne__(self, value, /)\n",
      " |      Return self!=value.\n",
      " |  \n",
      " |  __repr__(self, /)\n",
      " |      Return repr(self).\n",
      " |  \n",
      " |  __reversed__(self, /)\n",
      " |      Return a reverse iterator over the list.\n",
      " |  \n",
      " |  __rmul__(self, value, /)\n",
      " |      Return value*self.\n",
      " |  \n",
      " |  __setitem__(self, key, value, /)\n",
      " |      Set self[key] to value.\n",
      " |  \n",
      " |  __sizeof__(self, /)\n",
      " |      Return the size of the list in memory, in bytes.\n",
      " |  \n",
      " |  append(self, object, /)\n",
      " |      Append object to the end of the list.\n",
      " |  \n",
      " |  clear(self, /)\n",
      " |      Remove all items from list.\n",
      " |  \n",
      " |  copy(self, /)\n",
      " |      Return a shallow copy of the list.\n",
      " |  \n",
      " |  count(self, value, /)\n",
      " |      Return number of occurrences of value.\n",
      " |  \n",
      " |  extend(self, iterable, /)\n",
      " |      Extend list by appending elements from the iterable.\n",
      " |  \n",
      " |  index(self, value, start=0, stop=9223372036854775807, /)\n",
      " |      Return first index of value.\n",
      " |      \n",
      " |      Raises ValueError if the value is not present.\n",
      " |  \n",
      " |  insert(self, index, object, /)\n",
      " |      Insert object before index.\n",
      " |  \n",
      " |  pop(self, index=-1, /)\n",
      " |      Remove and return item at index (default last).\n",
      " |      \n",
      " |      Raises IndexError if list is empty or index is out of range.\n",
      " |  \n",
      " |  remove(self, value, /)\n",
      " |      Remove first occurrence of value.\n",
      " |      \n",
      " |      Raises ValueError if the value is not present.\n",
      " |  \n",
      " |  reverse(self, /)\n",
      " |      Reverse *IN PLACE*.\n",
      " |  \n",
      " |  sort(self, /, *, key=None, reverse=False)\n",
      " |      Stable sort *IN PLACE*.\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Static methods defined here:\n",
      " |  \n",
      " |  __new__(*args, **kwargs) from builtins.type\n",
      " |      Create and return a new object.  See help(type) for accurate signature.\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Data and other attributes defined here:\n",
      " |  \n",
      " |  __hash__ = None\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You need to have some practice in interpreting this sort of information.\n",
    "\n",
    "\n",
    "\n",
    "Scanning the above, we notice for example:\n",
    "\n",
    "* `list` is a class in python\n",
    "* It has some methods such as `append(self, object, /)` and `clear(self, /)`.\n",
    "\n",
    "We now create two object instances of a list class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-07-22T08:30:16.805628Z",
     "start_time": "2020-07-22T08:30:16.803121Z"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "alist = [1, 2, 3]\n",
    "blist = [4, 5, 6]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and apply methods we see in the Help documentation, here: `append()` and `clear()`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-07-22T08:31:07.394759Z",
     "start_time": "2020-07-22T08:31:07.378464Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "alist = [1, 2, 3, [4, 5, 6]]\n",
      "blist = []\n"
     ]
    }
   ],
   "source": [
    "alist = [1, 2, 3]\n",
    "blist = [4, 5, 6]\n",
    "\n",
    "# append blist as the last element of alist\n",
    "alist.append(blist)\n",
    "print('alist =', alist)\n",
    "\n",
    "# clear blist\n",
    "blist.clear()\n",
    "print('blist =', blist)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "#### Exercise 2\n",
    "\n",
    "* Read through the help information for list, above.\n",
    "* In a new cell, create lists called `alist` and `blist`:\n",
    "\n",
    "        alist = ['one','three','two']\n",
    "        blist = ['four','six','zero']\n",
    "    \n",
    "* print the lists with:\n",
    "\n",
    "        print(alist,blist)\n",
    "    \n",
    "Using the help information, work out how to:\n",
    "\n",
    "* extend `alist` with `blist` to create `['one','three','two','four','six','zero']`. N.B. This is not quite the same as our use of `append()` above.\n",
    "* sort the new `alist` into **alpabetical order** and print the results\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-07-22T08:38:21.816823Z",
     "start_time": "2020-07-22T08:38:21.812055Z"
    },
    "scrolled": true,
    "solution2": "hidden"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['one', 'three', 'two'] ['four', 'six', 'zero']\n",
      "extended ['one', 'three', 'two', 'four', 'six', 'zero']\n",
      "sorted ['four', 'one', 'six', 'three', 'two', 'zero']\n"
     ]
    }
   ],
   "source": [
    "# ANSWERS\n",
    "alist = ['one', 'three', 'two']\n",
    "blist = ['four', 'six', 'zero']\n",
    "print(alist, blist)\n",
    "\n",
    "# join: \n",
    "# extend(self, iterable, /)\n",
    "#      Extend list by appending elements from the iterable.\n",
    "alist.extend(blist)\n",
    "print(\"extended\", alist)\n",
    "\n",
    "# sort\n",
    "# sort(self, /, *, key=None, reverse=False)\n",
    "#       Stable sort *IN PLACE*.\n",
    "alist.sort()\n",
    "print(\"sorted\", alist)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## online help\n",
    "\n",
    "Not surprisingly, there is lots of help online. A key resource is [www.python.org](https://www.python.org/). Another useful one is [www.w3schools.com/python](https://www.w3schools.com/python):\n",
    "\n",
    "* [list](https://www.w3schools.com/python/python_ref_list.asp)\n",
    "* [list sort](https://www.w3schools.com/python/ref_list_sort.asp)\n",
    "* [list sort: try it yourself](https://www.w3schools.com/python/trypython.asp?filename=demo_ref_list_sort)\n",
    "\n",
    "A useful forum you can search for help on coding problems is [https://stackoverflow.com](https://stackoverflow.com), for example [https://stackoverflow.com/search?q=help+on+python+lists](https://stackoverflow.com/search?q=help+on+python+lists), but not all posts are equally useful: pay attention to comments from other users on any answer, as well as post votes. Do not look on `stackoverflow` until you have exhausted simpler help methods."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## help?\n",
    "\n",
    "You can get a shorter set of basic help by putting `?` after the object. \n",
    "\n",
    "In a notebook, this will show in a new window at the bottom of the book. You can get rid of this by clicking the `x`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "list?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "### Learning new things\n",
    "\n",
    "Let's use that knowledge to learn something new:\n",
    "\n",
    "* Use online material from [https://www.w3schools.com](https://www.w3schools.com/python) or elsewhere to learn the basics of `for` loops.\n",
    "\n",
    "#### Exercise 3\n",
    "\n",
    "* Find help for the class `range` to understand how to use this to generate a sequence of integers from 10 to 1 in steps of -1\n",
    "* Use what you have learned to write a `for` loop below that counts backwards from 10 to 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10\n",
      "9\n",
      "8\n",
      "7\n",
      "6\n",
      "5\n",
      "4\n",
      "3\n",
      "2\n",
      "1\n"
     ]
    }
   ],
   "source": [
    "# ANSWER\n",
    "# Use what you have learned to write a \n",
    "# `for` loop below that counts backwards from 10 to 0\n",
    "\n",
    "for i in range(10,0,-1):\n",
    "    print(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this session, we  have learned some different ways to access help on the operation and options for python commands. These include: `help()`, use of `?` and using online help. Practically, you may use one or more of these methods to find out how something works, or get some examples. We have come across the following commands:\n",
    "\n",
    "\n",
    "|  command | purpose  |   \n",
    "|---|---|\n",
    "| `help(m)`  |  print document string for method `m` |  \n",
    "| `m?`  |  print short document string for method `m` |  \n",
    "\n",
    "\n",
    "We have also touched upon the following commands in the exercises:\n",
    "\n",
    "\n",
    "|  command | purpose  |   \n",
    "|---|---|\n",
    "| `list`  |  Python data type for lists |  \n",
    "| `list.append()`  | append item to list  |   \n",
    "| `list.clear()`  | clear item from list  |  \n",
    "| `list.sort`  | in-line list sort  |  \n",
    "| `range(start,stop,step)`  | list-like generator for integers from `start` to (but not including) `stop` in steps of `step`  |  \n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "You might notice that there are many online forums you can post to to get advice on coding, and we mention  [https://stackoverflow.com](https://stackoverflow.com) as an example. Remember that not all posts are equally useful: pay attention to comments from other users on any answer, as well as post votes. Do not look on `stackoverflow` until you have exhausted simpler help methods. You should *not* generally be posting on these in this course. You will find answers to all that you need in these notes or on existing online pages. You most certainly must *not* post on forums asking questions about anyt exercises you need to complete or work you need to submit. The course administrators may monitor this.\n",
    "\n",
    "### You should know how to get help on Python functions \n",
    "\n",
    "You should know how to learn about how to use a particular function, through reading the help information. Take notice of the formatting of this, as you will need to be writing your own help statements later in the course.\n",
    "\n",
    "You should know how to use the Python function `range()` and understand teh basics of how to use the Python `list` data type.\n",
    "\n",
    "If you are unsure of any of these, then try going over the material again, explore other resources you may find, and/or come to the Thursday help sessions and ask for help."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "[<img src=\"images/noun_post_2109127.svg\" width=\"50\" align='right'>](004_Accounts.ipynb)\n",
    "[<img src=\"images/noun_pre_2109128.svg\" width=\"50\" align='right'>](002_Unix.ipynb)\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "gist": {
   "data": {
    "description": "Chapter0_help.ipynb",
    "public": true
   },
   "id": ""
  },
  "hide_input": false,
  "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"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": "1.1",
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "207px"
   },
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}