Merge

IPython/Release.py

@@ -22,7 +22,7 b" 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':

IPython/external/path.py

@@ -29,7 +29,10 b' 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']

IPython/iplib.py

@@ -54,6 +54,8 b' 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
 

MANIFEST.in

@@ -22,6 +22,12 b' 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

doc/do_sphinx.py

@@ -60,5 +60,5 b" 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('../..')

doc/source/conf.py

@@ -34,7 +34,7 b" 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 b" 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 = ''

doc/source/ipython.rst

@@ -17,6 +17,21 b' 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 b' 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,

setup.py

@@ -46,43 +46,19 b' 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 b" 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 b" 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),
              ]

doc/manual_base.lyx

@@ -1,10507 +0,0 b''
-#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
-<[e-mail]>
-\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-<python-version>
-\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
-<markus.banfi-AT-mospheira.net>
-\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.<TAB>
-\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 <macroname>
-\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 <filename>
-\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 <val>:
-\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 ~
-<command>:
-\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 ~
-<n>
-\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 ~
-<scheme>:
-\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 ~
-<name>
-\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 ~
-<name>
-\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 ~
-<name>
-\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 ~
-<name>
-\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 <name>
-\series default
-:
-\family default
- assume that your config file is 
-\family typewriter
-ipythonrc-<name>
-\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 ~
-<string>:
-\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 ~
-<string>:
-\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 ~
-<string>:
-\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 ~
-<name>
-\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 ~
-<n>
-\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 ~
-<string>
-\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 ~
-<string>
-\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 ~
-<string>
-\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 ~
-<string>:
-\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 ~
-<modename>
-\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 "<console>", 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 ~
-<object>
-\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 ~
-<object>
-\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 ~
-<object>
-\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 ~
-<object>
-\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
-<tab>
-\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
-<tab>
-\family default
-: '
-\family typewriter
-name._<tab>
-\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<n>
-\family default
- are dynamically created (
-\family typewriter
-<n>
-\family default
- being the prompt counter), such that 
-\newline
-
-\family typewriter
-_i<n> == _ih[<n>] == In[<n>].
-\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
-_<n> 
-\family default
-are dynamically created (
-\family typewriter
-<n>
-\family default
- being the prompt counter), such that the result of output 
-\family typewriter
-<n>
-\family default
- is always available as 
-\family typewriter
-_<n>
-\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 ~
-<file1>\InsetSpace ~
-<file2>\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 <name>
-\family default
- option (abbreviates to 
-\family typewriter
--p <name
-\family default
->)
-\family typewriter
- which
-\family default
- tells it to look for an rcfile named 
-\family typewriter
-ipythonrc-<name>
-\family default
-.
- 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-import_mod\InsetSpace ~
-<mod1>\InsetSpace ~
-<mod2>\InsetSpace ~
-...
-\family default
-\series default
-: import modules with '
-\family typewriter
-import
-\family default
- 
-\family typewriter
-<mod1>,<mod2>,...
-\family default
-' 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-import_some\InsetSpace ~
-<mod>\InsetSpace ~
-<f1>\InsetSpace ~
-<f2>\InsetSpace ~
-...
-\family default
-\series default
-: import functions with '
-\family typewriter
-from <mod> import
-\family default
- 
-\family typewriter
-<f1>,<f2>,...
-\family default
-' 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-import_all\InsetSpace ~
-<mod1>\InsetSpace ~
-<mod2>\InsetSpace ~
-...
-\family default
-\series default
-: for each module listed import functions with '
-\family typewriter
-from <mod> import *
-\family default
-' 
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-
-\family typewriter
-\series bold
-execute\InsetSpace ~
-<python\InsetSpace ~
-code>
-\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 ~
-<filename>
-\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 ~
-<alias_def>
-\family default
-\series default
-: this is equivalent to calling '
-\family typewriter
-%alias\InsetSpace ~
-<alias_def>
-\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 <name>
-\family default
-', it assumes that in your 
-\family typewriter
-IPYTHONDIR
-\family default
- there is a file called 
-\family typewriter
-ipythonrc-<name>
-\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 <cmkleffner-AT-gmx.de> 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 ~
-<filename>
-\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 <[e-mail]>.
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-\size small
-Copyright (c) 2001 Janko Hauser <[e-mail]> and 
-\newline
-Nathaniel Gray <n8gray@ca
-ltech.edu>.
-\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
-<[e-mail]>
-\family default
-, but the project was born from mixing in Fernando's code with the IPP project
- by Janko Hauser 
-\family typewriter
-<jhauser-AT-zscout.de>
-\family default
- and LazyPython by Nathan Gray 
-\family typewriter
-<n8gray-AT-caltech.edu>
-\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
-<rkern-AT-enthought.com>
-\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
-<tsanko-AT-gmail.com>
-\family default
- and Toni Alatalo 
-\family typewriter
-<antont-AT-an.org>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Brian\InsetSpace ~
-Granger 
-\family typewriter
-<bgranger-AT-scu.edu>
-\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
-<vivainio-AT-gmail.com>
-\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
-<bbum-AT-friday.com>
-\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
-<ping-AT-lfw.org>
-\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
-<baecker-AT-physik.tu-dresden.de>
-\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
-<fig-AT-monitor.net>
-\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
-<jack-AT-xiph.org>
-\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
-<a.schmolck-AT-gmx.net> 
-\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
-<andrea.riciputi-AT-libero.it>
-\family default
- Mac OSX information, Fink package management.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Gary\InsetSpace ~
-Bishop 
-\family typewriter
-<gb-AT-cs.unc.edu>
-\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
-<Jeff.Collins-AT-vexcel.com>
-\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
-<dryice-AT-liu.com.cn>
-\family default
- FreeBSD port.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Mike\InsetSpace ~
-Heeter 
-\family typewriter
-<korora-AT-SDF.LONESTAR.ORG>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Christopher\InsetSpace ~
-Hart 
-\family typewriter
-<hart-AT-caltech.edu>
-\family default
- PDB integration.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Milan\InsetSpace ~
-Zamazal 
-\family typewriter
-<pdm-AT-zamazal.org>
-\family default
- Emacs info.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Philip\InsetSpace ~
-Hisley 
-\family typewriter
-<compsys-AT-starpower.net>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Holger\InsetSpace ~
-Krekel 
-\family typewriter
-<pyth-AT-devel.trillke.net>
-\family default
- Tab completion, lots more.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Robin\InsetSpace ~
-Siebler 
-\family typewriter
-<robinsiebler-AT-starband.net>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Ralf\InsetSpace ~
-Ahlbrink
-\family typewriter
- <ralf_ahlbrink-AT-web.de>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Thorsten\InsetSpace ~
-Kampe 
-\family typewriter
-<thorsten-AT-thorstenkampe.de>
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Fredrik\InsetSpace ~
-Kant 
-\family typewriter
-<fredrik.kant-AT-front.com>
-\family default
- Windows setup.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Syver\InsetSpace ~
-Enstad 
-\family typewriter
-<syver-en-AT-online.no>
-\family default
- Windows setup.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Richard 
-\family typewriter
-<rxe-AT-renre-europe.com>
-\family default
- Global embedding.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Hayden\InsetSpace ~
-Callow 
-\family typewriter
-<h.callow-AT-elec.canterbury.ac.nz>
-\family default
- Gnuplot.py 1.6 compatibility.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Leonardo\InsetSpace ~
-Santagada 
-\family typewriter
-<retype-AT-terra.com.br>
-\family default
- Fixes for Windows installation.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Christopher\InsetSpace ~
-Armstrong 
-\family typewriter
-<radix-AT-twistedmatrix.com>
-\family default
- Bugfixes.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Francois\InsetSpace ~
-Pinard 
-\family typewriter
-<pinard-AT-iro.umontreal.ca>
-\family default
- Code and documentation fixes.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Cory\InsetSpace ~
-Dodt 
-\family typewriter
-<cdodt-AT-fcoe.k12.ca.us>
-\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
-<oaubert-AT-bat710.univ-lyon1.fr>
-\family default
- New magics.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-King\InsetSpace ~
-C.\InsetSpace ~
-Shu 
-\family typewriter
-<kingshu-AT-myrealbox.com>
-\family default
- Autoindent patch.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Chris\InsetSpace ~
-Drexler 
-\family typewriter
-<chris-AT-ac-drexler.de>
-\family default
- Readline packages for Win32/CygWin.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Gustavo\InsetSpace ~
-Cordova\InsetSpace ~
-Avila 
-\family typewriter
-<gcordova-AT-sismex.com>
-\family default
- EvalDict code for nice, lightweight string interpolation.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Kasper\InsetSpace ~
-Souren 
-\family typewriter
-<Kasper.Souren-AT-ircam.fr>
-\family default
- Bug reports, ideas.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Gever\InsetSpace ~
-Tulley 
-\family typewriter
-<gever-AT-helium.com>
-\family default
- Code contributions.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Ralf\InsetSpace ~
-Schmitt 
-\family typewriter
-<ralf-AT-brainbot.com>
-\family default
- Bug reports & fixes.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Oliver\InsetSpace ~
-Sander 
-\family typewriter
-<osander-AT-gmx.de>
-\family default
- Bug reports.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Rod\InsetSpace ~
-Holland 
-\family typewriter
-<rhh-AT-structurelabs.com>
-\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
-<pythondev-dang-AT-lazytwinacres.net>
-\family default
- Fixes, enhancement suggestions for system shell use.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Viktor\InsetSpace ~
-Ransmayr 
-\family typewriter
-<viktor.ransmayr-AT-t-online.de>
-\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
-<msalib-AT-mit.edu>
-\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
-<gnufnork-AT-hetdigitalegat.nl>
-\family default
- Bash-like prompt specials.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Antoon\InsetSpace ~
-Pardon 
-\family typewriter
-<Antoon.Pardon-AT-rece.vub.ac.be>
-\family default
- Critical fix for the multithreaded IPython.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-John\InsetSpace ~
-Hunter 
-\family typewriter
-<jdhunter-AT-nitace.bsd.uchicago.edu>
-\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
-<maffew-AT-cat.org.au>
-\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
-<prabhu_r-AT-users.sourceforge.net>
-\family default
- Help with (X)Emacs support, threading patches, ideas...
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Norbert\InsetSpace ~
-Tretkowski 
-\family typewriter
-<tretkowski-AT-inittab.de>
-\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
-<jorgen.stenarson-AT-bostream.nu>
-\family default
- Wildcard support implementation for searching namespaces.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Vivian\InsetSpace ~
-De\InsetSpace ~
-Smedt 
-\family typewriter
-<vivian-AT-vdesmedt.com>
-\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
-<scottt958-AT-yahoo.com.tw>
-\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
-<bialix-AT-ukr.net>
-\family default
- Improvements for win32 paging system.
-\end_layout
-
-\begin_layout List
-\labelwidthstring 00.00.0000
-Will\InsetSpace ~
-Maier 
-\family typewriter
-<willmaier-AT-ml1.net>
-\family default
- Official OpenBSD port.
-\end_layout
-
-\end_body
-\end_document