{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Configuring IPython" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Finding configuration options" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "IPython has many configurable attributes. These can be viewed using the `-h` flag to the command line applications:" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "=========\n", " IPython\n", "=========\n", "\n", "Tools for Interactive Computing in Python\n", "=========================================\n", "\n", " A Python shell with automatic history (input and output), dynamic object\n", " introspection, easier configuration, command completion, access to the\n", " system shell and more. IPython can also be embedded in running programs.\n", "\n", "Usage\n", "\n", " ipython [subcommand] [options] [-c cmd | -m mod | file] [--] [arg] ...\n", "\n", " If invoked with no options, it executes the file and exits, passing the\n", " remaining arguments to the script, just as if you had specified the same\n", " command with python. You may need to specify `--` before args to be passed\n", " to the script, to prevent IPython from attempting to parse them. If you\n", " specify the option `-i` before the filename, it will enter an interactive\n", " IPython session after running the script, rather than exiting. Files ending\n", " in .py will be treated as normal Python, but files ending in .ipy can\n", " contain special IPython syntax (magic commands, shell expansions, etc.).\n", "\n", " Almost all configuration in IPython is available via the command-line. Do\n", " `ipython --help-all` to see all available options. For persistent\n", " configuration, look into your `ipython_config.py` configuration file for\n", " details.\n", "\n", " This file is typically installed in the `IPYTHONDIR` directory, and there\n", " is a separate configuration directory for each profile. The default profile\n", " directory will be located in $IPYTHONDIR/profile_default. IPYTHONDIR\n", " defaults to to `$HOME/.ipython`. For Windows users, $HOME resolves to\n", " C:\\Documents and Settings\\YourUserName in most instances.\n", "\n", " To initialize a profile with the default configuration file, do::\n", "\n", " $> ipython profile create\n", "\n", " and start editing `IPYTHONDIR/profile_default/ipython_config.py`\n", "\n", " In IPython's documentation, we will refer to this directory as\n", " `IPYTHONDIR`, you can change its default location by creating an\n", " environment variable with this name and setting it to the desired path.\n", "\n", " For more information, see the manual available in HTML and PDF in your\n", " installation, or online at http://ipython.org/documentation.html.\n", "\n", "Subcommands\n", "-----------\n", "\n", "Subcommands are launched as `ipython cmd [args]`. For information on using\n", "subcommand 'cmd', do: `ipython cmd -h`.\n", "\n", "locate\n", " print the path to the IPython dir\n", "trust\n", " Sign notebooks to trust their potentially unsafe contents at load.\n", "install-nbextension\n", " Install IPython notebook extension files\n", "kernel\n", " Start a kernel without an attached frontend.\n", "kernelspec\n", " Manage IPython kernel specifications.\n", "console\n", " Launch the IPython terminal-based Console.\n", "nbconvert\n", " Convert notebooks to/from other formats.\n", "profile\n", " Create and manage IPython profiles.\n", "notebook\n", " Launch the IPython HTML Notebook Server.\n", "history\n", " Manage the IPython history database.\n", "qtconsole\n", " Launch the IPython Qt Console.\n", "\n", "Options\n", "-------\n", "\n", "Arguments that take values are actually convenience aliases to full\n", "Configurables, whose aliases are listed on the help line. For more information\n", "on full configurables, see '--help-all'.\n", "\n", "--nosep\n", " Eliminate all spacing between prompts.\n", "--quiet\n", " set log level to logging.CRITICAL (minimize logging output)\n", "--term-title\n", " Enable auto setting the terminal title.\n", "--pylab\n", " Pre-load matplotlib and numpy for interactive use with\n", " the default matplotlib backend.\n", "--init\n", " Initialize profile with default config files. This is equivalent\n", " to running `ipython profile create ` prior to startup.\n", "--pydb\n", " Use the third party 'pydb' package as debugger, instead of pdb.\n", " Requires that pydb is installed.\n", "--no-autoedit-syntax\n", " Turn off auto editing of files with syntax errors.\n", "--classic\n", " Gives IPython a similar feel to the classic Python prompt.\n", "--no-term-title\n", " Disable auto setting the terminal title.\n", "--no-banner\n", " Don't display a banner upon starting IPython.\n", "--no-automagic\n", " Turn off the auto calling of magic commands.\n", "--autoindent\n", " Turn on autoindenting.\n", "--no-deep-reload\n", " Disable deep (recursive) reloading by default.\n", "--matplotlib\n", " Configure matplotlib for interactive use with\n", " the default matplotlib backend.\n", "--debug\n", " set log level to logging.DEBUG (maximize logging output)\n", "--autoedit-syntax\n", " Turn on auto editing of files with syntax errors.\n", "--no-color-info\n", " Disable using colors for info related things.\n", "--no-pprint\n", " Disable auto pretty printing of results.\n", "--banner\n", " Display a banner upon starting IPython.\n", "--no-confirm-exit\n", " Don't prompt the user when exiting.\n", "--pdb\n", " Enable auto calling the pdb debugger after every exception.\n", "--color-info\n", " IPython can display information about objects via a set of functions,\n", " and optionally can use colors for this, syntax highlighting\n", " source code and various other elements. This is on by default, but can cause\n", " problems with some pagers. If you see such problems, you can disable the\n", " colours.\n", "--no-pdb\n", " Disable auto calling the pdb debugger after every exception.\n", "--quick\n", " Enable quick startup with no config files.\n", "--deep-reload\n", " Enable deep (recursive) reloading by default. IPython can use the\n", " deep_reload module which reloads changes in modules recursively (it\n", " replaces the reload() function, so you don't need to change anything to\n", " use it). deep_reload() forces a full reload of modules whose code may\n", " have changed, which the default reload() function does not. When\n", " deep_reload is off, IPython will use the normal reload(), but\n", " deep_reload will still be available as dreload(). This feature is off\n", " by default [which means that you have both normal reload() and\n", " dreload()].\n", "--no-autoindent\n", " Turn off autoindenting.\n", "--automagic\n", " Turn on the auto calling of magic commands. Type %%magic at the\n", " IPython prompt for more information.\n", "-i\n", " If running code from the command line, become interactive afterwards.\n", "--pprint\n", " Enable auto pretty printing of results.\n", "--confirm-exit\n", " Set to confirm when you try to exit IPython with an EOF (Control-D\n", " in Unix, Control-Z/Enter in Windows). By typing 'exit' or 'quit',\n", " you can force a direct exit without any confirmation.\n", "--config= (BaseIPythonApplication.extra_config_file)\n", " Default: ''\n", " Path to an extra config file to load.\n", " If specified, load this config file in addition to any other IPython config.\n", "--pylab= (InteractiveShellApp.pylab)\n", " Default: None\n", " Choices: ['auto', 'gtk', 'gtk3', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt4', 'qt5', 'tk', 'wx']\n", " Pre-load matplotlib and numpy for interactive use, selecting a particular\n", " matplotlib backend and loop integration.\n", "-c (InteractiveShellApp.code_to_run)\n", " Default: ''\n", " Execute the given command string.\n", "--log-level= (Application.log_level)\n", " Default: 30\n", " Choices: (0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL')\n", " Set the log level by value or name.\n", "--ipython-dir= (BaseIPythonApplication.ipython_dir)\n", " Default: ''\n", " The name of the IPython directory. This directory is used for logging\n", " configuration (through profiles), history storage, etc. The default is\n", " usually $HOME/.ipython. This option can also be specified through the\n", " environment variable IPYTHONDIR.\n", "--colors= (InteractiveShell.colors)\n", " Default: 'Linux'\n", " Choices: ('NoColor', 'LightBG', 'Linux')\n", " Set the color scheme (NoColor, Linux, or LightBG).\n", "--matplotlib= (InteractiveShellApp.matplotlib)\n", " Default: None\n", " Choices: ['auto', 'gtk', 'gtk3', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt4', 'qt5', 'tk', 'wx']\n", " Configure matplotlib for interactive use with the default matplotlib\n", " backend.\n", "-m (InteractiveShellApp.module_to_run)\n", " Default: ''\n", " Run the module as a script.\n", "--logfile= (InteractiveShell.logfile)\n", " Default: ''\n", " The name of the logfile to use.\n", "--ext= (InteractiveShellApp.extra_extension)\n", " Default: ''\n", " dotted module name of an IPython extension to load.\n", "--profile= (BaseIPythonApplication.profile)\n", " Default: 'default'\n", " The IPython profile to use.\n", "--logappend= (InteractiveShell.logappend)\n", " Default: ''\n", " Start logging to the given file in append mode.\n", "--cache-size= (InteractiveShell.cache_size)\n", " Default: 1000\n", " Set the size of the output cache. The default is 1000, you can change it\n", " permanently in your config file. Setting it to 0 completely disables the\n", " caching system, and the minimum value accepted is 20 (if you provide a value\n", " less than 20, it is reset to 0 and a warning is issued). This limit is\n", " defined because otherwise you'll spend more time re-flushing a too small\n", " cache than working\n", "--autocall= (InteractiveShell.autocall)\n", " Default: 0\n", " Choices: (0, 1, 2)\n", " Make IPython automatically call any callable object even if you didn't type\n", " explicit parentheses. For example, 'str 43' becomes 'str(43)' automatically.\n", " The value can be '0' to disable the feature, '1' for 'smart' autocall, where\n", " it is not applied if there are no more arguments on the line, and '2' for\n", " 'full' autocall, where all callable objects are automatically called (even\n", " if no arguments are present).\n", "--gui= (InteractiveShellApp.gui)\n", " Default: None\n", " Choices: ('glut', 'gtk', 'gtk3', 'osx', 'pyglet', 'qt', 'qt5', 'tk', 'wx')\n", " Enable GUI event loop integration with any of ('glut', 'gtk', 'gtk3', 'osx',\n", " 'pyglet', 'qt', 'qt5', 'tk', 'wx').\n", "--profile-dir= (ProfileDir.location)\n", " Default: ''\n", " Set the profile location directly. This overrides the logic used by the\n", " `profile` option.\n", "\n", "To see all available configurables, use `--help-all`\n", "\n", "Examples\n", "--------\n", "\n", " ipython --matplotlib # enable matplotlib integration\n", " ipython --matplotlib=qt # enable matplotlib integration with qt4 backend\n", " \n", " ipython --log-level=DEBUG # set logging to DEBUG\n", " ipython --profile=foo # start with profile foo\n", " \n", " ipython qtconsole # start the qtconsole GUI application\n", " ipython help qtconsole # show the help for the qtconsole subcmd\n", " \n", " ipython console # start the terminal-based console application\n", " ipython help console # show the help for the console subcmd\n", " \n", " ipython notebook # start the IPython notebook\n", " ipython help notebook # show the help for the notebook subcmd\n", " \n", " ipython profile create foo # create profile foo w/ default config files\n", " ipython help profile # show the help for the profile subcmd\n", " \n", " ipython locate # print the path to the IPython directory\n", " ipython locate profile foo # print the path to the directory for profile `foo`\n", " \n", " ipython nbconvert # convert notebooks to/from other formats\n", "\n" ] } ], "source": [ "!ipython -h" ] }, { "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", "execution_count": 2, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " If invoked with no options, it executes the file and \u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[Ks, passing the\r\n", " IPython session after running the script, rather than \u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[King. Files ending\r\n", "--confirm-\u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K\r\n", " Set to confirm when you try to \u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K IPython with an EOF (Control-D\r\n", " in Unix, Control-Z/Enter in Windows). By typing '\u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K' or 'quit',\r\n", " you can force a direct \u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K without any confirmation.\r\n", "--no-confirm-\u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K\r\n", " Don't prompt the user when \u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[King.\r\n", "--TerminalInteractiveShell.confirm_\u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K=\r\n", " Set to confirm when you try to \u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K IPython with an EOF (Control-D in Unix,\r\n", " Control-Z/Enter in Windows). By typing '\u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K' or 'quit', you can force a\r\n", " direct \u001b[1;31;46m\u001b[Kexit\u001b[m\u001b[K without any confirmation.\r\n" ] } ], "source": [ "!ipython --help-all | GREP_COLOR='1;31;46' grep --color exit" ] }, { "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": "markdown", "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": "markdown", "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", "execution_count": 3, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_config.py'\n", "[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_kernel_config.py'\n", "[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_console_config.py'\n", "[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_qtconsole_config.py'\n", "[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_notebook_config.py'\n", "[ProfileCreate] Generating default config file: '/home/takluyver/.ipython/profile_newprofile/ipython_nbconvert_config.py'\n" ] } ], "source": [ "!ipython profile create newprofile" ] }, { "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", "execution_count": 4, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "/home/takluyver/.ipython/profile_default\n", "/home/takluyver/.ipython/profile_newprofile\n" ] } ], "source": [ "!ipython locate profile default\n", "!ipython locate profile newprofile" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can skim" ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'/home/takluyver/.ipython/profile_default'" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "profile = get_ipython().profile_dir.location\n", "profile" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[0m\u001b[01;34mdb\u001b[0m/ ipython_nbconvert_config.py \u001b[01;34mnbconfig\u001b[0m/ \u001b[01;34mstartup\u001b[0m/\r\n", "history.sqlite ipython_notebook_config.py notebook.json \u001b[01;34mstatic\u001b[0m/\r\n", "history.sqlite-journal ipython_qtconsole_config.py \u001b[01;34mpid\u001b[0m/\r\n", "ipython_config.py \u001b[01;34mlog\u001b[0m/ \u001b[01;34msecurity\u001b[0m/\r\n" ] } ], "source": [ "ls $profile" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Let's peek at our config file" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "collapsed": false }, "outputs": [], "source": [ "pycat $profile/ipython_config.py" ] }, { "cell_type": "markdown", "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", "execution_count": 8, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "imports.py README\r\n" ] } ], "source": [ "!ls $profile/startup" ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "This is the IPython startup directory\r\n", "\r\n", ".py and .ipy files in this directory will be run *prior* to any code or files specified\r\n", "via the exec_lines or exec_files configurables whenever you load this profile.\r\n", "\r\n", "Files will be run in lexicographical order, so you can control the execution order of files\r\n", "with a prefix, e.g.::\r\n", "\r\n", " 00-first.py\r\n", " 50-middle.py\r\n", " 99-last.ipy\r\n" ] } ], "source": [ "!cat $profile/startup/README" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Adding common imports, so we never have to forget them again" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Writing /home/takluyver/.ipython/profile_default/startup/simpleimports.py\n" ] } ], "source": [ "%%writefile $profile/startup/simpleimports.py\n", "\n", "import sys, os, time, re" ] }, { "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", "execution_count": 11, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "sys" ] }, { "cell_type": "markdown", "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", "execution_count": 12, "metadata": { "collapsed": false }, "outputs": [], "source": [ "from IPython.core.magic import (register_line_magic, register_cell_magic,\n", " register_line_cell_magic)" ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "collapsed": false }, "outputs": [], "source": [ "@register_line_magic\n", "def sleep(line):\n", " \"\"\"A simple function for sleeping\"\"\"\n", " import time\n", " t = float(line)\n", " time.sleep(t)" ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "collapsed": false }, "outputs": [], "source": [ "%sleep 2" ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "collapsed": false }, "outputs": [], "source": [ "%sleep?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Cell Magic" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**Cell magics** take two args:\n", "\n", "1. the **line** on the same line of the magic \n", "2. the **cell** the multiline body of the cell after the first line" ] }, { "cell_type": "code", "execution_count": 16, "metadata": { "collapsed": false }, "outputs": [], "source": [ "@register_cell_magic\n", "def dummy(line, cell):\n", " \"\"\"dummy cell magic for displaying the line and cell it is passed\"\"\"\n", " print(\"line: %r\" % line)\n", " print(\"cell: %r\" % cell)" ] }, { "cell_type": "code", "execution_count": 17, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "line: 'this is the line'\n", "cell: 'this\\nis the\\ncell'\n" ] } ], "source": [ "%%dummy this is the line\n", "this\n", "is the\n", "cell" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For more details on declaring your own magics in more complex scenarios, [see our docs](http://ipython.org/ipython-doc/stable/interactive/reference.html#defining-your-own-magics)." ] } ], "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.4.3" } }, "nbformat": 4, "nbformat_minor": 0 }