notebooks/01.03-Magic-Commands.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",
    "< [Keyboard Shortcuts in the IPython Shell](01.02-Shell-Keyboard-Shortcuts.ipynb) | [Contents](Index.ipynb) | [Input and Output History](01.04-Input-Output-History.ipynb) >"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# IPython Magic Commands\n",
    "\n",
    "The previous two sections showed how IPython lets you use and explore Python efficiently and interactively.\n",
    "Here we'll begin discussing some of the enhancements that IPython adds on top of the normal Python syntax.\n",
    "These are known in IPython as *magic commands*, and are prefixed by the ``%`` character.\n",
    "These magic commands are designed to succinctly solve various common problems in standard data analysis.\n",
    "Magic commands come in two flavors: *line magics*, which are denoted by a single ``%`` prefix and operate on a single line of input, and *cell magics*, which are denoted by a double ``%%`` prefix and operate on multiple lines of input.\n",
    "We'll demonstrate and discuss a few brief examples here, and come back to more focused discussion of several useful magic commands later in the chapter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pasting Code Blocks: ``%paste`` and ``%cpaste``\n",
    "\n",
    "When working in the IPython interpreter, one common gotcha is that pasting multi-line code blocks can lead to unexpected errors, especially when indentation and interpreter markers are involved.\n",
    "A common case is that you find some example code on a website and want to paste it into your interpreter.\n",
    "Consider the following simple function:\n",
    "\n",
    "``` python\n",
    ">>> def donothing(x):\n",
    "...     return x\n",
    "\n",
    "```\n",
    "The code is formatted as it would appear in the Python interpreter, and if you copy and paste this directly into IPython you get an error:\n",
    "\n",
    "```ipython\n",
    "In [2]: >>> def donothing(x):\n",
    "   ...:     ...     return x\n",
    "   ...:     \n",
    "  File \"<ipython-input-20-5a66c8964687>\", line 2\n",
    "    ...     return x\n",
    "                 ^\n",
    "SyntaxError: invalid syntax\n",
    "```\n",
    "\n",
    "In the direct paste, the interpreter is confused by the additional prompt characters.\n",
    "But never fear–IPython's ``%paste`` magic function is designed to handle this exact type of multi-line, marked-up input:\n",
    "\n",
    "```ipython\n",
    "In [3]: %paste\n",
    ">>> def donothing(x):\n",
    "...     return x\n",
    "\n",
    "## -- End pasted text --\n",
    "```\n",
    "\n",
    "The ``%paste`` command both enters and executes the code, so now the function is ready to be used:\n",
    "\n",
    "```ipython\n",
    "In [4]: donothing(10)\n",
    "Out[4]: 10\n",
    "```\n",
    "\n",
    "A command with a similar intent is ``%cpaste``, which opens up an interactive multiline prompt in which you can paste one or more chunks of code to be executed in a batch:\n",
    "\n",
    "```ipython\n",
    "In [5]: %cpaste\n",
    "Pasting code; enter '--' alone on the line to stop or use Ctrl-D.\n",
    ":>>> def donothing(x):\n",
    ":...     return x\n",
    ":--\n",
    "```\n",
    "\n",
    "These magic commands, like others we'll see, make available functionality that would be difficult or impossible in a standard Python interpreter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running External Code: ``%run``\n",
    "As you begin developing more extensive code, you will likely find yourself working in both IPython for interactive exploration, as well as a text editor to store code that you want to reuse.\n",
    "Rather than running this code in a new window, it can be convenient to run it within your IPython session.\n",
    "This can be done with the ``%run`` magic.\n",
    "\n",
    "For example, imagine you've created a ``myscript.py`` file with the following contents:\n",
    "\n",
    "```python\n",
    "#-------------------------------------\n",
    "# file: myscript.py\n",
    "\n",
    "def square(x):\n",
    "    \"\"\"square a number\"\"\"\n",
    "    return x ** 2\n",
    "\n",
    "for N in range(1, 4):\n",
    "    print(N, \"squared is\", square(N))\n",
    "```\n",
    "\n",
    "You can execute this from your IPython session as follows:\n",
    "\n",
    "```ipython\n",
    "In [6]: %run myscript.py\n",
    "1 squared is 1\n",
    "2 squared is 4\n",
    "3 squared is 9\n",
    "```\n",
    "\n",
    "Note also that after you've run this script, any functions defined within it are available for use in your IPython session:\n",
    "\n",
    "```ipython\n",
    "In [7]: square(5)\n",
    "Out[7]: 25\n",
    "```\n",
    "\n",
    "There are several options to fine-tune how your code is run; you can see the documentation in the normal way, by typing **``%run?``** in the IPython interpreter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Timing Code Execution: ``%timeit``\n",
    "Another example of a useful magic function is ``%timeit``, which will automatically determine the execution time of the single-line Python statement that follows it.\n",
    "For example, we may want to check the performance of a list comprehension:\n",
    "\n",
    "```ipython\n",
    "In [8]: %timeit L = [n ** 2 for n in range(1000)]\n",
    "1000 loops, best of 3: 325 µs per loop\n",
    "```\n",
    "\n",
    "The benefit of ``%timeit`` is that for short commands it will automatically perform multiple runs in order to attain more robust results.\n",
    "For multi line statements, adding a second ``%`` sign will turn this into a cell magic that can handle multiple lines of input.\n",
    "For example, here's the equivalent construction with a ``for``-loop:\n",
    "\n",
    "```ipython\n",
    "In [9]: %%timeit\n",
    "   ...: L = []\n",
    "   ...: for n in range(1000):\n",
    "   ...:     L.append(n ** 2)\n",
    "   ...: \n",
    "1000 loops, best of 3: 373 µs per loop\n",
    "```\n",
    "\n",
    "We can immediately see that list comprehensions are about 10% faster than the equivalent ``for``-loop construction in this case.\n",
    "We'll explore ``%timeit`` and other approaches to timing and profiling code in [Profiling and Timing Code](01.07-Timing-and-Profiling.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Help on Magic Functions: ``?``, ``%magic``, and ``%lsmagic``\n",
    "\n",
    "Like normal Python functions, IPython magic functions have docstrings, and this useful\n",
    "documentation can be accessed in the standard manner.\n",
    "So, for example, to read the documentation of the ``%timeit`` magic simply type this:\n",
    "\n",
    "```ipython\n",
    "In [10]: %timeit?\n",
    "```\n",
    "\n",
    "Documentation for other functions can be accessed similarly.\n",
    "To access a general description of available magic functions, including some examples, you can type this:\n",
    "\n",
    "```ipython\n",
    "In [11]: %magic\n",
    "```\n",
    "\n",
    "For a quick and simple list of all available magic functions, type this:\n",
    "\n",
    "```ipython\n",
    "In [12]: %lsmagic\n",
    "```\n",
    "\n",
    "Finally, I'll mention that it is quite straightforward to define your own magic functions if you wish.\n",
    "We won't discuss it here, but if you are interested, see the references listed in [More IPython Resources](01.08-More-IPython-Resources.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Keyboard Shortcuts in the IPython Shell](01.02-Shell-Keyboard-Shortcuts.ipynb) | [Contents](Index.ipynb) | [Input and Output History](01.04-Input-Output-History.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
}