notebooks/01.01-Help-And-Documentation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--BOOK_INFORMATION-->\n",
    "<img align=\"left\" style=\"padding-right:10px;\" src=\"figures/PDSH-cover-small.png\">\n",
    "*This notebook contains an excerpt from the [Python Data Science Handbook](http://shop.oreilly.com/product/0636920034919.do) by Jake VanderPlas; the content is available [on GitHub](https://github.com/jakevdp/PythonDataScienceHandbook).*\n",
    "\n",
    "*The text is released under the [CC-BY-NC-ND license](https://creativecommons.org/licenses/by-nc-nd/3.0/us/legalcode), and code is released under the [MIT license](https://opensource.org/licenses/MIT). If you find this content useful, please consider supporting the work by [buying the book](http://shop.oreilly.com/product/0636920034919.do)!*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [IPython: Beyond Normal Python](01.00-IPython-Beyond-Normal-Python.ipynb) | [Contents](Index.ipynb) | [Keyboard Shortcuts in the IPython Shell](01.02-Shell-Keyboard-Shortcuts.ipynb) >"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Help and Documentation in IPython"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you read no other section in this chapter, read this one: I find the tools discussed here to be the most transformative contributions of IPython to my daily workflow.\n",
    "\n",
    "When a technologically-minded person is asked to help a friend, family member, or colleague with a computer problem, most of the time it's less a matter of knowing the answer as much as knowing how to quickly find an unknown answer.\n",
    "In data science it's the same: searchable web resources such as online documentation, mailing-list threads, and StackOverflow answers contain a wealth of information, even (especially?) if it is a topic you've found yourself searching before.\n",
    "Being an effective practitioner of data science is less about memorizing the tool or command you should use for every possible situation, and more about learning to effectively find the information you don't know, whether through a web search engine or another means.\n",
    "\n",
    "One of the most useful functions of IPython/Jupyter is to shorten the gap between the user and the type of documentation and search that will help them do their work effectively.\n",
    "While web searches still play a role in answering complicated questions, an amazing amount of information can be found through IPython alone.\n",
    "Some examples of the questions IPython can help answer in a few keystrokes:\n",
    "\n",
    "- How do I call this function? What arguments and options does it have?\n",
    "- What does the source code of this Python object look like?\n",
    "- What is in this package I imported? What attributes or methods does this object have?\n",
    "\n",
    "Here we'll discuss IPython's tools to quickly access this information, namely the ``?`` character to explore documentation, the ``??`` characters to explore source code, and the Tab key for auto-completion."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing Documentation with ``?``\n",
    "\n",
    "The Python language and its data science ecosystem is built with the user in mind, and one big part of that is access to documentation.\n",
    "Every Python object contains the reference to a string, known as a *doc string*, which in most cases will contain a concise summary of the object and how to use it.\n",
    "Python has a built-in ``help()`` function that can access this information and prints the results.\n",
    "For example, to see the documentation of the built-in ``len`` function, you can do the following:\n",
    "\n",
    "```ipython\n",
    "In [1]: help(len)\n",
    "Help on built-in function len in module builtins:\n",
    "\n",
    "len(...)\n",
    "    len(object) -> integer\n",
    "    \n",
    "    Return the number of items of a sequence or mapping.\n",
    "```\n",
    "\n",
    "Depending on your interpreter, this information may be displayed as inline text, or in some separate pop-up window."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because finding help on an object is so common and useful, IPython introduces the ``?`` character as a shorthand for accessing this documentation and other relevant information:\n",
    "\n",
    "```ipython\n",
    "In [2]: len?\n",
    "Type:        builtin_function_or_method\n",
    "String form: <built-in function len>\n",
    "Namespace:   Python builtin\n",
    "Docstring:\n",
    "len(object) -> integer\n",
    "\n",
    "Return the number of items of a sequence or mapping.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notation works for just about anything, including object methods:\n",
    "\n",
    "```ipython\n",
    "In [3]: L = [1, 2, 3]\n",
    "In [4]: L.insert?\n",
    "Type:        builtin_function_or_method\n",
    "String form: <built-in method insert of list object at 0x1024b8ea8>\n",
    "Docstring:   L.insert(index, object) -- insert object before index\n",
    "```\n",
    "\n",
    "or even objects themselves, with the documentation from their type:\n",
    "\n",
    "```ipython\n",
    "In [5]: L?\n",
    "Type:        list\n",
    "String form: [1, 2, 3]\n",
    "Length:      3\n",
    "Docstring:\n",
    "list() -> new empty list\n",
    "list(iterable) -> new list initialized from iterable's items\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Importantly, this will even work for functions or other objects you create yourself!\n",
    "Here we'll define a small function with a docstring:\n",
    "\n",
    "```ipython\n",
    "In [6]: def square(a):\n",
    "  ....:     \"\"\"Return the square of a.\"\"\"\n",
    "  ....:     return a ** 2\n",
    "  ....:\n",
    "```\n",
    "\n",
    "Note that to create a docstring for our function, we simply placed a string literal in the first line.\n",
    "Because doc strings are usually multiple lines, by convention we used Python's triple-quote notation for multi-line strings."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we'll use the ``?`` mark to find this doc string:\n",
    "\n",
    "```ipython\n",
    "In [7]: square?\n",
    "Type:        function\n",
    "String form: <function square at 0x103713cb0>\n",
    "Definition:  square(a)\n",
    "Docstring:   Return the square of a.\n",
    "```\n",
    "\n",
    "This quick access to documentation via docstrings is one reason you should get in the habit of always adding such inline documentation to the code you write!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing Source Code with ``??``\n",
    "Because the Python language is so easily readable, another level of insight can usually be gained by reading the source code of the object you're curious about.\n",
    "IPython provides a shortcut to the source code with the double question mark (``??``):\n",
    "\n",
    "```ipython\n",
    "In [8]: square??\n",
    "Type:        function\n",
    "String form: <function square at 0x103713cb0>\n",
    "Definition:  square(a)\n",
    "Source:\n",
    "def square(a):\n",
    "    \"Return the square of a\"\n",
    "    return a ** 2\n",
    "```\n",
    "\n",
    "For simple functions like this, the double question-mark can give quick insight into the under-the-hood details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you play with this much, you'll notice that sometimes the ``??`` suffix doesn't display any source code: this is generally because the object in question is not implemented in Python, but in C or some other compiled extension language.\n",
    "If this is the case, the ``??`` suffix gives the same output as the ``?`` suffix.\n",
    "You'll find this particularly with many of Python's built-in objects and types, for example ``len`` from above:\n",
    "\n",
    "```ipython\n",
    "In [9]: len??\n",
    "Type:        builtin_function_or_method\n",
    "String form: <built-in function len>\n",
    "Namespace:   Python builtin\n",
    "Docstring:\n",
    "len(object) -> integer\n",
    "\n",
    "Return the number of items of a sequence or mapping.\n",
    "```\n",
    "\n",
    "Using ``?`` and/or ``??`` gives a powerful and quick interface for finding information about what any Python function or module does."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exploring Modules with Tab-Completion\n",
    "\n",
    "IPython's other useful interface is the use of the tab key for auto-completion and exploration of the contents of objects, modules, and name-spaces.\n",
    "In the examples that follow, we'll use ``<TAB>`` to indicate when the Tab key should be pressed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tab-completion of object contents\n",
    "\n",
    "Every Python object has various attributes and methods associated with it.\n",
    "Like with the ``help`` function discussed before, Python has a built-in ``dir`` function that returns a list of these, but the tab-completion interface is much easier to use in practice.\n",
    "To see a list of all available attributes of an object, you can type the name of the object followed by a period (\"``.``\") character and the Tab key:\n",
    "\n",
    "```ipython\n",
    "In [10]: L.<TAB>\n",
    "L.append   L.copy     L.extend   L.insert   L.remove   L.sort     \n",
    "L.clear    L.count    L.index    L.pop      L.reverse  \n",
    "```\n",
    "\n",
    "To narrow-down the list, you can type the first character or several characters of the name, and the Tab key will find the matching attributes and methods:\n",
    "\n",
    "```ipython\n",
    "In [10]: L.c<TAB>\n",
    "L.clear  L.copy   L.count  \n",
    "\n",
    "In [10]: L.co<TAB>\n",
    "L.copy   L.count \n",
    "```\n",
    "\n",
    "If there is only a single option, pressing the Tab key will complete the line for you.\n",
    "For example, the following will instantly be replaced with ``L.count``:\n",
    "\n",
    "```ipython\n",
    "In [10]: L.cou<TAB>\n",
    "\n",
    "```\n",
    "\n",
    "Though Python has no strictly-enforced distinction between public/external attributes and private/internal attributes, by convention a preceding underscore is used to denote such methods.\n",
    "For clarity, these private methods and special methods are omitted from the list by default, but it's possible to list them by explicitly typing the underscore:\n",
    "\n",
    "```ipython\n",
    "In [10]: L._<TAB>\n",
    "L.__add__           L.__gt__            L.__reduce__\n",
    "L.__class__         L.__hash__          L.__reduce_ex__\n",
    "```\n",
    "\n",
    "For brevity, we've only shown the first couple lines of the output.\n",
    "Most of these are Python's special double-underscore methods (often nicknamed \"dunder\" methods)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tab completion when importing\n",
    "\n",
    "Tab completion is also useful when importing objects from packages.\n",
    "Here we'll use it to find all possible imports in the ``itertools`` package that start with ``co``:\n",
    "```\n",
    "In [10]: from itertools import co<TAB>\n",
    "combinations                   compress\n",
    "combinations_with_replacement  count\n",
    "```\n",
    "Similarly, you can use tab-completion to see which imports are available on your system (this will change depending on which third-party scripts and modules are visible to your Python session):\n",
    "```\n",
    "In [10]: import <TAB>\n",
    "Display all 399 possibilities? (y or n)\n",
    "Crypto              dis                 py_compile\n",
    "Cython              distutils           pyclbr\n",
    "...                 ...                 ...\n",
    "difflib             pwd                 zmq\n",
    "\n",
    "In [10]: import h<TAB>\n",
    "hashlib             hmac                http         \n",
    "heapq               html                husl         \n",
    "```\n",
    "(Note that for brevity, I did not print here all 399 importable packages and modules on my system.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Beyond tab completion: wildcard matching\n",
    "\n",
    "Tab completion is useful if you know the first few characters of the object or attribute you're looking for, but is little help if you'd like to match characters at the middle or end of the word.\n",
    "For this use-case, IPython provides a means of wildcard matching for names using the ``*`` character.\n",
    "\n",
    "For example, we can use this to list every object in the namespace that ends with ``Warning``:\n",
    "\n",
    "```ipython\n",
    "In [10]: *Warning?\n",
    "BytesWarning                  RuntimeWarning\n",
    "DeprecationWarning            SyntaxWarning\n",
    "FutureWarning                 UnicodeWarning\n",
    "ImportWarning                 UserWarning\n",
    "PendingDeprecationWarning     Warning\n",
    "ResourceWarning\n",
    "```\n",
    "\n",
    "Notice that the ``*`` character matches any string, including the empty string.\n",
    "\n",
    "Similarly, suppose we are looking for a string method that contains the word ``find`` somewhere in its name.\n",
    "We can search for it this way:\n",
    "\n",
    "```ipython\n",
    "In [10]: str.*find*?\n",
    "str.find\n",
    "str.rfind\n",
    "```\n",
    "\n",
    "I find this type of flexible wildcard search can be very useful for finding a particular command when getting to know a new package or reacquainting myself with a familiar one."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [IPython: Beyond Normal Python](01.00-IPython-Beyond-Normal-Python.ipynb) | [Contents](Index.ipynb) | [Keyboard Shortcuts in the IPython Shell](01.02-Shell-Keyboard-Shortcuts.ipynb) >"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}