{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> This is one of the 100 recipes of the [IPython Cookbook](http://ipython-books.github.io/), the definitive guide to high-performance scientific computing and data science in Python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1.5. Mastering IPython's configuration system"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%writefile random_magics.py\n",
    "# NOTE: We create the `random_magics.py` file here so that \n",
    "# you don't have to do it...\n",
    "from traitlets import Int, Float, Unicode, Bool\n",
    "#from IPython.utils.traitlets import Int, Float, Unicode, Bool # IPython < 4.x\n",
    "from IPython.core.magic import (Magics, magics_class, line_magic)\n",
    "import numpy as np\n",
    "\n",
    "@magics_class\n",
    "class RandomMagics(Magics):\n",
    "    text = Unicode(u'{n}', config=True)\n",
    "    max = Int(1000, config=True)\n",
    "    seed = Int(0, config=True)\n",
    "    \n",
    "    def __init__(self, shell):\n",
    "        super(RandomMagics, self).__init__(shell)\n",
    "        self._rng = np.random.RandomState(self.seed or None)\n",
    "        \n",
    "    @line_magic\n",
    "    def random(self, line):\n",
    "        return self.text.format(n=self._rng.randint(self.max))\n",
    "    \n",
    "def load_ipython_extension(ipython):\n",
    "    ipython.register_magics(RandomMagics)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. We create an IPython extension in a file `random_magics.py`. Let's start by importing a few objects:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "from traitlets import Int, Float, Unicode, Bool\n",
    "#from IPython.utils.traitlets import Int, Float, Unicode, Bool # IPython < 4.x\n",
    "from IPython.core.magic import (Magics, magics_class, line_magic)\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2. We create a `RandomMagics` class deriving from `Magics`. This class contains a few configurable parameters."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "@magics_class\n",
    "class RandomMagics(Magics):\n",
    "    text = Unicode(u'{n}', config=True)\n",
    "    max = Int(1000, config=True)\n",
    "    seed = Int(0, config=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. We need to call the parent's constructor. Then, we initialize a random number generator with a seed."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "    def __init__(self, shell):\n",
    "        super(RandomMagics, self).__init__(shell)\n",
    "        self._rng = np.random.RandomState(self.seed or None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "4. Then, we create a line magic `%random` that displays a random number."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "    @line_magic\n",
    "    def random(self, line):\n",
    "        return self.text.format(n=self._rng.randint(self.max))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "5. Finally, we register that magics when the extension is loaded."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "def load_ipython_extension(ipython):\n",
    "    ipython.register_magics(RandomMagics)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "6. Let's test our extension!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%load_ext random_magics"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%random"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%random"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "7. Our magics command has a few configurable parameters. These variables are meant to be configured by the user in the IPython configuration file, or in the console when starting IPython. To configure these variables in the terminal, we can type in a system shell the following command:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "ipython --profile=cookbook --RandomMagics.text='Your number is {n}.' --RandomMagics.max=10 --RandomMagics.seed=1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In that session, we get the following behavior:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "In [1]: %load_ext random_magics\n",
    "\n",
    "In [2]: %random\n",
    "Out[2]: u'Your number is 5.'\n",
    "\n",
    "In [3]: %random\n",
    "Out[3]: u'Your number is 8.'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "8. To configure the variables in the IPython configuration file, we have to open the file `~/.ipython/profile_cookbook/ipython_config.py` and add the following line:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "c.RandomMagics.text = 'random {n}'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After launching IPython, we get the following behavior:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%random"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> You'll find all the explanations, figures, references, and much more in the book (to be released later this summer).\n",
    "\n",
    "> [IPython Cookbook](http://ipython-books.github.io/), by [Cyrille Rossant](http://cyrille.rossant.net), Packt Publishing, 2014 (500 pages)."
   ]
  }
 ],
 "metadata": {
  "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}