An example of what autoreload does in its different modes.

Understanding-Autoreload.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to use `autoreload`\n",
    "\n",
    "I have been confused on how to use [`autoreload`](http://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html) IPython extension for a long time. The documentation simply wasn't clear to me. Or, rather, it seemed clear, but then I was surprised by the behavior.\n",
    "\n",
    "\n",
    "After submitting a bug request w/ [Daniel Margala](https://github.com/dmargala) (we were confused together), we got a [response](https://github.com/ipython/ipython/issues/10395#issuecomment-286467407) that helped to clear things up. \n",
    "\n",
    "I've updated this with my new understanding. Hopefully this helps anyone else who is confused."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "import os\n",
    "import sys\n",
    "import time\n",
    "sys.path.append(\"..\")\n",
    "%reload_ext autoreload"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Create a simple packe with a few simple modules that we will update. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "directory = \"../examplepackage/\"\n",
    "if not os.path.exists(directory):\n",
    "    os.makedirs(directory)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato.py\n",
    "\n",
    "def torpedo():\n",
    "    print('First module modification 0!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato2.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato2.py\n",
    "\n",
    "def torpedo2():\n",
    "    print('Second module modification 0!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato3.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato3.py\n",
    "\n",
    "def torpedo3():\n",
    "    print('Third module modification 0!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "# when hitting 'run all' this needs a short delay (probable race condition).\n",
    "time.sleep(1.5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "# `%autoreload 1`\n",
    "\n",
    "The docs say:\n",
    "\n",
    "```\n",
    "%autoreload 1\n",
    "\n",
    "Reload all modules imported with %aimport every time before executing the Python code typed.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import examplepackage.neato\n",
    "import examplepackage.neato2\n",
    "import examplepackage.neato3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "%autoreload 1\n",
    "%aimport examplepackage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You might think that importing `examplepackage` would result in that package being auto-reloaded if you updated code inside of it. You'd be wrong. Follow along!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato.torpedo()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato2.torpedo2()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Third module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato3.torpedo3()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato.py\n",
    "\n",
    "def torpedo():\n",
    "    print('First module modification 1')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato2.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato2.py\n",
    "\n",
    "def torpedo2():\n",
    "    print('Second module modification 1')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato3.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato3.py\n",
    "\n",
    "def torpedo3():\n",
    "    print('Third module modification 1!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "# when hitting 'run all' this needs a short delay (probable race condition).\n",
    "time.sleep(1.5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato.torpedo()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true,
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato2.torpedo2()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true,
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Third module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato3.torpedo3()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nothing is updated. You have to import the module explicitly like: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "%autoreload 1\n",
    "%aimport examplepackage.neato"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First module modification 1\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato.torpedo()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true,
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato2.torpedo2()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true,
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Third module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato3.torpedo3()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#  `%autoreload 2`\n",
    "\n",
    "The docs say: \n",
    "\n",
    "```\n",
    "%autoreload 2\n",
    "\n",
    "Reload all modules (except those excluded by %aimport) every time before executing the Python code typed.\n",
    "```\n",
    "\n",
    "I read this as \"if you set `%autoreload 2`, then it will reload all modules except whatever you `%aimport examplepackage.module`\". This is not how it works. When using `%aimport` you also have to flag it with a `-`. See below. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%autoreload 2\n",
    "%aimport examplepackage.neato\n",
    "%aimport -examplepackage.neato2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First module modification 1\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato.torpedo()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato2.torpedo2()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Third module modification 1!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato3.torpedo3()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato.py\n",
    "\n",
    "def torpedo():\n",
    "    print('First module modification 2!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato2.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato2.py\n",
    "\n",
    "def torpedo2():\n",
    "    print('Second module modification 2!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ../examplepackage/neato3.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile ../examplepackage/neato3.py\n",
    "\n",
    "def torpedo3():\n",
    "    print('Third module modification 2!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# when hitting 'run all' this needs a short delay (race condition).\n",
    "time.sleep(1.5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First module modification 2!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato.torpedo()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second module modification 0!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato2.torpedo2()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Third module modification 2!\n"
     ]
    }
   ],
   "source": [
    "examplepackage.neato3.torpedo3()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:py3]",
   "language": "python",
   "name": "conda-env-py3-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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}