notebooks/runipy.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       "\n",
       ".rendered_html {\n",
       "    font-family: \"proxima-nova\", helvetica;\n",
       "    font-size: 130%;\n",
       "    line-height: 1.5;\n",
       "}\n",
       "\n",
       ".rendered_html h1 {\n",
       "    margin: 0.25em 0em 0.5em;\n",
       "    color: #015C9C;\n",
       "    text-align: center;\n",
       "    line-height: 1.2; \n",
       "    page-break-before: always;\n",
       "}\n",
       "\n",
       ".rendered_html h2 {\n",
       "    margin: 1.1em 0em 0.5em;\n",
       "    color: #26465D;\n",
       "    line-height: 1.2;\n",
       "}\n",
       "\n",
       ".rendered_html h3 {\n",
       "    margin: 1.1em 0em 0.5em;\n",
       "    color: #002845;\n",
       "    line-height: 1.2;\n",
       "}\n",
       "\n",
       ".rendered_html li {\n",
       "    line-height: 1.5; \n",
       "}\n",
       "\n",
       "/*.prompt {\n",
       "    font-size: 120%; \n",
       "}*/\n",
       "\n",
       ".CodeMirror-lines {\n",
       "    font-size: 110%; \n",
       "}\n",
       "\n",
       "/*.output_area {\n",
       "    font-size: 120%; \n",
       "}*/\n",
       "\n",
       "/*#notebook {\n",
       "    background-image: url('files/images/witewall_3.png');\n",
       "}*/\n",
       "\n",
       "h1.bigtitle {\n",
       "    margin: 4cm 1cm 4cm 1cm;\n",
       "    font-size: 300%;\n",
       "}\n",
       "\n",
       "h3.point {\n",
       "    font-size: 200%;\n",
       "    text-align: center;\n",
       "    margin: 2em 0em 2em 0em;\n",
       "    #26465D\n",
       "}\n",
       "\n",
       ".logo {\n",
       "    margin: 20px 0 20px 0;\n",
       "}\n",
       "\n",
       "a.anchor-link {\n",
       "    display: none;\n",
       "}\n",
       "\n",
       "h1.title { \n",
       "    font-size: 250%;\n",
       "}\n",
       "\n",
       "</style>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%load_ext load_style\n",
    "%load_style talk.css"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# [runipy](https://github.com/paulgb/runipy)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr size=5>\n",
    "<font color='red' size='5'>ATTENTION</font>: If you have an old installation of **Runipy**, it is very unlikely to work with the new (format v4) IPython notebook (latest version 3.0 of IPython). \n",
    "\n",
    "I recommend that you install the latest development version of **runipy** from the [github repository](https://github.com/paulgb/runipy) with the following: \n",
    "\n",
    "```\n",
    "pip install https://github.com/paulgb/runipy/archive/master.zip\n",
    "```\n",
    "\n",
    "Another solution (for IPython version 3) is to use **nbconvert**, which now comes with an option to run a notebook in place and save the outputs in the same notebook, the (rather verbose) syntax is: \n",
    "\n",
    "\n",
    "```\n",
    "ᐅ ipython nbconvert notebook_to_execute.ipynb --ExecutePreprocessor.enabled=True --to notebook --output notebook_to_execute.ipynb\n",
    "```\n",
    "\n",
    "However it does not seem to handle passing environment variables as **runipy** does ... \n",
    "\n",
    "see [http://ipython.org/ipython-doc/dev/whatsnew/version3.html](http://ipython.org/ipython-doc/dev/whatsnew/version3.html) for the list of changes in the version 3.0 of IPython and the IPython notebook, see in particular the [backwards incompatible changes](http://ipython.org/ipython-doc/dev/whatsnew/version3.html#backwards-incompatible-changes) section.\n",
    "\n",
    "<hr size=5>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following comes from the doc of **Runipy** and goes through its major use cases"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The [IPython notebook](http://ipython.org/notebook.html) provides an interactive interface to a Python\n",
    "interpreter.\n",
    "\n",
    "*  **Literate programming**: the IPython notebook is an ideal format for\n",
    "   writing \"literate\" programs, in which the code is part of a larger\n",
    "   multi-media document. ``runipy`` lets you run such programs directly,\n",
    "   without first converting to a pure Python script.\n",
    "   \n",
    "*  **Report generation**: ``runipy`` can run the notebook and convert it\n",
    "   into HTML in one go, making it an easy way to automate reports.\n",
    "   \n",
    "*  **Data pipeline**: if you use IPython notebooks to create a data\n",
    "   pipeline, ``runipy`` lets you automate that pipeline without losing\n",
    "   the notebook formatting.\n",
    "\n",
    "### Requirements\n",
    "\n",
    "``runipy`` currently supports IPython versions 2.3.x and the current\n",
    "development version of 3.x.\n",
    "\n",
    "### Installation\n",
    "\n",
    "\n",
    "The easiest way to install ``runipy`` is with ``pip``:\n",
    "\n",
    "    $ pip install runipy\n",
    "\n",
    "### Command-line use\n",
    "\n",
    "\n",
    "To run a ``.ipynb`` file as a script, run:\n",
    "\n",
    "    $ runipy MyNotebook.ipynb\n",
    "\n",
    "To save the output of each cell back to the notebook file, run:\n",
    "\n",
    "    $ runipy -o MyNotebook.ipynb\n",
    "    \n",
    "**NOTE**: *The notebook seems to be automatically converted back to version 3 if it was in version 4.*\n",
    "\n",
    "To save the notebook output as a *new* notebook, run:\n",
    "\n",
    "    $ runipy MyNotebook.ipynb OutputNotebook.ipynb\n",
    "\n",
    "To run a ``.ipynb`` file and generate an ``HTML`` report, run:\n",
    "\n",
    "    $ runipy MyNotebook.ipynb --html report.html\n",
    "\n",
    "### Passing Arguments\n",
    "\n",
    "\n",
    "You can pass arguments to the notebook through environment variables.\n",
    "The use of environment variables is OS- and shell- dependent, but in a\n",
    "typical UNIX-like environment they can be passed on the command line\n",
    "before the program name:\n",
    "\n",
    "    $ myvar=value runipy MyNotebook.ipynb\n",
    "\n",
    "Then in the notebook, to access myvar:\n",
    "\n",
    "    from os import environ\n",
    "    myvar = environ['myvar']\n",
    "\n",
    "``environ`` is just a ``dict``, so you can use ``.get()`` to fall back\n",
    "on a default value:\n",
    "\n",
    "    from os import environ\n",
    "    myvar = environ.get('myvar', 'default!')\n",
    "\n",
    "### Stdin / Stdout\n",
    "\n",
    "``runipy`` can read stdin and stdout and sit in a UNIX pipeline:\n",
    "\n",
    "::\n",
    "\n",
    "    $ runipy --stdout < MyNotebook.ipynb > OutputNotebook.ipynb\n",
    "\n",
    "    $ cat MyNotebook.ipynb | runipy --stdout > OutputNotebook.ipynb\n",
    "\n",
    "### Programmatic use\n",
    "\n",
    "It is also possible to run IPython notebooks from Python, using:\n",
    "\n",
    "    from runipy.notebook_runner import NotebookRunner\n",
    "    from IPython.nbformat.current import read\n",
    "\n",
    "    notebook = read(open(\"MyNotebook.ipynb\"), 'json')\n",
    "    r = NotebookRunner(notebook)\n",
    "    r.run_notebook()\n",
    "\n",
    "and you can enable ``pylab`` with:\n",
    "\n",
    "    r = NotebookRunner(notebook, pylab=True)\n",
    "\n",
    "The notebook is stored in the object and can be saved using:\n",
    "\n",
    "    from IPython.nbformat.current import write\n",
    "    write(r.nb, open(\"MyOtherNotebook.ipynb\", 'w'), 'json')\n",
    "\n",
    "run\\_notebook() takes two optional arguments. The first,\n",
    "skip\\_exceptions, takes a boolean value (False by default). If True,\n",
    "exceptions will be ignored and the notebook will continue to execute\n",
    "cells after encountering an exception. The second argument is\n",
    "progress\\_callback, which must be either None or a function that takes\n",
    "one argument. This function is called after execution of each cell with\n",
    "the 0-based index of the cell just evaluated. This can be useful for\n",
    "tracking progress of long-running notebooks\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}