nbinclude.ipynb

{
 "metadata": {
  "name": "",
  "signature": "sha256:1f56b511216a5e82aad2795b758ba37019f548dfe27f8d6e6f0083209e5206fe"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# See below the first header for documentation\n",
      "# The code until then is bootstrap. It relies on an excessive number of hacks\n",
      "\n",
      "# Do not allow the remainder of this file to be imported using the \"import\" statement\n",
      "# The bootstrap process is designed for nbinclude instead of the import statement\n",
      "#NBIMPORT_STOP\n",
      "\n",
      "# This first cell is the only one run using the three-line nbinclude shim\n",
      "try:\n",
      "    nbinclude\n",
      "except NameError:\n",
      "    # Define nbinclude, if it is not already defined\n",
      "    # Uses the variable \"nbinclude_f\" to get the path to \"nbinclude.ipynb\", so it can\n",
      "    # be added to the module search path\n",
      "    def nbinclude(nbfile, root=nbinclude_f.name):\n",
      "        global __name__\n",
      "\n",
      "        import io\n",
      "        import IPython.nbformat.current\n",
      "        import os\n",
      "\n",
      "        # Find the notebook file\n",
      "        if not nbfile.endswith(\".ipynb\"):\n",
      "                nbfile = nbfile + \".ipynb\"\n",
      "\n",
      "        # Hacky notebook-finder. TODO: replace with the less hacky version below\n",
      "        if not os.path.isfile(nbfile):\n",
      "            candidate = os.path.join(os.getcwd(), nbfile)\n",
      "            if os.path.isfile(candidate):\n",
      "                nbfile = candidate\n",
      "            else:\n",
      "                candidate = os.path.join(get_ipython().config.NotebookManager.notebook_dir, nbfile)\n",
      "                if os.path.isfile(candidate):\n",
      "                    nbfile=candidate\n",
      "                else:\n",
      "                    candidate = os.path.join(os.path.dirname(root), nbfile)\n",
      "                    if os.path.isfile(candidate):\n",
      "                        nbfile = candidate\n",
      "\n",
      "        if not os.path.isfile(nbfile):\n",
      "            raise IOError, 'Notebook \"{}\" not found'.format(nbfile)\n",
      "\n",
      "        # Read it\n",
      "        with io.open(nbfile) as f:\n",
      "            nb = IPython.nbformat.current.read(f, 'json')\n",
      "\n",
      "        # Execute the cells in it\n",
      "        ip = get_ipython()\n",
      "        old_name = __name__\n",
      "        __name__ = os.path.basename(nbfile).split(\".ipynb\")[0].replace(\" \", \"\")\n",
      "        for cell in nb.worksheets[0].cells:\n",
      "            if cell.cell_type != 'code':\n",
      "                continue\n",
      "            inp = cell.input\n",
      "            stop = False\n",
      "            if \"#\" + \"NBINCLUDE_STOP\" in inp:\n",
      "                inp = inp.split(\"#\" + \"NBINCLUDE_STOP\")[0]\n",
      "                stop = True\n",
      "            ip.run_cell(inp)\n",
      "            if stop:\n",
      "                break\n",
      "        __name__ = old_name\n",
      "        \n",
      "    # Now that nbinclude is available, we can run the remainder of this notebook until NBINCLUDE_STOP\n",
      "    nbinclude(\"nbinclude\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This code sets up the python `import` statement for use with notebooks\n",
      "\n",
      "It has been borrowed from: http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/Notebook/Importing%20Notebooks.ipynb"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Now that everything has been set up, don't let nbinclude read any farther into the documentation part of the file"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#NBINCLUDE_STOP"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Documentation"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Setup"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This system allows importing and including IPython notebooks from other IPython notebooks.\n",
      "\n",
      "Quite naturally, it is a notebook itself.\n",
      "\n",
      "Other notebooks need access to `nbinclude` in order to use it. Since it's a notebook in itself, the following shim is required to import it:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Cross-notebook include shim\n",
      "with open(\"/home/nikita/dev/ipython-notebooks/nbtools/nbinclude.ipynb\") as nbinclude_f: # don't rename nbinclude_f\n",
      "    import IPython.nbformat.current\n",
      "    get_ipython().run_cell(IPython.nbformat.current.read(nbinclude_f, 'json').worksheets[0].cells[0].input)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "**Adding this shim to your notebook file will enable the behavior below**"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Cross-notebook python-style imports"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Notebooks can now be imported as if they were Python modules, for example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import nbinclude as nbi"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "importing IPython notebook from /home/nikita/dev/ipython-notebooks/nbtools/nbinclude.ipynb\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Importing normally reads all code cells in the notebook file.\n",
      "\n",
      "One way to protect against this is the standard guard:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "if __name__ == \"__main__\":\n",
      "    print \"This code will not run if the notebook is imported via the import statement"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The other is to use the `#NBIMPORT_STOP` macro (exact spelling - no space after the `#`).\n",
      "Everything in the notebook that is after this macro will not be run when the notebook is imported using the import statement"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Cross-notebook c-style includes"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "C-style includes for notebooks are also supported:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Searches for notebooks relative to the following locations:\n",
      "# 1. As absolute path\n",
      "# 2. Relative to the current working directory\n",
      "# 3. Relative to the default notebook folder\n",
      "# 4. Relative to the folder that contains nbinclude.ipynb\n",
      "nbinclude(\"nbinclude.ipynb\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Omitting the \".ipynb\" works, too\n",
      "nbinclude(\"nbinclude\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# So do absolute paths\n",
      "nbinclude(\"/home/nikita/dev/ipython-notebooks/nbtools/nbinclude.ipynb\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# And absolute paths that omit the \".ipynb\"\n",
      "nbinclude(\"/home/nikita/dev/ipython-notebooks/nbtools/nbinclude\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The classic guard works here, too:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "if __name__ == \"__main__\":\n",
      "    print \"This code will not run if the notebook is imported via nbinclude\""
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "There is also a magic macro, `#NBINCLUDE_STOP` (exact spelling). The remainder of the cell containing the macro, and any cells after it, will not be read by the nbinclude system.\n",
      "\n",
      "This is useful for separating cells at the beginning of the notebook (which contain function definitions you want to include), from cells at the end of the notebook (that you don't want to include)\n",
      "\n",
      "`#NBINCLUDE_STOP` and `NBIMPORT_STOP` are distinct macros on purpose."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}