From b1e83362bc5e055b6e36533015528015523a1a5c 2007-03-18 20:13:35 From: fperez Date: 2007-03-18 20:13:35 Subject: [PATCH] - applied Nicolas Pernetty's patch to improve support for (X)Emacs under Win32. - update docs to include mention of Qt4 support (it has been there for a long time, but no documentation mentioned it). --- diff --git a/IPython/ColorANSI.py b/IPython/ColorANSI.py index edc23bf..194cea7 100644 --- a/IPython/ColorANSI.py +++ b/IPython/ColorANSI.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- """Tools for coloring text in ANSI terminals. -$Id: ColorANSI.py 1005 2006-01-12 08:39:26Z fperez $""" +$Id: ColorANSI.py 2152 2007-03-18 20:13:35Z fperez $""" #***************************************************************************** # Copyright (C) 2002-2006 Fernando Perez. @@ -79,8 +79,14 @@ class InputTermColors: This class should be used as a mixin for building color schemes.""" NoColor = '' # for color schemes in color-less terminals. - Normal = '\001\033[0m\002' # Reset normal coloring - _base = '\001\033[%sm\002' # Template for all other colors + + if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs': + # (X)emacs on W32 gets confused with \001 and \002 so we remove them + Normal = '\033[0m' # Reset normal coloring + _base = '\033[%sm' # Template for all other colors + else: + Normal = '\001\033[0m\002' # Reset normal coloring + _base = '\001\033[%sm\002' # Template for all other colors # Build the actual color table as a set of class attributes: make_color_table(InputTermColors) diff --git a/IPython/genutils.py b/IPython/genutils.py index 467505c..6979116 100644 --- a/IPython/genutils.py +++ b/IPython/genutils.py @@ -5,7 +5,7 @@ General purpose utilities. This is a grab-bag of stuff I find useful in most programs I write. Some of these things are also convenient when working at the command line. -$Id: genutils.py 2108 2007-02-23 00:31:17Z fperez $""" +$Id: genutils.py 2152 2007-03-18 20:13:35Z fperez $""" #***************************************************************************** # Copyright (C) 2001-2006 Fernando Perez. @@ -1247,7 +1247,8 @@ def get_pager_start(pager,start): return start_string #---------------------------------------------------------------------------- -if os.name == "nt": +# (X)emacs on W32 doesn't like to be bypassed with msvcrt.getch() +if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs': import msvcrt def page_more(): """ Smart pausing between pages diff --git a/IPython/usage.py b/IPython/usage.py index 229f575..527c1bb 100644 --- a/IPython/usage.py +++ b/IPython/usage.py @@ -6,7 +6,7 @@ # the file COPYING, distributed as part of this software. #***************************************************************************** -# $Id: usage.py 2010 2006-12-20 15:29:17Z vivainio $ +# $Id: usage.py 2152 2007-03-18 20:13:35Z fperez $ from IPython import Release __author__ = '%s <%s>' % Release.authors['Fernando'] @@ -53,19 +53,19 @@ SPECIAL THREADING OPTIONS ization of ipython itself, before the normal option-handling mechanism is active. - -gthread, -qthread, -wthread, -pylab + -gthread, -qthread, -q4thread, -wthread, -pylab Only ONE of these can be given, and it can only be given as the first option passed to IPython (it will have no effect in any other position). They provide threading support for the GTK, QT and WXWidgets toolkits, and for the matplotlib library. - With any of the first three options, IPython starts running a + With any of the first four options, IPython starts running a separate thread for the graphical toolkit's operation, so that you can open and control graphical elements from within an - IPython command line, without blocking. All three provide - essentially the same functionality, respectively for GTK, QT and - WXWidgets (via their Python interfaces). + IPython command line, without blocking. All four provide + essentially the same functionality, respectively for GTK, QT3, + QT4 and WXWidgets (via their Python interfaces). Note that with -wthread, you can additionally use the -wxversion option to request a specific version of wx to be used. This @@ -81,14 +81,14 @@ SPECIAL THREADING OPTIONS execute (without blocking) any matplotlib-based script which calls show() at the end. - -tk The -g/q/wthread options, and -pylab (if matplotlib is + -tk The -g/q/q4/wthread options, and -pylab (if matplotlib is configured to use GTK, QT or WX), will normally block Tk graphical interfaces. This means that when GTK, QT or WX threading is active, any attempt to open a Tk GUI will result in a dead window, and possibly cause the Python interpreter to crash. An extra option, -tk, is available to address this issue. It can ONLY be given as a SECOND option after any of the - above (-gthread, -qthread, -wthread or -pylab). + above (-gthread, -qthread, q4thread, -wthread or -pylab). If -tk is given, IPython will try to coordinate Tk threading with GTK, QT or WX. This is however potentially unreliable, and diff --git a/doc/ChangeLog b/doc/ChangeLog index 9390e57..717ccab 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2007-03-18 Fernando Perez + + * IPython/ColorANSI.py (InputTermColors.Normal): applied Nicolas + Pernetty's patch to improve support for (X)Emacs under Win32. + 2007-03-17 Fernando Perez * IPython/Shell.py (hijack_wx): ipmort WX with current semantics diff --git a/doc/ipython.1 b/doc/ipython.1 index 25b3a62..e63a11b 100644 --- a/doc/ipython.1 +++ b/doc/ipython.1 @@ -36,18 +36,18 @@ The following special options are ONLY valid at the beginning of the command line, and not later. This is because they control the initialization of ipython itself, before the normal option-handling mechanism is active. .TP -.B \-gthread, \-qthread, \-wthread, \-pylab +.B \-gthread, \-qthread, \-q4thread, \-wthread, \-pylab Only ONE of these can be given, and it can only be given as the first option -passed to IPython (it will have no effect in any other position). They -provide threading support for the GTK, QT and WXWidgets toolkits, and for the +passed to IPython (it will have no effect in any other position). They provide +threading support for the GTK, QT3, QT4 and WXWidgets toolkits, and for the matplotlib library. .br .sp 1 -With any of the first three options, IPython starts running a separate thread +With any of the first four options, IPython starts running a separate thread for the graphical toolkit's operation, so that you can open and control graphical elements from within an IPython command line, without blocking. All -three provide essentially the same functionality, respectively for GTK, QT and -WXWidgets (via their Python interfaces). +four provide essentially the same functionality, respectively for GTK, QT3, QT4 +and WXWidgets (via their Python interfaces). .br .sp 1 Note that with \-wthread, you can additionally use the \-wxversion option to @@ -64,7 +64,7 @@ backend requires it. It also modifies the %run command to correctly execute (without blocking) any matplotlib-based script which calls show() at the end. .TP .B \-tk -The \-g/q/wthread options, and \-pylab (if matplotlib is configured to use +The \-g/q/q4/wthread options, and \-pylab (if matplotlib is configured to use GTK, QT or WX), will normally block Tk graphical interfaces. This means that when GTK, QT or WX threading is active, any attempt to open a Tk GUI will result in a dead window, and possibly cause the Python interpreter to crash. diff --git a/doc/manual_base.lyx b/doc/manual_base.lyx index e52ce4a..32948c6 100644 --- a/doc/manual_base.lyx +++ b/doc/manual_base.lyx @@ -1,5 +1,7 @@ -#LyX 1.3 created this file. For more info see http://www.lyx.org/ -\lyxformat 221 +#LyX 1.4.3 created this file. For more info see http://www.lyx.org/ +\lyxformat 245 +\begin_document +\begin_header \textclass article \begin_preamble %\usepackage{ae,aecompl} @@ -50,13 +52,12 @@ \fontscheme palatino \graphics default \paperfontsize 11 -\spacing single -\papersize Default -\paperpackage a4 -\use_geometry 1 -\use_amsmath 0 -\use_natbib 0 -\use_numerical_citations 0 +\spacing single +\papersize default +\use_geometry true +\use_amsmath 1 +\cite_engine basic +\use_bibtopic false \paperorientation portrait \leftmargin 1in \topmargin 1in @@ -67,97 +68,121 @@ \paragraph_separation skip \defskip medskip \quotes_language english -\quotes_times 2 \papercolumns 1 \papersides 2 \paperpagestyle fancy +\tracking_changes false +\output_changes true +\end_header -\layout Title +\begin_body +\begin_layout Title IPython -\newline +\newline -\size larger +\size larger An enhanced Interactive Python -\size large +\size large -\newline +\newline User Manual, v. __version__ -\layout Author +\end_layout +\begin_layout Author Fernando P�rez \begin_inset Foot -collapsed true +status collapsed -\layout Standard +\begin_layout Standard - -\size scriptsize +\size scriptsize Department of Applied Mathematics, University of Colorado at Boulder. -\family typewriter +\family typewriter -\end_inset +\end_layout +\end_inset -\layout Standard +\end_layout +\begin_layout Standard \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash latex{ -\end_inset +\end_layout + +\end_inset \begin_inset LatexCommand \tableofcontents{} -\end_inset +\end_inset \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard } -\end_inset +\end_layout +\end_inset -\layout Standard +\end_layout +\begin_layout Standard \begin_inset ERT -status Open +status open -\layout Standard +\begin_layout Standard -\backslash + +\backslash html{ -\backslash +\backslash bodytext{bgcolor=#ffffff}} -\end_inset +\end_layout + +\end_inset + +\end_layout -\layout Section -\pagebreak_top +\begin_layout Standard + +\newpage + +\end_layout + +\begin_layout Section Overview -\layout Standard +\end_layout +\begin_layout Standard One of Python's most useful features is its interactive interpreter. This system allows very fast testing of ideas without the overhead of creating test files as is typical in most programming languages. However, the interpreter supplied with the standard Python distribution is somewhat limited for extended interactive use. -\layout Standard +\end_layout +\begin_layout Standard IPython is a free software project (released under the BSD license) which tries to: -\layout Enumerate +\end_layout +\begin_layout Enumerate Provide an interactive shell superior to Python's default. IPython has many features for object introspection, system shell access, and its own special command system for adding functionality when working @@ -165,388 +190,425 @@ Provide an interactive shell superior to Python's default. It tries to be a very efficient environment both for Python code development and for exploration of problems using Python objects (in situations like data analysis). -\layout Enumerate +\end_layout +\begin_layout Enumerate Serve as an embeddable, ready to use interpreter for your own programs. IPython can be started with a single call from inside another program, providing access to the current namespace. This can be very useful both for debugging purposes and for situations where a blend of batch-processing and interactive exploration are needed. -\layout Enumerate +\end_layout +\begin_layout Enumerate Offer a flexible framework which can be used as the base environment for other systems with Python as the underlying language. Specifically scientific environments like Mathematica, IDL and Matlab inspired its design, but similar ideas can be useful in many fields. -\layout Enumerate +\end_layout +\begin_layout Enumerate Allow interactive testing of threaded graphical toolkits. IPython has support for interactive, non-blocking control of GTK, Qt and WX applications via special threading flags. The normal Python shell can only do this for Tkinter applications. -\layout Subsection +\end_layout +\begin_layout Subsection Main features -\layout Itemize +\end_layout +\begin_layout Itemize Dynamic object introspection. One can access docstrings, function definition prototypes, source code, source files and other details of any object accessible to the interpreter with a single keystroke (` -\family typewriter +\family typewriter ? -\family default +\family default ', and using ` -\family typewriter +\family typewriter ?? -\family default +\family default ' provides additional detail). -\layout Itemize +\end_layout +\begin_layout Itemize Searching through modules and namespaces with ` -\family typewriter +\family typewriter * -\family default +\family default ' wildcards, both when using the ` -\family typewriter +\family typewriter ? -\family default +\family default ' system and via the -\family typewriter +\family typewriter %psearch -\family default +\family default command. -\layout Itemize +\end_layout +\begin_layout Itemize Completion in the local namespace, by typing TAB at the prompt. This works for keywords, methods, variables and files in the current directory. This is supported via the readline library, and full access to configuring readline's behavior is provided. -\layout Itemize +\end_layout +\begin_layout Itemize Numbered input/output prompts with command history (persistent across sessions and tied to each profile), full searching in this history and caching of all input and output. -\layout Itemize +\end_layout +\begin_layout Itemize User-extensible `magic' commands. A set of commands prefixed with -\family typewriter +\family typewriter % -\family default +\family default is available for controlling IPython itself and provides directory control, namespace information and many aliases to common system shell commands. -\layout Itemize +\end_layout +\begin_layout Itemize Alias facility for defining your own system aliases. -\layout Itemize +\end_layout +\begin_layout Itemize Complete system shell access. Lines starting with ! are passed directly to the system shell, and using !! captures shell output into python variables for further use. -\layout Itemize +\end_layout +\begin_layout Itemize Background execution of Python commands in a separate thread. IPython has an internal job manager called -\family typewriter +\family typewriter jobs -\family default +\family default , and a conveninence backgrounding magic function called -\family typewriter +\family typewriter %bg -\family default +\family default . -\layout Itemize +\end_layout +\begin_layout Itemize The ability to expand python variables when calling the system shell. In a shell command, any python variable prefixed with -\family typewriter +\family typewriter $ -\family default +\family default is expanded. A double -\family typewriter +\family typewriter $$ -\family default +\family default allows passing a literal -\family typewriter +\family typewriter $ -\family default +\family default to the shell (for access to shell and environment variables like -\family typewriter +\family typewriter $PATH -\family default +\family default ). -\layout Itemize +\end_layout +\begin_layout Itemize Filesystem navigation, via a magic -\family typewriter +\family typewriter %cd -\family default +\family default command, along with a persistent bookmark system (using -\family typewriter +\family typewriter %bookmark -\family default +\family default ) for fast access to frequently visited directories. -\layout Itemize +\end_layout +\begin_layout Itemize A lightweight persistence framework via the -\family typewriter +\family typewriter %store -\family default +\family default command, which allows you to save arbitrary Python variables. These get restored automatically when your session restarts. -\layout Itemize +\end_layout +\begin_layout Itemize Automatic indentation (optional) of code as you type (through the readline library). -\layout Itemize +\end_layout +\begin_layout Itemize Macro system for quickly re-executing multiple lines of previous input with a single name. Macros can be stored persistently via -\family typewriter +\family typewriter %store -\family default +\family default and edited via -\family typewriter +\family typewriter %edit -\family default +\family default . -\layout Itemize +\end_layout +\begin_layout Itemize Session logging (you can then later use these logs as code in your programs). Logs can optionally timestamp all input, and also store session output (marked as comments, so the log remains valid Python source code). -\layout Itemize +\end_layout +\begin_layout Itemize Session restoring: logs can be replayed to restore a previous session to the state where you left it. -\layout Itemize +\end_layout +\begin_layout Itemize Verbose and colored exception traceback printouts. Easier to parse visually, and in verbose mode they produce a lot of useful debugging information (basically a terminal version of the cgitb module). -\layout Itemize +\end_layout +\begin_layout Itemize Auto-parentheses: callable objects can be executed without parentheses: -\family typewriter +\family typewriter `sin 3' -\family default +\family default is automatically converted to -\family typewriter +\family typewriter `sin(3) -\family default +\family default '. -\layout Itemize +\end_layout +\begin_layout Itemize Auto-quoting: using ` -\family typewriter +\family typewriter , -\family default +\family default ' or ` -\family typewriter +\family typewriter ; -\family default +\family default ' as the first character forces auto-quoting of the rest of the line: -\family typewriter -`,my_function a\SpecialChar ~ +\family typewriter +`,my_function a\InsetSpace ~ b' -\family default +\family default becomes automatically -\family typewriter +\family typewriter `my_function("a","b")' -\family default +\family default , while -\family typewriter -`;my_function a\SpecialChar ~ +\family typewriter +`;my_function a\InsetSpace ~ b' -\family default +\family default becomes -\family typewriter +\family typewriter `my_function("a b")' -\family default +\family default . -\layout Itemize +\end_layout +\begin_layout Itemize Extensible input syntax. You can define filters that pre-process user input to simplify input in special situations. This allows for example pasting multi-line code fragments which start with -\family typewriter +\family typewriter `>>>' -\family default +\family default or -\family typewriter +\family typewriter `...' -\family default +\family default such as those from other python sessions or the standard Python documentation. -\layout Itemize +\end_layout +\begin_layout Itemize Flexible configuration system. It uses a configuration file which allows permanent setting of all command-line options, module loading, code and file execution. The system allows recursive file inclusion, so you can have a base file with defaults and layers which load other customizations for particular projects. -\layout Itemize +\end_layout +\begin_layout Itemize Embeddable. You can call IPython as a python shell inside your own python programs. This can be used both for debugging code or for providing interactive abilities to your programs with knowledge about the local namespaces (very useful in debugging and data analysis situations). -\layout Itemize +\end_layout +\begin_layout Itemize Easy debugger access. You can set IPython to call up an enhanced version of the Python debugger ( -\family typewriter +\family typewriter pdb -\family default +\family default ) every time there is an uncaught exception. This drops you inside the code which triggered the exception with all the data live and it is possible to navigate the stack to rapidly isolate the source of a bug. The -\family typewriter +\family typewriter %run -\family default +\family default magic command --with the -\family typewriter +\family typewriter -d -\family default +\family default option-- can run any script under -\family typewriter +\family typewriter pdb -\family default +\family default 's control, automatically setting initial breakpoints for you. This version of -\family typewriter +\family typewriter pdb -\family default +\family default has IPython-specific improvements, including tab-completion and traceback coloring support. -\layout Itemize +\end_layout +\begin_layout Itemize Profiler support. You can run single statements (similar to -\family typewriter +\family typewriter profile.run() -\family default +\family default ) or complete programs under the profiler's control. While this is possible with standard -\family typewriter +\family typewriter cProfile -\family default +\family default or -\family typewriter +\family typewriter profile -\family default +\family default modules, IPython wraps this functionality with magic commands (see -\family typewriter +\family typewriter `%prun' -\family default +\family default and -\family typewriter +\family typewriter `%run -p -\family default +\family default ') convenient for rapid interactive work. -\layout Subsection +\end_layout +\begin_layout Subsection Portability and Python requirements -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Python requirements: -\series default +\series default IPython requires with Python version 2.3 or newer. If you are still using Python 2.2 and can not upgrade, the last version of IPython which worked with Python 2.2 was 0.6.15, so you will have to use that. -\layout Standard +\end_layout +\begin_layout Standard IPython is developed under -\series bold +\series bold Linux -\series default +\series default , but it should work in any reasonable Unix-type system (tested OK under Solaris and the *BSD family, for which a port exists thanks to Dryice Liu). -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Mac OS X -\series default +\series default : it works, apparently without any problems (thanks to Jim Boyle at Lawrence Livermore for the information). Thanks to Andrea Riciputi, Fink support is available. -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold CygWin -\series default +\series default : it works mostly OK, though some users have reported problems with prompt coloring. No satisfactory solution to this has been found so far, you may want to disable colors permanently in the -\family typewriter +\family typewriter ipythonrc -\family default +\family default configuration file if you experience problems. If you have proper color support under cygwin, please post to the IPython mailing list so this issue can be resolved for all users. -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Windows -\series default +\series default : it works well under Windows XP/2k, and I suspect NT should behave similarly. - Section\SpecialChar ~ + Section\InsetSpace ~ \begin_inset LatexCommand \ref{sub:Under-Windows} -\end_inset +\end_inset describes installation details for Windows, including some additional tools needed on this platform. -\layout Standard +\end_layout +\begin_layout Standard Windows 9x support is present, and has been reported to work fine (at least on WinME). -\layout Standard +\end_layout +\begin_layout Standard Note, that I have very little access to and experience with Windows development. However, an excellent group of Win32 users (led by Ville Vainio), consistently contribute bugfixes and platform-specific enhancements, so they more than make up for my deficiencies on that front. - In fact, Win32 users report using IPython as a system shell (see Sec.\SpecialChar ~ + In fact, Win32 users report using IPython as a system shell (see Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:IPython-as-shell} -\end_inset +\end_inset for details), as it offers a level of control and features which the default -\family typewriter +\family typewriter cmd.exe -\family default +\family default doesn't provide. -\layout Subsection +\end_layout +\begin_layout Subsection Location -\layout Standard +\end_layout +\begin_layout Standard IPython is generously hosted at \begin_inset LatexCommand \htmlurl{http://ipython.scipy.org} -\end_inset +\end_inset by the Enthought, Inc and the SciPy project. This site offers downloads, subversion access, mailing lists and a bug @@ -554,464 +616,525 @@ IPython is generously hosted at I am very grateful to Enthought ( \begin_inset LatexCommand \htmlurl{http://www.enthought.com} -\end_inset +\end_inset ) and all of the SciPy team for their contribution. -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:install} -\end_inset +\end_inset Installation -\layout Subsection +\end_layout +\begin_layout Subsection Instant instructions -\layout Standard +\end_layout +\begin_layout Standard If you are of the impatient kind, under Linux/Unix simply untar/unzip the download, then install with -\family typewriter +\family typewriter `python setup.py install' -\family default +\family default . Under Windows, double-click on the provided -\family typewriter +\family typewriter .exe -\family default +\family default binary installer. -\layout Standard +\end_layout +\begin_layout Standard Then, take a look at Sections \begin_inset LatexCommand \ref{sec:good_config} -\end_inset +\end_inset for configuring things optimally and \begin_inset LatexCommand \ref{sec:quick_tips} -\end_inset +\end_inset for quick tips on efficient use of IPython. You can later refer to the rest of the manual for all the gory details. -\layout Standard +\end_layout +\begin_layout Standard See the notes in sec. \begin_inset LatexCommand \ref{sec:upgrade} -\end_inset +\end_inset for upgrading IPython versions. -\layout Subsection +\end_layout +\begin_layout Subsection Detailed Unix instructions (Linux, Mac OS X, etc.) -\layout Standard +\end_layout +\begin_layout Standard For RPM based systems, simply install the supplied package in the usual manner. If you download the tar archive, the process is: -\layout Enumerate +\end_layout +\begin_layout Enumerate Unzip/untar the -\family typewriter +\family typewriter ipython-XXX.tar.gz -\family default +\family default file wherever you want ( -\family typewriter +\family typewriter XXX -\family default +\family default is the version number). It will make a directory called -\family typewriter +\family typewriter ipython-XXX. -\family default +\family default Change into that directory where you will find the files -\family typewriter +\family typewriter README -\family default +\family default and -\family typewriter +\family typewriter setup.py -\family default +\family default . -\family typewriter +\family typewriter O -\family default +\family default nce you've completed the installation, you can safely remove this directory. -\layout Enumerate +\end_layout +\begin_layout Enumerate If you are installing over a previous installation of version 0.2.0 or earlier, first remove your -\family typewriter +\family typewriter $HOME/.ipython -\family default +\family default directory, since the configuration file format has changed somewhat (the '=' were removed from all option specifications). Or you can call ipython with the -\family typewriter +\family typewriter -upgrade -\family default +\family default option and it will do this automatically for you. -\layout Enumerate +\end_layout +\begin_layout Enumerate IPython uses distutils, so you can install it by simply typing at the system prompt (don't type the -\family typewriter +\family typewriter $ -\family default +\family default ) -\newline +\newline -\family typewriter +\family typewriter $ python setup.py install -\family default +\family default -\newline +\newline Note that this assumes you have root access to your machine. If you don't have root access or don't want IPython to go in the default python directories, you'll need to use the \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash verb|--home| -\end_inset +\end_layout + +\end_inset option (or \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash verb|--prefix| -\end_inset +\end_layout + +\end_inset ). For example: -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash verb|$ python setup.py install --home $HOME/local| -\end_inset +\end_layout + +\end_inset -\newline +\newline will install IPython into -\family typewriter +\family typewriter $HOME/local -\family default +\family default and its subdirectories (creating them if necessary). -\newline +\newline You can type -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash verb|$ python setup.py --help| -\end_inset +\end_layout + +\end_inset -\newline +\newline for more details. -\newline +\newline Note that if you change the default location for \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash verb|--home| -\end_inset +\end_layout + +\end_inset at installation, IPython may end up installed at a location which is not part of your -\family typewriter +\family typewriter $PYTHONPATH -\family default +\family default environment variable. In this case, you'll need to configure this variable to include the actual directory where the -\family typewriter +\family typewriter IPython/ -\family default +\family default directory ended (typically the value you give to \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash verb|--home| -\end_inset +\end_layout + +\end_inset plus -\family typewriter +\family typewriter /lib/python -\family default +\family default ). -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Mac OSX information -\layout Standard +\end_layout +\begin_layout Standard Under OSX, there is a choice you need to make. Apple ships its own build of Python, which lives in the core OSX filesystem hierarchy. You can also manually install a separate Python, either purely by hand (typically in -\family typewriter +\family typewriter /usr/local -\family default +\family default ) or by using Fink, which puts everything under -\family typewriter +\family typewriter /sw -\family default +\family default . Which route to follow is a matter of personal preference, as I've seen users who favor each of the approaches. Here I will simply list the known installation issues under OSX, along with their solutions. -\layout Standard +\end_layout +\begin_layout Standard This page: \begin_inset LatexCommand \htmlurl{http://geosci.uchicago.edu/~tobis/pylab.html} -\end_inset +\end_inset contains information on this topic, with additional details on how to make IPython and matplotlib play nicely under OSX. -\layout Subsubsection* +\end_layout +\begin_layout Subsubsection* GUI problems -\layout Standard +\end_layout +\begin_layout Standard The following instructions apply to an install of IPython under OSX from unpacking the -\family typewriter +\family typewriter .tar.gz -\family default +\family default distribution and installing it for the default Python interpreter shipped by Apple. If you are using a fink install, fink will take care of these details for you, by installing IPython against fink's Python. -\layout Standard +\end_layout +\begin_layout Standard IPython offers various forms of support for interacting with graphical applicati ons from the command line, from simple Tk apps (which are in principle always supported by Python) to interactive control of WX, Qt and GTK apps. Under OSX, however, this requires that ipython is installed by calling the special -\family typewriter +\family typewriter pythonw -\family default +\family default script at installation time, which takes care of coordinating things with Apple's graphical environment. -\layout Standard +\end_layout +\begin_layout Standard So when installing under OSX, it is best to use the following command: -\family typewriter +\family typewriter -\newline +\newline -\family default +\family default \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash verb| $ sudo pythonw setup.py install --install-scripts=/usr/local/bin| -\end_inset +\end_layout + +\end_inset -\newline +\newline or -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash verb| $ sudo pythonw setup.py install --install-scripts=/usr/bin| -\end_inset +\end_layout +\end_inset -\newline + +\newline depending on where you like to keep hand-installed executables. -\layout Standard +\end_layout +\begin_layout Standard The resulting script will have an appropriate shebang line (the first line in the script whic begins with -\family typewriter +\family typewriter #!... -\family default +\family default ) such that the ipython interpreter can interact with the OS X GUI. If the installed version does not work and has a shebang line that points to, for example, just -\family typewriter +\family typewriter /usr/bin/python -\family default +\family default , then you might have a stale, cached version in your -\family typewriter +\family typewriter build/scripts- -\family default +\family default directory. Delete that directory and rerun the -\family typewriter +\family typewriter setup.py -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard It is also a good idea to use the special flag \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash verb|--install-scripts| -\end_inset +\end_layout + +\end_inset as indicated above, to ensure that the ipython scripts end up in a location which is part of your -\family typewriter +\family typewriter $PATH -\family default +\family default . Otherwise Apple's Python will put the scripts in an internal directory not available by default at the command line (if you use -\family typewriter +\family typewriter /usr/local/bin -\family default +\family default , you need to make sure this is in your -\family typewriter +\family typewriter $PATH -\family default +\family default , which may not be true by default). -\layout Subsubsection* +\end_layout +\begin_layout Subsubsection* Readline problems -\layout Standard +\end_layout +\begin_layout Standard By default, the Python version shipped by Apple does -\emph on +\emph on not -\emph default +\emph default include the readline library, so central to IPython's behavior. If you install IPython against Apple's Python, you will not have arrow keys, tab completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt readline library here: -\newline +\newline \begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip} -\end_inset +\end_inset -\layout Standard +\end_layout +\begin_layout Standard If you are using OSX 10.4 (Tiger), after installing this package you need to either: -\layout Enumerate +\end_layout +\begin_layout Enumerate move -\family typewriter +\family typewriter readline.so -\family default +\family default from -\family typewriter +\family typewriter /Library/Python/2.3 -\family default +\family default to -\family typewriter +\family typewriter /Library/Python/2.3/site-packages -\family default +\family default , or -\layout Enumerate +\end_layout +\begin_layout Enumerate install \begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/TigerPython23Compat.pkg.zip} -\end_inset +\end_inset -\layout Standard +\end_layout +\begin_layout Standard Users installing against Fink's Python or a properly hand-built one should not have this problem. -\layout Subsubsection* +\end_layout +\begin_layout Subsubsection* DarwinPorts -\layout Standard +\end_layout +\begin_layout Standard I report here a message from an OSX user, who suggests an alternative means of using IPython under this operating system with good results. Please let me know of any updates that may be useful for this section. His message is reproduced verbatim below: -\layout Quote +\end_layout +\begin_layout Quote From: Markus Banfi -\family typewriter +\family typewriter -\layout Quote +\end_layout +\begin_layout Quote As a MacOS X (10.4.2) user I prefer to install software using DawinPorts instead of Fink. I had no problems installing ipython with DarwinPorts. It's just: -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter +\family typewriter sudo port install py-ipython -\layout Quote +\end_layout +\begin_layout Quote It automatically resolved all dependencies (python24, readline, py-readline). So far I did not encounter any problems with the DarwinPorts port of ipython. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sub:Under-Windows} -\end_inset +\end_inset Windows instructions -\layout Standard +\end_layout +\begin_layout Standard Some of IPython's very useful features are: -\layout Itemize +\end_layout +\begin_layout Itemize Integrated readline support (Tab-based file, object and attribute completion, input history across sessions, editable command line, etc.) -\layout Itemize +\end_layout +\begin_layout Itemize Coloring of prompts, code and tracebacks. -\layout Standard +\end_layout +\begin_layout Standard These, by default, are only available under Unix-like operating systems. However, thanks to Gary Bishop's work, Windows XP/2k users can also benefit from them. @@ -1019,83 +1142,89 @@ These, by default, are only available under Unix-like operating systems. and color support, so that IPython under Windows XP/2k can be as friendly and powerful as under Unix-like environments. -\layout Standard +\end_layout +\begin_layout Standard This library, now named -\family typewriter +\family typewriter PyReadline -\family default +\family default , has been absorbed by the IPython team (J�rgen Stenarson, in particular), and it continues to be developed with new features, as well as being distribute d directly from the IPython site. -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter PyReadline -\family default +\family default extension requires -\family typewriter +\family typewriter CTypes -\family default +\family default and the windows IPython installer needs -\family typewriter +\family typewriter PyWin32 -\family default +\family default , so in all you need: -\layout Enumerate +\end_layout +\begin_layout Enumerate -\family typewriter +\family typewriter PyWin32 -\family default +\family default from \begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/mhammond} -\end_inset +\end_inset . -\layout Enumerate +\end_layout +\begin_layout Enumerate -\family typewriter +\family typewriter CTypes -\family default +\family default from \begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/theller/ctypes} -\end_inset +\end_inset (you -\emph on +\emph on must -\emph default +\emph default use version 0.9.1 or newer). -\layout Enumerate +\end_layout +\begin_layout Enumerate -\family typewriter +\family typewriter PyReadline -\family default +\family default for Windows from \begin_inset LatexCommand \htmlurl{http://projects.scipy.org/ipython/ipython/wiki/PyReadline/Intro} -\end_inset +\end_inset . That page contains further details on using and configuring the system to your liking. -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Warning about a broken readline-like library: -\series default +\series default several users have reported problems stemming from using the pseudo-readline library at \begin_inset LatexCommand \htmlurl{http://newcenturycomputers.net/projects/readline.html} -\end_inset +\end_inset . This is a broken library which, while called readline, only implements @@ -1104,20 +1233,22 @@ Warning about a broken readline-like library: and causes unpredictable crashes later. If you wish to use IPython under Windows, you must NOT use this library, which for all purposes is (at least as of version 1.6) terminally broken. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Installation procedure -\layout Standard +\end_layout +\begin_layout Standard Once you have the above installed, from the IPython download directory grab the -\family typewriter +\family typewriter ipython-XXX.win32.exe -\family default +\family default file, where -\family typewriter +\family typewriter XXX -\family default +\family default represents the version number. This is a regular windows executable installer, which you can simply double-cli ck to install. @@ -1125,103 +1256,110 @@ ck to install. IPython in the Windows list of applications, so you can later uninstall it from the Control Panel. -\layout Standard +\end_layout +\begin_layout Standard IPython tries to install the configuration information in a directory named -\family typewriter +\family typewriter .ipython -\family default +\family default ( -\family typewriter +\family typewriter _ipython -\family default +\family default under Windows) located in your `home' directory. IPython sets this directory by looking for a -\family typewriter +\family typewriter HOME -\family default +\family default environment variable; if such a variable does not exist, it uses -\family typewriter +\family typewriter HOMEDRIVE -\backslash +\backslash HOMEPATH -\family default +\family default (these are always defined by Windows). This typically gives something like -\family typewriter +\family typewriter C: -\backslash +\backslash Documents and Settings -\backslash +\backslash YourUserName -\family default +\family default , but your local details may vary. In this directory you will find all the files that configure IPython's defaults, and you can put there your profiles and extensions. This directory is automatically added by IPython to -\family typewriter +\family typewriter sys.path -\family default +\family default , so anything you place there can be found by -\family typewriter +\family typewriter import -\family default +\family default statements. -\layout Paragraph +\end_layout +\begin_layout Paragraph Upgrading -\layout Standard +\end_layout +\begin_layout Standard For an IPython upgrade, you should first uninstall the previous version. This will ensure that all files and directories (such as the documentation) which carry embedded version strings in their names are properly removed. -\layout Paragraph +\end_layout +\begin_layout Paragraph Manual installation under Win32 -\layout Standard +\end_layout +\begin_layout Standard In case the automatic installer does not work for some reason, you can download the -\family typewriter +\family typewriter ipython-XXX.tar.gz -\family default +\family default file, which contains the full IPython source distribution (the popular WinZip can read -\family typewriter +\family typewriter .tar.gz -\family default +\family default files). After uncompressing the archive, you can install it at a command terminal just like any other Python module, by using -\family typewriter +\family typewriter `python setup.py install' -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard After the installation, run the supplied -\family typewriter +\family typewriter win32_manual_post_install.py -\family default +\family default script, which creates the necessary Start Menu shortcuts for you. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:upgrade} -\end_inset +\end_inset Upgrading from a previous version -\layout Standard +\end_layout +\begin_layout Standard If you are upgrading from a previous version of IPython, after doing the routine installation described above, you should call IPython with the -\family typewriter +\family typewriter -upgrade -\family default +\family default option the first time you run your new copy. This will automatically update your configuration directory while preserving copies of your old files. @@ -1229,78 +1367,85 @@ If you are upgrading from a previous version of IPython, after doing the made into the new files. It is a good idea to do this as there may be new options available in the new configuration files which you will not have. -\layout Standard +\end_layout +\begin_layout Standard Under Windows, if you don't know how to call python scripts with arguments from a command line, simply delete the old config directory and IPython will make a new one. Win2k and WinXP users will find it in -\family typewriter +\family typewriter C: -\backslash +\backslash Documents and Settings -\backslash +\backslash YourUserName -\backslash +\backslash _ipython -\family default +\family default , and Win 9x users under -\family typewriter +\family typewriter C: -\backslash +\backslash Program Files -\backslash +\backslash IPython -\backslash +\backslash _ipython. -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:good_config} -\end_inset +\end_inset \begin_inset OptArg -collapsed true - -\layout Standard +status collapsed +\begin_layout Standard Initial configuration \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash ldots -\end_inset +\end_layout + +\end_inset + +\end_layout -\end_inset +\end_inset Initial configuration of your environment -\layout Standard +\end_layout +\begin_layout Standard This section will help you set various things in your environment for your IPython sessions to be as efficient as possible. All of IPython's configuration information, along with several example files, is stored in a directory named by default -\family typewriter +\family typewriter $HOME/.ipython -\family default +\family default . You can change this by defining the environment variable -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default , or at runtime with the command line option -\family typewriter +\family typewriter -ipythondir -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard If all goes well, the first time you run IPython it should automatically create a user copy of the config directory for you, based on its builtin defaults. @@ -1308,18 +1453,18 @@ If all goes well, the first time you run IPython it should automatically system. The main file you will modify to configure IPython's behavior is called -\family typewriter +\family typewriter ipythonrc -\family default +\family default (with a -\family typewriter +\family typewriter .ini -\family default +\family default extension under Windows), included for reference in Sec. \begin_inset LatexCommand \ref{sec:ipytonrc-sample} -\end_inset +\end_inset . This file is very commented and has many variables you can change to suit @@ -1327,618 +1472,684 @@ ipythonrc \begin_inset LatexCommand \ref{sec:customization} -\end_inset +\end_inset . Here we discuss the basic things you will want to make sure things are working properly from the beginning. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:help-access} -\end_inset +\end_inset Access to the Python help system -\layout Standard +\end_layout +\begin_layout Standard This is true for Python in general (not just for IPython): you should have an environment variable called -\family typewriter +\family typewriter PYTHONDOCS -\family default +\family default pointing to the directory where your HTML Python documentation lives. In my system it's -\family typewriter +\family typewriter /usr/share/doc/python-docs-2.3.4/html -\family default +\family default , check your local details or ask your systems administrator. -\layout Standard +\end_layout +\begin_layout Standard This is the directory which holds the HTML version of the Python manuals. Unfortunately it seems that different Linux distributions package these files differently, so you may have to look around a bit. Below I show the contents of this directory on my system for reference: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter [html]> ls -\newline -about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat tut/ - about.html api/ doc/ icons/ inst/ mac/ ref/ style.css -\layout Standard +\newline +about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat + tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css +\end_layout +\begin_layout Standard You should really make sure this variable is correctly set so that Python's pydoc-based help system works. It is a powerful and convenient system with full access to the Python manuals and all modules accessible to you. -\layout Standard +\end_layout +\begin_layout Standard Under Windows it seems that pydoc finds the documentation automatically, so no extra setup appears necessary. -\layout Subsection +\end_layout +\begin_layout Subsection Editor -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter %edit -\family default +\family default command (and its alias -\family typewriter +\family typewriter %ed -\family default +\family default ) will invoke the editor set in your environment as -\family typewriter +\family typewriter EDITOR -\family default +\family default . If this variable is not set, it will default to -\family typewriter +\family typewriter vi -\family default +\family default under Linux/Unix and to -\family typewriter +\family typewriter notepad -\family default +\family default under Windows. You may want to set this variable properly and to a lightweight editor which doesn't take too long to start (that is, something other than a new instance of -\family typewriter +\family typewriter Emacs -\family default +\family default ). This way you can edit multi-line code quickly and with the power of a real editor right inside IPython. -\layout Standard +\end_layout +\begin_layout Standard If you are a dedicated -\family typewriter +\family typewriter Emacs -\family default +\family default user, you should set up the -\family typewriter +\family typewriter Emacs -\family default +\family default server so that new requests are handled by the original process. This means that almost no time is spent in handling the request (assuming an -\family typewriter +\family typewriter Emacs -\family default +\family default process is already running). For this to work, you need to set your -\family typewriter +\family typewriter EDITOR -\family default +\family default environment variable to -\family typewriter +\family typewriter 'emacsclient' -\family default +\family default . -\family typewriter +\family typewriter -\family default +\family default The code below, supplied by Francois Pinard, can then be used in your -\family typewriter +\family typewriter .emacs -\family default +\family default file to enable the server: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter (defvar server-buffer-clients) -\newline -(when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) -\newline +\newline +(when (and (fboundp 'server-start) (string-equal + (getenv "TERM") 'xterm)) +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset +\end_layout + +\end_inset -\SpecialChar ~ -\SpecialChar ~ +\InsetSpace ~ +\InsetSpace ~ (server-start) -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset +\end_layout + +\end_inset -\SpecialChar ~ -\SpecialChar ~ +\InsetSpace ~ +\InsetSpace ~ (defun fp-kill-server-with-buffer-routine () -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset +\end_layout + +\end_inset -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ (and server-buffer-clients (server-done))) -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset +\end_layout + +\end_inset -\SpecialChar ~ -\SpecialChar ~ +\InsetSpace ~ +\InsetSpace ~ (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine)) -\layout Standard +\end_layout +\begin_layout Standard You can also set the value of this editor via the commmand-line option '- -\family typewriter +\family typewriter editor' -\family default +\family default or in your -\family typewriter +\family typewriter ipythonrc -\family default +\family default file. This is useful if you wish to use specifically for IPython an editor different from your typical default (and for Windows users who tend to use fewer environment variables). -\layout Subsection +\end_layout +\begin_layout Subsection Color -\layout Standard +\end_layout +\begin_layout Standard The default IPython configuration has most bells and whistles turned on (they're pretty safe). But there's one that -\emph on +\emph on may -\emph default +\emph default cause problems on some systems: the use of color on screen for displaying information. This is very useful, since IPython can show prompts and exception tracebacks with various colors, display syntax-highlighted source code, and in general make it easier to visually parse information. -\layout Standard +\end_layout +\begin_layout Standard The following terminals seem to handle the color sequences fine: -\layout Itemize +\end_layout +\begin_layout Itemize Linux main text console, KDE Konsole, Gnome Terminal, E-term, rxvt, xterm. -\layout Itemize +\end_layout +\begin_layout Itemize CDE terminal (tested under Solaris). This one boldfaces light colors. -\layout Itemize +\end_layout +\begin_layout Itemize (X)Emacs buffers. See sec. \begin_inset LatexCommand \ref{sec:emacs} -\end_inset +\end_inset for more details on using IPython with (X)Emacs. -\layout Itemize +\end_layout +\begin_layout Itemize A Windows (XP/2k) command prompt -\emph on +\emph on with Gary Bishop's support extensions -\emph default +\emph default . - Gary's extensions are discussed in Sec.\SpecialChar ~ + Gary's extensions are discussed in Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sub:Under-Windows} -\end_inset +\end_inset . -\layout Itemize +\end_layout +\begin_layout Itemize A Windows (XP/2k) CygWin shell. Although some users have reported problems; it is not clear whether there is an issue for everyone or only under specific configurations. If you have full color support under cygwin, please post to the IPython mailing list so this issue can be resolved for all users. -\layout Standard +\end_layout +\begin_layout Standard These have shown problems: -\layout Itemize +\end_layout +\begin_layout Itemize Windows command prompt in WinXP/2k logged into a Linux machine via telnet or ssh. -\layout Itemize +\end_layout +\begin_layout Itemize Windows native command prompt in WinXP/2k, -\emph on +\emph on without -\emph default +\emph default Gary Bishop's extensions. Once Gary's readline library is installed, the normal WinXP/2k command prompt works perfectly. -\layout Standard +\end_layout +\begin_layout Standard Currently the following color schemes are available: -\layout Itemize +\end_layout +\begin_layout Itemize -\family typewriter +\family typewriter NoColor -\family default +\family default : uses no color escapes at all (all escapes are empty \begin_inset Quotes eld -\end_inset +\end_inset \begin_inset Quotes eld -\end_inset +\end_inset strings). This 'scheme' is thus fully safe to use in any terminal. -\layout Itemize +\end_layout +\begin_layout Itemize -\family typewriter +\family typewriter Linux -\family default +\family default : works well in Linux console type environments: dark background with light fonts. It uses bright colors for information, so it is difficult to read if you have a light colored background. -\layout Itemize +\end_layout +\begin_layout Itemize -\family typewriter +\family typewriter LightBG -\family default +\family default : the basic colors are similar to those in the -\family typewriter +\family typewriter Linux -\family default +\family default scheme but darker. It is easy to read in terminals with light backgrounds. -\layout Standard +\end_layout +\begin_layout Standard IPython uses colors for two main groups of things: prompts and tracebacks which are directly printed to the terminal, and the object introspection system which passes large sets of data through a pager. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Input/Output prompts and exception tracebacks -\layout Standard +\end_layout +\begin_layout Standard You can test whether the colored prompts and tracebacks work on your system interactively by typing -\family typewriter +\family typewriter '%colors Linux' -\family default +\family default at the prompt (use ' -\family typewriter +\family typewriter %colors LightBG' -\family default +\family default if your terminal has a light background). If the input prompt shows garbage like: -\newline +\newline -\family typewriter +\family typewriter [0;32mIn [[1;32m1[0;32m]: [0;00m -\family default +\family default -\newline +\newline instead of (in color) something like: -\newline +\newline -\family typewriter +\family typewriter In [1]: -\family default +\family default -\newline +\newline this means that your terminal doesn't properly handle color escape sequences. You can go to a 'no color' mode by typing ' -\family typewriter +\family typewriter %colors NoColor -\family default +\family default '. -\layout Standard +\end_layout +\begin_layout Standard You can try using a different terminal emulator program (Emacs users, see below). To permanently set your color preferences, edit the file -\family typewriter +\family typewriter $HOME/.ipython/ipythonrc -\family default +\family default and set the -\family typewriter +\family typewriter colors -\family default +\family default option to the desired value. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Object details (types, docstrings, source code, etc.) -\layout Standard +\end_layout +\begin_layout Standard IPython has a set of special functions for studying the objects you are working with, discussed in detail in Sec. \begin_inset LatexCommand \ref{sec:dyn-object-info} -\end_inset +\end_inset . But this system relies on passing information which is longer than your screen through a data pager, such as the common Unix -\family typewriter +\family typewriter less -\family default +\family default and -\family typewriter +\family typewriter more -\family default +\family default programs. In order to be able to see this information in color, your pager needs to be properly configured. I strongly recommend using -\family typewriter +\family typewriter less -\family default +\family default instead of -\family typewriter +\family typewriter more -\family default +\family default , as it seems that -\family typewriter +\family typewriter more -\family default +\family default simply can not understand colored text correctly. -\layout Standard +\end_layout +\begin_layout Standard In order to configure -\family typewriter +\family typewriter less -\family default +\family default as your default pager, do the following: -\layout Enumerate +\end_layout +\begin_layout Enumerate Set the environment -\family typewriter +\family typewriter PAGER -\family default +\family default variable to -\family typewriter +\family typewriter less -\family default +\family default . -\layout Enumerate +\end_layout +\begin_layout Enumerate Set the environment -\family typewriter +\family typewriter LESS -\family default +\family default variable to -\family typewriter +\family typewriter -r -\family default +\family default (plus any other options you always want to pass to -\family typewriter +\family typewriter less -\family default +\family default by default). This tells -\family typewriter +\family typewriter less -\family default +\family default to properly interpret control sequences, which is how color information is given to your terminal. -\layout Standard +\end_layout +\begin_layout Standard For the -\family typewriter +\family typewriter csh -\family default +\family default or -\family typewriter +\family typewriter tcsh -\family default +\family default shells, add to your -\family typewriter +\family typewriter ~/.cshrc -\family default +\family default file the lines: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter setenv PAGER less -\newline +\newline setenv LESS -r -\layout Standard +\end_layout +\begin_layout Standard There is similar syntax for other Unix shells, look at your system documentation for details. -\layout Standard +\end_layout +\begin_layout Standard If you are on a system which lacks proper data pagers (such as Windows), IPython will use a very limited builtin pager. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:emacs} -\end_inset +\end_inset (X)Emacs configuration -\layout Standard +\end_layout +\begin_layout Standard Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, currently (X)Emacs and IPython get along very well. -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Important note: -\series default +\series default You will need to use a recent enough version of -\family typewriter +\family typewriter python-mode.el -\family default +\family default , along with the file -\family typewriter +\family typewriter ipython.el -\family default +\family default . You can check that the version you have of -\family typewriter +\family typewriter python-mode.el -\family default +\family default is new enough by either looking at the revision number in the file itself, or asking for it in (X)Emacs via -\family typewriter +\family typewriter M-x py-version -\family default +\family default . Versions 4.68 and newer contain the necessary fixes for proper IPython support. -\layout Standard +\end_layout +\begin_layout Standard The file -\family typewriter +\family typewriter ipython.el -\family default +\family default is included with the IPython distribution, in the documentation directory (where this manual resides in PDF and HTML formats). -\layout Standard +\end_layout +\begin_layout Standard Once you put these files in your Emacs path, all you need in your -\family typewriter +\family typewriter .emacs -\family default +\family default file is: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code (require 'ipython) -\layout Standard +\end_layout +\begin_layout Standard This should give you full support for executing code snippets via IPython, opening IPython as your Python shell via -\family typewriter -C-c\SpecialChar ~ +\family typewriter +C-c\InsetSpace ~ ! -\family default +\family default , etc. -\layout Standard +\end_layout +\begin_layout Standard If you happen to get garbage instead of colored prompts as described in the previous section, you may need to set also in your -\family typewriter +\family typewriter .emacs -\family default +\family default file: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code (setq ansi-color-for-comint-mode t) -\layout Subsubsection* +\end_layout +\begin_layout Subsubsection* Notes -\layout Itemize +\end_layout +\begin_layout Itemize There is one caveat you should be aware of: you must start the IPython shell -\emph on +\emph on before -\emph default +\emph default attempting to execute any code regions via -\family typewriter -C-c\SpecialChar ~ +\family typewriter +C-c\InsetSpace ~ | -\family default +\family default . Simply type -\family typewriter -C-c\SpecialChar ~ +\family typewriter +C-c\InsetSpace ~ ! -\family default +\family default to start IPython before passing any code regions to the interpreter, and you shouldn't experience any problems. -\newline -This is due to a bug in Python itself, which has been fixed for Python 2.3, - but exists as of Python 2.2.2 (reported as SF bug [ 737947 ]). -\layout Itemize +\newline +This is due to a bug in Python itself, + which has been fixed for Python 2.3, but exists as of Python 2.2.2 (reported + as SF bug [ 737947 ]). +\end_layout +\begin_layout Itemize The (X)Emacs support is maintained by Alexander Schmolck, so all comments/reques ts should be directed to him through the IPython mailing lists. -\layout Itemize +\end_layout +\begin_layout Itemize This code is still somewhat experimental so it's a bit rough around the edges (although in practice, it works quite well). -\layout Itemize +\end_layout +\begin_layout Itemize Be aware that if you customize -\family typewriter +\family typewriter py-python-command -\family default +\family default previously, this value will override what -\family typewriter +\family typewriter ipython.el -\family default +\family default does (because loading the customization variables comes later). -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:quick_tips} -\end_inset +\end_inset Quick tips -\layout Standard +\end_layout +\begin_layout Standard IPython can be used as an improved replacement for the Python prompt, and for that you don't really need to read any more of this manual. But in this section we'll try to summarize a few tips on how to make the @@ -1946,105 +2157,109 @@ IPython can be used as an improved replacement for the Python prompt, and things you might miss in the rest of the manual (which is getting long). We'll give references to parts in the manual which provide more detail when appropriate. -\layout Standard +\end_layout +\begin_layout Standard The following article by Jeremy Jones provides an introductory tutorial about IPython: -\newline +\newline \begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html} -\end_inset +\end_inset -\layout Itemize +\end_layout +\begin_layout Itemize The TAB key. TAB-completion, especially for attributes, is a convenient way to explore the structure of any object you're dealing with. Simply type -\family typewriter +\family typewriter object_name. -\family default +\family default and a list of the object's attributes will be printed (see sec. \begin_inset LatexCommand \ref{sec:readline} -\end_inset +\end_inset for more). Tab completion also works on file and directory names, which combined with IPython's alias system allows you to do from within IPython many of the things you normally would need the system shell for. -\layout Itemize +\end_layout +\begin_layout Itemize Explore your objects. Typing -\family typewriter +\family typewriter object_name? -\family default +\family default will print all sorts of details about any object, including docstrings, function definition lines (for call arguments) and constructor details for classes. The magic commands -\family typewriter +\family typewriter %pdoc -\family default +\family default , -\family typewriter +\family typewriter %pdef -\family default +\family default , -\family typewriter +\family typewriter %psource -\family default +\family default and -\family typewriter +\family typewriter %pfile -\family default +\family default will respectively print the docstring, function definition line, full source code and the complete file for any object (when they can be found). If automagic is on (it is by default), you don't need to type the ' -\family typewriter +\family typewriter % -\family default +\family default ' explicitly. See sec. \begin_inset LatexCommand \ref{sec:dyn-object-info} -\end_inset +\end_inset for more. -\layout Itemize +\end_layout +\begin_layout Itemize The -\family typewriter +\family typewriter %run -\family default +\family default magic command allows you to run any python script and load all of its data directly into the interactive namespace. Since the file is re-read from disk each time, changes you make to it are reflected immediately (in contrast to the behavior of -\family typewriter +\family typewriter import -\family default +\family default ). I rarely use -\family typewriter +\family typewriter import -\family default +\family default for code I am testing, relying on -\family typewriter +\family typewriter %run -\family default +\family default instead. See sec. \begin_inset LatexCommand \ref{sec:magic} -\end_inset +\end_inset for more on this and other magic commands, or type the name of any magic command and ? to get details on it. @@ -2052,838 +2267,911 @@ import \begin_inset LatexCommand \ref{sec:dreload} -\end_inset +\end_inset for a recursive reload command. -\newline +\newline -\family typewriter +\family typewriter %run -\family default +\family default also has special flags for timing the execution of your scripts ( -\family typewriter +\family typewriter -t -\family default +\family default ) and for executing them under the control of either Python's -\family typewriter +\family typewriter pdb -\family default +\family default debugger ( -\family typewriter +\family typewriter -d -\family default +\family default ) or profiler ( -\family typewriter +\family typewriter -p -\family default +\family default ). With all of these, -\family typewriter +\family typewriter %run -\family default +\family default can be used as the main tool for efficient interactive development of code which you write in your editor of choice. -\layout Itemize +\end_layout +\begin_layout Itemize Use the Python debugger, -\family typewriter +\family typewriter pdb -\family default +\family default \begin_inset Foot -collapsed true - -\layout Standard +status collapsed +\begin_layout Standard Thanks to Christian Hart and Matthew Arnison for the suggestions leading to IPython's improved debugger and profiler support. -\end_inset +\end_layout + +\end_inset . The -\family typewriter +\family typewriter %pdb -\family default +\family default command allows you to toggle on and off the automatic invocation of an IPython-enhanced -\family typewriter +\family typewriter pdb -\family default +\family default debugger (with coloring, tab completion and more) at any uncaught exception. The advantage of this is that -\family typewriter +\family typewriter pdb -\family default +\family default starts -\emph on +\emph on inside -\emph default +\emph default the function where the exception occurred, with all data still available. You can print variables, see code, execute statements and even walk up and down the call stack to track down the true source of the problem (which often is many layers in the stack above where the exception gets triggered). -\newline -Running programs with -\family typewriter +\newline +Runn +ing programs with +\family typewriter %run -\family default +\family default and pdb active can be an efficient to develop and debug code, in many cases eliminating the need for -\family typewriter +\family typewriter print -\family default +\family default statements or external debugging tools. I often simply put a -\family typewriter +\family typewriter 1/0 -\family default +\family default in a place where I want to take a look so that pdb gets called, quickly view whatever variables I need to or test various pieces of code and then remove the -\family typewriter +\family typewriter 1/0 -\family default +\family default . -\newline +\newline Note also that ` -\family typewriter +\family typewriter %run -d -\family default +\family default ' activates -\family typewriter +\family typewriter pdb -\family default +\family default and automatically sets initial breakpoints for you to step through your code, watch variables, etc. - See Sec.\SpecialChar ~ + See Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:cache_output} -\end_inset +\end_inset for details. -\layout Itemize +\end_layout +\begin_layout Itemize Use the output cache. All output results are automatically stored in a global dictionary named -\family typewriter +\family typewriter Out -\family default +\family default and variables named -\family typewriter +\family typewriter _1 -\family default +\family default , -\family typewriter +\family typewriter _2 -\family default +\family default , etc. alias them. For example, the result of input line 4 is available either as -\family typewriter +\family typewriter Out[4] -\family default +\family default or as -\family typewriter +\family typewriter _4 -\family default +\family default . Additionally, three variables named -\family typewriter +\family typewriter _ -\family default +\family default , -\family typewriter +\family typewriter __ -\family default +\family default and -\family typewriter +\family typewriter ___ -\family default +\family default are always kept updated with the for the last three results. This allows you to recall any previous result and further use it for new calculations. - See Sec.\SpecialChar ~ + See Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:cache_output} -\end_inset +\end_inset for more. -\layout Itemize +\end_layout +\begin_layout Itemize Put a ' -\family typewriter +\family typewriter ; -\family default +\family default ' at the end of a line to supress the printing of output. This is useful when doing calculations which generate long output you are not interested in seeing. The -\family typewriter +\family typewriter _* -\family default +\family default variables and the -\family typewriter +\family typewriter Out[] -\family default +\family default list do get updated with the contents of the output, even if it is not printed. You can thus still access the generated results this way for further processing. -\layout Itemize +\end_layout +\begin_layout Itemize A similar system exists for caching input. All input is stored in a global list called -\family typewriter +\family typewriter In -\family default +\family default , so you can re-execute lines 22 through 28 plus line 34 by typing -\family typewriter +\family typewriter 'exec In[22:29]+In[34]' -\family default +\family default (using Python slicing notation). If you need to execute the same set of lines often, you can assign them to a macro with the -\family typewriter +\family typewriter %macro -\family default +\family default -\family typewriter +\family typewriter function. -\family default +\family default See sec. \begin_inset LatexCommand \ref{sec:cache_input} -\end_inset +\end_inset for more. -\layout Itemize +\end_layout +\begin_layout Itemize Use your input history. The -\family typewriter +\family typewriter %hist -\family default +\family default command can show you all previous input, without line numbers if desired (option -\family typewriter +\family typewriter -n -\family default +\family default ) so you can directly copy and paste code either back in IPython or in a text editor. You can also save all your history by turning on logging via -\family typewriter +\family typewriter %logstart -\family default +\family default ; these logs can later be either reloaded as IPython sessions or used as code for your programs. -\layout Itemize +\end_layout +\begin_layout Itemize Define your own system aliases. Even though IPython gives you access to your system shell via the -\family typewriter +\family typewriter ! -\family default +\family default prefix, it is convenient to have aliases to the system commands you use most often. This allows you to work seamlessly from inside IPython with the same commands you are used to in your system shell. -\newline -IPython comes with some pre-defined aliases and a complete system for changing - directories, both via a stack (see -\family typewriter +\newline +IPython comes with some pre-defined + aliases and a complete system for changing directories, both via a stack + (see +\family typewriter %pushd -\family default +\family default , -\family typewriter +\family typewriter %popd -\family default +\family default and -\family typewriter +\family typewriter %dhist -\family default +\family default ) and via direct -\family typewriter +\family typewriter %cd -\family default +\family default . The latter keeps a history of visited directories and allows you to go to any previously visited one. -\layout Itemize +\end_layout +\begin_layout Itemize Use Python to manipulate the results of system commands. The ` -\family typewriter +\family typewriter !! -\family default +\family default ' special syntax, and the -\family typewriter +\family typewriter %sc -\family default +\family default and -\family typewriter +\family typewriter %sx -\family default +\family default magic commands allow you to capture system output into Python variables. -\layout Itemize +\end_layout +\begin_layout Itemize Expand python variables when calling the shell (either via -\family typewriter +\family typewriter `!' -\family default +\family default and -\family typewriter +\family typewriter `!!' -\family default +\family default or via aliases) by prepending a -\family typewriter +\family typewriter $ -\family default +\family default in front of them. You can also expand complete python expressions. - See sec.\SpecialChar ~ + See sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sub:System-shell-access} -\end_inset +\end_inset for more. -\layout Itemize +\end_layout +\begin_layout Itemize Use profiles to maintain different configurations (modules to load, function definitions, option settings) for particular tasks. You can then have customized versions of IPython for specific purposes. - See sec.\SpecialChar ~ + See sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:profiles} -\end_inset +\end_inset for more. -\layout Itemize +\end_layout +\begin_layout Itemize Embed IPython in your programs. A few lines of code are enough to load a complete IPython inside your own programs, giving you the ability to work with your data interactively after automatic processing has been completed. - See sec.\SpecialChar ~ + See sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:embed} -\end_inset +\end_inset for more. -\layout Itemize +\end_layout +\begin_layout Itemize Use the Python profiler. When dealing with performance issues, the -\family typewriter +\family typewriter %run -\family default +\family default command with a -\family typewriter +\family typewriter -p -\family default +\family default option allows you to run complete programs under the control of the Python profiler. The -\family typewriter +\family typewriter %prun -\family default +\family default command does a similar job for single Python expressions (like function calls). -\layout Itemize +\end_layout +\begin_layout Itemize Use the IPython.demo.Demo class to load any Python script as an interactive demo. With a minimal amount of simple markup, you can control the execution of the script, stopping as needed. - See sec.\SpecialChar ~ + See sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:interactive-demos} -\end_inset +\end_inset for more. -\layout Subsection +\end_layout +\begin_layout Subsection Source code handling tips -\layout Standard +\end_layout +\begin_layout Standard IPython is a line-oriented program, without full control of the terminal. Therefore, it doesn't support true multiline editing. However, it has a number of useful tools to help you in dealing effectively with more complex editing. -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter %edit -\family default +\family default command gives a reasonable approximation of multiline editing, by invoking your favorite editor on the spot. IPython will execute the code you type in there as if it were typed interactive ly. Type -\family typewriter +\family typewriter %edit? -\family default +\family default for the full details on the edit command. -\layout Standard +\end_layout +\begin_layout Standard If you have typed various commands during a session, which you'd like to reuse, IPython provides you with a number of tools. Start by using -\family typewriter +\family typewriter %hist -\family default +\family default to see your input history, so you can see the line numbers of all input. Let us say that you'd like to reuse lines 10 through 20, plus lines 24 and 28. All the commands below can operate on these with the syntax -\layout LyX-Code +\end_layout +\begin_layout LyX-Code %command 10-20 24 28 -\layout Standard +\end_layout +\begin_layout Standard where the command given can be: -\layout Itemize +\end_layout +\begin_layout Itemize -\family typewriter +\family typewriter %macro -\family default +\family default : this stores the lines into a variable which, when called at the prompt, re-executes the input. Macros can be edited later using -\family typewriter +\family typewriter `%edit macroname -\family default +\family default ', and they can be stored persistently across sessions with ` -\family typewriter +\family typewriter %store macroname -\family default +\family default ' (the storage system is per-profile). The combination of quick macros, persistent storage and editing, allows you to easily refine quick-and-dirty interactive input into permanent utilities , always available both in IPython and as files for general reuse. -\layout Itemize +\end_layout +\begin_layout Itemize -\family typewriter +\family typewriter %edit -\family default +\family default : this will open a text editor with those lines pre-loaded for further modificat ion. It will then execute the resulting file's contents as if you had typed it at the prompt. -\layout Itemize +\end_layout +\begin_layout Itemize -\family typewriter +\family typewriter %save -\family default +\family default : this saves the lines directly to a named file on disk. -\layout Standard +\end_layout +\begin_layout Standard While -\family typewriter +\family typewriter %macro -\family default +\family default saves input lines into memory for interactive re-execution, sometimes you'd like to save your input directly to a file. The -\family typewriter +\family typewriter %save -\family default +\family default magic does this: its input sytnax is the same as -\family typewriter +\family typewriter %macro -\family default +\family default , but it saves your input directly to a Python file. Note that the -\family typewriter +\family typewriter %logstart -\family default +\family default command also saves input, but it logs -\emph on +\emph on all -\emph default +\emph default input to disk (though you can temporarily suspend it and reactivate it with -\family typewriter +\family typewriter %logoff/%logon -\family default +\family default ); -\family typewriter +\family typewriter %save -\family default +\family default allows you to select which lines of input you need to save. -\layout Subsubsection* +\end_layout +\begin_layout Subsubsection* Lightweight 'version control' -\layout Standard +\end_layout +\begin_layout Standard When you call -\family typewriter +\family typewriter %edit -\family default +\family default with no arguments, IPython opens an empty editor with a temporary file, and it returns the contents of your editing session as a string variable. Thanks to IPython's output caching mechanism, this is automatically stored: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [1]: %edit -\layout LyX-Code +\end_layout +\begin_layout LyX-Code IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py -\layout LyX-Code +\end_layout +\begin_layout LyX-Code Editing... done. Executing edited code... -\layout LyX-Code +\end_layout +\begin_layout LyX-Code hello - this is a temporary file -\layout LyX-Code +\end_layout +\begin_layout LyX-Code Out[1]: "print 'hello - this is a temporary file' -\backslash +\backslash n" -\layout Standard +\end_layout +\begin_layout Standard Now, if you call -\family typewriter +\family typewriter `%edit -p' -\family default +\family default , IPython tries to open an editor with the same data as the last time you used -\family typewriter +\family typewriter %edit -\family default +\family default . So if you haven't used -\family typewriter +\family typewriter %edit -\family default +\family default in the meantime, this same contents will reopen; however, it will be done in a -\emph on +\emph on new file -\emph default +\emph default . This means that if you make changes and you later want to find an old version, you can always retrieve it by using its output number, via -\family typewriter +\family typewriter `%edit _NN' -\family default +\family default , where -\family typewriter +\family typewriter NN -\family default +\family default is the number of the output prompt. -\layout Standard +\end_layout +\begin_layout Standard Continuing with the example above, this should illustrate this idea: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [2]: edit -p -\layout LyX-Code +\end_layout +\begin_layout LyX-Code IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py -\layout LyX-Code +\end_layout +\begin_layout LyX-Code Editing... done. Executing edited code... -\layout LyX-Code +\end_layout +\begin_layout LyX-Code hello - now I made some changes -\layout LyX-Code +\end_layout +\begin_layout LyX-Code Out[2]: "print 'hello - now I made some changes' -\backslash +\backslash n" -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [3]: edit _1 -\layout LyX-Code +\end_layout +\begin_layout LyX-Code IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py -\layout LyX-Code +\end_layout +\begin_layout LyX-Code Editing... done. Executing edited code... -\layout LyX-Code +\end_layout +\begin_layout LyX-Code hello - this is a temporary file -\layout LyX-Code +\end_layout +\begin_layout LyX-Code IPython version control at work :) -\layout LyX-Code +\end_layout +\begin_layout LyX-Code Out[3]: "print 'hello - this is a temporary file' -\backslash +\backslash nprint 'IPython version control at work :)' -\backslash +\backslash n" -\layout Standard +\end_layout +\begin_layout Standard This section was written after a contribution by Alexander Belchenko on the IPython user list. -\layout LyX-Code +\end_layout -\layout Subsection +\begin_layout LyX-Code +\end_layout + +\begin_layout Subsection Effective logging -\layout Standard +\end_layout +\begin_layout Standard A very useful suggestion sent in by Robert Kern follows: -\layout Standard +\end_layout +\begin_layout Standard I recently happened on a nifty way to keep tidy per-project log files. I made a profile for my project (which is called "parkfield"). -\layout LyX-Code +\end_layout +\begin_layout LyX-Code include ipythonrc -\layout LyX-Code +\end_layout +\begin_layout LyX-Code # cancel earlier logfile invocation: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code logfile '' -\layout LyX-Code +\end_layout +\begin_layout LyX-Code execute import time -\layout LyX-Code +\end_layout +\begin_layout LyX-Code execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate' -\layout LyX-Code +\end_layout +\begin_layout LyX-Code execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d')) -\layout Standard +\end_layout +\begin_layout Standard I also added a shell alias for convenience: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code alias parkfield="ipython -pylab -profile parkfield" -\layout Standard +\end_layout +\begin_layout Standard Now I have a nice little directory with everything I ever type in, organized by project and date. -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Contribute your own: -\series default +\series default If you have your own favorite tip on using IPython efficiently for a certain task (especially things which can't be done in the normal Python interpreter), don't hesitate to send it! -\layout Section +\end_layout +\begin_layout Section Command-line use -\layout Standard +\end_layout +\begin_layout Standard You start IPython with the command: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter $ ipython [options] files -\layout Standard +\end_layout +\begin_layout Standard If invoked with no options, it executes all the files listed in sequence and drops you into the interpreter while still acknowledging any options you may have set in your ipythonrc file. This behavior is different from standard Python, which when called as -\family typewriter +\family typewriter python -i -\family default +\family default will only execute one file and ignore your configuration setup. -\layout Standard +\end_layout +\begin_layout Standard Please note that some of the configuration options are not available at the command line, simply because they are not practical here. Look into your ipythonrc configuration file for details on those. This file typically installed in the -\family typewriter +\family typewriter $HOME/.ipython -\family default +\family default directory. For Windows users, -\family typewriter +\family typewriter $HOME -\family default +\family default resolves to -\family typewriter +\family typewriter C: -\backslash +\backslash -\backslash +\backslash Documents and Settings -\backslash +\backslash -\backslash +\backslash YourUserName -\family default +\family default in most instances. In the rest of this text, we will refer to this directory as -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default . -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:threading-opts} -\end_inset +\end_inset Special Threading Options -\layout Standard +\end_layout +\begin_layout Standard The following special options are ONLY valid at the beginning of the command line, and not later. This is because they control the initial- ization of ipython itself, before the normal option-handling mechanism is active. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --gthread,\SpecialChar ~ --qthread,\SpecialChar ~ --wthread,\SpecialChar ~ +\family typewriter +\series bold +-gthread,\InsetSpace ~ +-qthread,\InsetSpace ~ +-q4thread,\InsetSpace ~ +-wthread,\InsetSpace ~ -pylab: -\family default -\series default +\family default +\series default Only -\emph on +\emph on one -\emph default +\emph default of these can be given, and it can only be given as the first option passed to IPython (it will have no effect in any other position). - They provide threading support for the GTK Qt and WXPython toolkits, and - for the matplotlib library. -\layout List -\labelwidthstring 00.00.0000 + They provide threading support for the GTK, Qt (versions 3 and 4) and WXPython + toolkits, and for the matplotlib library. +\end_layout -\SpecialChar ~ - With any of the first three options, IPython starts running a separate - thread for the graphical toolkit's operation, so that you can open and - control graphical elements from within an IPython command line, without - blocking. - All three provide essentially the same functionality, respectively for - GTK, QT and WXWidgets (via their Python interfaces). -\layout List +\begin_layout List \labelwidthstring 00.00.0000 +\InsetSpace ~ + With any of the first four options, IPython starts running a separate thread + for the graphical toolkit's operation, so that you can open and control + graphical elements from within an IPython command line, without blocking. + All four provide essentially the same functionality, respectively for GTK, + Qt3, Qt4 and WXWidgets (via their Python interfaces). +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ Note that with -\family typewriter +\family typewriter -wthread -\family default +\family default , you can additionally use the -wxversion option to request a specific version of wx to be used. This requires that you have the -\family typewriter +\family typewriter wxversion -\family default +\family default Python module installed, which is part of recent wxPython distributions. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ If -\family typewriter +\family typewriter -pylab -\family default +\family default is given, IPython loads special support for the mat plotlib library ( \begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net} -\end_inset +\end_inset ), allowing interactive usage of any of its backends as defined in the user's -\family typewriter +\family typewriter ~/.matplotlib/matplotlibrc -\family default +\family default file. It automatically activates GTK, Qt or WX threading for IPyhton if the choice of matplotlib backend requires it. It also modifies the -\family typewriter +\family typewriter %run -\family default +\family default command to correctly execute (without blocking) any matplotlib-based script which calls -\family typewriter +\family typewriter show() -\family default +\family default at the end. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -tk -\family default -\series default +\family default +\series default The -\family typewriter --g/q/wthread -\family default +\family typewriter +-g/q/q4/wthread +\family default options, and -\family typewriter +\family typewriter -pylab -\family default - (if matplotlib is configured to use GTK, Qt or WX), will normally block - Tk graphical interfaces. +\family default + (if matplotlib is configured to use GTK, Qt3, Qt4 or WX), will normally + block Tk graphical interfaces. This means that when either GTK, Qt or WX threading is active, any attempt to open a Tk GUI will result in a dead window, and possibly cause the Python interpreter to crash. An extra option, -\family typewriter +\family typewriter -tk -\family default +\family default , is available to address this issue. It can -\emph on +\emph on only -\emph default +\emph default be given as a -\emph on +\emph on second -\emph default +\emph default option after any of the above ( -\family typewriter +\family typewriter -gthread -\family default +\family default , -\family typewriter +\family typewriter -wthread -\family default +\family default or -\family typewriter +\family typewriter -pylab -\family default +\family default ). -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ If -\family typewriter +\family typewriter -tk -\family default +\family default is given, IPython will try to coordinate Tk threading with GTK, Qt or WX. This is however potentially unreliable, and you will have to test on your platform and Python configuration to determine whether it works for you. @@ -2893,265 +3181,281 @@ second caused random crashes and lockups of the Python interpreter. Under other operating systems (Mac OSX and Windows), you'll need to try it to find out, since currently no user reports are available. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ There is unfortunately no way for IPython to determine at run time whether -\family typewriter +\family typewriter -tk -\family default +\family default will work reliably or not, so you will need to do some experiments before relying on it for regular work. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:cmd-line-opts} -\end_inset +\end_inset Regular Options -\layout Standard +\end_layout +\begin_layout Standard After the above threading options have been given, regular options can follow in any order. All options can be abbreviated to their shortest non-ambiguous form and are case-sensitive. One or two dashes can be used. Some options have an alternate short form, indicated after a -\family typewriter +\family typewriter | -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard Most options can also be set from your ipythonrc configuration file. See the provided example for more details on what the options do. Options given at the command line override the values set in the ipythonrc file. -\layout Standard +\end_layout +\begin_layout Standard All options with a -\family typewriter +\family typewriter [no] -\family default +\family default prepended can be specified in negated form ( -\family typewriter +\family typewriter -nooption -\family default +\family default instead of -\family typewriter +\family typewriter -option -\family default +\family default ) to turn the feature off. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -help -\family default -\series default +\family default +\series default : print a help message and exit. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -pylab: -\family default -\series default +\family default +\series default this can -\emph on +\emph on only -\emph default +\emph default be given as the -\emph on +\emph on first -\emph default +\emph default option passed to IPython (it will have no effect in any other position). It adds special support for the matplotlib library ( \begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net} -\end_inset +\end_inset ), allowing interactive usage of any of its backends as defined in the user's -\family typewriter +\family typewriter .matplotlibrc -\family default +\family default file. It automatically activates GTK or WX threading for IPyhton if the choice of matplotlib backend requires it. It also modifies the -\family typewriter +\family typewriter %run -\family default +\family default command to correctly execute (without blocking) any matplotlib-based script which calls -\family typewriter +\family typewriter show() -\family default +\family default at the end. - See Sec.\SpecialChar ~ + See Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:matplotlib-support} -\end_inset +\end_inset for more details. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -autocall : -\family default -\series default +\family default +\series default Make IPython automatically call any callable object even if you didn't type explicit parentheses. For example, `str 43' becomes `str(43)' automatically. The value can be `0' to disable the feature, `1' for -\emph on +\emph on smart -\emph default +\emph default autocall, where it is not applied if there are no more arguments on the line, and `2' for -\emph on +\emph on full -\emph default +\emph default autocall, where all callable objects are automatically called (even if no arguments are present). The default is `1'. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]autoindent: -\family default -\series default +\family default +\series default Turn automatic indentation on/off. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]automagic -\series default +\series default : -\family default +\family default make magic commands automatic (without needing their first character to be -\family typewriter +\family typewriter % -\family default +\family default ). Type -\family typewriter +\family typewriter %magic -\family default +\family default at the IPython prompt for more information. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]autoedit_syntax: -\family default -\series default +\family default +\series default When a syntax error occurs after editing a file, automatically open the file to the trouble causing line for convenient fixing. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]banner -\series default +\series default : -\family default +\family default Print the initial information banner (default on). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --c\SpecialChar ~ +\family typewriter +\series bold +-c\InsetSpace ~ : -\family default -\series default +\family default +\series default execute the given command string, and set sys.argv to -\family typewriter +\family typewriter ['c'] -\family default +\family default . This is similar to the -\family typewriter +\family typewriter -c -\family default +\family default option in the normal Python interpreter. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --cache_size|cs\SpecialChar ~ +\family typewriter +\series bold +-cache_size|cs\InsetSpace ~ -\series default +\series default : -\family default +\family default size of the output cache (maximum number of entries to hold in memory). The default is 1000, you can change it permanently in your config file. Setting it to 0 completely disables the caching system, and the minimum value accepted is 20 (if you provide a value less than 20, it is reset to 0 and a warning is issued) This limit is defined because otherwise you'll spend more time re-flushing a too small cache than working. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -classic|cl -\series default +\series default : -\family default +\family default Gives IPython a similar feel to the classic Python prompt. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --colors\SpecialChar ~ +\family typewriter +\series bold +-colors\InsetSpace ~ : -\family default -\series default +\family default +\series default Color scheme for prompts and exception reporting. Currently implemented: NoColor, Linux and LightBG. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]color_info: -\family default -\series default +\family default +\series default IPython can display information about objects via a set of functions, and optionally can use colors for this, syntax highlighting source code and various other elements. @@ -3161,510 +3465,539 @@ full works for you. As a reference, the 'less' pager supplied with Mandrake 8.2 works ok, but that in RedHat 7.2 doesn't. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ Test it and turn it on permanently if it works with your system. The magic function -\family typewriter +\family typewriter %color_info -\family default +\family default allows you to toggle this interactively for testing. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]debug -\family default -\series default +\family default +\series default : Show information about the loading process. Very useful to pin down problems with your configuration files or to get details about session restores. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]deep_reload -\series default +\series default : -\family default +\family default IPython can use the -\family typewriter +\family typewriter deep_reload -\family default +\family default module which reloads changes in modules recursively (it replaces the -\family typewriter +\family typewriter reload() -\family default +\family default function, so you don't need to change anything to use it). -\family typewriter +\family typewriter deep_reload() -\family default +\family default forces a full reload of modules whose code may have changed, which the default -\family typewriter +\family typewriter reload() -\family default +\family default function does not. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ When deep_reload is off, IPython will use the normal -\family typewriter +\family typewriter reload() -\family default +\family default , but deep_reload will still be available as -\family typewriter +\family typewriter dreload() -\family default +\family default . This feature is off by default [which means that you have both normal -\family typewriter +\family typewriter reload() -\family default +\family default and -\family typewriter +\family typewriter dreload() -\family default +\family default ]. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --editor\SpecialChar ~ +\family typewriter +\series bold +-editor\InsetSpace ~ -\family default -\series default +\family default +\series default : Which editor to use with the -\family typewriter +\family typewriter %edit -\family default +\family default command. By default, IPython will honor your -\family typewriter +\family typewriter EDITOR -\family default +\family default environment variable (if not set, vi is the Unix default and notepad the Windows one). Since this editor is invoked on the fly by IPython and is meant for editing small code snippets, you may want to use a small, lightweight editor here (in case your default -\family typewriter +\family typewriter EDITOR -\family default +\family default is something like Emacs). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --ipythondir\SpecialChar ~ +\family typewriter +\series bold +-ipythondir\InsetSpace ~ -\series default +\series default : -\family default +\family default name of your IPython configuration directory -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default . This can also be specified through the environment variable -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default . -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -log|l -\family default -\series default +\family default +\series default : generate a log file of all input. The file is named -\family typewriter +\family typewriter ipython_log.py -\family default +\family default in your current directory (which prevents logs from multiple IPython sessions from trampling each other). You can use this to later restore a session by loading your logfile as a file to be executed with option -\family typewriter +\family typewriter -logplay -\family default +\family default (see below). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --logfile|lf\SpecialChar ~ +\family typewriter +\series bold +-logfile|lf\InsetSpace ~ -\series default +\series default : -\family default +\family default specify the name of your logfile. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --logplay|lp\SpecialChar ~ +\family typewriter +\series bold +-logplay|lp\InsetSpace ~ -\series default +\series default : -\family default +\family default you can replay a previous log. For restoring a session as close as possible to the state you left it in, use this option (don't just run the logfile). With -\family typewriter +\family typewriter -logplay -\family default +\family default , IPython will try to reconstruct the previous working environment in full, not just execute the commands in the logfile. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ When a session is restored, logging is automatically turned on again with the name of the logfile it was invoked with (it is read from the log header). So once you've turned logging on for a session, you can quit IPython and reload it as many times as you want and it will continue to log its history and restore from the beginning every time. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ Caveats: there are limitations in this option. The history variables -\family typewriter +\family typewriter _i* -\family default +\family default , -\family typewriter +\family typewriter _* -\family default +\family default and -\family typewriter +\family typewriter _dh -\family default +\family default don't get restored properly. In the future we will try to implement full session saving by writing and retrieving a 'snapshot' of the memory state of IPython. But our first attempts failed because of inherent limitations of Python's Pickle module, so this may have to wait. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]messages -\series default +\series default : -\family default +\family default Print messages which IPython collects about its startup process (default on). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]pdb -\family default -\series default +\family default +\series default : Automatically call the pdb debugger after every uncaught exception. If you are used to debugging using pdb, this puts you automatically inside of it after any call (either in IPython or in code called by it) which triggers an exception which goes uncaught. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]pprint -\series default +\series default : -\family default +\family default ipython can optionally use the pprint (pretty printer) module for displaying results. pprint tends to give a nicer display of nested data structures. If you like it, you can turn it on permanently in your config file (default off). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -profile|p -\series default +\series default : -\family default +\family default assume that your config file is -\family typewriter +\family typewriter ipythonrc- -\family default +\family default (looks in current dir first, then in -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default ). This is a quick way to keep and load multiple config files for different tasks, especially if you use the include option of config files. You can keep a basic -\family typewriter +\family typewriter IPYTHONDIR/ipythonrc -\family default +\family default file and then have other 'profiles' which include this one and load extra things for particular tasks. For example: -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\SpecialChar ~ +\family typewriter +\InsetSpace ~ -\family default +\family default 1. -\family typewriter +\family typewriter $HOME/.ipython/ipythonrc -\family default +\family default : load basic things you always want. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\SpecialChar ~ +\family typewriter +\InsetSpace ~ -\family default +\family default 2. -\family typewriter +\family typewriter $HOME/.ipython/ipythonrc-math -\family default +\family default : load (1) and basic math-related modules. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\SpecialChar ~ +\family typewriter +\InsetSpace ~ -\family default +\family default 3. -\family typewriter +\family typewriter $HOME/.ipython/ipythonrc-numeric -\family default +\family default : load (1) and Numeric and plotting modules. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ Since it is possible to create an endless loop by having circular file inclusions, IPython will stop if it reaches 15 recursive inclusions. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --prompt_in1|pi1\SpecialChar ~ +\family typewriter +\series bold +-prompt_in1|pi1\InsetSpace ~ : -\family default -\series default +\family default +\series default Specify the string used for input prompts. Note that if you are using numbered prompts, the number is represented with a ' -\backslash +\backslash #' in the string. Don't forget to quote strings with spaces embedded in them. Default: ' -\family typewriter -In\SpecialChar ~ +\family typewriter +In\InsetSpace ~ [ -\backslash +\backslash #]: -\family default +\family default '. - Sec.\SpecialChar ~ + Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:prompts} -\end_inset +\end_inset discusses in detail all the available escapes to customize your prompts. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --prompt_in2|pi2\SpecialChar ~ +\family typewriter +\series bold +-prompt_in2|pi2\InsetSpace ~ : -\family default -\series default +\family default +\series default Similar to the previous option, but used for the continuation prompts. The special sequence ' -\family typewriter +\family typewriter -\backslash +\backslash D -\family default +\family default ' is similar to ' -\family typewriter +\family typewriter -\backslash +\backslash # -\family default +\family default ', but with all digits replaced dots (so you can have your continuation prompt aligned with your input prompt). Default: ' -\family typewriter -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\family typewriter +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ . -\backslash +\backslash D.: -\family default +\family default ' (note three spaces at the start for alignment with ' -\family typewriter -In\SpecialChar ~ +\family typewriter +In\InsetSpace ~ [ -\backslash +\backslash #] -\family default +\family default '). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --prompt_out|po\SpecialChar ~ +\family typewriter +\series bold +-prompt_out|po\InsetSpace ~ : -\family default -\series default +\family default +\series default String used for output prompts, also uses numbers like -\family typewriter +\family typewriter prompt_in1 -\family default +\family default . Default: ' -\family typewriter +\family typewriter Out[ -\backslash +\backslash #]: -\family default +\family default ' -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -quick -\family default -\series default +\family default +\series default : start in bare bones mode (no config file loaded). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --rcfile\SpecialChar ~ +\family typewriter +\series bold +-rcfile\InsetSpace ~ -\series default +\series default : -\family default +\family default name of your IPython resource configuration file. Normally IPython loads ipythonrc (from current directory) or -\family typewriter +\family typewriter IPYTHONDIR/ipythonrc -\family default +\family default . -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ If the loading of your config file fails, IPython starts with a bare bones configuration (no modules loaded at all). -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -[no]readline -\family default -\series default +\family default +\series default : use the readline library, which is needed to support name completion and command history, among other things. It is enabled by default, but may cause problems for users of X/Emacs in Python comint or shell buffers. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ Note that X/Emacs 'eterm' buffers (opened with -\family typewriter -M-x\SpecialChar ~ +\family typewriter +M-x\InsetSpace ~ term -\family default +\family default ) support IPython's readline and syntax coloring fine, only 'emacs' ( -\family typewriter -M-x\SpecialChar ~ +\family typewriter +M-x\InsetSpace ~ shell -\family default +\family default and -\family typewriter -C-c\SpecialChar ~ +\family typewriter +C-c\InsetSpace ~ ! -\family default +\family default ) buffers do not. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --screen_length|sl\SpecialChar ~ +\family typewriter +\series bold +-screen_length|sl\InsetSpace ~ -\series default +\series default : -\family default +\family default number of lines of your screen. This is used to control printing of very long strings. Strings longer than this number of lines will be sent through a pager instead of directly printed. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ The default value for this is 0, which means IPython will auto-detect your screen size every time it needs to print certain potentially long strings (this doesn't change the behavior of the 'print' keyword, it's only triggered @@ -3672,152 +4005,165 @@ C-c\SpecialChar ~ If for some reason this isn't working well (it needs curses support), specify it yourself. Otherwise don't change the default. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --separate_in|si\SpecialChar ~ +\family typewriter +\series bold +-separate_in|si\InsetSpace ~ -\series default +\series default : -\family default +\family default separator before input prompts. Default: ' -\family typewriter +\family typewriter -\backslash +\backslash n -\family default +\family default ' -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --separate_out|so\SpecialChar ~ +\family typewriter +\series bold +-separate_out|so\InsetSpace ~ -\family default -\series default +\family default +\series default : separator before output prompts. Default: nothing. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --separate_out2|so2\SpecialChar ~ +\family typewriter +\series bold +-separate_out2|so2\InsetSpace ~ -\series default +\series default : -\family default +\family default separator after output prompts. Default: nothing. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ - For these three options, use the value 0 to specify no separator. -\layout List +\begin_layout List \labelwidthstring 00.00.0000 +\InsetSpace ~ + For these three options, use the value 0 to specify no separator. +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -nosep -\series default +\series default : -\family default +\family default shorthand for -\family typewriter +\family typewriter '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0' -\family default +\family default . Simply removes all input/output separators. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -upgrade -\family default -\series default +\family default +\series default : allows you to upgrade your -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default configuration when you install a new version of IPython. Since new versions may include new command line options or example files, this copies updated ipythonrc-type files. However, it backs up (with a -\family typewriter +\family typewriter .old -\family default +\family default extension) all files which it overwrites so that you can merge back any customizations you might have in your personal files. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold -Version -\series default +\series default : -\family default +\family default print version information and exit. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --wxversion\SpecialChar ~ +\family typewriter +\series bold +-wxversion\InsetSpace ~ : -\family default -\series default +\family default +\series default Select a specific version of wxPython (used in conjunction with -\family typewriter +\family typewriter -wthread -\family default +\family default ). Requires the wxversion module, part of recent wxPython distributions -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold --xmode\SpecialChar ~ +\family typewriter +\series bold +-xmode\InsetSpace ~ -\series default +\series default : -\family default +\family default Mode for exception reporting. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ - Valid modes: Plain, Context and Verbose. -\layout List +\begin_layout List \labelwidthstring 00.00.0000 +\InsetSpace ~ + Valid modes: Plain, Context and Verbose. +\end_layout -\SpecialChar ~ - Plain: similar to python's normal traceback printing. -\layout List +\begin_layout List \labelwidthstring 00.00.0000 +\InsetSpace ~ + Plain: similar to python's normal traceback printing. +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ Context: prints 5 lines of context source code around each line in the traceback. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ Verbose: similar to Context, but additionally prints the variables currently visible where the exception happened (shortening their strings if too long). This can potentially be very slow, if you happen to have a huge data structure @@ -3825,27 +4171,30 @@ IPYTHONDIR Your computer may appear to freeze for a while with cpu usage at 100%. If this occurs, you can cancel the traceback with Ctrl-C (maybe hitting it more than once). -\layout Section +\end_layout +\begin_layout Section Interactive use -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Warning -\series default +\series default : IPython relies on the existence of a global variable called -\family typewriter +\family typewriter __IP -\family default +\family default which controls the shell itself. If you redefine -\family typewriter +\family typewriter __IP -\family default +\family default to anything, bizarre behavior will quickly occur. -\layout Standard +\end_layout +\begin_layout Standard Other than the above warning, IPython is meant to work as a drop-in replacement for the standard interactive interpreter. As such, any code which is valid python should execute normally under IPython @@ -3853,651 +4202,715 @@ Other than the above warning, IPython is meant to work as a drop-in replacement It does, however, offer many features which are not available at a standard python prompt. What follows is a list of these. -\layout Subsection +\end_layout +\begin_layout Subsection Caution for Windows users -\layout Standard +\end_layout +\begin_layout Standard Windows, unfortunately, uses the ` -\family typewriter +\family typewriter -\backslash +\backslash -\family default +\family default ' character as a path separator. This is a terrible choice, because ` -\family typewriter +\family typewriter -\backslash +\backslash -\family default +\family default ' also represents the escape character in most modern programming languages, including Python. For this reason, issuing many of the commands discussed below (especially magics which affect the filesystem) with ` -\family typewriter +\family typewriter -\backslash +\backslash -\family default +\family default ' in them will cause strange errors. -\layout Standard +\end_layout +\begin_layout Standard A partial solution is to use instead the ` -\family typewriter +\family typewriter / -\family default +\family default ' character as a path separator, which Windows recognizes in -\emph on +\emph on most -\emph default +\emph default situations. However, in Windows commands ` -\family typewriter +\family typewriter / -\family default +\family default ' flags options, so you can not use it for the root directory. This means that paths beginning at the root must be typed in a contrived manner like: -\newline +\newline -\family typewriter +\family typewriter %copy -\backslash +\backslash opt/foo/bar.txt -\backslash +\backslash tmp -\layout Standard +\end_layout +\begin_layout Standard There is no sensible thing IPython can do to truly work around this flaw in Windows \begin_inset Foot -collapsed true - -\layout Standard +status collapsed +\begin_layout Standard If anyone comes up with a -\emph on +\emph on clean -\emph default +\emph default solution which works consistently and does not negatively impact other platforms at all, I'll gladly accept a patch. -\end_inset +\end_layout -. -\layout Subsection +\end_inset +. +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:magic} -\end_inset +\end_inset Magic command system -\layout Standard +\end_layout +\begin_layout Standard IPython will treat any line whose first character is a -\family typewriter +\family typewriter % -\family default +\family default as a special call to a 'magic' function. These allow you to control the behavior of IPython itself, plus a lot of system-type features. They are all prefixed with a -\family typewriter +\family typewriter % -\family default +\family default character, but parameters are given without parentheses or quotes. -\layout Standard +\end_layout +\begin_layout Standard Example: typing -\family typewriter +\family typewriter '%cd mydir' -\family default +\family default (without the quotes) changes you working directory to -\family typewriter +\family typewriter 'mydir' -\family default +\family default , if it exists. -\layout Standard +\end_layout +\begin_layout Standard If you have 'automagic' enabled (in your -\family typewriter +\family typewriter ipythonrc -\family default +\family default file, via the command line option -\family typewriter +\family typewriter -automagic -\family default +\family default or with the -\family typewriter +\family typewriter %automagic -\family default +\family default function), you don't need to type in the -\family typewriter +\family typewriter % -\family default +\family default explicitly. IPython will scan its internal list of magic functions and call one if it exists. With automagic on you can then just type ' -\family typewriter +\family typewriter cd mydir -\family default +\family default ' to go to directory ' -\family typewriter +\family typewriter mydir -\family default +\family default '. The automagic system has the lowest possible precedence in name searches, so defining an identifier with the same name as an existing magic function will shadow it for automagic use. You can still access the shadowed magic function by explicitly using the -\family typewriter +\family typewriter % -\family default +\family default character at the beginning of the line. -\layout Standard +\end_layout +\begin_layout Standard An example (with automagic on) should clarify all this: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [1]: cd ipython # %cd is called by automagic -\layout LyX-Code +\end_layout +\begin_layout LyX-Code /home/fperez/ipython -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [2]: cd=1 # now cd is just a variable -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [3]: cd .. # and doesn't work as a function anymore -\layout LyX-Code +\end_layout +\begin_layout LyX-Code ------------------------------------------------------------ -\layout LyX-Code +\end_layout +\begin_layout LyX-Code File "", line 1 -\layout LyX-Code +\end_layout +\begin_layout LyX-Code cd .. -\layout LyX-Code +\end_layout +\begin_layout LyX-Code ^ -\layout LyX-Code +\end_layout +\begin_layout LyX-Code SyntaxError: invalid syntax -\layout LyX-Code +\end_layout + +\begin_layout LyX-Code -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [4]: %cd .. # but %cd always works -\layout LyX-Code +\end_layout +\begin_layout LyX-Code /home/fperez -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [5]: del cd # if you remove the cd variable -\layout LyX-Code +\end_layout +\begin_layout LyX-Code In [6]: cd ipython # automagic can work again -\layout LyX-Code +\end_layout +\begin_layout LyX-Code /home/fperez/ipython -\layout Standard +\end_layout +\begin_layout Standard You can define your own magic functions to extend the system. The following is a snippet of code which shows how to do it. It is provided as file -\family typewriter +\family typewriter example-magic.py -\family default +\family default in the examples directory: -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset ERT -status Open +status open + +\begin_layout Standard -\layout Standard -\backslash +\backslash codelist{examples/example-magic.py} -\end_inset +\end_layout + +\end_inset -\layout Standard +\end_layout +\begin_layout Standard You can also define your own aliased names for magic functions. In your -\family typewriter +\family typewriter ipythonrc -\family default +\family default file, placing a line like: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter execute __IP.magic_cl = __IP.magic_clear -\layout Standard +\end_layout +\begin_layout Standard will define -\family typewriter +\family typewriter %cl -\family default +\family default as a new name for -\family typewriter +\family typewriter %clear -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard Type -\family typewriter +\family typewriter %magic -\family default +\family default for more information, including a list of all available magic functions at any time and their docstrings. You can also type -\family typewriter +\family typewriter %magic_function_name? -\family default +\family default (see sec. \begin_inset LatexCommand \ref{sec:dyn-object-info} -\end_inset +\end_inset for information on the -\family typewriter +\family typewriter '?' -\family default +\family default system) to get information about any particular magic function you are interested in. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Magic commands -\layout Standard +\end_layout +\begin_layout Standard The rest of this section is automatically generated for each release from the docstrings in the IPython code. Therefore the formatting is somewhat minimal, but this method has the advantage of having information always in sync with the code. -\layout Standard +\end_layout +\begin_layout Standard A list of all the magic commands available in IPython's -\emph on +\emph on default -\emph default +\emph default installation follows. This is similar to what you'll see by simply typing -\family typewriter +\family typewriter %magic -\family default +\family default at the prompt, but that will also give you information about magic commands you may have added as part of your personal customizations. -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset Include \input{magic.tex} preview false -\end_inset +\end_inset -\layout Subsection +\end_layout +\begin_layout Subsection Access to the standard Python help -\layout Standard +\end_layout +\begin_layout Standard As of Python 2.1, a help system is available with access to object docstrings and the Python manuals. Simply type -\family typewriter +\family typewriter 'help' -\family default +\family default (no quotes) to access it. You can also type -\family typewriter +\family typewriter help(object) -\family default +\family default to obtain information about a given object, and -\family typewriter +\family typewriter help('keyword') -\family default +\family default for information on a keyword. As noted in sec. \begin_inset LatexCommand \ref{sec:help-access} -\end_inset +\end_inset , you need to properly configure your environment variable -\family typewriter +\family typewriter PYTHONDOCS -\family default +\family default for this feature to work correctly. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:dyn-object-info} -\end_inset +\end_inset Dynamic object information -\layout Standard +\end_layout +\begin_layout Standard Typing -\family typewriter +\family typewriter ?word -\family default +\family default or -\family typewriter +\family typewriter word? -\family default +\family default prints detailed information about an object. If certain strings in the object are too long (docstrings, code, etc.) they get snipped in the center for brevity. This system gives access variable types and values, full source code for any object (if available), function prototypes and other useful information. -\layout Standard +\end_layout +\begin_layout Standard Typing -\family typewriter +\family typewriter ??word -\family default +\family default or -\family typewriter +\family typewriter word?? -\family default +\family default gives access to the full information without snipping long strings. Long strings are sent to the screen through the -\family typewriter +\family typewriter less -\family default +\family default pager if longer than the screen and printed otherwise. On systems lacking the -\family typewriter +\family typewriter less -\family default +\family default command, IPython uses a very basic internal pager. -\layout Standard +\end_layout +\begin_layout Standard The following magic functions are particularly useful for gathering information about your working environment. You can get more details by typing -\family typewriter +\family typewriter %magic -\family default +\family default or querying them individually (use -\family typewriter +\family typewriter %function_name? -\family default +\family default with or without the -\family typewriter +\family typewriter % -\family default +\family default ), this is just a summary: -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -%pdoc\SpecialChar ~ +\family typewriter +\series bold +%pdoc\InsetSpace ~ -\family default -\series default +\family default +\series default : Print (or run through a pager if too long) the docstring for an object. If the given object is a class, it will print both the class and the constructo r docstrings. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -%pdef\SpecialChar ~ +\family typewriter +\series bold +%pdef\InsetSpace ~ -\family default -\series default +\family default +\series default : Print the definition header for any callable object. If the object is a class, print the constructor information. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -%psource\SpecialChar ~ +\family typewriter +\series bold +%psource\InsetSpace ~ -\family default -\series default +\family default +\series default : Print (or run through a pager if too long) the source code for an object. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -%pfile\SpecialChar ~ +\family typewriter +\series bold +%pfile\InsetSpace ~ -\family default -\series default +\family default +\series default : Show the entire source file where an object was defined via a pager, opening it at the line where the object definition begins. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold %who/%whos -\family default -\series default +\family default +\series default : These functions give information about identifiers you have defined interactiv ely (not things you loaded or defined in your configuration files). -\family typewriter +\family typewriter %who -\family default +\family default just prints a list of identifiers and -\family typewriter +\family typewriter %whos -\family default +\family default prints a table with some basic details about each identifier. -\layout Standard +\end_layout +\begin_layout Standard Note that the dynamic object information functions ( -\family typewriter +\family typewriter ?/??, %pdoc, %pfile, %pdef, %psource -\family default +\family default ) give you access to documentation even on things which are not really defined as separate identifiers. Try for example typing -\family typewriter +\family typewriter {}.get? -\family default +\family default or after doing -\family typewriter +\family typewriter import os -\family default +\family default , type -\family typewriter +\family typewriter os.path.abspath?? -\family default +\family default . -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:readline} -\end_inset +\end_inset Readline-based features -\layout Standard +\end_layout +\begin_layout Standard These features require the GNU readline library, so they won't work if your Python installation lacks readline support. We will first describe the default behavior IPython uses, and then how to change it to suit your preferences. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Command line completion -\layout Standard +\end_layout +\begin_layout Standard At any time, hitting TAB will complete any available python commands or variable names, and show you a list of the possible completions if there's no unambiguous one. It will also complete filenames in the current directory if no python names match what you've typed so far. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Search command history -\layout Standard +\end_layout +\begin_layout Standard IPython provides two ways for searching through previous input and thus reduce the need for repetitive typing: -\layout Enumerate +\end_layout +\begin_layout Enumerate Start typing, and then use -\family typewriter +\family typewriter Ctrl-p -\family default +\family default (previous,up) and -\family typewriter +\family typewriter Ctrl-n -\family default +\family default (next,down) to search through only the history items that match what you've typed so far. If you use -\family typewriter +\family typewriter Ctrl-p/Ctrl-n -\family default +\family default at a blank prompt, they just behave like normal arrow keys. -\layout Enumerate +\end_layout +\begin_layout Enumerate Hit -\family typewriter +\family typewriter Ctrl-r -\family default +\family default : opens a search prompt. Begin typing and the system searches your history for lines that contain what you've typed so far, completing as much as it can. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Persistent command history across sessions -\layout Standard +\end_layout +\begin_layout Standard IPython will save your input history when it leaves and reload it next time you restart it. By default, the history file is named -\family typewriter +\family typewriter $IPYTHONDIR/history -\family default +\family default , but if you've loaded a named profile, ' -\family typewriter +\family typewriter -PROFILE_NAME -\family default +\family default ' is appended to the name. This allows you to keep separate histories related to various tasks: commands related to numerical work will not be clobbered by a system shell history, for example. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Autoindent -\layout Standard +\end_layout +\begin_layout Standard IPython can recognize lines ending in ':' and indent the next line, while also un-indenting automatically after 'raise' or 'return'. -\layout Standard +\end_layout +\begin_layout Standard This feature uses the readline library, so it will honor your -\family typewriter +\family typewriter ~/.inputrc -\family default +\family default configuration (or whatever file your -\family typewriter +\family typewriter INPUTRC -\family default +\family default variable points to). Adding the following lines to your -\family typewriter +\family typewriter .inputrc -\family default +\family default file can make indenting/unindenting more convenient ( -\family typewriter +\family typewriter M-i -\family default +\family default indents, -\family typewriter +\family typewriter M-u -\family default +\family default unindents): -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter $if Python -\newline +\newline " -\backslash -M-i": "\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\backslash +M-i": "\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ " -\newline +\newline " -\backslash +\backslash M-u": " -\backslash +\backslash d -\backslash +\backslash d -\backslash +\backslash d -\backslash +\backslash d" -\newline +\newline $endif -\layout Standard +\end_layout +\begin_layout Standard Note that there are 4 spaces between the quote marks after -\family typewriter +\family typewriter "M-i" -\family default +\family default above. -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Warning: -\series default +\series default this feature is ON by default, but it can cause problems with the pasting of multi-line indented code (the pasted code gets re-indented on each line). A magic function -\family typewriter +\family typewriter %autoindent -\family default +\family default allows you to toggle it on/off at runtime. You can also disable it permanently on in your -\family typewriter +\family typewriter ipythonrc -\family default +\family default file (set -\family typewriter +\family typewriter autoindent 0 -\family default +\family default ). -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Customizing readline behavior -\layout Standard +\end_layout +\begin_layout Standard All these features are based on the GNU readline library, which has an extremely customizable interface. Normally, readline is configured via a file which defines the behavior @@ -4507,1630 +4920,1769 @@ All these features are based on the GNU readline library, which has an extremely passing to readline valid options via a simple interface. In brief, you can customize readline by setting the following options in your -\family typewriter +\family typewriter ipythonrc -\family default +\family default configuration file (note that these options can -\emph on +\emph on not -\emph default +\emph default be specified at the command line): -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold readline_parse_and_bind: -\family default -\series default +\family default +\series default this option can appear as many times as you want, each time defining a string to be executed via a -\family typewriter +\family typewriter readline.parse_and_bind() -\family default +\family default command. The syntax for valid commands of this kind can be found by reading the documentation for the GNU readline library, as these commands are of the kind which readline accepts in its configuration file. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold readline_remove_delims: -\family default -\series default +\family default +\series default a string of characters to be removed from the default word-delimiters list used by readline, so that completions may be performed on strings which contain them. Do not change the default value unless you know what you're doing. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold readline_omit__names -\family default -\series default +\family default +\series default : when tab-completion is enabled, hitting -\family typewriter +\family typewriter -\family default +\family default after a ' -\family typewriter +\family typewriter . -\family default +\family default ' in a name will complete all attributes of an object, including all the special methods whose names include double underscores (like -\family typewriter +\family typewriter __getitem__ -\family default +\family default or -\family typewriter +\family typewriter __class__ -\family default +\family default ). If you'd rather not see these names by default, you can set this option to 1. Note that even when this option is set, you can still see those names by explicitly typing a -\family typewriter +\family typewriter _ -\family default +\family default after the period and hitting -\family typewriter +\family typewriter -\family default +\family default : ' -\family typewriter +\family typewriter name._ -\family default +\family default ' will always complete attribute names starting with ' -\family typewriter +\family typewriter _ -\family default +\family default '. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +\InsetSpace ~ This option is off by default so that new users see all attributes of any objects they are dealing with. -\layout Standard +\end_layout +\begin_layout Standard You will find the default values along with a corresponding detailed explanation in your -\family typewriter +\family typewriter ipythonrc -\family default +\family default file. -\layout Subsection +\end_layout +\begin_layout Subsection Session logging and restoring -\layout Standard +\end_layout +\begin_layout Standard You can log all input from a session either by starting IPython with the command line switches -\family typewriter +\family typewriter -log -\family default +\family default or -\family typewriter +\family typewriter -logfile -\family default +\family default (see sec. \begin_inset LatexCommand \ref{sec:cmd-line-opts} -\end_inset +\end_inset )or by activating the logging at any moment with the magic function -\family typewriter +\family typewriter %logstart -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard Log files can later be reloaded with the -\family typewriter +\family typewriter -logplay -\family default +\family default option and IPython will attempt to 'replay' the log by executing all the lines in it, thus restoring the state of a previous session. This feature is not quite perfect, but can still be useful in many cases. -\layout Standard +\end_layout +\begin_layout Standard The log files can also be used as a way to have a permanent record of any code you wrote while experimenting. Log files are regular text files which you can later open in your favorite text editor to extract code or to 'clean them up' before using them to replay a session. -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter %logstart -\family default +\family default function for activating logging in mid-session is used as follows: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter %logstart [log_name [log_mode]] -\layout Standard +\end_layout +\begin_layout Standard If no name is given, it defaults to a file named -\family typewriter +\family typewriter 'log' -\family default +\family default in your IPYTHONDIR directory, in -\family typewriter +\family typewriter 'rotate' -\family default +\family default mode (see below). -\layout Standard +\end_layout +\begin_layout Standard ' -\family typewriter +\family typewriter %logstart name -\family default +\family default ' saves to file -\family typewriter +\family typewriter 'name' -\family default +\family default in -\family typewriter +\family typewriter 'backup' -\family default +\family default mode. It saves your history up to that point and then continues logging. -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter %logstart -\family default +\family default takes a second optional parameter: logging mode. This can be one of (note that the modes are given unquoted): -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter +\family typewriter over -\family default +\family default : overwrite existing -\family typewriter +\family typewriter log_name -\family default +\family default . -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter +\family typewriter backup -\family default +\family default : rename (if exists) to -\family typewriter +\family typewriter log_name~ -\family default +\family default and start -\family typewriter +\family typewriter log_name -\family default +\family default . -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter +\family typewriter append -\family default +\family default : well, that says it. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter +\family typewriter rotate -\family default +\family default : create rotating logs -\family typewriter +\family typewriter log_name -\family default +\family default . -\family typewriter +\family typewriter 1~ -\family default +\family default , -\family typewriter +\family typewriter log_name.2~ -\family default +\family default , etc. -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter %logoff -\family default +\family default and -\family typewriter +\family typewriter %logon -\family default +\family default functions allow you to temporarily stop and resume logging to a file which had previously been started with -\family typewriter +\family typewriter %logstart -\family default +\family default . They will fail (with an explanation) if you try to use them before logging has been started. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sub:System-shell-access} -\end_inset +\end_inset System shell access -\layout Standard +\end_layout +\begin_layout Standard Any input line beginning with a -\family typewriter +\family typewriter ! -\family default +\family default character is passed verbatim (minus the -\family typewriter +\family typewriter ! -\family default +\family default , of course) to the underlying operating system. For example, typing -\family typewriter +\family typewriter !ls -\family default +\family default will run -\family typewriter +\family typewriter 'ls' -\family default +\family default in the current directory. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Manual capture of command output -\layout Standard +\end_layout +\begin_layout Standard If the input line begins with -\emph on +\emph on two -\emph default +\emph default exclamation marks, -\family typewriter +\family typewriter !! -\family default +\family default , the command is executed but its output is captured and returned as a python list, split on newlines. Any output sent by the subprocess to standard error is printed separately, so that the resulting list only captures standard output. The -\family typewriter +\family typewriter !! -\family default +\family default syntax is a shorthand for the -\family typewriter +\family typewriter %sx -\family default +\family default magic command. -\layout Standard +\end_layout +\begin_layout Standard Finally, the -\family typewriter +\family typewriter %sc -\family default +\family default magic (short for `shell capture') is similar to -\family typewriter +\family typewriter %sx -\family default +\family default , but allowing more fine-grained control of the capture details, and storing the result directly into a named variable. -\layout Standard +\end_layout -See Sec.\SpecialChar ~ +\begin_layout Standard +See Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:magic} -\end_inset +\end_inset for details on the magics -\family typewriter +\family typewriter %sc -\family default +\family default and -\family typewriter +\family typewriter %sx -\family default +\family default , or use IPython's own help ( -\family typewriter +\family typewriter sc? -\family default +\family default and -\family typewriter +\family typewriter sx? -\family default +\family default ) for further details. -\layout Standard +\end_layout +\begin_layout Standard IPython also allows you to expand the value of python variables when making system calls. Any python variable or expression which you prepend with -\family typewriter +\family typewriter $ -\family default +\family default will get expanded before the system call is made. -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [1]: pyvar='Hello world' -\newline +\newline In [2]: !echo "A python variable: $pyvar" -\newline -A python variable: Hello world -\layout Standard +\newline +A python + variable: Hello world +\end_layout +\begin_layout Standard If you want the shell to actually see a literal -\family typewriter +\family typewriter $ -\family default +\family default , you need to type it twice: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [3]: !echo "A system variable: $$HOME" -\newline +\newline A system variable: /home/fperez -\layout Standard +\end_layout +\begin_layout Standard You can pass arbitrary expressions, though you'll need to delimit them with -\family typewriter +\family typewriter {} -\family default +\family default if there is ambiguity as to the extent of the expression: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [5]: x=10 -\newline +\newline In [6]: y=20 -\newline +\newline In [13]: !echo $x+y -\newline +\newline 10+y -\newline +\newline In [7]: !echo ${x+y} -\newline -30 -\layout Standard +\newline +30 + +\end_layout +\begin_layout Standard Even object attributes can be expanded: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [12]: !echo $sys.argv -\newline +\newline [/home/fperez/usr/bin/ipython] -\layout Subsection +\end_layout +\begin_layout Subsection System command aliases -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter %alias -\family default +\family default magic function and the -\family typewriter +\family typewriter alias -\family default +\family default option in the -\family typewriter +\family typewriter ipythonrc -\family default +\family default configuration file allow you to define magic functions which are in fact system shell commands. These aliases can have parameters. -\layout Standard +\end_layout +\begin_layout Standard ' -\family typewriter +\family typewriter %alias alias_name cmd -\family default +\family default ' defines ' -\family typewriter +\family typewriter alias_name -\family default +\family default ' as an alias for ' -\family typewriter +\family typewriter cmd -\family default +\family default ' -\layout Standard +\end_layout +\begin_layout Standard Then, typing ' -\family typewriter +\family typewriter %alias_name params -\family default +\family default ' will execute the system command ' -\family typewriter +\family typewriter cmd params -\family default +\family default ' (from your underlying operating system). -\layout Standard +\end_layout +\begin_layout Standard You can also define aliases with parameters using -\family typewriter +\family typewriter %s -\family default +\family default specifiers (one per parameter). The following example defines the -\family typewriter +\family typewriter %parts -\family default +\family default function as an alias to the command ' -\family typewriter +\family typewriter echo first %s second %s -\family default +\family default ' where each -\family typewriter +\family typewriter %s -\family default +\family default will be replaced by a positional parameter to the call to -\family typewriter +\family typewriter %parts: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [1]: alias parts echo first %s second %s -\newline +\newline In [2]: %parts A B -\newline -first A second B -\newline +\newline +first A second + B +\newline In [3]: %parts A -\newline +\newline Incorrect number of arguments: 2 expected. -\newline +\newline parts is an alias to: 'echo first %s second %s' -\layout Standard +\end_layout +\begin_layout Standard If called with no parameters, -\family typewriter +\family typewriter %alias -\family default +\family default prints the table of currently defined aliases. -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter %rehash/rehashx -\family default +\family default magics allow you to load your entire -\family typewriter +\family typewriter $PATH -\family default +\family default as ipython aliases. - See their respective docstrings (or sec.\SpecialChar ~ + See their respective docstrings (or sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:magic} -\end_inset +\end_inset for further details). -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:dreload} -\end_inset +\end_inset Recursive reload -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter dreload -\family default +\family default function does a recursive reload of a module: changes made to the module since you imported will actually be available without having to exit. -\layout Subsection +\end_layout +\begin_layout Subsection Verbose and colored exception traceback printouts -\layout Standard +\end_layout +\begin_layout Standard IPython provides the option to see very detailed exception tracebacks, which can be especially useful when debugging large programs. You can run any Python file with the -\family typewriter +\family typewriter %run -\family default +\family default function to benefit from these detailed tracebacks. Furthermore, both normal and verbose tracebacks can be colored (if your terminal supports it) which makes them much easier to parse visually. -\layout Standard +\end_layout +\begin_layout Standard See the magic -\family typewriter +\family typewriter xmode -\family default +\family default and -\family typewriter +\family typewriter colors -\family default +\family default functions for details (just type -\family typewriter +\family typewriter %magic -\family default +\family default ). -\layout Standard +\end_layout +\begin_layout Standard These features are basically a terminal version of Ka-Ping Yee's -\family typewriter +\family typewriter cgitb -\family default +\family default module, now part of the standard Python library. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:cache_input} -\end_inset +\end_inset Input caching system -\layout Standard +\end_layout +\begin_layout Standard IPython offers numbered prompts (In/Out) with input and output caching. All input is saved and can be retrieved as variables (besides the usual arrow key recall). -\layout Standard +\end_layout +\begin_layout Standard The following GLOBAL variables always exist (so don't overwrite them!): -\family typewriter +\family typewriter _i -\family default +\family default : stores previous input. -\family typewriter +\family typewriter _ii -\family default +\family default : next previous. -\family typewriter +\family typewriter _iii -\family default +\family default : next-next previous. -\family typewriter +\family typewriter _ih -\family default +\family default : a list of all input -\family typewriter +\family typewriter _ih[n] -\family default +\family default is the input from line -\family typewriter +\family typewriter n -\family default +\family default and this list is aliased to the global variable -\family typewriter +\family typewriter In -\family default +\family default . If you overwrite -\family typewriter +\family typewriter In -\family default +\family default with a variable of your own, you can remake the assignment to the internal list with a simple -\family typewriter +\family typewriter 'In=_ih' -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard Additionally, global variables named -\family typewriter +\family typewriter _i -\family default +\family default are dynamically created ( -\family typewriter +\family typewriter -\family default +\family default being the prompt counter), such that -\newline +\newline -\family typewriter +\family typewriter _i == _ih[] == In[]. -\layout Standard +\end_layout +\begin_layout Standard For example, what you typed at prompt 14 is available as -\family typewriter +\family typewriter _i14, -\family default +\family default -\family typewriter +\family typewriter _ih[14] -\family default +\family default and -\family typewriter +\family typewriter In[14] -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard This allows you to easily cut and paste multi line interactive prompts by printing them out: they print like a clean string, without prompt characters. You can also manipulate them like regular variables (they are strings), modify or exec them (typing -\family typewriter +\family typewriter 'exec _i9' -\family default +\family default will re-execute the contents of input prompt 9, ' -\family typewriter +\family typewriter exec In[9:14]+In[18] -\family default +\family default ' will re-execute lines 9 through 13 and line 18). -\layout Standard +\end_layout +\begin_layout Standard You can also re-execute multiple lines of input easily by using the magic -\family typewriter +\family typewriter %macro -\family default +\family default function (which automates the process and allows re-execution without having to type ' -\family typewriter +\family typewriter exec -\family default +\family default ' every time). The macro system also allows you to re-execute previous lines which include magic function calls (which require special processing). Type -\family typewriter +\family typewriter %macro? -\family default +\family default or see sec. \begin_inset LatexCommand \ref{sec:magic} -\end_inset +\end_inset for more details on the macro system. -\layout Standard +\end_layout +\begin_layout Standard A history function -\family typewriter +\family typewriter %hist -\family default +\family default allows you to see any part of your input history by printing a range of the -\family typewriter +\family typewriter _i -\family default +\family default variables. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:cache_output} -\end_inset +\end_inset Output caching system -\layout Standard +\end_layout +\begin_layout Standard For output that is returned from actions, a system similar to the input cache exists but using -\family typewriter +\family typewriter _ -\family default +\family default instead of -\family typewriter +\family typewriter _i -\family default +\family default . Only actions that produce a result (NOT assignments, for example) are cached. If you are familiar with Mathematica, IPython's -\family typewriter +\family typewriter _ -\family default +\family default variables behave exactly like Mathematica's -\family typewriter +\family typewriter % -\family default +\family default variables. -\layout Standard +\end_layout +\begin_layout Standard The following GLOBAL variables always exist (so don't overwrite them!): -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold _ -\family default -\series default +\family default +\series default (a -\emph on +\emph on single -\emph default +\emph default underscore) : stores previous output, like Python's default interpreter. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold __ -\family default -\series default +\family default +\series default (two underscores): next previous. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold +\family typewriter +\series bold ___ -\family default -\series default +\family default +\series default (three underscores): next-next previous. -\layout Standard +\end_layout +\begin_layout Standard Additionally, global variables named -\family typewriter +\family typewriter _ -\family default +\family default are dynamically created ( -\family typewriter +\family typewriter -\family default +\family default being the prompt counter), such that the result of output -\family typewriter +\family typewriter -\family default +\family default is always available as -\family typewriter +\family typewriter _ -\family default +\family default (don't use the angle brackets, just the number, e.g. -\family typewriter +\family typewriter _21 -\family default +\family default ). -\layout Standard +\end_layout +\begin_layout Standard These global variables are all stored in a global dictionary (not a list, since it only has entries for lines which returned a result) available under the names -\family typewriter +\family typewriter _oh -\family default +\family default and -\family typewriter +\family typewriter Out -\family default +\family default (similar to -\family typewriter +\family typewriter _ih -\family default +\family default and -\family typewriter +\family typewriter In -\family default +\family default ). So the output from line 12 can be obtained as -\family typewriter +\family typewriter _12 -\family default +\family default , -\family typewriter +\family typewriter Out[12] -\family default +\family default or -\family typewriter +\family typewriter _oh[12] -\family default +\family default . If you accidentally overwrite the -\family typewriter +\family typewriter Out -\family default +\family default variable you can recover it by typing -\family typewriter +\family typewriter 'Out=_oh -\family default +\family default ' at the prompt. -\layout Standard +\end_layout +\begin_layout Standard This system obviously can potentially put heavy memory demands on your system, since it prevents Python's garbage collector from removing any previously computed results. You can control how many results are kept in memory with the option (at the command line or in your -\family typewriter +\family typewriter ipythonrc -\family default +\family default file) -\family typewriter +\family typewriter cache_size -\family default +\family default . If you set it to 0, the whole system is completely disabled and the prompts revert to the classic -\family typewriter +\family typewriter '>>>' -\family default +\family default of normal Python. -\layout Subsection +\end_layout +\begin_layout Subsection Directory history -\layout Standard +\end_layout +\begin_layout Standard Your history of visited directories is kept in the global list -\family typewriter +\family typewriter _dh -\family default +\family default , and the magic -\family typewriter +\family typewriter %cd -\family default +\family default command can be used to go to any entry in that list. The -\family typewriter +\family typewriter %dhist -\family default +\family default command allows you to view this history. -\layout Subsection +\end_layout +\begin_layout Subsection Automatic parentheses and quotes -\layout Standard +\end_layout +\begin_layout Standard These features were adapted from Nathan Gray's LazyPython. They are meant to allow less typing for common situations. -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Automatic parentheses -\layout Standard +\end_layout +\begin_layout Standard Callable objects (i.e. functions, methods, etc) can be invoked like this (notice the commas between the arguments): -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter >>> callable_ob arg1, arg2, arg3 -\layout Standard +\end_layout +\begin_layout Standard and the input will be translated to this: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter --> callable_ob(arg1, arg2, arg3) -\layout Standard +\end_layout +\begin_layout Standard You can force automatic parentheses by using '/' as the first character of a line. For example: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter >>> /globals # becomes 'globals()' -\layout Standard +\end_layout +\begin_layout Standard Note that the '/' MUST be the first character on the line! This won't work: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter >>> print /globals # syntax error -\layout Standard +\end_layout +\begin_layout Standard In most cases the automatic algorithm should work, so you should rarely need to explicitly invoke /. One notable exception is if you are trying to call a function with a list of tuples as arguments (the parenthesis will confuse IPython): -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [1]: zip (1,2,3),(4,5,6) # won't work -\layout Standard +\end_layout +\begin_layout Standard but this will work: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [2]: /zip (1,2,3),(4,5,6) -\newline +\newline ------> zip ((1,2,3),(4,5,6)) -\newline -Out[2]= [(1, 4), (2, 5), (3, 6)] -\layout Standard +\newline +Out[2]= [(1, 4), + (2, 5), (3, 6)] +\end_layout +\begin_layout Standard IPython tells you that it has altered your command line by displaying the new command line preceded by -\family typewriter +\family typewriter --> -\family default +\family default . e.g.: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [18]: callable list -\newline +\newline -------> callable (list) -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Automatic quoting -\layout Standard +\end_layout +\begin_layout Standard You can force automatic quoting of a function's arguments by using -\family typewriter +\family typewriter `,' -\family default +\family default or -\family typewriter +\family typewriter `;' -\family default +\family default as the first character of a line. For example: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter >>> ,my_function /home/me # becomes my_function("/home/me") -\layout Standard +\end_layout +\begin_layout Standard If you use -\family typewriter +\family typewriter `;' -\family default +\family default instead, the whole argument is quoted as a single string (while -\family typewriter +\family typewriter `,' -\family default +\family default splits on whitespace): -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter >>> ,my_function a b c # becomes my_function("a","b","c") -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter >>> ;my_function a b c # becomes my_function("a b c") -\layout Standard +\end_layout +\begin_layout Standard Note that the ` -\family typewriter +\family typewriter , -\family default +\family default ' or ` -\family typewriter +\family typewriter ; -\family default +\family default ' MUST be the first character on the line! This won't work: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter >>> x = ,my_function /home/me # syntax error -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:customization} -\end_inset +\end_inset Customization -\layout Standard +\end_layout +\begin_layout Standard As we've already mentioned, IPython reads a configuration file which can be specified at the command line ( -\family typewriter +\family typewriter -rcfile -\family default +\family default ) or which by default is assumed to be called -\family typewriter +\family typewriter ipythonrc -\family default +\family default . Such a file is looked for in the current directory where IPython is started and then in your -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default , which allows you to have local configuration files for specific projects. In this section we will call these types of configuration files simply rcfiles (short for resource configuration file). -\layout Standard +\end_layout +\begin_layout Standard The syntax of an rcfile is one of key-value pairs separated by whitespace, one per line. Lines beginning with a -\family typewriter +\family typewriter # -\family default +\family default are ignored as comments, but comments can -\series bold +\series bold not -\series default +\series default be put on lines with data (the parser is fairly primitive). Note that these are not python files, and this is deliberate, because it allows us to do some things which would be quite tricky to implement if they were normal python files. -\layout Standard +\end_layout +\begin_layout Standard First, an rcfile can contain permanent default values for almost all command line options (except things like -\family typewriter +\family typewriter -help -\family default +\family default or -\family typewriter +\family typewriter -Version -\family default +\family default ). - Sec\SpecialChar ~ + Sec\InsetSpace ~ \begin_inset LatexCommand \ref{sec:cmd-line-opts} -\end_inset +\end_inset contains a description of all command-line options. However, values you explicitly specify at the command line override the values defined in the rcfile. -\layout Standard +\end_layout +\begin_layout Standard Besides command line option values, the rcfile can specify values for certain extra special options which are not available at the command line. These options are briefly described below. -\layout Standard +\end_layout +\begin_layout Standard Each of these options may appear as many times as you need it in the file. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -include\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\family typewriter +\series bold +include\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ ... -\family default -\series default +\family default +\series default : you can name -\emph on +\emph on other -\emph default +\emph default rcfiles you want to recursively load up to 15 levels (don't use the -\family typewriter +\family typewriter <> -\family default +\family default brackets in your names!). This feature allows you to define a 'base' rcfile with general options and special-purpose files which can be loaded only when needed with particular configuration options. To make this more convenient, IPython accepts the -\family typewriter +\family typewriter -profile -\family default +\family default option (abbreviates to -\family typewriter +\family typewriter -p ) -\family typewriter +\family typewriter which -\family default +\family default tells it to look for an rcfile named -\family typewriter +\family typewriter ipythonrc- -\family default +\family default . -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -import_mod\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\family typewriter +\series bold +import_mod\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ ... -\family default -\series default +\family default +\series default : import modules with ' -\family typewriter +\family typewriter import -\family default +\family default -\family typewriter +\family typewriter ,,... -\family default +\family default ' -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -import_some\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\family typewriter +\series bold +import_some\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ ... -\family default -\series default +\family default +\series default : import functions with ' -\family typewriter +\family typewriter from import -\family default +\family default -\family typewriter +\family typewriter ,,... -\family default +\family default ' -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -import_all\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\family typewriter +\series bold +import_all\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ ... -\family default -\series default +\family default +\series default : for each module listed import functions with ' -\family typewriter +\family typewriter from import * -\family default +\family default ' -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -execute\SpecialChar ~ - -\family default -\series default +\family default +\series default : give any single-line python code to be executed. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -execfile\SpecialChar ~ +\family typewriter +\series bold +execfile\InsetSpace ~ -\family default -\series default +\family default +\series default : execute the python file given with an ' -\family typewriter +\family typewriter execfile(filename) -\family default +\family default ' command. Username expansion is performed on the given names. So if you need any amount of extra fancy customization that won't fit in any of the above 'canned' options, you can just put it in a separate python file and execute it. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 -\family typewriter -\series bold -alias\SpecialChar ~ +\family typewriter +\series bold +alias\InsetSpace ~ -\family default -\series default +\family default +\series default : this is equivalent to calling ' -\family typewriter -%alias\SpecialChar ~ +\family typewriter +%alias\InsetSpace ~ -\family default +\family default ' at the IPython command line. This way, from within IPython you can do common system tasks without having to exit it or use the -\family typewriter +\family typewriter ! -\family default +\family default escape. IPython isn't meant to be a shell replacement, but it is often very useful to be able to do things with files while testing code. This gives you the flexibility to have within IPython any aliases you may be used to under your normal system shell. -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:ipytonrc-sample} -\end_inset +\end_inset Sample -\family typewriter +\family typewriter ipythonrc -\family default +\family default file -\layout Standard +\end_layout +\begin_layout Standard The default rcfile, called -\family typewriter +\family typewriter ipythonrc -\family default +\family default and supplied in your -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default directory contains lots of comments on all of these options. We reproduce it here for reference: -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset ERT -status Open +status open -\layout Standard +\begin_layout Standard -\backslash + +\backslash codelist{../IPython/UserConfig/ipythonrc} -\end_inset +\end_layout +\end_inset -\layout Subsection +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:prompts} -\end_inset +\end_inset Fine-tuning your prompt -\layout Standard +\end_layout +\begin_layout Standard IPython's prompts can be customized using a syntax similar to that of the -\family typewriter +\family typewriter bash -\family default +\family default shell. Many of -\family typewriter +\family typewriter bash -\family default +\family default 's escapes are supported, as well as a few additional ones. We list them below: -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash # the prompt/history count number -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash D the prompt/history count, with the actual digits replaced by dots. Used mainly in continuation prompts (prompt_in2) -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash w the current working directory -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash W the basename of current working directory -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash X -\emph on +\emph on n -\emph default +\emph default where \begin_inset Formula $n=0\ldots5.$ -\end_inset +\end_inset The current working directory, with -\family typewriter +\family typewriter $HOME -\family default +\family default replaced by -\family typewriter +\family typewriter ~ -\family default +\family default , and filtered out to contain only \begin_inset Formula $n$ -\end_inset +\end_inset path elements -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash Y -\emph on +\emph on n -\emph default +\emph default Similar to -\backslash +\backslash X -\emph on +\emph on n -\emph default +\emph default , but with the \begin_inset Formula $n+1$ -\end_inset +\end_inset element included if it is -\family typewriter +\family typewriter ~ -\family default +\family default (this is similar to the behavior of the %c -\emph on +\emph on n -\emph default +\emph default escapes in -\family typewriter +\family typewriter tcsh -\family default +\family default ) -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash u the username of the current user -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash $ if the effective UID is 0, a #, otherwise a $ -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash h the hostname up to the first `.' -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash H the hostname -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash n a newline -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash r a carriage return -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash v IPython version string -\layout Standard +\end_layout +\begin_layout Standard In addition to these, ANSI color escapes can be insterted into the prompts, as -\family typewriter +\family typewriter -\backslash +\backslash C_ -\emph on +\emph on ColorName -\family default -\emph default +\family default +\emph default . The list of valid color names is: Black, Blue, Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White, Yellow. -\layout Standard +\end_layout +\begin_layout Standard Finally, IPython supports the evaluation of arbitrary expressions in your prompt string. The prompt strings are evaluated through the syntax of PEP 215, but basically you can use -\family typewriter +\family typewriter $x.y -\family default +\family default to expand the value of -\family typewriter +\family typewriter x.y -\family default +\family default , and for more complicated expressions you can use braces: -\family typewriter +\family typewriter ${foo()+x} -\family default +\family default will call function -\family typewriter +\family typewriter foo -\family default +\family default and add to it the value of -\family typewriter +\family typewriter x -\family default +\family default , before putting the result into your prompt. For example, using -\newline +\newline -\family typewriter +\family typewriter prompt_in1 '${commands.getoutput("uptime")} -\backslash +\backslash nIn [ -\backslash +\backslash #]: ' -\newline +\newline -\family default +\family default will print the result of the uptime command on each prompt (assuming the -\family typewriter +\family typewriter commands -\family default +\family default module has been imported in your -\family typewriter +\family typewriter ipythonrc -\family default +\family default file). -\layout Subsubsection +\end_layout +\begin_layout Subsubsection Prompt examples -\layout Standard +\end_layout +\begin_layout Standard The following options in an ipythonrc file will give you IPython's default prompts: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter prompt_in1 'In [ -\backslash +\backslash #]:' -\newline -prompt_in2 '\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\newline +prompt_in2 '\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ . -\backslash +\backslash D.:' -\newline +\newline prompt_out 'Out[ -\backslash +\backslash #]:' -\layout Standard +\end_layout +\begin_layout Standard which look like this: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [1]: 1+2 -\newline +\newline Out[1]: 3 -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [2]: for i in (1,2,3): -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -...: \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +...: \InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ print i, -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset +\end_layout -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ ...: -\newline +\newline 1 2 3 -\layout Standard +\end_layout +\begin_layout Standard These will give you a very colorful prompt with path information: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter #prompt_in1 ' -\backslash +\backslash C_Red -\backslash +\backslash u -\backslash +\backslash C_Blue[ -\backslash +\backslash C_Cyan -\backslash +\backslash Y1 -\backslash +\backslash C_Blue] -\backslash +\backslash C_LightGreen -\backslash +\backslash #>' -\newline +\newline prompt_in2 ' .. -\backslash +\backslash D>' -\newline +\newline prompt_out '< -\backslash +\backslash #>' -\layout Standard +\end_layout +\begin_layout Standard which look like this: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter \color red fperez \color blue @@ -6143,39 +6695,42 @@ fperez 1> \color default 1+2 -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ \color red <1> \color default 3 -\newline +\newline \color red fperez @@ -6189,123 +6744,132 @@ fperez 2> \color default for i in (1,2,3): -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ \color green ...> \color default - \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ + \InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ print i, -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ \color green ...> \color default -\newline +\newline 1 2 3 -\layout Standard +\end_layout +\begin_layout Standard The following shows the usage of dynamic expression evaluation: -\layout Subsection - +\end_layout +\begin_layout Subsection \begin_inset LatexCommand \label{sec:profiles} -\end_inset +\end_inset IPython profiles -\layout Standard +\end_layout +\begin_layout Standard As we already mentioned, IPython supports the -\family typewriter +\family typewriter -profile -\family default +\family default command-line option (see sec. \begin_inset LatexCommand \ref{sec:cmd-line-opts} -\end_inset +\end_inset ). A profile is nothing more than a particular configuration file like your basic -\family typewriter +\family typewriter ipythonrc -\family default +\family default one, but with particular customizations for a specific purpose. When you start IPython with ' -\family typewriter +\family typewriter ipython -profile -\family default +\family default ', it assumes that in your -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default there is a file called -\family typewriter +\family typewriter ipythonrc- -\family default +\family default , and loads it instead of the normal -\family typewriter +\family typewriter ipythonrc -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard This system allows you to maintain multiple configurations which load modules, set options, define functions, etc. suitable for different tasks and activate them in a very simple manner. @@ -6314,1654 +6878,1836 @@ This system allows you to maintain multiple configurations which load modules, can include another configuration file. The most common way to use profiles is then to have each one include your basic -\family typewriter +\family typewriter ipythonrc -\family default +\family default file as a starting point, and then add further customizations. -\layout Standard +\end_layout +\begin_layout Standard In sections \begin_inset LatexCommand \ref{sec:syntax-extensions} -\end_inset +\end_inset and \begin_inset LatexCommand \ref{sec:Gnuplot} -\end_inset +\end_inset we discuss some particular profiles which come as part of the standard IPython distribution. You may also look in your -\family typewriter +\family typewriter IPYTHONDIR -\family default +\family default directory, any file whose name begins with -\family typewriter +\family typewriter ipythonrc- -\family default +\family default is a profile. You can use those as examples for further customizations to suit your own needs. -\layout Section - +\end_layout +\begin_layout Section \begin_inset OptArg -collapsed false - -\layout Standard +status open +\begin_layout Standard IPython as default... -\end_inset +\end_layout + +\end_inset IPython as your default Python environment -\layout Standard +\end_layout +\begin_layout Standard Python honors the environment variable -\family typewriter +\family typewriter PYTHONSTARTUP -\family default +\family default and will execute at startup the file referenced by this variable. If you put at the end of this file the following two lines of code: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter import IPython -\newline +\newline IPython.Shell.IPShell().mainloop(sys_exit=1) -\layout Standard +\end_layout +\begin_layout Standard then IPython will be your working environment anytime you start Python. The -\family typewriter +\family typewriter sys_exit=1 -\family default +\family default is needed to have IPython issue a call to -\family typewriter +\family typewriter sys.exit() -\family default +\family default when it finishes, otherwise you'll be back at the normal Python ' -\family typewriter +\family typewriter >>> -\family default +\family default ' prompt \begin_inset Foot -collapsed true - -\layout Standard +status collapsed +\begin_layout Standard Based on an idea by Holger Krekel. -\end_inset +\end_layout + +\end_inset . -\layout Standard +\end_layout +\begin_layout Standard This is probably useful to developers who manage multiple Python versions and don't want to have correspondingly multiple IPython versions. Note that in this mode, there is no way to pass IPython any command-line options, as those are trapped first by Python itself. -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:embed} -\end_inset +\end_inset Embedding IPython -\layout Standard +\end_layout +\begin_layout Standard It is possible to start an IPython instance -\emph on +\emph on inside -\emph default +\emph default your own Python programs. This allows you to evaluate dynamically the state of your code, operate with your variables, analyze them, etc. Note however that any changes you make to values while in the shell do -\emph on +\emph on not -\emph default +\emph default propagate back to the running code, so it is safe to modify your values because you won't break your code in bizarre ways by doing so. -\layout Standard +\end_layout +\begin_layout Standard This feature allows you to easily have a fully functional python environment for doing object introspection anywhere in your code with a simple function call. In some cases a simple print statement is enough, but if you need to do more detailed analysis of a code fragment this feature can be very valuable. -\layout Standard +\end_layout +\begin_layout Standard It can also be useful in scientific computing situations where it is common to need to do some automatic, computationally intensive part and then stop to look at data, plots, etc \begin_inset Foot -collapsed true - -\layout Standard +status collapsed +\begin_layout Standard This functionality was inspired by IDL's combination of the -\family typewriter +\family typewriter stop -\family default +\family default keyword and the -\family typewriter +\family typewriter .continue -\family default +\family default executive command, which I have found very useful in the past, and by a posting on comp.lang.python by cmkl on Dec. 06/01 concerning similar uses of pyrepl. -\end_inset +\end_layout + +\end_inset . Opening an IPython instance will give you full access to your data and functions, and you can resume program execution once you are done with the interactive part (perhaps to stop again later, as many times as needed). -\layout Standard +\end_layout +\begin_layout Standard The following code snippet is the bare minimum you need to include in your Python programs for this to work (detailed examples follow later): -\layout LyX-Code +\end_layout +\begin_layout LyX-Code from IPython.Shell import IPShellEmbed -\layout LyX-Code +\end_layout +\begin_layout LyX-Code ipshell = IPShellEmbed() -\layout LyX-Code +\end_layout +\begin_layout LyX-Code ipshell() # this call anywhere in your program will start IPython -\layout Standard +\end_layout +\begin_layout Standard You can run embedded instances even in code which is itself being run at the IPython interactive prompt with ' -\family typewriter -%run\SpecialChar ~ +\family typewriter +%run\InsetSpace ~ -\family default +\family default '. Since it's easy to get lost as to where you are (in your top-level IPython or in your embedded one), it's a good idea in such cases to set the in/out prompts to something different for the embedded instances. The code examples below illustrate this. -\layout Standard +\end_layout +\begin_layout Standard You can also have multiple IPython instances in your program and open them separately, for example with different options for data presentation. If you close and open the same instance multiple times, its prompt counters simply continue from each execution to the next. -\layout Standard +\end_layout +\begin_layout Standard Please look at the docstrings in the -\family typewriter +\family typewriter Shell.py -\family default +\family default module for more details on the use of this system. -\layout Standard +\end_layout +\begin_layout Standard The following sample file illustrating how to use the embedding functionality is provided in the examples directory as -\family typewriter +\family typewriter example-embed.py -\family default +\family default . It should be fairly self-explanatory: -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset ERT -status Open +status open + +\begin_layout Standard -\layout Standard -\backslash +\backslash codelist{examples/example-embed.py} -\end_inset +\end_layout + +\end_inset -\layout Standard +\end_layout +\begin_layout Standard Once you understand how the system functions, you can use the following code fragments in your programs which are ready for cut and paste: -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset ERT -status Open +status open + +\begin_layout Standard -\layout Standard -\backslash +\backslash codelist{examples/example-embed-short.py} -\end_inset +\end_layout +\end_inset -\layout Section +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:using-pdb} -\end_inset +\end_inset Using the Python debugger ( -\family typewriter +\family typewriter pdb -\family default +\family default ) -\layout Subsection +\end_layout +\begin_layout Subsection Running entire programs via -\family typewriter +\family typewriter pdb -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter pdb -\family default +\family default , the Python debugger, is a powerful interactive debugger which allows you to step through code, set breakpoints, watch variables, etc. IPython makes it very easy to start any script under the control of -\family typewriter +\family typewriter pdb -\family default +\family default , regardless of whether you have wrapped it into a -\family typewriter +\family typewriter `main()' -\family default +\family default function or not. For this, simply type -\family typewriter +\family typewriter `%run -d myscript' -\family default +\family default at an IPython prompt. See the -\family typewriter +\family typewriter %run -\family default +\family default command's documentation (via -\family typewriter +\family typewriter `%run?' -\family default - or in Sec.\SpecialChar ~ +\family default + or in Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:magic} -\end_inset +\end_inset ) for more details, including how to control where -\family typewriter +\family typewriter pdb -\family default +\family default will stop execution first. -\layout Standard +\end_layout +\begin_layout Standard For more information on the use of the -\family typewriter +\family typewriter pdb -\family default +\family default debugger, read the included -\family typewriter +\family typewriter pdb.doc -\family default +\family default file (part of the standard Python distribution). On a stock Linux system it is located at -\family typewriter +\family typewriter /usr/lib/python2.3/pdb.doc -\family default +\family default , but the easiest way to read it is by using the -\family typewriter +\family typewriter help() -\family default +\family default function of the -\family typewriter +\family typewriter pdb -\family default +\family default module as follows (in an IPython prompt): -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter In [1]: import pdb -\newline +\newline In [2]: pdb.help() -\layout Standard +\end_layout +\begin_layout Standard This will load the -\family typewriter +\family typewriter pdb.doc -\family default +\family default document in a file viewer for you automatically. -\layout Subsection +\end_layout +\begin_layout Subsection Automatic invocation of -\family typewriter +\family typewriter pdb -\family default +\family default on exceptions -\layout Standard +\end_layout +\begin_layout Standard IPython, if started with the -\family typewriter +\family typewriter -pdb -\family default +\family default option (or if the option is set in your rc file) can call the Python -\family typewriter +\family typewriter pdb -\family default +\family default debugger every time your code triggers an uncaught exception \begin_inset Foot -collapsed true - -\layout Standard +status collapsed +\begin_layout Standard Many thanks to Christopher Hart for the request which prompted adding this feature to IPython. -\end_inset +\end_layout + +\end_inset . This feature can also be toggled at any time with the -\family typewriter +\family typewriter %pdb -\family default +\family default magic command. This can be extremely useful in order to find the origin of subtle bugs, because -\family typewriter +\family typewriter pdb -\family default +\family default opens up at the point in your code which triggered the exception, and while your program is at this point `dead', all the data is still available and you can walk up and down the stack frame and understand the origin of the problem. -\layout Standard +\end_layout +\begin_layout Standard Furthermore, you can use these debugging facilities both with the embedded IPython mode and without IPython at all. For an embedded shell (see sec. \begin_inset LatexCommand \ref{sec:embed} -\end_inset +\end_inset ), simply call the constructor with -\family typewriter +\family typewriter `-pdb' -\family default +\family default in the argument string and automatically -\family typewriter +\family typewriter pdb -\family default +\family default will be called if an uncaught exception is triggered by your code. -\layout Standard +\end_layout +\begin_layout Standard For stand-alone use of the feature in your programs which do not use IPython at all, put the following lines toward the top of your `main' routine: -\layout Standard -\align left +\end_layout + +\begin_layout Standard +\align left -\family typewriter +\family typewriter import sys,IPython.ultraTB -\newline -sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbose', color_scheme=`Linux', - call_pdb=1) -\layout Standard +\newline +sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbos +e', color_scheme=`Linux', call_pdb=1) +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter mode -\family default +\family default keyword can be either -\family typewriter +\family typewriter `Verbose' -\family default +\family default or -\family typewriter +\family typewriter `Plain' -\family default +\family default , giving either very detailed or normal tracebacks respectively. The -\family typewriter +\family typewriter color_scheme -\family default +\family default keyword can be one of -\family typewriter +\family typewriter `NoColor' -\family default +\family default , -\family typewriter +\family typewriter `Linux' -\family default +\family default (default) or -\family typewriter +\family typewriter `LightBG' -\family default +\family default . These are the same options which can be set in IPython with -\family typewriter +\family typewriter -colors -\family default +\family default and -\family typewriter +\family typewriter -xmode -\family default +\family default . -\layout Standard +\end_layout +\begin_layout Standard This will give any of your programs detailed, colored tracebacks with automatic invocation of -\family typewriter +\family typewriter pdb -\family default +\family default . -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:syntax-extensions} -\end_inset +\end_inset Extensions for syntax processing -\layout Standard +\end_layout +\begin_layout Standard This isn't for the faint of heart, because the potential for breaking things is quite high. But it can be a very powerful and useful feature. In a nutshell, you can redefine the way IPython processes the user input line to accept new, special extensions to the syntax without needing to change any of IPython's own code. -\layout Standard +\end_layout +\begin_layout Standard In the -\family typewriter +\family typewriter IPython/Extensions -\family default +\family default directory you will find some examples supplied, which we will briefly describe now. These can be used `as is' (and both provide very useful functionality), or you can use them as a starting point for writing your own extensions. -\layout Subsection +\end_layout +\begin_layout Subsection Pasting of code starting with -\family typewriter +\family typewriter `>>> -\family default +\family default ' or -\family typewriter +\family typewriter `... -\family default +\family default ' -\layout Standard +\end_layout +\begin_layout Standard In the python tutorial it is common to find code examples which have been taken from real python sessions. The problem with those is that all the lines begin with either -\family typewriter +\family typewriter `>>> -\family default +\family default ' or -\family typewriter +\family typewriter `... -\family default +\family default ', which makes it impossible to paste them all at once. One must instead do a line by line manual copying, carefully removing the leading extraneous characters. -\layout Standard +\end_layout +\begin_layout Standard This extension identifies those starting characters and removes them from the input automatically, so that one can paste multi-line examples directly into IPython, saving a lot of time. Please look at the file -\family typewriter +\family typewriter InterpreterPasteInput.py -\family default +\family default in the -\family typewriter +\family typewriter IPython/Extensions -\family default +\family default directory for details on how this is done. -\layout Standard +\end_layout +\begin_layout Standard IPython comes with a special profile enabling this feature, called -\family typewriter +\family typewriter tutorial -\family default -\emph on +\family default +\emph on . -\emph default +\emph default Simply start IPython via -\family typewriter -`ipython\SpecialChar ~ --p\SpecialChar ~ +\family typewriter +`ipython\InsetSpace ~ +-p\InsetSpace ~ tutorial' -\family default +\family default and the feature will be available. In a normal IPython session you can activate the feature by importing the corresponding module with: -\newline +\newline -\family typewriter +\family typewriter In [1]: import IPython.Extensions.InterpreterPasteInput -\layout Standard +\end_layout +\begin_layout Standard The following is a 'screenshot' of how things work when this extension is on, copying an example from the standard tutorial: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter IPython profile: tutorial -\newline -\SpecialChar ~ +\newline +\InsetSpace ~ -\newline +\newline *** Pasting of code with ">>>" or "..." has been enabled. -\newline -\SpecialChar ~ +\newline +\InsetSpace ~ -\newline -In [1]: >>> def fib2(n): # return Fibonacci series up to n -\newline +\newline +In + [1]: >>> def fib2(n): # return Fibonacci series up to n +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ - ...: ...\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ + ...: ...\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ """Return a list containing the Fibonacci series up to n.""" -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ - ...: ...\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ + ...: ...\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ result = [] -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ - ...: ...\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ + ...: ...\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ a, b = 0, 1 -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ - ...: ...\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ + ...: ...\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ while b < n: -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ - ...: ...\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - result.append(b)\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ + ...: ...\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ + result.append(b)\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ # see below -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ - ...: ...\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ + ...: ...\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ a, b = b, a+b -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ - ...: ...\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ + ...: ...\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ return result -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset +\end_layout + +\end_inset -\SpecialChar ~ -\SpecialChar ~ +\InsetSpace ~ +\InsetSpace ~ ...: -\newline -\SpecialChar ~ +\newline +\InsetSpace ~ -\newline +\newline In [2]: fib2(10) -\newline +\newline Out[2]: [1, 1, 2, 3, 5, 8] -\layout Standard +\end_layout +\begin_layout Standard Note that as currently written, this extension does -\emph on +\emph on not -\emph default +\emph default recognize IPython's prompts for pasting. Those are more complicated, since the user can change them very easily, they involve numbers and can vary in length. One could however extract all the relevant information from the IPython instance and build an appropriate regular expression. This is left as an exercise for the reader. -\layout Subsection +\end_layout +\begin_layout Subsection Input of physical quantities with units -\layout Standard +\end_layout +\begin_layout Standard The module -\family typewriter +\family typewriter PhysicalQInput -\family default +\family default allows a simplified form of input for physical quantities with units. This file is meant to be used in conjunction with the -\family typewriter +\family typewriter PhysicalQInteractive -\family default +\family default module (in the same directory) and -\family typewriter +\family typewriter Physics.PhysicalQuantities -\family default +\family default from Konrad Hinsen's ScientificPython ( \begin_inset LatexCommand \htmlurl{http://dirac.cnrs-orleans.fr/ScientificPython/} -\end_inset +\end_inset ). -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter Physics.PhysicalQuantities -\family default +\family default module defines -\family typewriter +\family typewriter PhysicalQuantity -\family default +\family default objects, but these must be declared as instances of a class. For example, to define -\family typewriter +\family typewriter v -\family default - as a velocity of 3\SpecialChar ~ +\family default + as a velocity of 3\InsetSpace ~ m/s, normally you would write: -\family typewriter +\family typewriter -\newline +\newline In [1]: v = PhysicalQuantity(3,'m/s') -\layout Standard +\end_layout +\begin_layout Standard Using the -\family typewriter +\family typewriter PhysicalQ_Input -\family default +\family default extension this can be input instead as: -\family typewriter +\family typewriter -\newline +\newline In [1]: v = 3 m/s -\family default +\family default -\newline +\newline which is much more convenient for interactive use (even though it is blatantly invalid Python syntax). -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter physics -\family default +\family default profile supplied with IPython (enabled via -\family typewriter +\family typewriter 'ipython -p physics' -\family default +\family default ) uses these extensions, which you can also activate with: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter from math import * # math MUST be imported BEFORE PhysicalQInteractive -\newline -from IPython.Extensions.PhysicalQInteractive import * -\newline -import IPython.Extensions.PhysicalQInput -\layout Section - - +\newline +from + IPython.Extensions.PhysicalQInteractive import * +\newline +import IPython.Extensions.PhysicalQ +Input +\end_layout + +\begin_layout Section \begin_inset LatexCommand \label{sec:IPython-as-shell} -\end_inset +\end_inset IPython as a system shell -\layout Standard +\end_layout +\begin_layout Standard IPython ships with a special profile called -\family typewriter +\family typewriter pysh -\family default +\family default , which you can activate at the command line as -\family typewriter +\family typewriter `ipython -p pysh' -\family default +\family default . This loads -\family typewriter +\family typewriter InterpreterExec -\family default +\family default , along with some additional facilities and a prompt customized for filesystem navigation. -\layout Standard +\end_layout +\begin_layout Standard Note that this does -\emph on +\emph on not -\emph default +\emph default make IPython a full-fledged system shell. In particular, it has no job control, so if you type Ctrl-Z (under Unix), you'll suspend pysh itself, not the process you just started. -\layout Standard +\end_layout +\begin_layout Standard What the shell profile allows you to do is to use the convenient and powerful syntax of Python to do quick scripting at the command line. Below we describe some of its features. -\layout Subsection +\end_layout +\begin_layout Subsection Aliases -\layout Standard +\end_layout +\begin_layout Standard All of your -\family typewriter +\family typewriter $PATH -\family default +\family default has been loaded as IPython aliases, so you should be able to type any normal system command and have it executed. See -\family typewriter +\family typewriter %alias? -\family default +\family default and -\family typewriter +\family typewriter %unalias? -\family default +\family default for details on the alias facilities. See also -\family typewriter +\family typewriter %rehash? -\family default +\family default and -\family typewriter +\family typewriter %rehashx? -\family default +\family default for details on the mechanism used to load -\family typewriter +\family typewriter $PATH -\family default +\family default . -\layout Subsection +\end_layout +\begin_layout Subsection Special syntax -\layout Standard +\end_layout +\begin_layout Standard Any lines which begin with -\family typewriter +\family typewriter `~' -\family default +\family default , -\family typewriter +\family typewriter `/' -\family default +\family default and -\family typewriter +\family typewriter `.' -\family default +\family default will be executed as shell commands instead of as Python code. The special escapes below are also recognized. -\family typewriter +\family typewriter !cmd -\family default +\family default is valid in single or multi-line input, all others are only valid in single-lin e input: -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter !cmd -\family default +\family default pass `cmd' directly to the shell -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter !!cmd -\family default +\family default execute `cmd' and return output as a list (split on ` -\backslash +\backslash n') -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter $var=cmd -\family default +\family default capture output of cmd into var, as a string -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter $$var=cmd -\family default +\family default capture output of cmd into var, as a list (split on ` -\backslash +\backslash n') -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter $ -\family default +\family default / -\family typewriter +\family typewriter $$ -\family default +\family default syntaxes make Python variables from system output, which you can later use for further scripting. The converse is also possible: when executing an alias or calling to the system via -\family typewriter +\family typewriter ! -\family default +\family default / -\family typewriter +\family typewriter !! -\family default +\family default , you can expand any python variable or expression by prepending it with -\family typewriter +\family typewriter $ -\family default +\family default . Full details of the allowed syntax can be found in Python's PEP 215. -\layout Standard +\end_layout +\begin_layout Standard A few brief examples will illustrate these (note that the indentation below may be incorrectly displayed): -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|3> !ls *s.py -\newline +\newline scopes.py strings.py -\layout Standard +\end_layout +\begin_layout Standard ls is an internal alias, so there's no need to use -\family typewriter +\family typewriter ! -\family default +\family default : -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|4> ls *s.py -\newline +\newline scopes.py* strings.py -\layout Standard +\end_layout +\begin_layout Standard !!ls will return the output into a Python variable: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|5> !!ls *s.py -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ <5> ['scopes.py', 'strings.py'] -\newline +\newline fperez[~/test]|6> print _5 -\newline -['scopes.py', 'strings.py'] -\layout Standard +\newline +['scopes.py', 'strings.py +'] +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter $ -\family default +\family default and -\family typewriter +\family typewriter $$ -\family default +\family default allow direct capture to named variables: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|7> $astr = ls *s.py -\newline +\newline fperez[~/test]|8> astr -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ <8> 'scopes.py -\backslash +\backslash nstrings.py' -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|9> $$alist = ls *s.py -\newline +\newline fperez[~/test]|10> alist -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ <10> ['scopes.py', 'strings.py'] -\layout Standard +\end_layout +\begin_layout Standard alist is now a normal python list you can loop over. Using -\family typewriter +\family typewriter $ -\family default +\family default will expand back the python values when alias calls are made: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|11> for f in alist: -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -|..> \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +|..> \InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ print 'file',f, -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -|..> \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +|..> \InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ wc -l $f -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed -\layout Standard +\begin_layout Standard -\backslash + +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ |..> -\newline +\newline file scopes.py 13 scopes.py -\newline +\newline file strings.py 4 strings.py -\layout Standard +\end_layout +\begin_layout Standard Note that you may need to protect your variables with braces if you want to append strings to their names. To copy all files in alist to -\family typewriter +\family typewriter .bak -\family default +\family default extensions, you must use: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|12> for f in alist: -\newline +\newline \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash hspace*{0mm} -\end_inset - -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -|..> \SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ +\end_layout + +\end_inset + +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +|..> \InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ +\InsetSpace ~ cp $f ${f}.bak -\layout Standard +\end_layout +\begin_layout Standard If you try using -\family typewriter +\family typewriter $f.bak -\family default +\family default , you'll get an AttributeError exception saying that your string object doesn't have a -\family typewriter +\family typewriter .bak -\family default +\family default attribute. This is because the -\family typewriter +\family typewriter $ -\family default +\family default expansion mechanism allows you to expand full Python expressions: -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter fperez[~/test]|13> echo "sys.platform is: $sys.platform" -\newline +\newline sys.platform is: linux2 -\layout Standard +\end_layout +\begin_layout Standard IPython's input history handling is still active, which allows you to rerun a single block of multi-line input by simply using exec: -\newline +\newline -\family typewriter +\family typewriter fperez[~/test]|14> $$alist = ls *.eps -\newline +\newline fperez[~/test]|15> exec _i11 -\newline -file image2.eps 921 image2.eps -\newline +\newline +file image2.eps + 921 image2.eps +\newline file image.eps 921 image.eps -\layout Standard +\end_layout +\begin_layout Standard While these are new special-case syntaxes, they are designed to allow very efficient use of the shell with minimal typing. At an interactive shell prompt, conciseness of expression wins over readability. -\layout Subsection +\end_layout +\begin_layout Subsection Useful functions and modules -\layout Standard +\end_layout +\begin_layout Standard The os, sys and shutil modules from the Python standard library are automaticall y loaded. Some additional functions, useful for shell usage, are listed below. You can request more help about them with ` -\family typewriter +\family typewriter ? -\family default +\family default '. -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter shell -\family default +\family default - execute a command in the underlying system shell -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter system -\family default +\family default - like -\family typewriter +\family typewriter shell() -\family default +\family default , but return the exit status of the command -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter sout -\family default +\family default - capture the output of a command as a string -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter lout -\family default +\family default - capture the output of a command as a list (split on ` -\backslash +\backslash n') -\layout Description +\end_layout +\begin_layout Description -\family typewriter +\family typewriter getoutputerror -\family default +\family default - capture (output,error) of a shell commandss -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter sout -\family default +\family default / -\family typewriter +\family typewriter lout -\family default +\family default are the functional equivalents of -\family typewriter +\family typewriter $ -\family default +\family default / -\family typewriter +\family typewriter $$ -\family default +\family default . They are provided to allow you to capture system output in the middle of true python code, function definitions, etc (where -\family typewriter +\family typewriter $ -\family default +\family default and -\family typewriter +\family typewriter $$ -\family default +\family default are invalid). -\layout Subsection +\end_layout +\begin_layout Subsection Directory management -\layout Standard +\end_layout +\begin_layout Standard Since each command passed by pysh to the underlying system is executed in a subshell which exits immediately, you can NOT use !cd to navigate the filesystem. -\layout Standard +\end_layout +\begin_layout Standard Pysh provides its own builtin -\family typewriter +\family typewriter `%cd -\family default +\family default ' magic command to move in the filesystem (the -\family typewriter +\family typewriter % -\family default +\family default is not required with automagic on). It also maintains a list of visited directories (use -\family typewriter +\family typewriter %dhist -\family default +\family default to see it) and allows direct switching to any of them. Type -\family typewriter +\family typewriter `cd? -\family default +\family default ' for more details. -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter %pushd -\family default +\family default , -\family typewriter +\family typewriter %popd -\family default +\family default and -\family typewriter +\family typewriter %dirs -\family default +\family default are provided for directory stack handling. -\layout Subsection +\end_layout +\begin_layout Subsection Prompt customization -\layout Standard +\end_layout +\begin_layout Standard The supplied -\family typewriter +\family typewriter ipythonrc-pysh -\family default +\family default profile comes with an example of a very colored and detailed prompt, mainly to serve as an illustration. The valid escape sequences, besides color names, are: -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash # - Prompt number. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash D - Dots, as many as there are digits in -\backslash +\backslash # (so they align). -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash w - Current working directory (cwd). -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash W - Basename of current working directory. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash X -\emph on +\emph on N -\emph default +\emph default - Where -\emph on +\emph on N -\emph default +\emph default =0..5. N terms of the cwd, with $HOME written as ~. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash Y -\emph on +\emph on N -\emph default +\emph default - Where -\emph on +\emph on N -\emph default +\emph default =0..5. Like X -\emph on +\emph on N -\emph default +\emph default , but if ~ is term -\emph on +\emph on N -\emph default +\emph default +1 it's also shown. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash u - Username. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash H - Full hostname. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash h - Hostname up to first '.' -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash $ - Root symbol ($ or #). -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash t - Current time, in H:M:S format. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash v - IPython release version. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash n - Newline. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash r - Carriage return. -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash -\backslash +\backslash - An explicitly escaped ' -\backslash +\backslash '. -\layout Standard +\end_layout +\begin_layout Standard You can configure your prompt colors using any ANSI color escape. Each color escape sets the color for any subsequent text, until another escape comes in and changes things. The valid color escapes are: -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Black -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Blue -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Brown -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Cyan -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_DarkGray -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Green -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_LightBlue -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_LightCyan -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_LightGray -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_LightGreen -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_LightPurple -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_LightRed -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Purple -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Red -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_White -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Yellow -\layout Description +\end_layout +\begin_layout Description -\backslash +\backslash C_Normal Stop coloring, defaults to your terminal settings. -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:Threading-support} -\end_inset +\end_inset Threading support -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold WARNING: -\series default +\series default The threading support is still somewhat experimental, and it has only seen reasonable testing under Linux. Threaded code is particularly tricky to debug, and it tends to show extremely @@ -7969,25 +8715,26 @@ The threading support is still somewhat experimental, and it has only seen Since I only have access to Linux machines, I will have to rely on user's experiences and assistance for this area of IPython to improve under other platforms. -\layout Standard +\end_layout +\begin_layout Standard IPython, via the -\family typewriter +\family typewriter -gthread -\family default +\family default , -\family typewriter +\family typewriter -qthread -\family default +\family default and -\family typewriter +\family typewriter -wthread -\family default - options (described in Sec.\SpecialChar ~ +\family default + options (described in Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:threading-opts} -\end_inset +\end_inset ), can run in multithreaded mode to support pyGTK, Qt and WXPython applications respectively. @@ -7995,181 +8742,193 @@ IPython, via the under a normal Python interpreter, starting a pyGTK, Qt or WXPython application will immediately freeze the shell. -\layout Standard +\end_layout +\begin_layout Standard IPython, with one of these options (you can only use one at a time), separates the graphical loop and IPython's code execution run into different threads. This allows you to test interactively (with -\family typewriter +\family typewriter %run -\family default +\family default , for example) your GUI code without blocking. -\layout Standard +\end_layout +\begin_layout Standard A nice mini-tutorial on using IPython along with the Qt Designer application is available at the SciPy wiki: \begin_inset LatexCommand \htmlurl{http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer} -\end_inset +\end_inset . -\layout Subsection +\end_layout +\begin_layout Subsection Tk issues -\layout Standard +\end_layout -As indicated in Sec.\SpecialChar ~ +\begin_layout Standard +As indicated in Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:threading-opts} -\end_inset +\end_inset , a special -\family typewriter +\family typewriter -tk -\family default +\family default option is provided to try and allow Tk graphical applications to coexist interactively with WX, Qt or GTK ones. Whether this works at all, however, is very platform and configuration dependent. Please experiment with simple test cases before committing to using this combination of Tk and GTK/Qt/WX threading in a production environment. -\layout Subsection +\end_layout +\begin_layout Subsection Signals and Threads -\layout Standard +\end_layout +\begin_layout Standard When any of the thread systems (GTK, Qt or WX) are active, either directly or via -\family typewriter +\family typewriter -pylab -\family default +\family default with a threaded backend, it is impossible to interrupt long-running Python code via -\family typewriter +\family typewriter Ctrl-C -\family default +\family default . IPython can not pass the KeyboardInterrupt exception (or the underlying -\family typewriter +\family typewriter SIGINT -\family default +\family default ) across threads, so any long-running process started from IPython will run to completion, or will have to be killed via an external (OS-based) mechanism. -\layout Standard +\end_layout +\begin_layout Standard To the best of my knowledge, this limitation is imposed by the Python interprete r itself, and it comes from the difficulty of writing portable signal/threaded code. If any user is an expert on this topic and can suggest a better solution, I would love to hear about it. In the IPython sources, look at the -\family typewriter +\family typewriter Shell.py -\family default +\family default module, and in particular at the -\family typewriter +\family typewriter runcode() -\family default +\family default method. -\layout Subsection +\end_layout +\begin_layout Subsection I/O pitfalls -\layout Standard +\end_layout +\begin_layout Standard Be mindful that the Python interpreter switches between threads every \begin_inset Formula $N$ -\end_inset +\end_inset - bytecodes, where the default value as of Python\SpecialChar ~ + bytecodes, where the default value as of Python\InsetSpace ~ 2.3 is \begin_inset Formula $N=100.$ -\end_inset +\end_inset This value can be read by using the -\family typewriter +\family typewriter sys.getcheckinterval() -\family default +\family default function, and it can be reset via -\family typewriter +\family typewriter sys.setcheckinterval( -\emph on +\emph on N -\emph default +\emph default ) -\family default +\family default . This switching of threads can cause subtly confusing effects if one of your threads is doing file I/O. In text mode, most systems only flush file buffers when they encounter a -\family typewriter +\family typewriter ` -\backslash +\backslash n' -\family default +\family default . An instruction as simple as -\family typewriter +\family typewriter -\newline -\SpecialChar ~ -\SpecialChar ~ +\newline +\InsetSpace ~ +\InsetSpace ~ print >> filehandle, \begin_inset Quotes eld -\end_inset +\end_inset hello world \begin_inset Quotes erd -\end_inset +\end_inset -\family default +\family default -\newline +\newline actually consists of several bytecodes, so it is possible that the newline does not reach your file before the next thread switch. Similarly, if you are writing to a file in binary mode, the file won't be flushed until the buffer fills, and your other thread may see apparently truncated files. -\layout Standard +\end_layout +\begin_layout Standard For this reason, if you are using IPython's thread support and have (for example) a GUI application which will read data generated by files written to from the IPython thread, the safest approach is to open all of your files in unbuffered mode (the third argument to the -\family typewriter +\family typewriter file/open -\family default +\family default function is the buffering value): -\newline +\newline -\family typewriter -\SpecialChar ~ -\SpecialChar ~ +\family typewriter +\InsetSpace ~ +\InsetSpace ~ filehandle = open(filename,mode,0) -\layout Standard +\end_layout +\begin_layout Standard This is obviously a brute force way of avoiding race conditions with the file buffering. If you want to do it cleanly, and you have a resource which is being shared by the interactive IPython loop and your GUI thread, you should really handle it with thread locking and syncrhonization properties. The Python documentation discusses these. -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:interactive-demos} -\end_inset +\end_inset Interactive demos with IPython -\layout Standard +\end_layout +\begin_layout Standard IPython ships with a basic system for running scripts interactively in sections, useful when presenting code to audiences. A few tags embedded in comments (so that the script remains valid Python @@ -8178,90 +8937,103 @@ IPython ships with a basic system for running scripts interactively in sections, executing it, and returning to the interactive prompt after each block. The interactive namespace is updated after each block is run with the contents of the demo's namespace. -\layout Standard +\end_layout +\begin_layout Standard This allows you to show a piece of code, run it and then execute interactively commands based on the variables just created. Once you want to continue, you simply execute the next block of the demo. The following listing shows the markup necessary for dividing a script into sections for execution as a demo. -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset ERT -status Open +status open + +\begin_layout Standard -\layout Standard -\backslash +\backslash codelist{examples/example-demo.py} -\end_inset +\end_layout +\end_inset -\layout Standard +\end_layout + +\begin_layout Standard In order to run a file as a demo, you must first make a -\family typewriter +\family typewriter Demo -\family default +\family default object out of it. If the file is named -\family typewriter +\family typewriter myscript.py -\family default +\family default , the following code will make a demo: -\layout LyX-Code +\end_layout +\begin_layout LyX-Code from IPython.demo import Demo -\layout LyX-Code +\end_layout +\begin_layout LyX-Code mydemo = Demo('myscript.py') -\layout Standard +\end_layout +\begin_layout Standard This creates the -\family typewriter +\family typewriter mydemo -\family default +\family default object, whose blocks you run one at a time by simply calling the object with no arguments. If you have autocall active in IPython (the default), all you need to do is type -\layout LyX-Code +\end_layout +\begin_layout LyX-Code mydemo -\layout Standard +\end_layout +\begin_layout Standard and IPython will call it, executing each block. Demo objects can be restarted, you can move forward or back skipping blocks, re-execute the last block, etc. Simply use the Tab key on a demo object to see its methods, and call -\family typewriter +\family typewriter `?' -\family default +\family default on them to see their docstrings for more usage details. In addition, the -\family typewriter +\family typewriter demo -\family default +\family default module itself contains a comprehensive docstring, which you can access via -\layout LyX-Code +\end_layout +\begin_layout LyX-Code from IPython import demo -\layout LyX-Code +\end_layout +\begin_layout LyX-Code demo? -\layout Standard +\end_layout +\begin_layout Standard -\series bold +\series bold Limitations: -\series default +\series default It is important to note that these demos are limited to fairly simple uses. In particular, you can -\emph on +\emph on not -\emph default +\emph default put division marks in indented code (loops, if statements, function definitions , etc.) Supporting something like this would basically require tracking the internal execution state of the Python interpreter, so only top-level divisions @@ -8269,385 +9041,417 @@ not If you want to be able to open an IPython instance at an arbitrary point in a program, you can use IPython's embedding facilities, described in detail in Sec\SpecialChar \@. -\SpecialChar ~ +\InsetSpace ~ \begin_inset LatexCommand \ref{sec:embed} -\end_inset +\end_inset . -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:matplotlib-support} -\end_inset +\end_inset Plotting with -\family typewriter +\family typewriter matplotlib -\family default +\family default -\layout Standard +\end_layout +\begin_layout Standard The matplotlib library ( \begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net} -\end_inset +\end_inset ) provides high quality 2D plotting for Python. Matplotlib can produce plots on screen using a variety of GUI toolkits, including Tk, GTK and WXPython. It also provides a number of commands useful for scientific computing, all with a syntax compatible with that of the popular Matlab program. -\layout Standard +\end_layout +\begin_layout Standard IPython accepts the special option -\family typewriter +\family typewriter -pylab -\family default - (Sec.\SpecialChar ~ +\family default + (Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:cmd-line-opts} -\end_inset +\end_inset ). This configures it to support matplotlib, honoring the settings in the -\family typewriter +\family typewriter .matplotlibrc -\family default +\family default file. IPython will detect the user's choice of matplotlib GUI backend, and automatica lly select the proper threading model to prevent blocking. It also sets matplotlib in interactive mode and modifies -\family typewriter +\family typewriter %run -\family default +\family default slightly, so that any matplotlib-based script can be executed using -\family typewriter +\family typewriter %run -\family default +\family default and the final -\family typewriter +\family typewriter show() -\family default +\family default command does not block the interactive shell. -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter -pylab -\family default +\family default option must be given first in order for IPython to configure its threading mode. However, you can still issue other options afterwards. This allows you to have a matplotlib-based environment customized with - additional modules using the standard IPython profile mechanism (Sec.\SpecialChar ~ + additional modules using the standard IPython profile mechanism (Sec.\InsetSpace ~ \begin_inset LatexCommand \ref{sec:profiles} -\end_inset +\end_inset ): `` -\family typewriter +\family typewriter ipython -pylab -p myprofile -\family default +\family default '' will load the profile defined in -\family typewriter +\family typewriter ipythonrc-myprofile -\family default +\family default after configuring matplotlib. -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:Gnuplot} -\end_inset +\end_inset Plotting with -\family typewriter +\family typewriter Gnuplot -\layout Standard +\end_layout +\begin_layout Standard Through the magic extension system described in sec. \begin_inset LatexCommand \ref{sec:magic} -\end_inset +\end_inset , IPython incorporates a mechanism for conveniently interfacing with the Gnuplot system ( \begin_inset LatexCommand \htmlurl{http://www.gnuplot.info} -\end_inset +\end_inset ). Gnuplot is a very complete 2D and 3D plotting package available for many operating systems and commonly included in modern Linux distributions. -\layout Standard +\end_layout +\begin_layout Standard Besides having Gnuplot installed, this functionality requires the -\family typewriter +\family typewriter Gnuplot.py -\family default +\family default module for interfacing python with Gnuplot. It can be downloaded from: \begin_inset LatexCommand \htmlurl{http://gnuplot-py.sourceforge.net} -\end_inset +\end_inset . -\layout Subsection +\end_layout +\begin_layout Subsection Proper Gnuplot configuration -\layout Standard +\end_layout +\begin_layout Standard As of version 4.0, Gnuplot has excellent mouse and interactive keyboard support. However, as of -\family typewriter +\family typewriter Gnuplot.py -\family default +\family default version 1.7, a new option was added to communicate between Python and Gnuplot via FIFOs (pipes). This mechanism, while fast, also breaks the mouse system. You must therefore set the variable -\family typewriter +\family typewriter prefer_fifo_data -\family default +\family default to -\family typewriter +\family typewriter 0 -\family default +\family default in file -\family typewriter +\family typewriter gp_unix.py -\family default +\family default if you wish to keep the interactive mouse and keyboard features working properly ( -\family typewriter +\family typewriter prefer_inline_data -\family default +\family default also must be -\family typewriter +\family typewriter 0 -\family default +\family default , but this is the default so unless you've changed it manually you should be fine). -\layout Standard +\end_layout +\begin_layout Standard 'Out of the box', Gnuplot is configured with a rather poor set of size, color and linewidth choices which make the graphs fairly hard to read on modern high-resolution displays (although they work fine on old 640x480 ones). Below is a section of my -\family typewriter +\family typewriter .Xdefaults -\family default +\family default file which I use for having a more convenient Gnuplot setup. Remember to load it by running -\family typewriter +\family typewriter `xrdb .Xdefaults` -\family default +\family default : -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter !****************************************************************** -\newline -! gnuplot options -\newline +\newline +! gnuplot + options +\newline ! modify this for a convenient window size -\newline +\newline gnuplot*geometry: 780x580 -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter ! on-screen font (not for PostScript) -\newline -gnuplot*font: -misc-fixed-bold-r-normal--15-120-100-100-c-90-iso8859-1 -\layout Standard +\newline +gnuplot*font: -misc-fixed-bold-r-normal--15 +-120-100-100-c-90-iso8859-1 +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter ! color options -\newline +\newline gnuplot*background: black -\newline +\newline gnuplot*textColor: white -\newline -gnuplot*borderColor: white -\newline +\newline +gnuplot*borderCo +lor: white +\newline gnuplot*axisColor: white -\newline +\newline gnuplot*line1Color: red -\newline -gnuplot*line2Color: green -\newline +\newline +gnuplot*line2Color: + green +\newline gnuplot*line3Color: blue -\newline +\newline gnuplot*line4Color: magenta -\newline -gnuplot*line5Color: cyan -\newline +\newline +gnuplot*line5Color: + cyan +\newline gnuplot*line6Color: sienna -\newline +\newline gnuplot*line7Color: orange -\newline -gnuplot*line8Color: coral -\layout Standard +\newline +gnuplot*line8Color: + coral +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter ! multiplicative factor for point styles -\newline +\newline gnuplot*pointsize: 2 -\layout Standard +\end_layout +\begin_layout Standard -\family typewriter +\family typewriter ! line width options (in pixels) -\newline +\newline gnuplot*borderWidth: 2 -\newline -gnuplot*axisWidth: 2 -\newline +\newline +gnuplot*axisWidth: + 2 +\newline gnuplot*line1Width: 2 -\newline +\newline gnuplot*line2Width: 2 -\newline +\newline gnuplot*line3Width: 2 -\newline -gnuplot*line4Width: 2 -\newline +\newline +gnuplot*line4Wi +dth: 2 +\newline gnuplot*line5Width: 2 -\newline +\newline gnuplot*line6Width: 2 -\newline +\newline gnuplot*line7Width: 2 -\newline -gnuplot*line8Width: 2 -\layout Subsection +\newline +gnuplot*lin +e8Width: 2 +\end_layout +\begin_layout Subsection The -\family typewriter +\family typewriter IPython.GnuplotRuntime -\family default +\family default module -\layout Standard +\end_layout +\begin_layout Standard IPython includes a module called -\family typewriter +\family typewriter Gnuplot2.py -\family default +\family default which extends and improves the default -\family typewriter +\family typewriter Gnuplot -\family default +\family default . -\family typewriter +\family typewriter py -\family default +\family default (which it still relies upon). For example, the new -\family typewriter +\family typewriter plot -\family default +\family default function adds several improvements to the original making it more convenient for interactive use, and -\family typewriter +\family typewriter hardcopy -\family default +\family default fixes a bug in the original which under some circumstances blocks the creation of PostScript output. -\layout Standard +\end_layout +\begin_layout Standard For scripting use, -\family typewriter +\family typewriter GnuplotRuntime.py -\family default +\family default is provided, which wraps -\family typewriter +\family typewriter Gnuplot2.py -\family default +\family default and creates a series of global aliases. These make it easy to control Gnuplot plotting jobs through the Python language. -\layout Standard +\end_layout +\begin_layout Standard Below is some example code which illustrates how to configure Gnuplot inside your own programs but have it available for further interactive use through an embedded IPython instance. Simply run this file at a system prompt. This file is provided as -\family typewriter +\family typewriter example-gnuplot.py -\family default +\family default in the examples directory: -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset ERT -status Open +status open + +\begin_layout Standard -\layout Standard -\backslash +\backslash codelist{examples/example-gnuplot.py} -\end_inset +\end_layout +\end_inset -\layout Subsection +\end_layout + +\begin_layout Subsection The -\family typewriter +\family typewriter numeric -\family default +\family default profile: a scientific computing environment -\layout Standard +\end_layout +\begin_layout Standard The -\family typewriter +\family typewriter numeric -\family default +\family default IPython profile, which you can activate with -\family typewriter +\family typewriter `ipython -p numeric -\family default +\family default ' will automatically load the IPython Gnuplot extensions (plus Numeric and other useful things for numerical computing), contained in the -\family typewriter +\family typewriter IPython.GnuplotInteractive -\family default +\family default module. This will create the globals -\family typewriter +\family typewriter Gnuplot -\family default +\family default (an alias to the improved Gnuplot2 module), -\family typewriter +\family typewriter gp -\family default +\family default (a Gnuplot active instance), the new magic commands -\family typewriter +\family typewriter %gpc -\family default +\family default and -\family typewriter +\family typewriter %gp_set_instance -\family default +\family default and several other convenient globals. Type -\family typewriter +\family typewriter gphelp() -\family default +\family default for further details. -\layout Standard +\end_layout +\begin_layout Standard This should turn IPython into a convenient environment for numerical computing, with all the functions in the NumPy library and the Gnuplot facilities for plotting. @@ -8655,44 +9459,49 @@ This should turn IPython into a convenient environment for numerical computing, scientific computing, available at \begin_inset LatexCommand \htmlurl{http://scipy.org} -\end_inset +\end_inset . -\layout Standard +\end_layout +\begin_layout Standard If you are in the middle of a working session with numerical objects and need to plot them but you didn't start the -\family typewriter +\family typewriter numeric -\family default +\family default profile, you can load these extensions at any time by typing -\newline +\newline -\family typewriter +\family typewriter from IPython.GnuplotInteractive import * -\newline +\newline -\family default +\family default at the IPython prompt. This will allow you to keep your objects intact and start using Gnuplot to view them. -\layout Section +\end_layout +\begin_layout Section Reporting bugs -\layout Subsection* +\end_layout +\begin_layout Subsection* Automatic crash reports -\layout Standard +\end_layout +\begin_layout Standard Ideally, IPython itself shouldn't crash. It will catch exceptions produced by you, but bugs in its internals will still crash it. -\layout Standard +\end_layout +\begin_layout Standard In such a situation, IPython will leave a file named -\family typewriter +\family typewriter IPython_crash_report.txt -\family default +\family default in your IPYTHONDIR directory (that way if crashes happen several times it won't litter many directories, the post-mortem file is always located in the same place and new occurrences just overwrite the previous one). @@ -8700,86 +9509,99 @@ IPython_crash_report.txt \begin_inset LatexCommand \ref{sec:credits} -\end_inset +\end_inset for names and addresses), it will help us -\emph on +\emph on a lot -\emph default +\emph default in understanding the cause of the problem and fixing it sooner. -\layout Subsection* +\end_layout +\begin_layout Subsection* The bug tracker -\layout Standard +\end_layout +\begin_layout Standard IPython also has an online bug-tracker, located at \begin_inset LatexCommand \htmlurl{http://projects.scipy.org/ipython/ipython/report/1} -\end_inset +\end_inset . In addition to mailing the developers, it would be a good idea to file a bug report here. This will ensure that the issue is properly followed to conclusion. To report new bugs you will have to register first. -\layout Standard +\end_layout +\begin_layout Standard You can also use this bug tracker to file feature requests. -\layout Section +\end_layout +\begin_layout Section Brief history -\layout Subsection +\end_layout +\begin_layout Subsection Origins -\layout Standard +\end_layout +\begin_layout Standard The current IPython system grew out of the following three projects: -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 ipython by Fernando P \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash '{e} -\end_inset +\end_layout + +\end_inset rez. I was working on adding Mathematica-type prompts and a flexible configuration system (something better than -\family typewriter +\family typewriter $PYTHONSTARTUP -\family default +\family default ) to the standard Python interactive interpreter. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 IPP by Janko Hauser. Very well organized, great usability. Had an old help system. IPP was used as the `container' code into which I added the functionality from ipython and LazyPython. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 LazyPython by Nathan Gray. Simple but -\emph on +\emph on very -\emph default +\emph default powerful. The quick syntax (auto parens, auto quotes) and verbose/colored tracebacks were all taken from here. -\layout Standard +\end_layout +\begin_layout Standard When I found out (see sec. \begin_inset LatexCommand \ref{figgins} -\end_inset +\end_inset ) about IPP and LazyPython I tried to join all three into a unified system. I thought this could provide a very nice working environment, both for @@ -8788,17 +9610,20 @@ When I found out (see sec. and help facilities. I think it worked reasonably well, though it was a lot more work than I had initially planned. -\layout Subsection +\end_layout +\begin_layout Subsection Current status -\layout Standard +\end_layout +\begin_layout Standard The above listed features work, and quite well for the most part. But until a major internal restructuring is done (see below), only bug fixing will be done, no other features will be added (unless very minor and well localized in the cleaner parts of the code). -\layout Standard +\end_layout +\begin_layout Standard IPython consists of some 18000 lines of pure python code, of which roughly two thirds is reasonably clean. The rest is, messy code which needs a massive restructuring before any @@ -8806,98 +9631,112 @@ IPython consists of some 18000 lines of pure python code, of which roughly Even the messy code is fairly well documented though, and most of the problems in the (non-existent) class design are well pointed to by a PyChecker run. So the rewriting work isn't that bad, it will just be time-consuming. -\layout Subsection +\end_layout +\begin_layout Subsection Future -\layout Standard +\end_layout +\begin_layout Standard See the separate -\family typewriter +\family typewriter new_design -\family default +\family default document for details. Ultimately, I would like to see IPython become part of the standard Python distribution as a `big brother with batteries' to the standard Python interacti ve interpreter. But that will never happen with the current state of the code, so all contribut ions are welcome. -\layout Section +\end_layout +\begin_layout Section License -\layout Standard +\end_layout +\begin_layout Standard IPython is released under the terms of the BSD license, whose general form can be found at: \begin_inset LatexCommand \htmlurl{http://www.opensource.org/licenses/bsd-license.php} -\end_inset +\end_inset . The full text of the IPython license is reproduced below: -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small IPython is released under a BSD-type license. -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez . -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small Copyright (c) 2001 Janko Hauser and -\newline -Nathaniel Gray . -\layout Quote +\newline +Nathaniel Gray . +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small All rights reserved. -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small a. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small b. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small c. Neither the name of the copyright holders nor the names of any contributors to this software may be used to endorse or promote products derived from this software without specific prior written permission. -\layout Quote +\end_layout +\begin_layout Quote -\family typewriter -\size small +\family typewriter +\size small THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR @@ -8910,640 +9749,712 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -\layout Standard +\end_layout +\begin_layout Standard Individual authors are the holders of the copyright for their code and are listed in each file. -\layout Standard +\end_layout +\begin_layout Standard Some files ( -\family typewriter +\family typewriter DPyGetOpt.py -\family default +\family default , for example) may be licensed under different conditions. Ultimately each file indicates clearly the conditions under which its author/au thors have decided to publish the code. -\layout Standard +\end_layout +\begin_layout Standard Versions of IPython up to and including 0.6.3 were released under the GNU Lesser General Public License (LGPL), available at \begin_inset LatexCommand \htmlurl{http://www.gnu.org/copyleft/lesser.html} -\end_inset +\end_inset . -\layout Section - +\end_layout +\begin_layout Section \begin_inset LatexCommand \label{sec:credits} -\end_inset +\end_inset Credits -\layout Standard +\end_layout +\begin_layout Standard IPython is mainly developed by Fernando P \begin_inset ERT -status Collapsed +status collapsed + +\begin_layout Standard -\layout Standard -\backslash +\backslash '{e} -\end_inset +\end_layout + +\end_inset rez -\family typewriter +\family typewriter -\family default +\family default , but the project was born from mixing in Fernando's code with the IPP project by Janko Hauser -\family typewriter +\family typewriter -\family default +\family default and LazyPython by Nathan Gray -\family typewriter +\family typewriter -\family default +\family default . For all IPython-related requests, please contact Fernando. -\layout Standard +\end_layout +\begin_layout Standard As of early 2006, the following developers have joined the core team: -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Robert\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Robert\InsetSpace ~ Kern -\family typewriter +\family typewriter -\family default +\family default : co-mentored the 2005 Google Summer of Code project to develop python interacti ve notebooks (XML documents) and graphical interface. This project was awarded to the students Tzanko Matev -\family typewriter +\family typewriter -\family default +\family default and Toni Alatalo -\family typewriter +\family typewriter -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Brian\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Brian\InsetSpace ~ Granger -\family typewriter +\family typewriter -\family default +\family default : extending IPython to allow support for interactive parallel computing. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Ville\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Ville\InsetSpace ~ Vainio -\family typewriter +\family typewriter -\family default +\family default : Ville is the new maintainer for the main trunk of IPython after version 0.7.1. -\layout Standard +\end_layout +\begin_layout Standard User or development help should be requested via the IPython mailing lists: -\layout Description +\end_layout -User\SpecialChar ~ +\begin_layout Description +User\InsetSpace ~ list: \begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-user} -\end_inset +\end_inset -\layout Description +\end_layout -Developer's\SpecialChar ~ +\begin_layout Description +Developer's\InsetSpace ~ list: \begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-dev} -\end_inset +\end_inset -\layout Standard +\end_layout +\begin_layout Standard The IPython project is also very grateful to \begin_inset Foot -collapsed true - -\layout Standard +status collapsed +\begin_layout Standard I've mangled email addresses to reduce spam, since the IPython manuals can be accessed online. -\end_inset +\end_layout + +\end_inset : -\layout Standard +\end_layout +\begin_layout Standard Bill Bumgarner -\family typewriter +\family typewriter -\family default +\family default : for providing the DPyGetOpt module which gives very powerful and convenient handling of command-line options (light years ahead of what Python 2.1.1's getopt module does). -\layout Standard +\end_layout +\begin_layout Standard Ka-Ping Yee -\family typewriter +\family typewriter -\family default +\family default : for providing the Itpl module for convenient and powerful string interpolation with a much nicer syntax than formatting through the '%' operator. -\layout Standard +\end_layout +\begin_layout Standard Arnd Baecker -\family typewriter +\family typewriter -\family default +\family default : for his many very useful suggestions and comments, and lots of help with testing and documentation checking. Many of IPython's newer features are a result of discussions with him (bugs are still my fault, not his). -\layout Standard +\end_layout -Obviously Guido van\SpecialChar ~ +\begin_layout Standard +Obviously Guido van\InsetSpace ~ Rossum and the whole Python development team, that goes without saying. -\layout Standard +\end_layout +\begin_layout Standard IPython's website is generously hosted at \begin_inset LatexCommand \htmlurl{http://ipython.scipy.org} -\end_inset +\end_inset by Enthought ( \begin_inset LatexCommand \htmlurl{http://www.enthought.com} -\end_inset +\end_inset ). I am very grateful to them and all of the SciPy team for their contribution. -\layout Standard - +\end_layout +\begin_layout Standard \begin_inset LatexCommand \label{figgins} -\end_inset +\end_inset Fernando would also like to thank Stephen Figgins -\family typewriter +\family typewriter -\family default +\family default , an O'Reilly Python editor. His Oct/11/2001 article about IPP and LazyPython, was what got this project started. You can read it at: \begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html} -\end_inset +\end_inset . -\layout Standard +\end_layout +\begin_layout Standard And last but not least, all the kind IPython users who have emailed new code, bug reports, fixes, comments and ideas. A brief list follows, please let me know if I have ommitted your name by accident: -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Jack\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Jack\InsetSpace ~ Moffit -\family typewriter +\family typewriter -\family default +\family default Bug fixes, including the infamous color problem. This bug alone caused many lost hours and frustration, many thanks to him for the fix. I've always been a fan of Ogg & friends, now I have one more reason to like these folks. -\newline -Jack is also contributing with Debian packaging and many other things. -\layout List -\labelwidthstring 00.00.0000 +\newline +Jack is also contributing with Debian packaging and many + other things. +\end_layout -Alexander\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Alexander\InsetSpace ~ Schmolck -\family typewriter +\family typewriter -\family default +\family default Emacs work, bug reports, bug fixes, ideas, lots more. The ipython.el mode for (X)Emacs is Alex's code, providing full support for IPython under (X)Emacs. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Andrea\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Andrea\InsetSpace ~ Riciputi -\family typewriter +\family typewriter -\family default +\family default Mac OSX information, Fink package management. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Gary\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Gary\InsetSpace ~ Bishop -\family typewriter +\family typewriter -\family default +\family default Bug reports, and patches to work around the exception handling idiosyncracies of WxPython. Readline and color support for Windows. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Jeffrey\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Jeffrey\InsetSpace ~ Collins -\family typewriter +\family typewriter -\family default +\family default Bug reports. Much improved readline support, including fixes for Python 2.3. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Dryice\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Dryice\InsetSpace ~ Liu -\family typewriter +\family typewriter -\family default +\family default FreeBSD port. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Mike\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Mike\InsetSpace ~ Heeter -\family typewriter +\family typewriter -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Christopher\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Christopher\InsetSpace ~ Hart -\family typewriter +\family typewriter -\family default +\family default PDB integration. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Milan\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Milan\InsetSpace ~ Zamazal -\family typewriter +\family typewriter -\family default +\family default Emacs info. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Philip\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Philip\InsetSpace ~ Hisley -\family typewriter +\family typewriter -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Holger\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Holger\InsetSpace ~ Krekel -\family typewriter +\family typewriter -\family default +\family default Tab completion, lots more. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Robin\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Robin\InsetSpace ~ Siebler -\family typewriter +\family typewriter -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Ralf\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Ralf\InsetSpace ~ Ahlbrink -\family typewriter +\family typewriter -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Thorsten\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Thorsten\InsetSpace ~ Kampe -\family typewriter +\family typewriter -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Fredrik\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Fredrik\InsetSpace ~ Kant -\family typewriter +\family typewriter -\family default +\family default Windows setup. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Syver\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Syver\InsetSpace ~ Enstad -\family typewriter +\family typewriter -\family default +\family default Windows setup. -\layout List -\labelwidthstring 00.00.0000 +\end_layout +\begin_layout List +\labelwidthstring 00.00.0000 Richard -\family typewriter +\family typewriter -\family default +\family default Global embedding. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Hayden\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Hayden\InsetSpace ~ Callow -\family typewriter +\family typewriter -\family default +\family default Gnuplot.py 1.6 compatibility. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Leonardo\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Leonardo\InsetSpace ~ Santagada -\family typewriter +\family typewriter -\family default +\family default Fixes for Windows installation. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Christopher\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Christopher\InsetSpace ~ Armstrong -\family typewriter +\family typewriter -\family default +\family default Bugfixes. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Francois\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Francois\InsetSpace ~ Pinard -\family typewriter +\family typewriter -\family default +\family default Code and documentation fixes. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Cory\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Cory\InsetSpace ~ Dodt -\family typewriter +\family typewriter -\family default +\family default Bug reports and Windows ideas. Patches for Windows installer. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Olivier\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Olivier\InsetSpace ~ Aubert -\family typewriter +\family typewriter -\family default +\family default New magics. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -King\SpecialChar ~ -C.\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +King\InsetSpace ~ +C.\InsetSpace ~ Shu -\family typewriter +\family typewriter -\family default +\family default Autoindent patch. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Chris\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Chris\InsetSpace ~ Drexler -\family typewriter +\family typewriter -\family default +\family default Readline packages for Win32/CygWin. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Gustavo\SpecialChar ~ -Cordova\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Gustavo\InsetSpace ~ +Cordova\InsetSpace ~ Avila -\family typewriter +\family typewriter -\family default +\family default EvalDict code for nice, lightweight string interpolation. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Kasper\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Kasper\InsetSpace ~ Souren -\family typewriter +\family typewriter -\family default +\family default Bug reports, ideas. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Gever\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Gever\InsetSpace ~ Tulley -\family typewriter +\family typewriter -\family default +\family default Code contributions. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Ralf\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Ralf\InsetSpace ~ Schmitt -\family typewriter +\family typewriter -\family default +\family default Bug reports & fixes. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Oliver\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Oliver\InsetSpace ~ Sander -\family typewriter +\family typewriter -\family default +\family default Bug reports. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Rod\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Rod\InsetSpace ~ Holland -\family typewriter +\family typewriter -\family default +\family default Bug reports and fixes to logging module. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Daniel\SpecialChar ~ -'Dang'\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Daniel\InsetSpace ~ +'Dang'\InsetSpace ~ Griffith -\family typewriter +\family typewriter -\family default +\family default Fixes, enhancement suggestions for system shell use. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Viktor\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Viktor\InsetSpace ~ Ransmayr -\family typewriter +\family typewriter -\family default +\family default Tests and reports on Windows installation issues. Contributed a true Windows binary installer. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Mike\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Mike\InsetSpace ~ Salib -\family typewriter +\family typewriter -\family default +\family default Help fixing a subtle bug related to traceback printing. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -W.J.\SpecialChar ~ -van\SpecialChar ~ -der\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +W.J.\InsetSpace ~ +van\InsetSpace ~ +der\InsetSpace ~ Laan -\family typewriter +\family typewriter -\family default +\family default Bash-like prompt specials. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Antoon\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Antoon\InsetSpace ~ Pardon -\family typewriter +\family typewriter -\family default +\family default Critical fix for the multithreaded IPython. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -John\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +John\InsetSpace ~ Hunter -\family typewriter +\family typewriter -\family default +\family default Matplotlib author, helped with all the development of support for matplotlib in IPyhton, including making necessary changes to matplotlib itself. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Matthew\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Matthew\InsetSpace ~ Arnison -\family typewriter +\family typewriter -\family default +\family default Bug reports, ` -\family typewriter +\family typewriter %run -d -\family default +\family default ' idea. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Prabhu\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Prabhu\InsetSpace ~ Ramachandran -\family typewriter +\family typewriter -\family default +\family default Help with (X)Emacs support, threading patches, ideas... -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Norbert\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Norbert\InsetSpace ~ Tretkowski -\family typewriter +\family typewriter -\family default +\family default help with Debian packaging and distribution. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -George\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +George\InsetSpace ~ Sakkis < -\family typewriter +\family typewriter gsakkis-AT-eden.rutgers.edu> -\family default +\family default New matcher for tab-completing named arguments of user-defined functions. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -J�rgen\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +J�rgen\InsetSpace ~ Stenarson -\family typewriter +\family typewriter -\family default +\family default Wildcard support implementation for searching namespaces. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Vivian\SpecialChar ~ -De\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Vivian\InsetSpace ~ +De\InsetSpace ~ Smedt -\family typewriter +\family typewriter -\family default +\family default Debugger enhancements, so that when pdb is activated from within IPython, coloring, tab completion and other features continue to work seamlessly. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Scott\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Scott\InsetSpace ~ Tsai -\family typewriter +\family typewriter -\family default +\family default Support for automatic editor invocation on syntax errors (see \begin_inset LatexCommand \htmlurl{http://www.scipy.net/roundup/ipython/issue36} -\end_inset +\end_inset ). -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Alexander\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Alexander\InsetSpace ~ Belchenko -\family typewriter +\family typewriter -\family default +\family default Improvements for win32 paging system. -\layout List -\labelwidthstring 00.00.0000 +\end_layout -Will\SpecialChar ~ +\begin_layout List +\labelwidthstring 00.00.0000 +Will\InsetSpace ~ Maier -\family typewriter +\family typewriter -\family default +\family default Official OpenBSD port. -\the_end +\end_layout + +\end_body +\end_document diff --git a/win32_manual_post_install.py b/win32_manual_post_install.py index 40addde..9475afb 100644 --- a/win32_manual_post_install.py +++ b/win32_manual_post_install.py @@ -88,6 +88,11 @@ def run(wait=0): # make shortcuts for IPython, html and pdf docs. print 'Making entries for IPython in Start Menu...', + # Create .bat file in \\Scripts + fic = open(sys.prefix + '\\Scripts\\ipython.bat','w') + fic.write('"' + sys.prefix + '\\python.exe' + '" -i ' + '"' + sys.prefix + '\\Scripts\ipython" %*') + fic.close() + # Create shortcuts in Programs\IPython: if not os.path.isdir(ip_prog_dir): os.mkdir(ip_prog_dir)