{
 "metadata": {
  "name": "Configuring IPython"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Configuring IPython"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Finding configuration options"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "IPython has many configuration attributes. These can be viewed using the `-h` flag to the command line applications:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!ipython -h"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This is an important trick for finding out configuration info:\n",
      "    \n",
      "    $> ipython [subcommand] --help-all | grep [-C context] PATTERN\n",
      "\n",
      "`--help-all` exposes everything configurable in IPython,\n",
      "there is a good chance you will find what you are looking for."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "A common configuration question is:\n",
      "\n",
      "> how do I disable the \"Do you really want to exit\" message when quitting with `Ctrl-d`?\n",
      "\n",
      "Well, logically this has to do with `exit`, so let's look for it:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!ipython --help-all | grep exit"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Which shows me that I can disable the confirmation for a single IPython session with\n",
      "\n",
      "    $> ipython --no-confirm-exit\n",
      "    \n",
      "or I can set the `TerminalInteractiveShell.confirm_exit=False` in a config file,\n",
      "to have it be the default behavior."
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Configuration principles"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Here are the design principles of the IPython configuration system: \n",
      "\n",
      "* Configuration is always done using class attributes\n",
      "* Classes that have configurable attributes are subclasses of `Configurable`\n",
      "* Attributes that are configurable are typed traitlets objects (`Bool`, `Unicode`, etc.) that have `config=True`\n",
      "* In config files, configurable attributes can be set using the format `Class.attr_name=the_value`\n",
      "* At the command line, configurable attributes can be set using the syntax `--Class.attr_name=the_value`\n",
      "* At the command line, some attributes have shorthands of the form `--attr-name=value`\n",
      "* Values set at the command line have higher priority than those set in config files"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "The IPython Profile"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "IPython has a notion of 'profiles' - these are directories that live in your IPYTHONDIR,\n",
      "which contain configuration and runtime information.\n",
      "\n",
      "Let's create the default profile"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!ipython profile create"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This creates a profile in your IPYTHONDIR (`ipython locate` is a quick way to see where your IPYTHONDIR is),\n",
      "and populates it with automatically generated default config files."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!ipython locate profile default"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You can skim"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "profile = get_ipython().profile_dir.location\n",
      "profile"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ls $profile"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Let's peek at our config file"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "pycat $profile/ipython_config.py"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "The %config magic"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The `%config` magic lets you do some configuration at runtime, rather than in configuration files."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%pylab inline"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "`%config` with no arguments will show you what configurable objects exist:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%config"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "And `%config Class` will show you the config for that class:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%config InlineBackend"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Most importantly, the `%config` magic can be used to change the value of a configurable attribute at runtime. Here we tell the inline matplotlib backend to use SVG instead of the default PNG"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = linspace(0,10,1000)\n",
      "y = sin(x)\n",
      "plot(x,sin(x))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%config InlineBackend.figure_format = 'svg'"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "plot(x,sin(x))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Defining your own magic"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "As we have seen already, IPython has cell and line magics. You can define your own magics using any Python function and the `register_magic_function` method:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ip = get_ipython()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def sleep_magic(line):\n",
      "    \"\"\"A simple function for sleeping\"\"\"\n",
      "    t = float(line)\n",
      "    import time\n",
      "    time.sleep(t)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ip.register_magic_function(sleep_magic, \"line\", \"sleep\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%sleep 2"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%sleep?"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ip.magics_manager.define_magic?"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Exercise"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Define `%tic` and `%toc` magics, which can be use for simple timings, e.g. where\n",
      "\n",
      "    for p in range(1,4):\n",
      "        N = 10**p\n",
      "        print \"N=%i\" % N\n",
      "        %tic\n",
      "        A = np.random.random((N,N))\n",
      "        np.linalg.eigvals(A)\n",
      "        %toc\n",
      "\n",
      "each `%toc` will print the time since the last `%tic`. Create separate `tic` and `toc` functions that read and write\n",
      "a global time variable."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%load soln/tictocf.py"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import time\n",
      "\n",
      "def format_time(dt):\n",
      "    if dt < 1e-6:\n",
      "        return u\"%.3g ns\" % (dt * 1e9)\n",
      "    elif dt < 1e-3:\n",
      "        return u\"%.3g \u00b5s\" % (dt * 1e6)\n",
      "    elif dt < 1:\n",
      "        return u\"%.3g ms\" % (dt * 1e3)\n",
      "    else:\n",
      "        return \"%.3g s\" % dt\n",
      "\n",
      "def tic(line):\n",
      "    global t0\n",
      "    t0 = time.time()\n",
      "\n",
      "def toc(line):\n",
      "    global t0\n",
      "    print format_time(time.time() - t0)\n",
      "\n",
      "ip = get_ipython()\n",
      "ip.register_magic_function(tic)\n",
      "ip.register_magic_function(toc)\n"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import numpy as np\n",
      "\n",
      "for p in range(1,4):\n",
      "    N = 10**p\n",
      "    print \"N=%i\" % N\n",
      "    %tic\n",
      "    A = np.random.random((N,N))\n",
      "    np.linalg.eigvals(A)\n",
      "    %toc"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Startup files"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Startup files are simple Python or IPython scripts\n",
      "that are run whenever you start IPython.\n",
      "These are a useful way to do super common imports,\n",
      "or for building database connections to load on startup of a non-default profile.\n",
      "\n",
      "We can use a startup file to ensure that our `%tic/toc` magics are always defined,\n",
      "every time we start IPython."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!ls $profile/startup"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Adding common imports, so we never have to forget them again"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%file simpleimports.py\n",
      "\n",
      "import sys, os, time, re"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!cp simpleimports.py $profile/startup/simpleimports.py"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "And the same can be done for our tic/toc magics"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!cp soln/tictocf.py $profile/startup/tictocf.py"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "**Restart the kernel** and then run the following cells immediately to verify these scripts have been executed:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "sys"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%tic\n",
      "time.sleep(0.5)\n",
      "%toc"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}