diff --git a/IPython/Release.py b/IPython/Release.py index b06094b..72e896e 100644 --- a/IPython/Release.py +++ b/IPython/Release.py @@ -22,7 +22,7 @@ name = 'ipython' # because bdist_rpm does not accept dashes (an RPM) convention, and # bdist_deb does not accept underscores (a Debian convention). -revision = '96' +revision = '109' branch = 'ipython' if branch == 'ipython': diff --git a/IPython/external/path.py b/IPython/external/path.py index 038d7ce..6b0f952 100644 --- a/IPython/external/path.py +++ b/IPython/external/path.py @@ -29,7 +29,10 @@ Date: 9 Mar 2007 from __future__ import generators -import sys, warnings, os, fnmatch, glob, shutil, codecs, md5 +import sys, warnings, os, fnmatch, glob, shutil, codecs +# deprecated in python 2.6 +warnings.filterwarnings('ignore', r'.*md5.*') +import md5 __version__ = '2.2' __all__ = ['path'] diff --git a/IPython/iplib.py b/IPython/iplib.py index 1bb1650..03846f8 100644 --- a/IPython/iplib.py +++ b/IPython/iplib.py @@ -54,6 +54,8 @@ import sys import tempfile import traceback import types +import warnings +warnings.filterwarnings('ignore', r'.*sets module*') from sets import Set from pprint import pprint, pformat diff --git a/MANIFEST.in b/MANIFEST.in index 4e3de84..d3bd989 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -22,6 +22,12 @@ exclude doc/manual/*.log exclude doc/manual/*.out exclude doc/manual/*.pl exclude doc/manual/*.tex +exclude doc/build/doctrees/* +exclude doc/build/latex/* +exclude doc/build/html/_sources/* + + + global-exclude *~ global-exclude *.flc diff --git a/doc/do_sphinx.py b/doc/do_sphinx.py index 6a1455a..296061e 100644 --- a/doc/do_sphinx.py +++ b/doc/do_sphinx.py @@ -60,5 +60,5 @@ if sys.platform != 'win32': oscmd('makeindex -s python.ist modipython.idx') oscmd('pdflatex ipython.tex') oscmd('pdflatex ipython.tex') - + oscmd('cp ipython.pdf ../html') os.chdir('../..') diff --git a/doc/manual_base.lyx b/doc/manual_base.lyx deleted file mode 100644 index 3f385cd..0000000 --- a/doc/manual_base.lyx +++ /dev/null @@ -1,10507 +0,0 @@ -#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} -\usepackage{color} - -% A few colors to replace the defaults for certain link types -\definecolor{orange}{cmyk}{0,0.4,0.8,0.2} -\definecolor{darkorange}{rgb}{.71,0.21,0.01} -\definecolor{darkred}{rgb}{.52,0.08,0.01} -\definecolor{darkgreen}{rgb}{.12,.54,.11} - -% Use and configure listings package for nicely formatted code -\usepackage{listings} -\lstset{ - language=Python, - basicstyle=\small\ttfamily, - commentstyle=\ttfamily\color{blue}, - stringstyle=\ttfamily\color{darkorange}, - showstringspaces=false, - breaklines=true, - postbreak = \space\dots -} - -\usepackage[%pdftex, % needed for pdflatex - breaklinks=true, % so long urls are correctly broken across lines - colorlinks=true, - urlcolor=blue, - linkcolor=darkred, - citecolor=darkgreen, - ]{hyperref} - -\usepackage{html} - -% This helps prevent overly long lines that stretch beyond the margins -\sloppy - -% Define a \codelist command which either uses listings for latex, or -% plain verbatim for html (since latex2html doesn't understand the -% listings package). -\usepackage{verbatim} -\newcommand{\codelist}[1] { -\latex{\lstinputlisting{#1}} -\html{\verbatiminput{#1}} -} -\end_preamble -\language english -\inputencoding latin1 -\fontscheme palatino -\graphics default -\paperfontsize 11 -\spacing single -\papersize default -\use_geometry true -\use_amsmath 1 -\cite_engine basic -\use_bibtopic false -\paperorientation portrait -\leftmargin 1in -\topmargin 1in -\rightmargin 1in -\bottommargin 1in -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation skip -\defskip medskip -\quotes_language english -\papercolumns 1 -\papersides 2 -\paperpagestyle fancy -\tracking_changes false -\output_changes true -\end_header - -\begin_body - -\begin_layout Title -IPython -\newline - -\size larger -An enhanced Interactive Python -\size large - -\newline -User Manual, v. - __version__ -\end_layout - -\begin_layout Author -Fernando Pérez -\begin_inset Foot -status collapsed - -\begin_layout Standard - -\size scriptsize -Department of Applied Mathematics, University of Colorado at Boulder. - -\family typewriter - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -latex{ -\end_layout - -\end_inset - - -\begin_inset LatexCommand \tableofcontents{} - -\end_inset - - -\begin_inset ERT -status collapsed - -\begin_layout Standard - -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Standard - - -\backslash -html{ -\backslash -bodytext{bgcolor=#ffffff}} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard - -\newpage - -\end_layout - -\begin_layout Section -Overview -\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. -\end_layout - -\begin_layout Standard -IPython is a free software project (released under the BSD license) which - tries to: -\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 - interactively. - 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). -\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. -\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. -\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. -\end_layout - -\begin_layout Subsection -Main features -\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 default -', and using ` -\family typewriter -?? -\family default -' provides additional detail). -\end_layout - -\begin_layout Itemize -Searching through modules and namespaces with ` -\family typewriter -* -\family default -' wildcards, both when using the ` -\family typewriter -? -\family default -' system and via the -\family typewriter -%psearch -\family default - command. -\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. -\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. -\end_layout - -\begin_layout Itemize -User-extensible `magic' commands. - A set of commands prefixed with -\family typewriter -% -\family default - is available for controlling IPython itself and provides directory control, - namespace information and many aliases to common system shell commands. -\end_layout - -\begin_layout Itemize -Alias facility for defining your own system aliases. -\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. -\end_layout - -\begin_layout Itemize -Background execution of Python commands in a separate thread. - IPython has an internal job manager called -\family typewriter -jobs -\family default -, and a conveninence backgrounding magic function called -\family typewriter -%bg -\family default -. -\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 default - is expanded. - A double -\family typewriter -$$ -\family default - allows passing a literal -\family typewriter -$ -\family default - to the shell (for access to shell and environment variables like -\family typewriter -$PATH -\family default -). -\end_layout - -\begin_layout Itemize -Filesystem navigation, via a magic -\family typewriter -%cd -\family default - command, along with a persistent bookmark system (using -\family typewriter -%bookmark -\family default -) for fast access to frequently visited directories. -\end_layout - -\begin_layout Itemize -A lightweight persistence framework via the -\family typewriter -%store -\family default - command, which allows you to save arbitrary Python variables. - These get restored automatically when your session restarts. -\end_layout - -\begin_layout Itemize -Automatic indentation (optional) of code as you type (through the readline - library). -\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 -%store -\family default - and edited via -\family typewriter -%edit -\family default -. - -\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). -\end_layout - -\begin_layout Itemize -Session restoring: logs can be replayed to restore a previous session to - the state where you left it. -\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). -\end_layout - -\begin_layout Itemize -Auto-parentheses: callable objects can be executed without parentheses: - -\family typewriter -`sin 3' -\family default - is automatically converted to -\family typewriter -`sin(3) -\family default -'. -\end_layout - -\begin_layout Itemize -Auto-quoting: using ` -\family typewriter -, -\family default -' or ` -\family typewriter -; -\family default -' as the first character forces auto-quoting of the rest of the line: -\family typewriter -`,my_function a\InsetSpace ~ -b' -\family default - becomes automatically -\family typewriter -`my_function("a","b")' -\family default -, while -\family typewriter -`;my_function a\InsetSpace ~ -b' -\family default - becomes -\family typewriter -`my_function("a b")' -\family default -. -\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 default - or -\family typewriter -`...' -\family default - such as those from other python sessions or the standard Python documentation. -\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. -\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). -\end_layout - -\begin_layout Itemize -Easy debugger access. - You can set IPython to call up an enhanced version of the Python debugger - ( -\family typewriter -pdb -\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 -%run -\family default - magic command --with the -\family typewriter --d -\family default - option-- can run any script under -\family typewriter -pdb -\family default -'s control, automatically setting initial breakpoints for you. - This version of -\family typewriter -pdb -\family default - has IPython-specific improvements, including tab-completion and traceback - coloring support. -\end_layout - -\begin_layout Itemize -Profiler support. - You can run single statements (similar to -\family typewriter -profile.run() -\family default -) or complete programs under the profiler's control. - While this is possible with standard -\family typewriter -cProfile -\family default - or -\family typewriter -profile -\family default - modules, IPython wraps this functionality with magic commands (see -\family typewriter -`%prun' -\family default - and -\family typewriter -`%run -p -\family default -') convenient for rapid interactive work. -\end_layout - -\begin_layout Itemize -Doctest support. - The special -\family typewriter -%doctest_mode -\family default - command toggles a mode that allows you to paste existing doctests (with - leading ` -\family typewriter ->>> -\family default -' prompts and whitespace) and uses doctest-compatible prompts and output, - so you can use IPython sessions as doctest code. -\end_layout - -\begin_layout Subsection -Portability and Python requirements -\end_layout - -\begin_layout Standard - -\series bold -Python requirements: -\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. -\end_layout - -\begin_layout Standard -IPython is developed under -\series bold -Linux -\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). -\end_layout - -\begin_layout Standard - -\series bold -Mac OS X -\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. -\end_layout - -\begin_layout Standard - -\series bold -CygWin -\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 -ipythonrc -\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. -\end_layout - -\begin_layout Standard - -\series bold -Windows -\series default -: it works well under Windows XP/2k, and I suspect NT should behave similarly. - Section\InsetSpace ~ - -\begin_inset LatexCommand \ref{sub:Under-Windows} - -\end_inset - - describes installation details for Windows, including some additional tools - needed on this platform. -\end_layout - -\begin_layout Standard -Windows 9x support is present, and has been reported to work fine (at least - on WinME). -\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.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:IPython-as-shell} - -\end_inset - - for details), as it offers a level of control and features which the default - -\family typewriter -cmd.exe -\family default - doesn't provide. -\end_layout - -\begin_layout Subsection -Location -\end_layout - -\begin_layout Standard -IPython is generously hosted at -\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org} - -\end_inset - - by the Enthought, Inc and the SciPy project. - This site offers downloads, subversion access, mailing lists and a bug - tracking system. - I am very grateful to Enthought ( -\begin_inset LatexCommand \htmlurl{http://www.enthought.com} - -\end_inset - -) and all of the SciPy team for their contribution. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:install} - -\end_inset - -Installation -\end_layout - -\begin_layout Subsection -Instant instructions -\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 -`python setup.py install' -\family default -. - Under Windows, double-click on the provided -\family typewriter -.exe -\family default - binary installer. -\end_layout - -\begin_layout Standard -Then, take a look at Sections -\begin_inset LatexCommand \ref{sec:good_config} - -\end_inset - - for configuring things optimally and -\begin_inset LatexCommand \ref{sec:quick_tips} - -\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. -\end_layout - -\begin_layout Standard -See the notes in sec. - -\begin_inset LatexCommand \ref{sec:upgrade} - -\end_inset - - for upgrading IPython versions. -\end_layout - -\begin_layout Subsection -Detailed Unix instructions (Linux, Mac OS X, etc.) -\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: -\end_layout - -\begin_layout Enumerate -Unzip/untar the -\family typewriter -ipython-XXX.tar.gz -\family default - file wherever you want ( -\family typewriter -XXX -\family default - is the version number). - It will make a directory called -\family typewriter -ipython-XXX. - -\family default -Change into that directory where you will find the files -\family typewriter -README -\family default - and -\family typewriter -setup.py -\family default -. - -\family typewriter - O -\family default -nce you've completed the installation, you can safely remove this directory. - -\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 -$HOME/.ipython -\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 --upgrade -\family default - option and it will do this automatically for you. -\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 default -) -\newline - -\family typewriter -$ python setup.py install -\family default - -\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 - -\begin_layout Standard - - -\backslash -verb|--home| -\end_layout - -\end_inset - - option (or -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb|--prefix| -\end_layout - -\end_inset - -). - For example: -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb|$ python setup.py install --home $HOME/local| -\end_layout - -\end_inset - - -\newline -will install IPython into -\family typewriter -$HOME/local -\family default -and its subdirectories (creating them if necessary). -\newline -You can type -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb|$ python setup.py --help| -\end_layout - -\end_inset - - -\newline -for more details. -\newline -Note that if you change the default location for -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb|--home| -\end_layout - -\end_inset - - at installation, IPython may end up installed at a location which is not - part of your -\family typewriter -$PYTHONPATH -\family default - environment variable. - In this case, you'll need to configure this variable to include the actual - directory where the -\family typewriter -IPython/ -\family default - directory ended (typically the value you give to -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb|--home| -\end_layout - -\end_inset - - plus -\family typewriter -/lib/python -\family default -). -\end_layout - -\begin_layout Subsubsection -Mac OSX information -\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 -/usr/local -\family default -) or by using Fink, which puts everything under -\family typewriter -/sw -\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. -\end_layout - -\begin_layout Standard -This page: -\begin_inset LatexCommand \htmlurl{http://geosci.uchicago.edu/~tobis/pylab.html} - -\end_inset - - contains information on this topic, with additional details on how to make - IPython and matplotlib play nicely under OSX. -\end_layout - -\begin_layout Subsubsection* -GUI problems -\end_layout - -\begin_layout Standard -The following instructions apply to an install of IPython under OSX from - unpacking the -\family typewriter -.tar.gz -\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. -\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 -pythonw -\family default - script at installation time, which takes care of coordinating things with - Apple's graphical environment. -\end_layout - -\begin_layout Standard -So when installing under OSX, it is best to use the following command: -\family typewriter - -\newline - -\family default - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb| $ sudo pythonw setup.py install --install-scripts=/usr/local/bin| -\end_layout - -\end_inset - - -\newline - or -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb| $ sudo pythonw setup.py install --install-scripts=/usr/bin| -\end_layout - -\end_inset - - -\newline -depending on where you like to keep hand-installed executables. -\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 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 -/usr/bin/python -\family default -, then you might have a stale, cached version in your -\family typewriter -build/scripts- -\family default - directory. - Delete that directory and rerun the -\family typewriter -setup.py -\family default -. - -\end_layout - -\begin_layout Standard -It is also a good idea to use the special flag -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -verb|--install-scripts| -\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 -$PATH -\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 -/usr/local/bin -\family default -, you need to make sure this is in your -\family typewriter -$PATH -\family default -, which may not be true by default). -\end_layout - -\begin_layout Subsubsection* -Readline problems -\end_layout - -\begin_layout Standard -By default, the Python version shipped by Apple does -\emph on -not -\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 - -\begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip} - -\end_inset - - -\end_layout - -\begin_layout Standard -If you are using OSX 10.4 (Tiger), after installing this package you need - to either: -\end_layout - -\begin_layout Enumerate -move -\family typewriter -readline.so -\family default - from -\family typewriter -/Library/Python/2.3 -\family default - to -\family typewriter -/Library/Python/2.3/site-packages -\family default -, or -\end_layout - -\begin_layout Enumerate -install -\begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/TigerPython23Compat.pkg.zip} - -\end_inset - - -\end_layout - -\begin_layout Standard -Users installing against Fink's Python or a properly hand-built one should - not have this problem. -\end_layout - -\begin_layout Subsubsection* -DarwinPorts -\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: -\end_layout - -\begin_layout Quote -From: Markus Banfi -\family typewriter - -\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: -\end_layout - -\begin_layout Quote - -\family typewriter -sudo port install py-ipython -\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. - -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sub:Under-Windows} - -\end_inset - -Windows instructions -\end_layout - -\begin_layout Standard -Some of IPython's very useful features are: -\end_layout - -\begin_layout Itemize -Integrated readline support (Tab-based file, object and attribute completion, - input history across sessions, editable command line, etc.) -\end_layout - -\begin_layout Itemize -Coloring of prompts, code and tracebacks. -\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. - His readline library originally implemented both GNU readline functionality - and color support, so that IPython under Windows XP/2k can be as friendly - and powerful as under Unix-like environments. - -\end_layout - -\begin_layout Standard -This library, now named -\family typewriter -PyReadline -\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. -\end_layout - -\begin_layout Standard -The -\family typewriter - PyReadline -\family default - extension requires -\family typewriter -CTypes -\family default - and the windows IPython installer needs -\family typewriter -PyWin32 -\family default -, so in all you need: -\end_layout - -\begin_layout Enumerate - -\family typewriter -PyWin32 -\family default - from -\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/pywin32} - -\end_inset - -. -\end_layout - -\begin_layout Enumerate - -\family typewriter -PyReadline -\family default - for Windows from -\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org/moin/PyReadline/Intro} - -\end_inset - -. - That page contains further details on using and configuring the system - to your liking. -\end_layout - -\begin_layout Enumerate -Finally, -\emph on -only -\emph default -if you are using Python 2.3 or 2.4, you need -\family typewriter -CTypes -\family default - from -\begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/theller/ctypes} - -\end_inset - - (you -\emph on -must -\emph default - use version 0.9.1 or newer). - This package is included in Python 2.5, so you don't need to manually get - it if your Python version is 2.5 or newer. -\end_layout - -\begin_layout Standard - -\series bold -Warning about a broken readline-like library: -\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 - -. - This is a broken library which, while called readline, only implements - an incomplete subset of the readline API. - Since it is still called readline, it fools IPython's detection mechanisms - 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. -\end_layout - -\begin_layout Subsubsection -Installation procedure -\end_layout - -\begin_layout Standard -Once you have the above installed, from the IPython download directory grab - the -\family typewriter -ipython-XXX.win32.exe -\family default - file, where -\family typewriter -XXX -\family default - represents the version number. - This is a regular windows executable installer, which you can simply double-cli -ck to install. - It will add an entry for IPython to your Start Menu, as well as registering - IPython in the Windows list of applications, so you can later uninstall - it from the Control Panel. - -\end_layout - -\begin_layout Standard -IPython tries to install the configuration information in a directory named - -\family typewriter -.ipython -\family default - ( -\family typewriter -_ipython -\family default - under Windows) located in your `home' directory. - IPython sets this directory by looking for a -\family typewriter -HOME -\family default - environment variable; if such a variable does not exist, it uses -\family typewriter -HOMEDRIVE -\backslash -HOMEPATH -\family default -(these are always defined by Windows). - This typically gives something like -\family typewriter -C: -\backslash -Documents and Settings -\backslash -YourUserName -\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 -sys.path -\family default -, so anything you place there can be found by -\family typewriter -import -\family default - statements. -\end_layout - -\begin_layout Paragraph -Upgrading -\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. -\end_layout - -\begin_layout Paragraph -Manual installation under Win32 -\end_layout - -\begin_layout Standard -In case the automatic installer does not work for some reason, you can download - the -\family typewriter -ipython-XXX.tar.gz -\family default - file, which contains the full IPython source distribution (the popular - WinZip can read -\family typewriter -.tar.gz -\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 -`python setup.py install' -\family default -. - -\end_layout - -\begin_layout Standard -After the installation, run the supplied -\family typewriter -win32_manual_post_install.py -\family default -script, which creates the necessary Start Menu shortcuts for you. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:upgrade} - -\end_inset - -Upgrading from a previous version -\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 --upgrade -\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. - You can then later merge back any personal customizations you may have - 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. -\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 -C: -\backslash -Documents and Settings -\backslash -YourUserName -\backslash -_ipython -\family default -, and Win 9x users under -\family typewriter -C: -\backslash -Program Files -\backslash -IPython -\backslash -_ipython. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:good_config} - -\end_inset - - -\begin_inset OptArg -status collapsed - -\begin_layout Standard -Initial configuration -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -ldots -\end_layout - -\end_inset - - -\end_layout - -\end_inset - -Initial configuration of your environment -\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 -$HOME/.ipython -\family default -. - You can change this by defining the environment variable -\family typewriter -IPYTHONDIR -\family default -, or at runtime with the command line option -\family typewriter --ipythondir -\family default -. -\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. - You can look at the files it creates to learn more about configuring the - system. - The main file you will modify to configure IPython's behavior is called - -\family typewriter -ipythonrc -\family default - (with a -\family typewriter -.ini -\family default - extension under Windows), included for reference in Sec. - -\begin_inset LatexCommand \ref{sec:ipytonrc-sample} - -\end_inset - -. - This file is very commented and has many variables you can change to suit - your taste, you can find more details in Sec. - -\begin_inset LatexCommand \ref{sec:customization} - -\end_inset - -. - Here we discuss the basic things you will want to make sure things are - working properly from the beginning. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:help-access} - -\end_inset - -Access to the Python help system -\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 -PYTHONDOCS -\family default - pointing to the directory where your HTML Python documentation lives. - In my system it's -\family typewriter -/usr/share/doc/python-docs-2.3.4/html -\family default -, check your local details or ask your systems administrator. - -\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: -\end_layout - -\begin_layout Standard - -\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 -\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. -\end_layout - -\begin_layout Standard -Under Windows it seems that pydoc finds the documentation automatically, - so no extra setup appears necessary. -\end_layout - -\begin_layout Subsection -Editor -\end_layout - -\begin_layout Standard -The -\family typewriter -%edit -\family default - command (and its alias -\family typewriter -%ed -\family default -) will invoke the editor set in your environment as -\family typewriter -EDITOR -\family default -. - If this variable is not set, it will default to -\family typewriter -vi -\family default - under Linux/Unix and to -\family typewriter -notepad -\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 -Emacs -\family default -). - This way you can edit multi-line code quickly and with the power of a real - editor right inside IPython. - -\end_layout - -\begin_layout Standard -If you are a dedicated -\family typewriter -Emacs -\family default - user, you should set up the -\family typewriter -Emacs -\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 -Emacs -\family default - process is already running). - For this to work, you need to set your -\family typewriter -EDITOR -\family default -environment variable to -\family typewriter -'emacsclient' -\family default -. - -\family typewriter - -\family default -The code below, supplied by Francois Pinard, can then be used in your -\family typewriter -.emacs -\family default - file to enable the server: -\end_layout - -\begin_layout Standard - -\family typewriter -(defvar server-buffer-clients) -\newline -(when (and (fboundp 'server-start) (string-equal - (getenv "TERM") 'xterm)) -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -(server-start) -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -(defun fp-kill-server-with-buffer-routine () -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -(and server-buffer-clients (server-done))) -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine)) -\end_layout - -\begin_layout Standard -You can also set the value of this editor via the commmand-line option '- -\family typewriter -editor' -\family default - or in your -\family typewriter -ipythonrc -\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). -\end_layout - -\begin_layout Subsection -Color -\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 -may -\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. -\end_layout - -\begin_layout Standard -The following terminals seem to handle the color sequences fine: -\end_layout - -\begin_layout Itemize -Linux main text console, KDE Konsole, Gnome Terminal, E-term, rxvt, xterm. -\end_layout - -\begin_layout Itemize -CDE terminal (tested under Solaris). - This one boldfaces light colors. -\end_layout - -\begin_layout Itemize -(X)Emacs buffers. - See sec. -\begin_inset LatexCommand \ref{sec:emacs} - -\end_inset - - for more details on using IPython with (X)Emacs. -\end_layout - -\begin_layout Itemize -A Windows (XP/2k) command prompt -\emph on -with Gary Bishop's support extensions -\emph default -. - Gary's extensions are discussed in Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sub:Under-Windows} - -\end_inset - -. -\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. -\end_layout - -\begin_layout Standard -These have shown problems: -\end_layout - -\begin_layout Itemize -Windows command prompt in WinXP/2k logged into a Linux machine via telnet - or ssh. -\end_layout - -\begin_layout Itemize -Windows native command prompt in WinXP/2k, -\emph on -without -\emph default -Gary Bishop's extensions. - Once Gary's readline library is installed, the normal WinXP/2k command - prompt works perfectly. -\end_layout - -\begin_layout Standard -Currently the following color schemes are available: -\end_layout - -\begin_layout Itemize - -\family typewriter -NoColor -\family default -: uses no color escapes at all (all escapes are empty -\begin_inset Quotes eld -\end_inset - - -\begin_inset Quotes eld -\end_inset - - strings). - This 'scheme' is thus fully safe to use in any terminal. -\end_layout - -\begin_layout Itemize - -\family typewriter -Linux -\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. -\end_layout - -\begin_layout Itemize - -\family typewriter -LightBG -\family default -: the basic colors are similar to those in the -\family typewriter -Linux -\family default - scheme but darker. - It is easy to read in terminals with light backgrounds. -\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. -\end_layout - -\begin_layout Subsubsection -Input/Output prompts and exception tracebacks -\end_layout - -\begin_layout Standard -You can test whether the colored prompts and tracebacks work on your system - interactively by typing -\family typewriter -'%colors Linux' -\family default - at the prompt (use ' -\family typewriter -%colors LightBG' -\family default - if your terminal has a light background). - If the input prompt shows garbage like: -\newline - -\family typewriter -[0;32mIn [[1;32m1[0;32m]: [0;00m -\family default - -\newline -instead of (in color) something like: -\newline - -\family typewriter -In [1]: -\family default - -\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 -%colors NoColor -\family default -'. - -\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 - $HOME/.ipython/ipythonrc -\family default -and set the -\family typewriter -colors -\family default - option to the desired value. -\end_layout - -\begin_layout Subsubsection -Object details (types, docstrings, source code, etc.) -\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 - -. - But this system relies on passing information which is longer than your - screen through a data pager, such as the common Unix -\family typewriter -less -\family default - and -\family typewriter -more -\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 -less -\family default - instead of -\family typewriter -more -\family default -, as it seems that -\family typewriter -more -\family default - simply can not understand colored text correctly. -\end_layout - -\begin_layout Standard -In order to configure -\family typewriter -less -\family default - as your default pager, do the following: -\end_layout - -\begin_layout Enumerate -Set the environment -\family typewriter -PAGER -\family default - variable to -\family typewriter -less -\family default -. -\end_layout - -\begin_layout Enumerate -Set the environment -\family typewriter -LESS -\family default - variable to -\family typewriter --r -\family default - (plus any other options you always want to pass to -\family typewriter -less -\family default - by default). - This tells -\family typewriter -less -\family default - to properly interpret control sequences, which is how color information - is given to your terminal. -\end_layout - -\begin_layout Standard -For the -\family typewriter -csh -\family default - or -\family typewriter -tcsh -\family default - shells, add to your -\family typewriter -~/.cshrc -\family default - file the lines: -\end_layout - -\begin_layout Standard - -\family typewriter -setenv PAGER less -\newline -setenv LESS -r -\end_layout - -\begin_layout Standard -There is similar syntax for other Unix shells, look at your system documentation - for details. -\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. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:emacs} - -\end_inset - -(X)Emacs configuration -\end_layout - -\begin_layout Standard -Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, currently - (X)Emacs and IPython get along very well. - -\end_layout - -\begin_layout Standard - -\series bold -Important note: -\series default - You will need to use a recent enough version of -\family typewriter -python-mode.el -\family default -, along with the file -\family typewriter -ipython.el -\family default -. - You can check that the version you have of -\family typewriter -python-mode.el -\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 -M-x py-version -\family default -. - Versions 4.68 and newer contain the necessary fixes for proper IPython support. -\end_layout - -\begin_layout Standard -The file -\family typewriter -ipython.el -\family default - is included with the IPython distribution, in the documentation directory - (where this manual resides in PDF and HTML formats). -\end_layout - -\begin_layout Standard -Once you put these files in your Emacs path, all you need in your -\family typewriter -.emacs -\family default - file is: -\end_layout - -\begin_layout LyX-Code -(require 'ipython) -\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\InsetSpace ~ -! -\family default -, etc. - -\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 -.emacs -\family default - file: -\end_layout - -\begin_layout LyX-Code -(setq ansi-color-for-comint-mode t) -\end_layout - -\begin_layout Subsubsection* -Notes -\end_layout - -\begin_layout Itemize -There is one caveat you should be aware of: you must start the IPython shell - -\emph on -before -\emph default - attempting to execute any code regions via -\family typewriter -C-c\InsetSpace ~ -| -\family default -. - Simply type -\family typewriter -C-c\InsetSpace ~ -! -\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 ]). -\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. - -\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). -\end_layout - -\begin_layout Itemize -Be aware that if you customize -\family typewriter -py-python-command -\family default - previously, this value will override what -\family typewriter -ipython.el -\family default - does (because loading the customization variables comes later). -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:quick_tips} - -\end_inset - -Quick tips -\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 - most effective use of it for everyday Python development, highlighting - 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. -\end_layout - -\begin_layout Standard -The following article by Jeremy Jones provides an introductory tutorial - about IPython: -\newline - -\begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html} - -\end_inset - - -\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 -object_name. -\family default - and a list of the object's attributes will be printed (see sec. - -\begin_inset LatexCommand \ref{sec:readline} - -\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. - -\end_layout - -\begin_layout Itemize -Explore your objects. - Typing -\family typewriter -object_name? -\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 -%pdoc -\family default -, -\family typewriter -%pdef -\family default -, -\family typewriter -%psource -\family default - and -\family typewriter -%pfile -\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 default -' explicitly. - See sec. - -\begin_inset LatexCommand \ref{sec:dyn-object-info} - -\end_inset - - for more. -\end_layout - -\begin_layout Itemize -The -\family typewriter -%run -\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 -import -\family default -). - I rarely use -\family typewriter -import -\family default - for code I am testing, relying on -\family typewriter -%run -\family default - instead. - See sec. - -\begin_inset LatexCommand \ref{sec:magic} - -\end_inset - - for more on this and other magic commands, or type the name of any magic - command and ? to get details on it. - See also sec. - -\begin_inset LatexCommand \ref{sec:dreload} - -\end_inset - - for a recursive reload command. -\newline - -\family typewriter -%run -\family default - also has special flags for timing the execution of your scripts ( -\family typewriter --t -\family default -) and for executing them under the control of either Python's -\family typewriter -pdb -\family default -debugger ( -\family typewriter --d -\family default -) or profiler ( -\family typewriter --p -\family default -). - With all of these, -\family typewriter -%run -\family default - can be used as the main tool for efficient interactive development of code - which you write in your editor of choice. -\end_layout - -\begin_layout Itemize -Use the Python debugger, -\family typewriter -pdb -\family default - -\begin_inset Foot -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_layout - -\end_inset - -. - The -\family typewriter -%pdb -\family default - command allows you to toggle on and off the automatic invocation of an - IPython-enhanced -\family typewriter -pdb -\family default - debugger (with coloring, tab completion and more) at any uncaught exception. - The advantage of this is that -\family typewriter -pdb -\family default - starts -\emph on -inside -\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 -Runn -ing programs with -\family typewriter -%run -\family default - and pdb active can be an efficient to develop and debug code, in many cases - eliminating the need for -\family typewriter -print -\family default - statements or external debugging tools. - I often simply put a -\family typewriter -1/0 -\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 -1/0 -\family default -. -\newline -Note also that ` -\family typewriter -%run -d -\family default -' activates -\family typewriter -pdb -\family default - and automatically sets initial breakpoints for you to step through your - code, watch variables, etc. - See Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:cache_output} - -\end_inset - - for details. -\end_layout - -\begin_layout Itemize -Use the output cache. - All output results are automatically stored in a global dictionary named - -\family typewriter -Out -\family default - and variables named -\family typewriter -_1 -\family default -, -\family typewriter -_2 -\family default -, etc. - alias them. - For example, the result of input line 4 is available either as -\family typewriter -Out[4] -\family default - or as -\family typewriter -_4 -\family default -. - Additionally, three variables named -\family typewriter -_ -\family default -, -\family typewriter -__ -\family default - and -\family typewriter -___ -\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.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:cache_output} - -\end_inset - - for more. -\end_layout - -\begin_layout Itemize -Put a ' -\family typewriter -; -\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 default - variables and the -\family typewriter -Out[] -\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. -\end_layout - -\begin_layout Itemize -A similar system exists for caching input. - All input is stored in a global list called -\family typewriter -In -\family default - , so you can re-execute lines 22 through 28 plus line 34 by typing -\family typewriter -'exec In[22:29]+In[34]' -\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 -%macro -\family default - -\family typewriter -function. - -\family default -See sec. - -\begin_inset LatexCommand \ref{sec:cache_input} - -\end_inset - - for more. -\end_layout - -\begin_layout Itemize -Use your input history. - The -\family typewriter -%hist -\family default - command can show you all previous input, without line numbers if desired - (option -\family typewriter --n -\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 -%logstart -\family default -; these logs can later be either reloaded as IPython sessions or used as - code for your programs. -\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 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 -%pushd -\family default -, -\family typewriter -%popd -\family default - and -\family typewriter -%dhist -\family default -) and via direct -\family typewriter -%cd -\family default -. - The latter keeps a history of visited directories and allows you to go - to any previously visited one. -\end_layout - -\begin_layout Itemize -Use Python to manipulate the results of system commands. - The ` -\family typewriter -!! -\family default -' special syntax, and the -\family typewriter -%sc -\family default - and -\family typewriter -%sx -\family default - magic commands allow you to capture system output into Python variables. -\end_layout - -\begin_layout Itemize -Expand python variables when calling the shell (either via -\family typewriter -`!' -\family default - and -\family typewriter -`!!' -\family default - or via aliases) by prepending a -\family typewriter -$ -\family default - in front of them. - You can also expand complete python expressions. - See sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sub:System-shell-access} - -\end_inset - - for more. -\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.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:profiles} - -\end_inset - - for more. -\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.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:embed} - -\end_inset - - for more. -\end_layout - -\begin_layout Itemize -Use the Python profiler. - When dealing with performance issues, the -\family typewriter -%run -\family default - command with a -\family typewriter --p -\family default - option allows you to run complete programs under the control of the Python - profiler. - The -\family typewriter -%prun -\family default - command does a similar job for single Python expressions (like function - calls). -\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.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:interactive-demos} - -\end_inset - - for more. -\end_layout - -\begin_layout Itemize -Run your doctests from within IPython for development and debugging. - The special -\family typewriter -%doctest_mode -\family default - command toggles a mode where the prompt, output and exceptions display - matches as closely as possible that of the default Python interpreter. - In addition, this mode allows you to directly paste in code that contains - leading ` -\family typewriter ->>> -\family default -' prompts, even if they have extra leading whitespace (as is common in doctest - files). - This combined with the ` -\family typewriter -%history -t -\family default -n' call to see your translated history (with these extra prompts removed - and no line numbers) allows for an easy doctest workflow, where you can - go from doctest to interactive execution to pasting into valid Python code - as needed. -\end_layout - -\begin_layout Subsection -Source code handling tips -\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. -\end_layout - -\begin_layout Standard -The -\family typewriter -%edit -\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 -%edit? -\family default - for the full details on the edit command. -\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 -%hist -\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 -\end_layout - -\begin_layout LyX-Code -%command 10-20 24 28 -\end_layout - -\begin_layout Standard -where the command given can be: -\end_layout - -\begin_layout Itemize - -\family typewriter -%macro -\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 -`%edit macroname -\family default -', and they can be stored persistently across sessions with ` -\family typewriter -%store macroname -\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. -\end_layout - -\begin_layout Itemize - -\family typewriter -%edit -\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. -\end_layout - -\begin_layout Itemize - -\family typewriter -%save -\family default -: this saves the lines directly to a named file on disk. -\end_layout - -\begin_layout Standard -While -\family typewriter -%macro -\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 -%save -\family default - magic does this: its input sytnax is the same as -\family typewriter -%macro -\family default -, but it saves your input directly to a Python file. - Note that the -\family typewriter -%logstart -\family default - command also saves input, but it logs -\emph on -all -\emph default - input to disk (though you can temporarily suspend it and reactivate it - with -\family typewriter -%logoff/%logon -\family default -); -\family typewriter -%save -\family default - allows you to select which lines of input you need to save. -\end_layout - -\begin_layout Subsubsection* -Lightweight 'version control' -\end_layout - -\begin_layout Standard -When you call -\family typewriter -%edit -\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: -\end_layout - -\begin_layout LyX-Code -In [1]: %edit -\end_layout - -\begin_layout LyX-Code -IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py -\end_layout - -\begin_layout LyX-Code -Editing... - done. - Executing edited code... -\end_layout - -\begin_layout LyX-Code -hello - this is a temporary file -\end_layout - -\begin_layout LyX-Code -Out[1]: "print 'hello - this is a temporary file' -\backslash -n" -\end_layout - -\begin_layout Standard -Now, if you call -\family typewriter -`%edit -p' -\family default -, IPython tries to open an editor with the same data as the last time you - used -\family typewriter -%edit -\family default -. - So if you haven't used -\family typewriter -%edit -\family default - in the meantime, this same contents will reopen; however, it will be done - in a -\emph on -new file -\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 -`%edit _NN' -\family default -, where -\family typewriter -NN -\family default - is the number of the output prompt. -\end_layout - -\begin_layout Standard -Continuing with the example above, this should illustrate this idea: -\end_layout - -\begin_layout LyX-Code -In [2]: edit -p -\end_layout - -\begin_layout LyX-Code -IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py -\end_layout - -\begin_layout LyX-Code -Editing... - done. - Executing edited code... -\end_layout - -\begin_layout LyX-Code -hello - now I made some changes -\end_layout - -\begin_layout LyX-Code -Out[2]: "print 'hello - now I made some changes' -\backslash -n" -\end_layout - -\begin_layout LyX-Code -In [3]: edit _1 -\end_layout - -\begin_layout LyX-Code -IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py -\end_layout - -\begin_layout LyX-Code -Editing... - done. - Executing edited code... -\end_layout - -\begin_layout LyX-Code -hello - this is a temporary file -\end_layout - -\begin_layout LyX-Code -IPython version control at work :) -\end_layout - -\begin_layout LyX-Code -Out[3]: "print 'hello - this is a temporary file' -\backslash -nprint 'IPython version control at work :)' -\backslash -n" -\end_layout - -\begin_layout Standard -This section was written after a contribution by Alexander Belchenko on - the IPython user list. -\end_layout - -\begin_layout LyX-Code - -\end_layout - -\begin_layout Subsection -Effective logging -\end_layout - -\begin_layout Standard -A very useful suggestion sent in by Robert Kern follows: -\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"). -\end_layout - -\begin_layout LyX-Code -include ipythonrc -\end_layout - -\begin_layout LyX-Code -# cancel earlier logfile invocation: -\end_layout - -\begin_layout LyX-Code -logfile '' -\end_layout - -\begin_layout LyX-Code -execute import time -\end_layout - -\begin_layout LyX-Code -execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate' -\end_layout - -\begin_layout LyX-Code -execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d')) -\end_layout - -\begin_layout Standard -I also added a shell alias for convenience: -\end_layout - -\begin_layout LyX-Code -alias parkfield="ipython -pylab -profile parkfield" -\end_layout - -\begin_layout Standard -Now I have a nice little directory with everything I ever type in, organized - by project and date. -\end_layout - -\begin_layout Standard - -\series bold -Contribute your own: -\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! -\end_layout - -\begin_layout Section -Command-line use -\end_layout - -\begin_layout Standard -You start IPython with the command: -\end_layout - -\begin_layout Standard - -\family typewriter -$ ipython [options] files -\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 -python -i -\family default - will only execute one file and ignore your configuration setup. -\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 -$HOME/.ipython -\family default - directory. - For Windows users, -\family typewriter -$HOME -\family default - resolves to -\family typewriter -C: -\backslash - -\backslash -Documents and Settings -\backslash - -\backslash -YourUserName -\family default - in most instances. - In the rest of this text, we will refer to this directory as -\family typewriter -IPYTHONDIR -\family default -. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:threading-opts} - -\end_inset - -Special Threading Options -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --gthread,\InsetSpace ~ --qthread,\InsetSpace ~ --q4thread,\InsetSpace ~ --wthread,\InsetSpace ~ --pylab: -\family default -\series default - Only -\emph on -one -\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 (versions 3 and 4) and WXPython - toolkits, and for the matplotlib library. -\end_layout - -\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 - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - Note that with -\family typewriter --wthread -\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 -wxversion -\family default - Python module installed, which is part of recent wxPython distributions. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - If -\family typewriter --pylab -\family default - is given, IPython loads special support for the mat plotlib library ( -\begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net} - -\end_inset - -), allowing interactive usage of any of its backends as defined in the user's - -\family typewriter -~/.matplotlib/matplotlibrc -\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 -%run -\family default - command to correctly execute (without blocking) any matplotlib-based script - which calls -\family typewriter -show() -\family default - at the end. - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --tk -\family default -\series default - The -\family typewriter --g/q/q4/wthread -\family default - options, and -\family typewriter --pylab -\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 --tk -\family default -, is available to address this issue. - It can -\emph on -only -\emph default - be given as a -\emph on -second -\emph default - option after any of the above ( -\family typewriter --gthread -\family default -, -\family typewriter --wthread -\family default - or -\family typewriter --pylab -\family default -). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - If -\family typewriter --tk -\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. - Debian users have reported success, apparently due to the fact that Debian - builds all of Tcl, Tk, Tkinter and Python with pthreads support. - Under other Linux environments (such as Fedora Core 2/3), this option has - 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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - There is unfortunately no way for IPython to determine at run time whether - -\family typewriter --tk -\family default - will work reliably or not, so you will need to do some experiments before - relying on it for regular work. - -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:cmd-line-opts} - -\end_inset - -Regular Options -\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 default -. -\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. -\end_layout - -\begin_layout Standard -All options with a -\family typewriter -[no] -\family default - prepended can be specified in negated form ( -\family typewriter --nooption -\family default - instead of -\family typewriter --option -\family default -) to turn the feature off. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --help -\family default -\series default -: print a help message and exit. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --pylab: -\family default -\series default - this can -\emph on -only -\emph default - be given as the -\emph on -first -\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 - -), allowing interactive usage of any of its backends as defined in the user's - -\family typewriter -.matplotlibrc -\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 -%run -\family default - command to correctly execute (without blocking) any matplotlib-based script - which calls -\family typewriter -show() -\family default - at the end. - See Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:matplotlib-support} - -\end_inset - - for more details. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --autocall : -\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 -smart -\emph default - autocall, where it is not applied if there are no more arguments on the - line, and `2' for -\emph on -full -\emph default - autocall, where all callable objects are automatically called (even if - no arguments are present). - The default is `1'. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]autoindent: -\family default -\series default - Turn automatic indentation on/off. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]automagic -\series default -: -\family default - make magic commands automatic (without needing their first character to - be -\family typewriter -% -\family default -). - Type -\family typewriter -%magic -\family default - at the IPython prompt for more information. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]autoedit_syntax: -\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. - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]banner -\series default -: -\family default - Print the initial information banner (default on). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --c\InsetSpace ~ -: -\family default -\series default - execute the given command string, and set sys.argv to -\family typewriter -['c'] -\family default -. - This is similar to the -\family typewriter --c -\family default - option in the normal Python interpreter. - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --cache_size|cs\InsetSpace ~ - -\series 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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --classic|cl -\series default -: -\family default - Gives IPython a similar feel to the classic Python prompt. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --colors\InsetSpace ~ -: -\family default -\series default - Color scheme for prompts and exception reporting. - Currently implemented: NoColor, Linux and LightBG. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]color_info: -\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. - However, because this information is passed through a pager (like 'less') - and many pagers get confused with color codes, this option is off by default. - You can test it and turn it on permanently in your ipythonrc file if it - works for you. - As a reference, the 'less' pager supplied with Mandrake 8.2 works ok, but - that in RedHat 7.2 doesn't. -\end_layout - -\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 -%color_info -\family default - allows you to toggle this interactively for testing. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]debug -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]deep_reload -\series default -: -\family default - IPython can use the -\family typewriter -deep_reload -\family default - module which reloads changes in modules recursively (it replaces the -\family typewriter -reload() -\family default - function, so you don't need to change anything to use it). - -\family typewriter -deep_reload() -\family default - forces a full reload of modules whose code may have changed, which the - default -\family typewriter -reload() -\family default - function does not. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - When deep_reload is off, IPython will use the normal -\family typewriter -reload() -\family default -, but deep_reload will still be available as -\family typewriter -dreload() -\family default -. - This feature is off by default [which means that you have both normal -\family typewriter -reload() -\family default - and -\family typewriter -dreload() -\family default -]. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --editor\InsetSpace ~ - -\family default -\series default -: Which editor to use with the -\family typewriter -%edit -\family default - command. - By default, IPython will honor your -\family typewriter -EDITOR -\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 -EDITOR -\family default - is something like Emacs). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --ipythondir\InsetSpace ~ - -\series default -: -\family default - name of your IPython configuration directory -\family typewriter -IPYTHONDIR -\family default -. - This can also be specified through the environment variable -\family typewriter -IPYTHONDIR -\family default -. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --log|l -\family default -\series default -: generate a log file of all input. - The file is named -\family typewriter -ipython_log.py -\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 --logplay -\family default - (see below). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --logfile|lf\InsetSpace ~ - -\series default -: -\family default -specify the name of your logfile. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --logplay|lp\InsetSpace ~ - -\series 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 --logplay -\family default -, IPython will try to reconstruct the previous working environment in full, - not just execute the commands in the logfile. -\end_layout - -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - Caveats: there are limitations in this option. - The history variables -\family typewriter -_i* -\family default -, -\family typewriter -_* -\family default - and -\family typewriter -_dh -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]messages -\series default -: -\family default - Print messages which IPython collects about its startup process (default - on). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]pdb -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]pprint -\series 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). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --profile|p -\series default -: -\family default - assume that your config file is -\family typewriter -ipythonrc- -\family default - (looks in current dir first, then in -\family typewriter -IPYTHONDIR -\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 -IPYTHONDIR/ipythonrc -\family default - file and then have other 'profiles' which include this one and load extra - things for particular tasks. - For example: -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\InsetSpace ~ - -\family default -1. - -\family typewriter - $HOME/.ipython/ipythonrc -\family default - : load basic things you always want. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\InsetSpace ~ - -\family default -2. - -\family typewriter - $HOME/.ipython/ipythonrc-math -\family default - : load (1) and basic math-related modules. - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\InsetSpace ~ - -\family default -3. - -\family typewriter - $HOME/.ipython/ipythonrc-numeric -\family default - : load (1) and Numeric and plotting modules. -\end_layout - -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --prompt_in1|pi1\InsetSpace ~ -: -\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 -#' in the string. - Don't forget to quote strings with spaces embedded in them. - Default: ' -\family typewriter -In\InsetSpace ~ -[ -\backslash -#]: -\family default -'. - Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:prompts} - -\end_inset - - discusses in detail all the available escapes to customize your prompts. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --prompt_in2|pi2\InsetSpace ~ -: -\family default -\series default - Similar to the previous option, but used for the continuation prompts. - The special sequence ' -\family typewriter - -\backslash -D -\family default -' is similar to ' -\family typewriter - -\backslash -# -\family default -', but with all digits replaced dots (so you can have your continuation - prompt aligned with your input prompt). - Default: ' -\family typewriter -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -. -\backslash -D.: -\family default -' (note three spaces at the start for alignment with ' -\family typewriter -In\InsetSpace ~ -[ -\backslash -#] -\family default -'). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --prompt_out|po\InsetSpace ~ -: -\family default -\series default - String used for output prompts, also uses numbers like -\family typewriter -prompt_in1 -\family default -. - Default: ' -\family typewriter -Out[ -\backslash -#]: -\family default -' -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --quick -\family default -\series default -: start in bare bones mode (no config file loaded). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --rcfile\InsetSpace ~ - -\series default -: -\family default - name of your IPython resource configuration file. - Normally IPython loads ipythonrc (from current directory) or -\family typewriter - IPYTHONDIR/ipythonrc -\family default -. -\end_layout - -\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). -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --[no]readline -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - Note that X/Emacs 'eterm' buffers (opened with -\family typewriter -M-x\InsetSpace ~ -term -\family default -) support IPython's readline and syntax coloring fine, only 'emacs' ( -\family typewriter -M-x\InsetSpace ~ -shell -\family default - and -\family typewriter -C-c\InsetSpace ~ -! -\family default -) buffers do not. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --screen_length|sl\InsetSpace ~ - -\series 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. -\end_layout - -\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 - internally). - If for some reason this isn't working well (it needs curses support), specify - it yourself. - Otherwise don't change the default. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --separate_in|si\InsetSpace ~ - -\series default -: -\family default - separator before input prompts. - Default: ' -\family typewriter - -\backslash -n -\family default -' -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --separate_out|so\InsetSpace ~ - -\family default -\series default -: separator before output prompts. - Default: nothing. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --separate_out2|so2\InsetSpace ~ - -\series default -: -\family default - separator after output prompts. - Default: nothing. -\end_layout - -\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 --nosep -\series default -: -\family default -shorthand for -\family typewriter -'-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0' -\family default -. - Simply removes all input/output separators. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --upgrade -\family default -\series default -: allows you to upgrade your -\family typewriter -IPYTHONDIR -\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 -.old -\family default - extension) all files which it overwrites so that you can merge back any - customizations you might have in your personal files. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --Version -\series default -: -\family default - print version information and exit. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --wxversion\InsetSpace ~ -: -\family default -\series default - Select a specific version of wxPython (used in conjunction with -\family typewriter --wthread -\family default -). - Requires the wxversion module, part of recent wxPython distributions -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold --xmode\InsetSpace ~ - -\series default -: -\family default - Mode for exception reporting. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - Valid modes: Plain, Context and Verbose. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - Plain: similar to python's normal traceback printing. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -\InsetSpace ~ - Context: prints 5 lines of context source code around each line in the - traceback. -\end_layout - -\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 - whose string representation is complex to compute. - 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). -\end_layout - -\begin_layout Section -Interactive use -\end_layout - -\begin_layout Standard - -\series bold -Warning -\series default -: IPython relies on the existence of a global variable called -\family typewriter -__IP -\family default - which controls the shell itself. - If you redefine -\family typewriter -__IP -\family default - to anything, bizarre behavior will quickly occur. -\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 - (cases where this is not true should be reported as bugs). - It does, however, offer many features which are not available at a standard - python prompt. - What follows is a list of these. -\end_layout - -\begin_layout Subsection -Caution for Windows users -\end_layout - -\begin_layout Standard -Windows, unfortunately, uses the ` -\family typewriter - -\backslash - -\family default -' character as a path separator. - This is a terrible choice, because ` -\family typewriter - -\backslash - -\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 - -\backslash - -\family default -' in them will cause strange errors. -\end_layout - -\begin_layout Standard -A partial solution is to use instead the ` -\family typewriter -/ -\family default -' character as a path separator, which Windows recognizes in -\emph on -most -\emph default - situations. - However, in Windows commands ` -\family typewriter -/ -\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 - -\family typewriter -%copy -\backslash -opt/foo/bar.txt -\backslash -tmp -\end_layout - -\begin_layout Standard -There is no sensible thing IPython can do to truly work around this flaw - in Windows -\begin_inset Foot -status collapsed - -\begin_layout Standard -If anyone comes up with a -\emph on -clean -\emph default - solution which works consistently and does not negatively impact other - platforms at all, I'll gladly accept a patch. -\end_layout - -\end_inset - -. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:magic} - -\end_inset - -Magic command system -\end_layout - -\begin_layout Standard -IPython will treat any line whose first character is a -\family typewriter -% -\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 default - character, but parameters are given without parentheses or quotes. -\end_layout - -\begin_layout Standard -Example: typing -\family typewriter -'%cd mydir' -\family default - (without the quotes) changes you working directory to -\family typewriter -'mydir' -\family default -, if it exists. -\end_layout - -\begin_layout Standard -If you have 'automagic' enabled (in your -\family typewriter -ipythonrc -\family default - file, via the command line option -\family typewriter --automagic -\family default -or with the -\family typewriter -%automagic -\family default - function), you don't need to type in the -\family typewriter -% -\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 -cd mydir -\family default -' to go to directory ' -\family typewriter -mydir -\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 default - character at the beginning of the line. -\end_layout - -\begin_layout Standard -An example (with automagic on) should clarify all this: -\end_layout - -\begin_layout LyX-Code -In [1]: cd ipython # %cd is called by automagic -\end_layout - -\begin_layout LyX-Code -/home/fperez/ipython -\end_layout - -\begin_layout LyX-Code -In [2]: cd=1 # now cd is just a variable -\end_layout - -\begin_layout LyX-Code -In [3]: cd .. - # and doesn't work as a function anymore -\end_layout - -\begin_layout LyX-Code ------------------------------------------------------------- -\end_layout - -\begin_layout LyX-Code - File "", line 1 -\end_layout - -\begin_layout LyX-Code - cd .. -\end_layout - -\begin_layout LyX-Code - ^ -\end_layout - -\begin_layout LyX-Code -SyntaxError: invalid syntax -\end_layout - -\begin_layout LyX-Code - -\end_layout - -\begin_layout LyX-Code -In [4]: %cd .. - # but %cd always works -\end_layout - -\begin_layout LyX-Code -/home/fperez -\end_layout - -\begin_layout LyX-Code -In [5]: del cd # if you remove the cd variable -\end_layout - -\begin_layout LyX-Code -In [6]: cd ipython # automagic can work again -\end_layout - -\begin_layout LyX-Code -/home/fperez/ipython -\end_layout - -\begin_layout Standard -You can define your own magic functions to extend the system. - The following example defines a new magic command, -\family typewriter -%impall -\family default -: -\end_layout - -\begin_layout LyX-Code -import IPython.ipapi -\end_layout - -\begin_layout LyX-Code -ip = IPython.ipapi.get() -\end_layout - -\begin_layout LyX-Code - -\end_layout - -\begin_layout LyX-Code -def doimp(self, arg): -\end_layout - -\begin_layout LyX-Code - ip = self.api -\end_layout - -\begin_layout LyX-Code - ip.ex("import %s; reload(%s); from %s import *" % ( -\end_layout - -\begin_layout LyX-Code - arg,arg,arg) -\end_layout - -\begin_layout LyX-Code - ) -\end_layout - -\begin_layout LyX-Code -ip.expose_magic('impall', doimp) -\end_layout - -\begin_layout Standard -You can also define your own aliased names for magic functions. - In your -\family typewriter -ipythonrc -\family default - file, placing a line like: -\end_layout - -\begin_layout Standard - -\family typewriter -execute __IP.magic_cl = __IP.magic_clear -\end_layout - -\begin_layout Standard -will define -\family typewriter -%cl -\family default - as a new name for -\family typewriter -%clear -\family default -. -\end_layout - -\begin_layout Standard -Type -\family typewriter -%magic -\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 -%magic_function_name? -\family default - (see sec. - -\begin_inset LatexCommand \ref{sec:dyn-object-info} - -\end_inset - - for information on the -\family typewriter -'?' -\family default - system) to get information about any particular magic function you are - interested in. -\end_layout - -\begin_layout Subsubsection -Magic commands -\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. -\end_layout - -\begin_layout Standard -A list of all the magic commands available in IPython's -\emph on -default -\emph default - installation follows. - This is similar to what you'll see by simply typing -\family typewriter -%magic -\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. -\end_layout - -\begin_layout Standard -\begin_inset Include \input{magic.tex} -preview false - -\end_inset - - -\end_layout - -\begin_layout Subsection -Access to the standard Python help -\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 -'help' -\family default - (no quotes) to access it. - You can also type -\family typewriter -help(object) -\family default - to obtain information about a given object, and -\family typewriter -help('keyword') -\family default - for information on a keyword. - As noted in sec. - -\begin_inset LatexCommand \ref{sec:help-access} - -\end_inset - -, you need to properly configure your environment variable -\family typewriter -PYTHONDOCS -\family default - for this feature to work correctly. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:dyn-object-info} - -\end_inset - -Dynamic object information -\end_layout - -\begin_layout Standard -Typing -\family typewriter -?word -\family default - or -\family typewriter -word? -\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. -\end_layout - -\begin_layout Standard -Typing -\family typewriter -??word -\family default - or -\family typewriter -word?? -\family default - gives access to the full information without snipping long strings. - Long strings are sent to the screen through the -\family typewriter -less -\family default - pager if longer than the screen and printed otherwise. - On systems lacking the -\family typewriter -less -\family default - command, IPython uses a very basic internal pager. -\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 -%magic -\family default - or querying them individually (use -\family typewriter -%function_name? -\family default - with or without the -\family typewriter -% -\family default -), this is just a summary: -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -%pdoc\InsetSpace ~ - -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -%pdef\InsetSpace ~ - -\family default -\series default -: Print the definition header for any callable object. - If the object is a class, print the constructor information. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -%psource\InsetSpace ~ - -\family default -\series default -: Print (or run through a pager if too long) the source code for an object. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -%pfile\InsetSpace ~ - -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -%who/%whos -\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 -%who -\family default - just prints a list of identifiers and -\family typewriter -%whos -\family default - prints a table with some basic details about each identifier. -\end_layout - -\begin_layout Standard -Note that the dynamic object information functions ( -\family typewriter -?/??, %pdoc, %pfile, %pdef, %psource -\family default -) give you access to documentation even on things which are not really defined - as separate identifiers. - Try for example typing -\family typewriter -{}.get? -\family default - or after doing -\family typewriter -import os -\family default -, type -\family typewriter -os.path.abspath?? -\family default -. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:readline} - -\end_inset - -Readline-based features -\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. -\end_layout - -\begin_layout Subsubsection -Command line completion -\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. -\end_layout - -\begin_layout Subsubsection -Search command history -\end_layout - -\begin_layout Standard -IPython provides two ways for searching through previous input and thus - reduce the need for repetitive typing: -\end_layout - -\begin_layout Enumerate -Start typing, and then use -\family typewriter -Ctrl-p -\family default - (previous,up) and -\family typewriter -Ctrl-n -\family default - (next,down) to search through only the history items that match what you've - typed so far. - If you use -\family typewriter -Ctrl-p/Ctrl-n -\family default - at a blank prompt, they just behave like normal arrow keys. -\end_layout - -\begin_layout Enumerate -Hit -\family typewriter -Ctrl-r -\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. -\end_layout - -\begin_layout Subsubsection -Persistent command history across sessions -\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 -$IPYTHONDIR/history -\family default -, but if you've loaded a named profile, ' -\family typewriter --PROFILE_NAME -\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. -\end_layout - -\begin_layout Subsubsection -Autoindent -\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'. - -\end_layout - -\begin_layout Standard -This feature uses the readline library, so it will honor your -\family typewriter -~/.inputrc -\family default - configuration (or whatever file your -\family typewriter -INPUTRC -\family default - variable points to). - Adding the following lines to your -\family typewriter -.inputrc -\family default - file can make indenting/unindenting more convenient ( -\family typewriter -M-i -\family default - indents, -\family typewriter -M-u -\family default - unindents): -\end_layout - -\begin_layout Standard - -\family typewriter -$if Python -\newline -" -\backslash -M-i": "\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -" -\newline -" -\backslash -M-u": " -\backslash -d -\backslash -d -\backslash -d -\backslash -d" -\newline -$endif -\end_layout - -\begin_layout Standard -Note that there are 4 spaces between the quote marks after -\family typewriter -"M-i" -\family default - above. -\end_layout - -\begin_layout Standard - -\series bold -Warning: -\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 -%autoindent -\family default - allows you to toggle it on/off at runtime. - You can also disable it permanently on in your -\family typewriter -ipythonrc -\family default - file (set -\family typewriter -autoindent 0 -\family default -). -\end_layout - -\begin_layout Subsubsection -Customizing readline behavior -\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 - of the library; the details of the syntax for this can be found in the - readline documentation available with your system or on the Internet. - IPython doesn't read this file (if it exists) directly, but it does support - passing to readline valid options via a simple interface. - In brief, you can customize readline by setting the following options in - your -\family typewriter -ipythonrc -\family default - configuration file (note that these options can -\emph on -not -\emph default - be specified at the command line): -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -readline_parse_and_bind: -\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 -readline.parse_and_bind() -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -readline_remove_delims: -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -readline_omit__names -\family default -\series default -: when tab-completion is enabled, hitting -\family typewriter - -\family default - after a ' -\family typewriter -. -\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 -__getitem__ -\family default - or -\family typewriter -__class__ -\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 default - after the period and hitting -\family typewriter - -\family default -: ' -\family typewriter -name._ -\family default -' will always complete attribute names starting with ' -\family typewriter -_ -\family default -'. -\end_layout - -\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. -\end_layout - -\begin_layout Standard -You will find the default values along with a corresponding detailed explanation - in your -\family typewriter -ipythonrc -\family default - file. -\end_layout - -\begin_layout Subsection -Session logging and restoring -\end_layout - -\begin_layout Standard -You can log all input from a session either by starting IPython with the - command line switches -\family typewriter --log -\family default - or -\family typewriter --logfile -\family default -(see sec. - -\begin_inset LatexCommand \ref{sec:cmd-line-opts} - -\end_inset - -)or by activating the logging at any moment with the magic function -\family typewriter -%logstart -\family default -. - -\end_layout - -\begin_layout Standard -Log files can later be reloaded with the -\family typewriter --logplay -\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. -\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. -\end_layout - -\begin_layout Standard -The -\family typewriter -%logstart -\family default - function for activating logging in mid-session is used as follows: -\end_layout - -\begin_layout Standard - -\family typewriter -%logstart [log_name [log_mode]] -\end_layout - -\begin_layout Standard -If no name is given, it defaults to a file named -\family typewriter -'log' -\family default - in your IPYTHONDIR directory, in -\family typewriter -'rotate' -\family default - mode (see below). -\end_layout - -\begin_layout Standard -' -\family typewriter -%logstart name -\family default -' saves to file -\family typewriter -'name' -\family default - in -\family typewriter -'backup' -\family default - mode. - It saves your history up to that point and then continues logging. -\end_layout - -\begin_layout Standard - -\family typewriter -%logstart -\family default - takes a second optional parameter: logging mode. - This can be one of (note that the modes are given unquoted): -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -over -\family default -: overwrite existing -\family typewriter -log_name -\family default -. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -backup -\family default -: rename (if exists) to -\family typewriter -log_name~ -\family default - and start -\family typewriter -log_name -\family default -. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -append -\family default -: well, that says it. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -rotate -\family default -: create rotating logs -\family typewriter -log_name -\family default -. -\family typewriter -1~ -\family default -, -\family typewriter -log_name.2~ -\family default -, etc. -\end_layout - -\begin_layout Standard -The -\family typewriter -%logoff -\family default - and -\family typewriter -%logon -\family default - functions allow you to temporarily stop and resume logging to a file which - had previously been started with -\family typewriter -%logstart -\family default -. - They will fail (with an explanation) if you try to use them before logging - has been started. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sub:System-shell-access} - -\end_inset - -System shell access -\end_layout - -\begin_layout Standard -Any input line beginning with a -\family typewriter -! -\family default - character is passed verbatim (minus the -\family typewriter -! -\family default -, of course) to the underlying operating system. - For example, typing -\family typewriter -!ls -\family default - will run -\family typewriter -'ls' -\family default - in the current directory. -\end_layout - -\begin_layout Subsubsection -Manual capture of command output -\end_layout - -\begin_layout Standard -If the input line begins with -\emph on -two -\emph default - exclamation marks, -\family typewriter -!! -\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 default - syntax is a shorthand for the -\family typewriter -%sx -\family default - magic command. -\end_layout - -\begin_layout Standard -Finally, the -\family typewriter -%sc -\family default - magic (short for `shell capture') is similar to -\family typewriter -%sx -\family default -, but allowing more fine-grained control of the capture details, and storing - the result directly into a named variable. -\end_layout - -\begin_layout Standard -See Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:magic} - -\end_inset - - for details on the magics -\family typewriter -%sc -\family default - and -\family typewriter -%sx -\family default -, or use IPython's own help ( -\family typewriter -sc? -\family default - and -\family typewriter -sx? -\family default -) for further details. -\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 default - will get expanded before the system call is made. - -\end_layout - -\begin_layout Standard - -\family typewriter -In [1]: pyvar='Hello world' -\newline -In [2]: !echo "A python variable: $pyvar" -\newline -A python - variable: Hello world -\end_layout - -\begin_layout Standard -If you want the shell to actually see a literal -\family typewriter -$ -\family default -, you need to type it twice: -\end_layout - -\begin_layout Standard - -\family typewriter -In [3]: !echo "A system variable: $$HOME" -\newline -A system variable: /home/fperez -\end_layout - -\begin_layout Standard -You can pass arbitrary expressions, though you'll need to delimit them with - -\family typewriter -{} -\family default - if there is ambiguity as to the extent of the expression: -\end_layout - -\begin_layout Standard - -\family typewriter -In [5]: x=10 -\newline -In [6]: y=20 -\newline -In [13]: !echo $x+y -\newline -10+y -\newline -In [7]: !echo ${x+y} -\newline -30 - -\end_layout - -\begin_layout Standard -Even object attributes can be expanded: -\end_layout - -\begin_layout Standard - -\family typewriter -In [12]: !echo $sys.argv -\newline -[/home/fperez/usr/bin/ipython] -\end_layout - -\begin_layout Subsection -System command aliases -\end_layout - -\begin_layout Standard -The -\family typewriter -%alias -\family default - magic function and the -\family typewriter -alias -\family default - option in the -\family typewriter -ipythonrc -\family default - configuration file allow you to define magic functions which are in fact - system shell commands. - These aliases can have parameters. - -\end_layout - -\begin_layout Standard -' -\family typewriter -%alias alias_name cmd -\family default -' defines ' -\family typewriter -alias_name -\family default -' as an alias for ' -\family typewriter -cmd -\family default -' -\end_layout - -\begin_layout Standard -Then, typing ' -\family typewriter -%alias_name params -\family default -' will execute the system command ' -\family typewriter -cmd params -\family default -' (from your underlying operating system). - -\end_layout - -\begin_layout Standard -You can also define aliases with parameters using -\family typewriter -%s -\family default - specifiers (one per parameter). - The following example defines the -\family typewriter -%parts -\family default - function as an alias to the command ' -\family typewriter -echo first %s second %s -\family default -' where each -\family typewriter -%s -\family default - will be replaced by a positional parameter to the call to -\family typewriter -%parts: -\end_layout - -\begin_layout Standard - -\family typewriter -In [1]: alias parts echo first %s second %s -\newline -In [2]: %parts A B -\newline -first A second - B -\newline -In [3]: %parts A -\newline -Incorrect number of arguments: 2 expected. - -\newline -parts is an alias to: 'echo first %s second %s' -\end_layout - -\begin_layout Standard -If called with no parameters, -\family typewriter -%alias -\family default - prints the table of currently defined aliases. -\end_layout - -\begin_layout Standard -The -\family typewriter -%rehash/rehashx -\family default - magics allow you to load your entire -\family typewriter -$PATH -\family default - as ipython aliases. - See their respective docstrings (or sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:magic} - -\end_inset - - for further details). -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:dreload} - -\end_inset - -Recursive reload -\end_layout - -\begin_layout Standard -The -\family typewriter -dreload -\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. -\end_layout - -\begin_layout Subsection -Verbose and colored exception traceback printouts -\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 -%run -\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. -\end_layout - -\begin_layout Standard -See the magic -\family typewriter -xmode -\family default - and -\family typewriter -colors -\family default - functions for details (just type -\family typewriter -%magic -\family default -). -\end_layout - -\begin_layout Standard -These features are basically a terminal version of Ka-Ping Yee's -\family typewriter -cgitb -\family default - module, now part of the standard Python library. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:cache_input} - -\end_inset - -Input caching system -\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). -\end_layout - -\begin_layout Standard -The following GLOBAL variables always exist (so don't overwrite them!): - -\family typewriter -_i -\family default -: stores previous input. - -\family typewriter -_ii -\family default -: next previous. - -\family typewriter -_iii -\family default -: next-next previous. - -\family typewriter -_ih -\family default - : a list of all input -\family typewriter -_ih[n] -\family default - is the input from line -\family typewriter -n -\family default - and this list is aliased to the global variable -\family typewriter -In -\family default -. - If you overwrite -\family typewriter -In -\family default - with a variable of your own, you can remake the assignment to the internal - list with a simple -\family typewriter -'In=_ih' -\family default -. -\end_layout - -\begin_layout Standard -Additionally, global variables named -\family typewriter -_i -\family default - are dynamically created ( -\family typewriter - -\family default - being the prompt counter), such that -\newline - -\family typewriter -_i == _ih[] == In[]. -\end_layout - -\begin_layout Standard -For example, what you typed at prompt 14 is available as -\family typewriter -_i14, -\family default - -\family typewriter -_ih[14] -\family default - and -\family typewriter -In[14] -\family default -. -\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 -'exec _i9' -\family default - will re-execute the contents of input prompt 9, ' -\family typewriter -exec In[9:14]+In[18] -\family default -' will re-execute lines 9 through 13 and line 18). -\end_layout - -\begin_layout Standard -You can also re-execute multiple lines of input easily by using the magic - -\family typewriter -%macro -\family default - function (which automates the process and allows re-execution without having - to type ' -\family typewriter -exec -\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 -%macro? -\family default - or see sec. - -\begin_inset LatexCommand \ref{sec:magic} - -\end_inset - - for more details on the macro system. -\end_layout - -\begin_layout Standard -A history function -\family typewriter -%hist -\family default - allows you to see any part of your input history by printing a range of - the -\family typewriter -_i -\family default - variables. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:cache_output} - -\end_inset - -Output caching system -\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 default - instead of -\family typewriter -_i -\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 default - variables behave exactly like Mathematica's -\family typewriter -% -\family default - variables. -\end_layout - -\begin_layout Standard -The following GLOBAL variables always exist (so don't overwrite them!): - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -_ -\family default -\series default - (a -\emph on -single -\emph default - underscore) : stores previous output, like Python's default interpreter. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -__ -\family default -\series default - (two underscores): next previous. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -___ -\family default -\series default - (three underscores): next-next previous. -\end_layout - -\begin_layout Standard -Additionally, global variables named -\family typewriter -_ -\family default -are dynamically created ( -\family typewriter - -\family default - being the prompt counter), such that the result of output -\family typewriter - -\family default - is always available as -\family typewriter -_ -\family default - (don't use the angle brackets, just the number, e.g. - -\family typewriter -_21 -\family default -). -\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 -_oh -\family default - and -\family typewriter -Out -\family default - (similar to -\family typewriter -_ih -\family default - and -\family typewriter -In -\family default -). - So the output from line 12 can be obtained as -\family typewriter -_12 -\family default -, -\family typewriter -Out[12] -\family default - or -\family typewriter -_oh[12] -\family default -. - If you accidentally overwrite the -\family typewriter -Out -\family default - variable you can recover it by typing -\family typewriter -'Out=_oh -\family default -' at the prompt. -\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 -ipythonrc -\family default - file) -\family typewriter -cache_size -\family default -. - If you set it to 0, the whole system is completely disabled and the prompts - revert to the classic -\family typewriter -'>>>' -\family default - of normal Python. -\end_layout - -\begin_layout Subsection -Directory history -\end_layout - -\begin_layout Standard -Your history of visited directories is kept in the global list -\family typewriter -_dh -\family default -, and the magic -\family typewriter -%cd -\family default - command can be used to go to any entry in that list. - The -\family typewriter -%dhist -\family default - command allows you to view this history. -\end_layout - -\begin_layout Subsection -Automatic parentheses and quotes -\end_layout - -\begin_layout Standard -These features were adapted from Nathan Gray's LazyPython. - They are meant to allow less typing for common situations. -\end_layout - -\begin_layout Subsubsection -Automatic parentheses -\end_layout - -\begin_layout Standard -Callable objects (i.e. - functions, methods, etc) can be invoked like this (notice the commas between - the arguments): -\end_layout - -\begin_layout Standard - -\family typewriter ->>> callable_ob arg1, arg2, arg3 -\end_layout - -\begin_layout Standard -and the input will be translated to this: -\end_layout - -\begin_layout Standard - -\family typewriter ---> callable_ob(arg1, arg2, arg3) -\end_layout - -\begin_layout Standard -You can force automatic parentheses by using '/' as the first character - of a line. - For example: -\end_layout - -\begin_layout Standard - -\family typewriter ->>> /globals # becomes 'globals()' -\end_layout - -\begin_layout Standard -Note that the '/' MUST be the first character on the line! This won't work: - -\end_layout - -\begin_layout Standard - -\family typewriter ->>> print /globals # syntax error -\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): -\end_layout - -\begin_layout Standard - -\family typewriter -In [1]: zip (1,2,3),(4,5,6) # won't work -\end_layout - -\begin_layout Standard -but this will work: -\end_layout - -\begin_layout Standard - -\family typewriter -In [2]: /zip (1,2,3),(4,5,6) -\newline -------> zip ((1,2,3),(4,5,6)) -\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 default -. - e.g.: -\end_layout - -\begin_layout Standard - -\family typewriter -In [18]: callable list -\newline --------> callable (list) -\end_layout - -\begin_layout Subsubsection -Automatic quoting -\end_layout - -\begin_layout Standard -You can force automatic quoting of a function's arguments by using -\family typewriter -`,' -\family default - or -\family typewriter -`;' -\family default - as the first character of a line. - For example: -\end_layout - -\begin_layout Standard - -\family typewriter ->>> ,my_function /home/me # becomes my_function("/home/me") -\end_layout - -\begin_layout Standard -If you use -\family typewriter -`;' -\family default - instead, the whole argument is quoted as a single string (while -\family typewriter -`,' -\family default - splits on whitespace): -\end_layout - -\begin_layout Standard - -\family typewriter ->>> ,my_function a b c # becomes my_function("a","b","c") -\end_layout - -\begin_layout Standard - -\family typewriter ->>> ;my_function a b c # becomes my_function("a b c") -\end_layout - -\begin_layout Standard -Note that the ` -\family typewriter -, -\family default -' or ` -\family typewriter -; -\family default -' MUST be the first character on the line! This won't work: -\end_layout - -\begin_layout Standard - -\family typewriter ->>> x = ,my_function /home/me # syntax error -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:customization} - -\end_inset - -Customization -\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 --rcfile -\family default -) or which by default is assumed to be called -\family typewriter -ipythonrc -\family default -. - Such a file is looked for in the current directory where IPython is started - and then in your -\family typewriter -IPYTHONDIR -\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). -\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 default - are ignored as comments, but comments can -\series bold -not -\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. -\end_layout - -\begin_layout Standard -First, an rcfile can contain permanent default values for almost all command - line options (except things like -\family typewriter --help -\family default - or -\family typewriter --Version -\family default -). - Sec\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:cmd-line-opts} - -\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. -\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. - -\end_layout - -\begin_layout Standard -Each of these options may appear as many times as you need it in the file. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -include\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -... -\family default -\series default -: you can name -\emph on -other -\emph default -rcfiles you want to recursively load up to 15 levels (don't use the -\family typewriter -<> -\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 --profile -\family default - option (abbreviates to -\family typewriter --p ) -\family typewriter - which -\family default - tells it to look for an rcfile named -\family typewriter -ipythonrc- -\family default -. - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -import_mod\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -... -\family default -\series default -: import modules with ' -\family typewriter -import -\family default - -\family typewriter -,,... -\family default -' -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -import_some\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -... -\family default -\series default -: import functions with ' -\family typewriter -from import -\family default - -\family typewriter -,,... -\family default -' -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -import_all\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -... -\family default -\series default -: for each module listed import functions with ' -\family typewriter -from import * -\family default -' -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -execute\InsetSpace ~ - -\family default -\series default -: give any single-line python code to be executed. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -execfile\InsetSpace ~ - -\family default -\series default -: execute the python file given with an ' -\family typewriter -execfile(filename) -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 - -\family typewriter -\series bold -alias\InsetSpace ~ - -\family default -\series default -: this is equivalent to calling ' -\family typewriter -%alias\InsetSpace ~ - -\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 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. -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:ipytonrc-sample} - -\end_inset - -Sample -\family typewriter -ipythonrc -\family default - file -\end_layout - -\begin_layout Standard -The default rcfile, called -\family typewriter -ipythonrc -\family default - and supplied in your -\family typewriter -IPYTHONDIR -\family default -directory contains lots of comments on all of these options. - We reproduce it here for reference: -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Standard - - -\backslash -codelist{../IPython/UserConfig/ipythonrc} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:prompts} - -\end_inset - -Fine-tuning your prompt -\end_layout - -\begin_layout Standard -IPython's prompts can be customized using a syntax similar to that of the - -\family typewriter -bash -\family default - shell. - Many of -\family typewriter -bash -\family default -'s escapes are supported, as well as a few additional ones. - We list them below: -\end_layout - -\begin_layout Description - -\backslash -# the prompt/history count number. - This escape is automatically wrapped in the coloring codes for the currently - active color scheme. -\end_layout - -\begin_layout Description - -\backslash -N the 'naked' prompt/history count number: this is just the number itself, - without any coloring applied to it. - This lets you produce numbered prompts with your own colors. -\end_layout - -\begin_layout Description - -\backslash -D the prompt/history count, with the actual digits replaced by dots. - Used mainly in continuation prompts (prompt_in2) -\end_layout - -\begin_layout Description - -\backslash -w the current working directory -\end_layout - -\begin_layout Description - -\backslash -W the basename of current working directory -\end_layout - -\begin_layout Description - -\backslash -X -\emph on -n -\emph default - where -\begin_inset Formula $n=0\ldots5.$ -\end_inset - - The current working directory, with -\family typewriter -$HOME -\family default - replaced by -\family typewriter -~ -\family default -, and filtered out to contain only -\begin_inset Formula $n$ -\end_inset - - path elements -\end_layout - -\begin_layout Description - -\backslash -Y -\emph on -n -\emph default - Similar to -\backslash -X -\emph on -n -\emph default -, but with the -\begin_inset Formula $n+1$ -\end_inset - - element included if it is -\family typewriter -~ -\family default - (this is similar to the behavior of the %c -\emph on -n -\emph default - escapes in -\family typewriter -tcsh -\family default -) -\end_layout - -\begin_layout Description - -\backslash -u the username of the current user -\end_layout - -\begin_layout Description - -\backslash -$ if the effective UID is 0, a #, otherwise a $ -\end_layout - -\begin_layout Description - -\backslash -h the hostname up to the first `.' -\end_layout - -\begin_layout Description - -\backslash -H the hostname -\end_layout - -\begin_layout Description - -\backslash -n a newline -\end_layout - -\begin_layout Description - -\backslash -r a carriage return -\end_layout - -\begin_layout Description - -\backslash -v IPython version string -\end_layout - -\begin_layout Standard -In addition to these, ANSI color escapes can be insterted into the prompts, - as -\family typewriter - -\backslash -C_ -\emph on -ColorName -\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. -\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 -$x.y -\family default - to expand the value of -\family typewriter -x.y -\family default -, and for more complicated expressions you can use braces: -\family typewriter -${foo()+x} -\family default - will call function -\family typewriter -foo -\family default - and add to it the value of -\family typewriter -x -\family default -, before putting the result into your prompt. - For example, using -\newline - -\family typewriter -prompt_in1 '${commands.getoutput("uptime")} -\backslash -nIn [ -\backslash -#]: ' -\newline - -\family default -will print the result of the uptime command on each prompt (assuming the - -\family typewriter -commands -\family default - module has been imported in your -\family typewriter -ipythonrc -\family default - file). -\end_layout - -\begin_layout Subsubsection -Prompt examples -\end_layout - -\begin_layout Standard -The following options in an ipythonrc file will give you IPython's default - prompts: -\end_layout - -\begin_layout Standard - -\family typewriter -prompt_in1 'In [ -\backslash -#]:' -\newline -prompt_in2 '\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -. -\backslash -D.:' -\newline -prompt_out 'Out[ -\backslash -#]:' -\end_layout - -\begin_layout Standard -which look like this: -\end_layout - -\begin_layout Standard - -\family typewriter -In [1]: 1+2 -\newline -Out[1]: 3 -\end_layout - -\begin_layout Standard - -\family typewriter -In [2]: for i in (1,2,3): -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -...: \InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -print i, -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -...: -\newline -1 2 3 -\end_layout - -\begin_layout Standard -These will give you a very colorful prompt with path information: -\end_layout - -\begin_layout Standard - -\family typewriter -#prompt_in1 ' -\backslash -C_Red -\backslash -u -\backslash -C_Blue[ -\backslash -C_Cyan -\backslash -Y1 -\backslash -C_Blue] -\backslash -C_LightGreen -\backslash -#>' -\newline -prompt_in2 ' .. -\backslash -D>' -\newline -prompt_out '< -\backslash -#>' -\end_layout - -\begin_layout Standard -which look like this: -\end_layout - -\begin_layout Standard - -\family typewriter -\color red -fperez -\color blue -[ -\color cyan -~/ipython -\color blue -] -\color green -1> -\color none - 1+2 -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - -\color red -<1> -\color none - 3 -\newline - -\color red -fperez -\color blue -[ -\color cyan -~/ipython -\color blue -] -\color green -2> -\color none - for i in (1,2,3): -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - -\color green -...> -\color none - \InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -print i, -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - -\color green -...> -\color none - -\newline -1 2 3 -\end_layout - -\begin_layout Standard -The following shows the usage of dynamic expression evaluation: -\end_layout - -\begin_layout Subsection -\begin_inset LatexCommand \label{sec:profiles} - -\end_inset - -IPython profiles -\end_layout - -\begin_layout Standard -As we already mentioned, IPython supports the -\family typewriter --profile -\family default - command-line option (see sec. - -\begin_inset LatexCommand \ref{sec:cmd-line-opts} - -\end_inset - -). - A profile is nothing more than a particular configuration file like your - basic -\family typewriter -ipythonrc -\family default - one, but with particular customizations for a specific purpose. - When you start IPython with ' -\family typewriter -ipython -profile -\family default -', it assumes that in your -\family typewriter -IPYTHONDIR -\family default - there is a file called -\family typewriter -ipythonrc- -\family default -, and loads it instead of the normal -\family typewriter -ipythonrc -\family default -. -\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. - In order to avoid having to repeat all of your basic options (common things - that don't change such as your color preferences, for example), any profile - can include another configuration file. - The most common way to use profiles is then to have each one include your - basic -\family typewriter -ipythonrc -\family default - file as a starting point, and then add further customizations. -\end_layout - -\begin_layout Standard -In sections -\begin_inset LatexCommand \ref{sec:syntax-extensions} - -\end_inset - - and -\begin_inset LatexCommand \ref{sec:Gnuplot} - -\end_inset - - we discuss some particular profiles which come as part of the standard - IPython distribution. - You may also look in your -\family typewriter -IPYTHONDIR -\family default - directory, any file whose name begins with -\family typewriter -ipythonrc- -\family default - is a profile. - You can use those as examples for further customizations to suit your own - needs. -\end_layout - -\begin_layout Section -\begin_inset OptArg -status open - -\begin_layout Standard -IPython as default... -\end_layout - -\end_inset - -IPython as your default Python environment -\end_layout - -\begin_layout Standard -Python honors the environment variable -\family typewriter -PYTHONSTARTUP -\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: -\end_layout - -\begin_layout Standard - -\family typewriter -import IPython -\newline -IPython.Shell.IPShell().mainloop(sys_exit=1) -\end_layout - -\begin_layout Standard -then IPython will be your working environment anytime you start Python. - The -\family typewriter -sys_exit=1 -\family default - is needed to have IPython issue a call to -\family typewriter -sys.exit() -\family default - when it finishes, otherwise you'll be back at the normal Python ' -\family typewriter ->>> -\family default -' prompt -\begin_inset Foot -status collapsed - -\begin_layout Standard -Based on an idea by Holger Krekel. -\end_layout - -\end_inset - -. -\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. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:embed} - -\end_inset - -Embedding IPython -\end_layout - -\begin_layout Standard -It is possible to start an IPython instance -\emph on -inside -\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 -not -\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. -\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. -\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 -status collapsed - -\begin_layout Standard -This functionality was inspired by IDL's combination of the -\family typewriter -stop -\family default - keyword and the -\family typewriter -.continue -\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_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). -\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): -\end_layout - -\begin_layout LyX-Code -from IPython.Shell import IPShellEmbed -\end_layout - -\begin_layout LyX-Code -ipshell = IPShellEmbed() -\end_layout - -\begin_layout LyX-Code -ipshell() # this call anywhere in your program will start IPython -\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\InsetSpace ~ - -\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. -\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. -\end_layout - -\begin_layout Standard -Please look at the docstrings in the -\family typewriter -Shell.py -\family default - module for more details on the use of this system. -\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 -example-embed.py -\family default -. - It should be fairly self-explanatory: -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Standard - - -\backslash -codelist{examples/example-embed.py} -\end_layout - -\end_inset - - -\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: -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Standard - - -\backslash -codelist{examples/example-embed-short.py} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:using-pdb} - -\end_inset - -Using the Python debugger ( -\family typewriter -pdb -\family default -) -\end_layout - -\begin_layout Subsection -Running entire programs via -\family typewriter -pdb -\end_layout - -\begin_layout Standard - -\family typewriter -pdb -\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 -pdb -\family default -, regardless of whether you have wrapped it into a -\family typewriter -`main()' -\family default - function or not. - For this, simply type -\family typewriter -`%run -d myscript' -\family default - at an IPython prompt. - See the -\family typewriter -%run -\family default - command's documentation (via -\family typewriter -`%run?' -\family default - or in Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:magic} - -\end_inset - -) for more details, including how to control where -\family typewriter -pdb -\family default - will stop execution first. -\end_layout - -\begin_layout Standard -For more information on the use of the -\family typewriter -pdb -\family default - debugger, read the included -\family typewriter -pdb.doc -\family default - file (part of the standard Python distribution). - On a stock Linux system it is located at -\family typewriter -/usr/lib/python2.3/pdb.doc -\family default -, but the easiest way to read it is by using the -\family typewriter -help() -\family default - function of the -\family typewriter -pdb -\family default - module as follows (in an IPython prompt): -\end_layout - -\begin_layout Standard - -\family typewriter -In [1]: import pdb -\newline -In [2]: pdb.help() -\end_layout - -\begin_layout Standard -This will load the -\family typewriter -pdb.doc -\family default - document in a file viewer for you automatically. -\end_layout - -\begin_layout Subsection -Automatic invocation of -\family typewriter -pdb -\family default - on exceptions -\end_layout - -\begin_layout Standard -IPython, if started with the -\family typewriter --pdb -\family default - option (or if the option is set in your rc file) can call the Python -\family typewriter -pdb -\family default - debugger every time your code triggers an uncaught exception -\begin_inset Foot -status collapsed - -\begin_layout Standard -Many thanks to Christopher Hart for the request which prompted adding this - feature to IPython. -\end_layout - -\end_inset - -. - This feature can also be toggled at any time with the -\family typewriter -%pdb -\family default - magic command. - This can be extremely useful in order to find the origin of subtle bugs, - because -\family typewriter -pdb -\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. -\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 - -), simply call the constructor with -\family typewriter -`-pdb' -\family default - in the argument string and automatically -\family typewriter -pdb -\family default - will be called if an uncaught exception is triggered by your code. - -\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: -\end_layout - -\begin_layout Standard -\align left - -\family typewriter -import sys,IPython.ultraTB -\newline -sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbos -e', color_scheme=`Linux', call_pdb=1) -\end_layout - -\begin_layout Standard -The -\family typewriter -mode -\family default - keyword can be either -\family typewriter -`Verbose' -\family default - or -\family typewriter -`Plain' -\family default -, giving either very detailed or normal tracebacks respectively. - The -\family typewriter -color_scheme -\family default - keyword can be one of -\family typewriter -`NoColor' -\family default -, -\family typewriter -`Linux' -\family default - (default) or -\family typewriter -`LightBG' -\family default -. - These are the same options which can be set in IPython with -\family typewriter --colors -\family default - and -\family typewriter --xmode -\family default -. -\end_layout - -\begin_layout Standard -This will give any of your programs detailed, colored tracebacks with automatic - invocation of -\family typewriter -pdb -\family default -. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:syntax-extensions} - -\end_inset - -Extensions for syntax processing -\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. -\end_layout - -\begin_layout Standard -In the -\family typewriter -IPython/Extensions -\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. -\end_layout - -\begin_layout Subsection -Pasting of code starting with -\family typewriter -`>>> -\family default -' or -\family typewriter -`... - -\family default -' -\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 default -' or -\family typewriter -`... - -\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. -\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 -InterpreterPasteInput.py -\family default - in the -\family typewriter -IPython/Extensions -\family default - directory for details on how this is done. -\end_layout - -\begin_layout Standard -IPython comes with a special profile enabling this feature, called -\family typewriter -tutorial -\family default -\emph on -. - -\emph default - Simply start IPython via -\family typewriter -`ipython\InsetSpace ~ --p\InsetSpace ~ -tutorial' -\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 - -\family typewriter -In [1]: import IPython.Extensions.InterpreterPasteInput -\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: -\end_layout - -\begin_layout Standard - -\family typewriter -IPython profile: tutorial -\newline -\InsetSpace ~ - -\newline -*** Pasting of code with ">>>" or "..." has been enabled. -\newline -\InsetSpace ~ - -\newline -In - [1]: >>> def fib2(n): # return Fibonacci series up to n -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: ...\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - """Return a list containing the Fibonacci series up to n.""" -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: ...\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - result = [] -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: ...\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - a, b = 0, 1 -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: ...\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - while b < n: -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: ...\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - result.append(b)\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - # see below -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: ...\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - a, b = b, a+b -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: ...\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ - return result -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ - ...: -\newline -\InsetSpace ~ - -\newline -In [2]: fib2(10) -\newline -Out[2]: [1, 1, 2, 3, 5, 8] -\end_layout - -\begin_layout Standard -Note that as currently written, this extension does -\emph on -not -\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. -\end_layout - -\begin_layout Subsection -Input of physical quantities with units -\end_layout - -\begin_layout Standard -The module -\family typewriter -PhysicalQInput -\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 -PhysicalQInteractive -\family default - module (in the same directory) and -\family typewriter -Physics.PhysicalQuantities -\family default - from Konrad Hinsen's ScientificPython ( -\begin_inset LatexCommand \htmlurl{http://dirac.cnrs-orleans.fr/ScientificPython/} - -\end_inset - -). -\end_layout - -\begin_layout Standard -The -\family typewriter -Physics.PhysicalQuantities -\family default - module defines -\family typewriter -PhysicalQuantity -\family default - objects, but these must be declared as instances of a class. - For example, to define -\family typewriter -v -\family default - as a velocity of 3\InsetSpace ~ -m/s, normally you would write: -\family typewriter - -\newline -In [1]: v = PhysicalQuantity(3,'m/s') -\end_layout - -\begin_layout Standard -Using the -\family typewriter -PhysicalQ_Input -\family default - extension this can be input instead as: -\family typewriter - -\newline -In [1]: v = 3 m/s -\family default - -\newline -which is much more convenient for interactive use (even though it is blatantly - invalid Python syntax). -\end_layout - -\begin_layout Standard -The -\family typewriter -physics -\family default - profile supplied with IPython (enabled via -\family typewriter -'ipython -p physics' -\family default -) uses these extensions, which you can also activate with: -\end_layout - -\begin_layout Standard - -\family typewriter -from math import * # math MUST be imported BEFORE PhysicalQInteractive -\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 - -IPython as a system shell -\end_layout - -\begin_layout Standard -IPython ships with a special profile called -\family typewriter -pysh -\family default -, which you can activate at the command line as -\family typewriter -`ipython -p pysh' -\family default -. - This loads -\family typewriter -InterpreterExec -\family default -, along with some additional facilities and a prompt customized for filesystem - navigation. -\end_layout - -\begin_layout Standard -Note that this does -\emph on -not -\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. - -\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. -\end_layout - -\begin_layout Subsection -Aliases -\end_layout - -\begin_layout Standard -All of your -\family typewriter -$PATH -\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 -%alias? -\family default - and -\family typewriter -%unalias? -\family default - for details on the alias facilities. - See also -\family typewriter -%rehash? -\family default - and -\family typewriter -%rehashx? -\family default -for details on the mechanism used to load -\family typewriter -$PATH -\family default -. -\end_layout - -\begin_layout Subsection -Special syntax -\end_layout - -\begin_layout Standard -Any lines which begin with -\family typewriter -`~' -\family default -, -\family typewriter -`/' -\family default - and -\family typewriter -`.' -\family default - will be executed as shell commands instead of as Python code. - The special escapes below are also recognized. - -\family typewriter -!cmd -\family default - is valid in single or multi-line input, all others are only valid in single-lin -e input: -\end_layout - -\begin_layout Description - -\family typewriter -!cmd -\family default - pass `cmd' directly to the shell -\end_layout - -\begin_layout Description - -\family typewriter -!!cmd -\family default - execute `cmd' and return output as a list (split on ` -\backslash -n') -\end_layout - -\begin_layout Description - -\family typewriter -$var=cmd -\family default - capture output of cmd into var, as a string -\end_layout - -\begin_layout Description - -\family typewriter -$$var=cmd -\family default - capture output of cmd into var, as a list (split on ` -\backslash -n') -\end_layout - -\begin_layout Standard -The -\family typewriter -$ -\family default -/ -\family typewriter -$$ -\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 default -/ -\family typewriter -!! -\family default -, you can expand any python variable or expression by prepending it with - -\family typewriter -$ -\family default -. - Full details of the allowed syntax can be found in Python's PEP 215. -\end_layout - -\begin_layout Standard -A few brief examples will illustrate these (note that the indentation below - may be incorrectly displayed): -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|3> !ls *s.py -\newline -scopes.py strings.py -\end_layout - -\begin_layout Standard -ls is an internal alias, so there's no need to use -\family typewriter -! -\family default -: -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|4> ls *s.py -\newline -scopes.py* strings.py -\end_layout - -\begin_layout Standard -!!ls will return the output into a Python variable: -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|5> !!ls *s.py -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -<5> ['scopes.py', 'strings.py'] -\newline -fperez[~/test]|6> print _5 -\newline -['scopes.py', 'strings.py -'] -\end_layout - -\begin_layout Standard - -\family typewriter -$ -\family default - and -\family typewriter -$$ -\family default - allow direct capture to named variables: -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|7> $astr = ls *s.py -\newline -fperez[~/test]|8> astr -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -<8> 'scopes.py -\backslash -nstrings.py' -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|9> $$alist = ls *s.py -\newline -fperez[~/test]|10> alist -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -<10> ['scopes.py', 'strings.py'] -\end_layout - -\begin_layout Standard -alist is now a normal python list you can loop over. - Using -\family typewriter -$ -\family default - will expand back the python values when alias calls are made: -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|11> for f in alist: -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\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 - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\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 - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\end_layout - -\end_inset - -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -\InsetSpace ~ -|..> -\newline -file scopes.py 13 scopes.py -\newline -file strings.py 4 strings.py -\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 -.bak -\family default - extensions, you must use: -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|12> for f in alist: -\newline - -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -hspace*{0mm} -\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 -\end_layout - -\begin_layout Standard -If you try using -\family typewriter -$f.bak -\family default -, you'll get an AttributeError exception saying that your string object - doesn't have a -\family typewriter -.bak -\family default - attribute. - This is because the -\family typewriter -$ -\family default - expansion mechanism allows you to expand full Python expressions: -\end_layout - -\begin_layout Standard - -\family typewriter -fperez[~/test]|13> echo "sys.platform is: $sys.platform" -\newline -sys.platform is: linux2 -\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 - -\family typewriter -fperez[~/test]|14> $$alist = ls *.eps -\newline -fperez[~/test]|15> exec _i11 -\newline -file image2.eps - 921 image2.eps -\newline -file image.eps 921 image.eps -\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. -\end_layout - -\begin_layout Subsection -Useful functions and modules -\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 default -'. -\end_layout - -\begin_layout Description - -\family typewriter -shell -\family default - - execute a command in the underlying system shell -\end_layout - -\begin_layout Description - -\family typewriter -system -\family default - - like -\family typewriter -shell() -\family default -, but return the exit status of the command -\end_layout - -\begin_layout Description - -\family typewriter -sout -\family default - - capture the output of a command as a string -\end_layout - -\begin_layout Description - -\family typewriter -lout -\family default - - capture the output of a command as a list (split on ` -\backslash -n') -\end_layout - -\begin_layout Description - -\family typewriter -getoutputerror -\family default - - capture (output,error) of a shell commandss -\end_layout - -\begin_layout Standard - -\family typewriter -sout -\family default -/ -\family typewriter -lout -\family default - are the functional equivalents of -\family typewriter -$ -\family default -/ -\family typewriter -$$ -\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 default - and -\family typewriter -$$ -\family default - are invalid). -\end_layout - -\begin_layout Subsection -Directory management -\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. -\end_layout - -\begin_layout Standard -Pysh provides its own builtin -\family typewriter -`%cd -\family default -' magic command to move in the filesystem (the -\family typewriter -% -\family default - is not required with automagic on). - It also maintains a list of visited directories (use -\family typewriter -%dhist -\family default - to see it) and allows direct switching to any of them. - Type -\family typewriter -`cd? -\family default -' for more details. -\end_layout - -\begin_layout Standard - -\family typewriter -%pushd -\family default -, -\family typewriter -%popd -\family default - and -\family typewriter -%dirs -\family default - are provided for directory stack handling. -\end_layout - -\begin_layout Subsection -Prompt customization -\end_layout - -\begin_layout Standard -The supplied -\family typewriter -ipythonrc-pysh -\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: -\end_layout - -\begin_layout Description - -\backslash -# - Prompt number, wrapped in the color escapes for the input prompt (determined - by the current color scheme). -\end_layout - -\begin_layout Description - -\backslash -N - Just the prompt counter number, -\emph on -without -\emph default - any coloring wrappers. - You can thus customize the actual prompt colors manually. -\end_layout - -\begin_layout Description - -\backslash -D - Dots, as many as there are digits in -\backslash -# (so they align). -\end_layout - -\begin_layout Description - -\backslash -w - Current working directory (cwd). -\end_layout - -\begin_layout Description - -\backslash -W - Basename of current working directory. -\end_layout - -\begin_layout Description - -\backslash -X -\emph on -N -\emph default - - Where -\emph on -N -\emph default -=0..5. - N terms of the cwd, with $HOME written as ~. -\end_layout - -\begin_layout Description - -\backslash -Y -\emph on -N -\emph default - - Where -\emph on -N -\emph default -=0..5. - Like X -\emph on -N -\emph default -, but if ~ is term -\emph on -N -\emph default -+1 it's also shown. -\end_layout - -\begin_layout Description - -\backslash -u - Username. -\end_layout - -\begin_layout Description - -\backslash -H - Full hostname. -\end_layout - -\begin_layout Description - -\backslash -h - Hostname up to first '.' -\end_layout - -\begin_layout Description - -\backslash -$ - Root symbol ($ or #). - -\end_layout - -\begin_layout Description - -\backslash -t - Current time, in H:M:S format. -\end_layout - -\begin_layout Description - -\backslash -v - IPython release version. - -\end_layout - -\begin_layout Description - -\backslash -n - Newline. - -\end_layout - -\begin_layout Description - -\backslash -r - Carriage return. - -\end_layout - -\begin_layout Description - -\backslash - -\backslash - - An explicitly escaped ' -\backslash -'. -\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: -\end_layout - -\begin_layout Description - -\backslash -C_Black -\end_layout - -\begin_layout Description - -\backslash -C_Blue -\end_layout - -\begin_layout Description - -\backslash -C_Brown -\end_layout - -\begin_layout Description - -\backslash -C_Cyan -\end_layout - -\begin_layout Description - -\backslash -C_DarkGray -\end_layout - -\begin_layout Description - -\backslash -C_Green -\end_layout - -\begin_layout Description - -\backslash -C_LightBlue -\end_layout - -\begin_layout Description - -\backslash -C_LightCyan -\end_layout - -\begin_layout Description - -\backslash -C_LightGray -\end_layout - -\begin_layout Description - -\backslash -C_LightGreen -\end_layout - -\begin_layout Description - -\backslash -C_LightPurple -\end_layout - -\begin_layout Description - -\backslash -C_LightRed -\end_layout - -\begin_layout Description - -\backslash -C_Purple -\end_layout - -\begin_layout Description - -\backslash -C_Red -\end_layout - -\begin_layout Description - -\backslash -C_White -\end_layout - -\begin_layout Description - -\backslash -C_Yellow -\end_layout - -\begin_layout Description - -\backslash -C_Normal Stop coloring, defaults to your terminal settings. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:Threading-support} - -\end_inset - -Threading support -\end_layout - -\begin_layout Standard - -\series bold -WARNING: -\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 - platform-dependent behavior. - 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. -\end_layout - -\begin_layout Standard -IPython, via the -\family typewriter --gthread -\family default - , -\family typewriter --qthread -\family default -, -\family typewriter --q4thread -\family default - and -\family typewriter --wthread -\family default - options (described in Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:threading-opts} - -\end_inset - -), can run in multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython - applications respectively. - These GUI toolkits need to control the python main loop of execution, so - under a normal Python interpreter, starting a pyGTK, Qt3, Qt4 or WXPython - application will immediately freeze the shell. - -\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 -%run -\family default -, for example) your GUI code without blocking. -\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_layout - -\begin_layout Subsection -Tk issues -\end_layout - -\begin_layout Standard -As indicated in Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:threading-opts} - -\end_inset - -, a special -\family typewriter --tk -\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. -\end_layout - -\begin_layout Subsection -I/O pitfalls -\end_layout - -\begin_layout Standard -Be mindful that the Python interpreter switches between threads every -\begin_inset Formula $N$ -\end_inset - - bytecodes, where the default value as of Python\InsetSpace ~ -2.3 is -\begin_inset Formula $N=100.$ -\end_inset - - This value can be read by using the -\family typewriter -sys.getcheckinterval() -\family default - function, and it can be reset via -\family typewriter -sys.setcheckinterval( -\emph on -N -\emph 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 -` -\backslash -n' -\family default -. - An instruction as simple as -\family typewriter - -\newline -\InsetSpace ~ -\InsetSpace ~ -print >> filehandle, -\begin_inset Quotes eld -\end_inset - -hello world -\begin_inset Quotes erd -\end_inset - - -\family default - -\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. - -\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 -file/open -\family default - function is the buffering value): -\newline - -\family typewriter -\InsetSpace ~ -\InsetSpace ~ -filehandle = open(filename,mode,0) -\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. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:interactive-demos} - -\end_inset - -Interactive demos with IPython -\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 - code) divide a file into separate blocks, and the demo can be run one block - at a time, with IPython printing (with syntax highlighting) the block before - 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. -\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. -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Standard - - -\backslash -codelist{examples/example-demo.py} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -In order to run a file as a demo, you must first make a -\family typewriter -Demo -\family default - object out of it. - If the file is named -\family typewriter -myscript.py -\family default -, the following code will make a demo: -\end_layout - -\begin_layout LyX-Code -from IPython.demo import Demo -\end_layout - -\begin_layout LyX-Code -mydemo = Demo('myscript.py') -\end_layout - -\begin_layout Standard -This creates the -\family typewriter -mydemo -\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 -\end_layout - -\begin_layout LyX-Code -mydemo -\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 default - on them to see their docstrings for more usage details. - In addition, the -\family typewriter -demo -\family default - module itself contains a comprehensive docstring, which you can access - via -\end_layout - -\begin_layout LyX-Code -from IPython import demo -\end_layout - -\begin_layout LyX-Code -demo? -\end_layout - -\begin_layout Standard - -\series bold -Limitations: -\series default - It is important to note that these demos are limited to fairly simple uses. - In particular, you can -\emph on -not -\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 - are allowed. - 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 \@. -\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:embed} - -\end_inset - -. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:matplotlib-support} - -\end_inset - -Plotting with -\family typewriter -matplotlib -\family default - -\end_layout - -\begin_layout Standard -The matplotlib library ( -\begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net} - -\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. -\end_layout - -\begin_layout Standard -IPython accepts the special option -\family typewriter --pylab -\family default - (Sec.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:cmd-line-opts} - -\end_inset - -). - This configures it to support matplotlib, honoring the settings in the - -\family typewriter -.matplotlibrc -\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 -%run -\family default - slightly, so that any matplotlib-based script can be executed using -\family typewriter -%run -\family default - and the final -\family typewriter -show() -\family default - command does not block the interactive shell. -\end_layout - -\begin_layout Standard -The -\family typewriter --pylab -\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.\InsetSpace ~ - -\begin_inset LatexCommand \ref{sec:profiles} - -\end_inset - -): `` -\family typewriter -ipython -pylab -p myprofile -\family default -'' will load the profile defined in -\family typewriter -ipythonrc-myprofile -\family default - after configuring matplotlib. -\end_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:Gnuplot} - -\end_inset - -Plotting with -\family typewriter -Gnuplot -\end_layout - -\begin_layout Standard -Through the magic extension system described in sec. - -\begin_inset LatexCommand \ref{sec:magic} - -\end_inset - -, IPython incorporates a mechanism for conveniently interfacing with the - Gnuplot system ( -\begin_inset LatexCommand \htmlurl{http://www.gnuplot.info} - -\end_inset - -). - Gnuplot is a very complete 2D and 3D plotting package available for many - operating systems and commonly included in modern Linux distributions. - -\end_layout - -\begin_layout Standard -Besides having Gnuplot installed, this functionality requires the -\family typewriter -Gnuplot.py -\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_layout - -\begin_layout Subsection -Proper Gnuplot configuration -\end_layout - -\begin_layout Standard -As of version 4.0, Gnuplot has excellent mouse and interactive keyboard support. - However, as of -\family typewriter -Gnuplot.py -\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 -prefer_fifo_data -\family default - to -\family typewriter -0 -\family default - in file -\family typewriter -gp_unix.py -\family default - if you wish to keep the interactive mouse and keyboard features working - properly ( -\family typewriter -prefer_inline_data -\family default - also must be -\family typewriter -0 -\family default -, but this is the default so unless you've changed it manually you should - be fine). -\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 -.Xdefaults -\family default - file which I use for having a more convenient Gnuplot setup. - Remember to load it by running -\family typewriter -`xrdb .Xdefaults` -\family default -: -\end_layout - -\begin_layout Standard - -\family typewriter -!****************************************************************** -\newline -! gnuplot - options -\newline -! modify this for a convenient window size -\newline -gnuplot*geometry: 780x580 -\end_layout - -\begin_layout Standard - -\family typewriter -! on-screen font (not for PostScript) -\newline -gnuplot*font: -misc-fixed-bold-r-normal--15 --120-100-100-c-90-iso8859-1 -\end_layout - -\begin_layout Standard - -\family typewriter -! color options -\newline -gnuplot*background: black -\newline -gnuplot*textColor: white -\newline -gnuplot*borderCo -lor: white -\newline -gnuplot*axisColor: white -\newline -gnuplot*line1Color: red -\newline -gnuplot*line2Color: - green -\newline -gnuplot*line3Color: blue -\newline -gnuplot*line4Color: magenta -\newline -gnuplot*line5Color: - cyan -\newline -gnuplot*line6Color: sienna -\newline -gnuplot*line7Color: orange -\newline -gnuplot*line8Color: - coral -\end_layout - -\begin_layout Standard - -\family typewriter -! multiplicative factor for point styles -\newline -gnuplot*pointsize: 2 -\end_layout - -\begin_layout Standard - -\family typewriter -! line width options (in pixels) -\newline -gnuplot*borderWidth: 2 -\newline -gnuplot*axisWidth: - 2 -\newline -gnuplot*line1Width: 2 -\newline -gnuplot*line2Width: 2 -\newline -gnuplot*line3Width: 2 -\newline -gnuplot*line4Wi -dth: 2 -\newline -gnuplot*line5Width: 2 -\newline -gnuplot*line6Width: 2 -\newline -gnuplot*line7Width: 2 -\newline -gnuplot*lin -e8Width: 2 -\end_layout - -\begin_layout Subsection -The -\family typewriter -IPython.GnuplotRuntime -\family default - module -\end_layout - -\begin_layout Standard -IPython includes a module called -\family typewriter -Gnuplot2.py -\family default - which extends and improves the default -\family typewriter -Gnuplot -\family default -. -\family typewriter -py -\family default - (which it still relies upon). - For example, the new -\family typewriter -plot -\family default - function adds several improvements to the original making it more convenient - for interactive use, and -\family typewriter -hardcopy -\family default - fixes a bug in the original which under some circumstances blocks the creation - of PostScript output. -\end_layout - -\begin_layout Standard -For scripting use, -\family typewriter -GnuplotRuntime.py -\family default - is provided, which wraps -\family typewriter -Gnuplot2.py -\family default - and creates a series of global aliases. - These make it easy to control Gnuplot plotting jobs through the Python - language. -\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 -example-gnuplot.py -\family default - in the examples directory: -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Standard - - -\backslash -codelist{examples/example-gnuplot.py} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -The -\family typewriter -numeric -\family default - profile: a scientific computing environment -\end_layout - -\begin_layout Standard -The -\family typewriter -numeric -\family default - IPython profile, which you can activate with -\family typewriter -`ipython -p numeric -\family default -' will automatically load the IPython Gnuplot extensions (plus Numeric and - other useful things for numerical computing), contained in the -\family typewriter -IPython.GnuplotInteractive -\family default - module. - This will create the globals -\family typewriter -Gnuplot -\family default -(an alias to the improved Gnuplot2 module), -\family typewriter -gp -\family default - (a Gnuplot active instance), the new magic commands -\family typewriter -%gpc -\family default - and -\family typewriter -%gp_set_instance -\family default - and several other convenient globals. - Type -\family typewriter -gphelp() -\family default - for further details. -\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. - Further improvements can be obtained by loading the SciPy libraries for - scientific computing, available at -\begin_inset LatexCommand \htmlurl{http://scipy.org} - -\end_inset - -. -\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 -numeric -\family default - profile, you can load these extensions at any time by typing -\newline - -\family typewriter -from IPython.GnuplotInteractive import * -\newline - -\family default -at the IPython prompt. - This will allow you to keep your objects intact and start using Gnuplot - to view them. -\end_layout - -\begin_layout Section -Reporting bugs -\end_layout - -\begin_layout Subsection* -Automatic crash reports -\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. -\end_layout - -\begin_layout Standard -In such a situation, IPython will leave a file named -\family typewriter -IPython_crash_report.txt -\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). - If you can mail this file to the developers (see sec. - -\begin_inset LatexCommand \ref{sec:credits} - -\end_inset - - for names and addresses), it will help us -\emph on -a lot -\emph default - in understanding the cause of the problem and fixing it sooner. -\end_layout - -\begin_layout Subsection* -The bug tracker -\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 - -. - 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. -\end_layout - -\begin_layout Standard -You can also use this bug tracker to file feature requests. -\end_layout - -\begin_layout Section -Brief history -\end_layout - -\begin_layout Subsection -Origins -\end_layout - -\begin_layout Standard -The current IPython system grew out of the following three projects: -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -ipython by Fernando P -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -'{e} -\end_layout - -\end_inset - -rez. - I was working on adding Mathematica-type prompts and a flexible configuration - system (something better than -\family typewriter -$PYTHONSTARTUP -\family default -) to the standard Python interactive interpreter. -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -LazyPython by Nathan Gray. - Simple but -\emph on -very -\emph default - powerful. - The quick syntax (auto parens, auto quotes) and verbose/colored tracebacks - were all taken from here. -\end_layout - -\begin_layout Standard -When I found out (see sec. - -\begin_inset LatexCommand \ref{figgins} - -\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 - regular programming and scientific computing: shell-like features, IDL/Matlab - numerics, Mathematica-type prompt history and great object introspection - and help facilities. - I think it worked reasonably well, though it was a lot more work than I - had initially planned. -\end_layout - -\begin_layout Subsection -Current status -\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). -\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 - further major work is done. - 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. -\end_layout - -\begin_layout Subsection -Future -\end_layout - -\begin_layout Standard -See the separate -\family typewriter -new_design -\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. -\end_layout - -\begin_layout Section -License -\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 - -. - The full text of the IPython license is reproduced below: -\end_layout - -\begin_layout Quote - -\family typewriter -\size small -IPython is released under a BSD-type license. -\end_layout - -\begin_layout Quote - -\family typewriter -\size small -Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez . -\end_layout - -\begin_layout Quote - -\family typewriter -\size small -Copyright (c) 2001 Janko Hauser and -\newline -Nathaniel Gray . -\end_layout - -\begin_layout Quote - -\family typewriter -\size small -All rights reserved. -\end_layout - -\begin_layout Quote - -\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: -\end_layout - -\begin_layout Quote - -\family typewriter -\size small -a. - Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. -\end_layout - -\begin_layout Quote - -\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. -\end_layout - -\begin_layout Quote - -\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. -\end_layout - -\begin_layout Quote - -\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 - PURPOSE ARE DISCLAIMED. - IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, - BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON - ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF - THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -\end_layout - -\begin_layout Standard -Individual authors are the holders of the copyright for their code and are - listed in each file. -\end_layout - -\begin_layout Standard -Some files ( -\family typewriter -DPyGetOpt.py -\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. -\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_layout - -\begin_layout Section -\begin_inset LatexCommand \label{sec:credits} - -\end_inset - -Credits -\end_layout - -\begin_layout Standard -IPython is mainly developed by Fernando P -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -'{e} -\end_layout - -\end_inset - -rez -\family typewriter - -\family default -, but the project was born from mixing in Fernando's code with the IPP project - by Janko Hauser -\family typewriter - -\family default - and LazyPython by Nathan Gray -\family typewriter - -\family default -. - For all IPython-related requests, please contact Fernando. - -\end_layout - -\begin_layout Standard -As of early 2006, the following developers have joined the core team: -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Robert\InsetSpace ~ -Kern -\family typewriter - -\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 default - and Toni Alatalo -\family typewriter - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Brian\InsetSpace ~ -Granger -\family typewriter - -\family default -: extending IPython to allow support for interactive parallel computing. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Ville\InsetSpace ~ -Vainio -\family typewriter - -\family default -: Ville is the new maintainer for the main trunk of IPython after version - 0.7.1. -\end_layout - -\begin_layout Standard -User or development help should be requested via the IPython mailing lists: -\end_layout - -\begin_layout Description -User\InsetSpace ~ -list: -\begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-user} - -\end_inset - - -\end_layout - -\begin_layout Description -Developer's\InsetSpace ~ -list: -\begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-dev} - -\end_inset - - -\end_layout - -\begin_layout Standard -The IPython project is also very grateful to -\begin_inset Foot -status collapsed - -\begin_layout Standard -I've mangled email addresses to reduce spam, since the IPython manuals can - be accessed online. -\end_layout - -\end_inset - -: -\end_layout - -\begin_layout Standard -Bill Bumgarner -\family typewriter - -\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). -\end_layout - -\begin_layout Standard -Ka-Ping Yee -\family typewriter - -\family default -: for providing the Itpl module for convenient and powerful string interpolation - with a much nicer syntax than formatting through the '%' operator. -\end_layout - -\begin_layout Standard -Arnd Baecker -\family typewriter - -\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). -\end_layout - -\begin_layout Standard -Obviously Guido van\InsetSpace ~ -Rossum and the whole Python development team, that goes - without saying. -\end_layout - -\begin_layout Standard -IPython's website is generously hosted at -\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org} - -\end_inset - - by Enthought ( -\begin_inset LatexCommand \htmlurl{http://www.enthought.com} - -\end_inset - -). - I am very grateful to them and all of the SciPy team for their contribution. -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand \label{figgins} - -\end_inset - -Fernando would also like to thank Stephen Figgins -\family typewriter - -\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_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: -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Jack\InsetSpace ~ -Moffit -\family typewriter - -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Alexander\InsetSpace ~ -Schmolck -\family typewriter - -\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. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Andrea\InsetSpace ~ -Riciputi -\family typewriter - -\family default - Mac OSX information, Fink package management. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Gary\InsetSpace ~ -Bishop -\family typewriter - -\family default - Bug reports, and patches to work around the exception handling idiosyncracies - of WxPython. - Readline and color support for Windows. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Jeffrey\InsetSpace ~ -Collins -\family typewriter - -\family default - Bug reports. - Much improved readline support, including fixes for Python 2.3. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Dryice\InsetSpace ~ -Liu -\family typewriter - -\family default - FreeBSD port. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Mike\InsetSpace ~ -Heeter -\family typewriter - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Christopher\InsetSpace ~ -Hart -\family typewriter - -\family default - PDB integration. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Milan\InsetSpace ~ -Zamazal -\family typewriter - -\family default - Emacs info. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Philip\InsetSpace ~ -Hisley -\family typewriter - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Holger\InsetSpace ~ -Krekel -\family typewriter - -\family default - Tab completion, lots more. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Robin\InsetSpace ~ -Siebler -\family typewriter - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Ralf\InsetSpace ~ -Ahlbrink -\family typewriter - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Thorsten\InsetSpace ~ -Kampe -\family typewriter - -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Fredrik\InsetSpace ~ -Kant -\family typewriter - -\family default - Windows setup. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Syver\InsetSpace ~ -Enstad -\family typewriter - -\family default - Windows setup. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Richard -\family typewriter - -\family default - Global embedding. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Hayden\InsetSpace ~ -Callow -\family typewriter - -\family default - Gnuplot.py 1.6 compatibility. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Leonardo\InsetSpace ~ -Santagada -\family typewriter - -\family default - Fixes for Windows installation. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Christopher\InsetSpace ~ -Armstrong -\family typewriter - -\family default - Bugfixes. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Francois\InsetSpace ~ -Pinard -\family typewriter - -\family default - Code and documentation fixes. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Cory\InsetSpace ~ -Dodt -\family typewriter - -\family default - Bug reports and Windows ideas. - Patches for Windows installer. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Olivier\InsetSpace ~ -Aubert -\family typewriter - -\family default - New magics. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -King\InsetSpace ~ -C.\InsetSpace ~ -Shu -\family typewriter - -\family default - Autoindent patch. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Chris\InsetSpace ~ -Drexler -\family typewriter - -\family default - Readline packages for Win32/CygWin. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Gustavo\InsetSpace ~ -Cordova\InsetSpace ~ -Avila -\family typewriter - -\family default - EvalDict code for nice, lightweight string interpolation. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Kasper\InsetSpace ~ -Souren -\family typewriter - -\family default - Bug reports, ideas. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Gever\InsetSpace ~ -Tulley -\family typewriter - -\family default - Code contributions. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Ralf\InsetSpace ~ -Schmitt -\family typewriter - -\family default - Bug reports & fixes. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Oliver\InsetSpace ~ -Sander -\family typewriter - -\family default - Bug reports. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Rod\InsetSpace ~ -Holland -\family typewriter - -\family default - Bug reports and fixes to logging module. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Daniel\InsetSpace ~ -'Dang'\InsetSpace ~ -Griffith -\family typewriter - -\family default - Fixes, enhancement suggestions for system shell use. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Viktor\InsetSpace ~ -Ransmayr -\family typewriter - -\family default - Tests and reports on Windows installation issues. - Contributed a true Windows binary installer. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Mike\InsetSpace ~ -Salib -\family typewriter - -\family default - Help fixing a subtle bug related to traceback printing. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -W.J.\InsetSpace ~ -van\InsetSpace ~ -der\InsetSpace ~ -Laan -\family typewriter - -\family default - Bash-like prompt specials. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Antoon\InsetSpace ~ -Pardon -\family typewriter - -\family default - Critical fix for the multithreaded IPython. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -John\InsetSpace ~ -Hunter -\family typewriter - -\family default - Matplotlib author, helped with all the development of support for matplotlib - in IPyhton, including making necessary changes to matplotlib itself. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Matthew\InsetSpace ~ -Arnison -\family typewriter - -\family default - Bug reports, ` -\family typewriter -%run -d -\family default -' idea. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Prabhu\InsetSpace ~ -Ramachandran -\family typewriter - -\family default - Help with (X)Emacs support, threading patches, ideas... -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Norbert\InsetSpace ~ -Tretkowski -\family typewriter - -\family default - help with Debian packaging and distribution. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -George\InsetSpace ~ -Sakkis < -\family typewriter -gsakkis-AT-eden.rutgers.edu> -\family default - New matcher for tab-completing named arguments of user-defined functions. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Jörgen\InsetSpace ~ -Stenarson -\family typewriter - -\family default - Wildcard support implementation for searching namespaces. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Vivian\InsetSpace ~ -De\InsetSpace ~ -Smedt -\family typewriter - -\family default - Debugger enhancements, so that when pdb is activated from within IPython, - coloring, tab completion and other features continue to work seamlessly. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Scott\InsetSpace ~ -Tsai -\family typewriter - -\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_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Alexander\InsetSpace ~ -Belchenko -\family typewriter - -\family default - Improvements for win32 paging system. -\end_layout - -\begin_layout List -\labelwidthstring 00.00.0000 -Will\InsetSpace ~ -Maier -\family typewriter - -\family default - Official OpenBSD port. -\end_layout - -\end_body -\end_document diff --git a/doc/source/conf.py b/doc/source/conf.py index 0270b6e..3708400 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -34,7 +34,7 @@ master_doc = 'ipython' # General substitutions. project = 'IPython' -copyright = '2008, IPython team' +copyright = '2008, Fernando Perez' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. @@ -120,7 +120,7 @@ latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). -latex_documents = [('ipython','ipython.tex','IPython Documentation','IPython developers','manual')] +latex_documents = [('ipython','ipython.tex','IPython Documentation','Fernando Perez (and contributors)','manual')] # Additional stuff for the LaTeX preamble. #latex_preamble = '' diff --git a/doc/source/ipython.rst b/doc/source/ipython.rst index 4cbb7de..b34cf00 100644 --- a/doc/source/ipython.rst +++ b/doc/source/ipython.rst @@ -17,6 +17,21 @@ Indices and tables * :ref:`modindex` * :ref:`search` +Introduction +============ + +This is the official documentation for IPython 0.x series (i.e. what +we are used to refer to just as "IPython"). The original text of the +manual (most of which is still in place) has been authored by Fernando +Perez, but as recommended usage patterns and new features have +emerged, this manual has been updated to reflect that fact. Most of +the additions have been authored by Ville M. Vainio. + +The manual has been generated from reStructuredText source markup with +Sphinx, which should make it much easier to keep it up-to-date in the +future. Some reST artifacts and bugs may still be apparent in the +documentation, but this should improve as the toolchain matures. + Overview ======== @@ -181,7 +196,7 @@ Windows 9x support is present, and has been reported to work fine (at least on WinME). Location -======== +-------- IPython is generously hosted at http://ipython.scipy.org by the Enthought, Inc and the SciPy project. This site offers downloads, diff --git a/setup.py b/setup.py index 20daf9f..65944b3 100755 --- a/setup.py +++ b/setup.py @@ -46,43 +46,19 @@ from distutils.core import setup # update the manuals when building a source dist if len(sys.argv) >= 2 and sys.argv[1] in ('sdist','bdist_rpm'): + import textwrap from IPython.genutils import target_update # list of things to be updated. Each entry is a triplet of args for # target_update() - to_update = [('doc/magic.tex', - ['IPython/Magic.py'], - "cd doc && ./update_magic.sh" ), - - ('doc/manual.lyx', - ['IPython/Release.py','doc/manual_base.lyx'], - "cd doc && ./update_version.sh" ), - - ('doc/manual/manual.html', - ['doc/manual.lyx', - 'doc/magic.tex', - 'doc/examples/example-gnuplot.py', - 'doc/examples/example-embed.py', - 'doc/examples/example-embed-short.py', - 'IPython/UserConfig/ipythonrc', - ], - "cd doc && " - "lyxport -tt --leave --pdf " - "--html -o '-noinfo -split +1 -local_icons' manual.lyx"), - - ('doc/new_design.pdf', - ['doc/new_design.lyx'], - "cd doc && lyxport -tt --pdf new_design.lyx"), - - ('doc/ipython.1.gz', - ['doc/ipython.1'], - "cd doc && gzip -9c ipython.1 > ipython.1.gz"), - - ('doc/pycolor.1.gz', - ['doc/pycolor.1'], - "cd doc && gzip -9c pycolor.1 > pycolor.1.gz"), - ] - for target in to_update: - target_update(*target) + + def oscmd(s): + print ">", s + os.system(s) + + oscmd("cd doc && python do_sphinx.py") + + oscmd("cd doc && gzip -9c ipython.1 > ipython.1.gz") + oscmd("cd doc && gzip -9c pycolor.1 > pycolor.1.gz") # Release.py contains version, authors, license, url, keywords, etc. execfile(pjoin('IPython','Release.py')) @@ -113,9 +89,12 @@ exclude = ('.sh','.1.gz') docfiles = filter(lambda f:file_doesnt_endwith(f,exclude),glob('doc/*')) examfiles = filter(isfile, glob('doc/examples/*.py')) -manfiles = filter(isfile, glob('doc/manual/*.html')) + \ - filter(isfile, glob('doc/manual/*.css')) + \ - filter(isfile, glob('doc/manual/*.png')) +manfiles = filter(isfile, glob('doc/build/html/*')) +manstatic = filter(isfile, glob('doc/build/html/_static/*')) + +# filter(isfile, glob('doc/manual/*.css')) + \ +# filter(isfile, glob('doc/manual/*.png')) + manpages = filter(isfile, glob('doc/*.1.gz')) cfgfiles = filter(isfile, glob('IPython/UserConfig/*')) scriptfiles = filter(isfile, ['scripts/ipython','scripts/pycolor', @@ -135,6 +114,7 @@ if 'bdist_wininst' in sys.argv: datafiles = [('data', docdirbase, docfiles), ('data', pjoin(docdirbase, 'examples'),examfiles), ('data', pjoin(docdirbase, 'manual'),manfiles), + ('data', pjoin(docdirbase, 'manual/_static'),manstatic), ('data', manpagebase, manpages), ('data',pjoin(docdirbase, 'extensions'),igridhelpfiles), ]