##// END OF EJS Templates
Updated the main introduction to IPython in the Sphinx docs.
Brian E Granger -
Show More
@@ -1,3 +1,5 b''
1 .. _install_index:
2
1 3 ==================
2 4 Installation
3 5 ==================
@@ -4,18 +4,6 b''
4 4 Introduction
5 5 ============
6 6
7 This is the official documentation for IPython 0.x series (i.e. what
8 we are used to refer to just as "IPython"). The original text of the
9 manual (most of which is still in place) has been authored by Fernando
10 Perez, but as recommended usage patterns and new features have
11 emerged, this manual has been updated to reflect that fact. Most of
12 the additions have been authored by Ville M. Vainio.
13
14 The manual has been generated from reStructuredText source markup with
15 Sphinx, which should make it much easier to keep it up-to-date in the
16 future. Some reST artifacts and bugs may still be apparent in the
17 documentation, but this should improve as the toolchain matures.
18
19 7 Overview
20 8 ========
21 9
@@ -25,8 +13,19 b' creating test files as is typical in most programming languages.'
25 13 However, the interpreter supplied with the standard Python distribution
26 14 is somewhat limited for extended interactive use.
27 15
28 IPython is a free software project (released under the BSD license)
29 which tries to:
16 The goal of IPython is to create a comprehensive environment for
17 interactive and exploratory computing. To support, this goal, IPython
18 has two main components:
19
20 * An enhanced interactive Python shell.
21 * An architecture for interactive parallel computing.
22
23 All of IPython is open source (released under the revised BSD license).
24
25 Enhanced interactive Python shell
26 =================================
27
28 IPython's interactive shell (`ipython`), has the following goals:
30 29
31 30 1. Provide an interactive shell superior to Python's default. IPython
32 31 has many features for object introspection, system shell access,
@@ -50,17 +49,16 b' which tries to:'
50 49 WX applications via special threading flags. The normal Python
51 50 shell can only do this for Tkinter applications.
52 51
53
54 Main features
55 -------------
52 Main features of the interactive shell
53 --------------------------------------
56 54
57 55 * Dynamic object introspection. One can access docstrings, function
58 56 definition prototypes, source code, source files and other details
59 57 of any object accessible to the interpreter with a single
60 keystroke ('?', and using '??' provides additional detail).
61 * Searching through modules and namespaces with '*' wildcards, both
62 when using the '?' system and via the %psearch command.
63 * Completion in the local namespace, by typing TAB at the prompt.
58 keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
59 * Searching through modules and namespaces with :samp:`*` wildcards, both
60 when using the :samp:`?` system and via the :samp:`%psearch` command.
61 * Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
64 62 This works for keywords, modules, methods, variables and files in the
65 63 current directory. This is supported via the readline library, and
66 64 full access to configuring readline's behavior is provided.
@@ -70,31 +68,31 b' Main features'
70 68 across sessions and tied to each profile), full searching in this
71 69 history and caching of all input and output.
72 70 * User-extensible 'magic' commands. A set of commands prefixed with
73 % is available for controlling IPython itself and provides
71 :samp:`%` is available for controlling IPython itself and provides
74 72 directory control, namespace information and many aliases to
75 73 common system shell commands.
76 74 * Alias facility for defining your own system aliases.
77 * Complete system shell access. Lines starting with ! are passed
78 directly to the system shell, and using !! or var = !cmd
75 * Complete system shell access. Lines starting with :samp:`!` are passed
76 directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd`
79 77 captures shell output into python variables for further use.
80 78 * Background execution of Python commands in a separate thread.
81 79 IPython has an internal job manager called jobs, and a
82 conveninence backgrounding magic function called %bg.
80 conveninence backgrounding magic function called :samp:`%bg`.
83 81 * The ability to expand python variables when calling the system
84 shell. In a shell command, any python variable prefixed with $ is
85 expanded. A double $$ allows passing a literal $ to the shell (for
86 access to shell and environment variables like $PATH).
87 * Filesystem navigation, via a magic %cd command, along with a
88 persistent bookmark system (using %bookmark) for fast access to
82 shell. In a shell command, any python variable prefixed with :samp:`$` is
83 expanded. A double :samp:`$$` allows passing a literal :samp:`$` to the shell (for
84 access to shell and environment variables like :envvar:`PATH`).
85 * Filesystem navigation, via a magic :samp:`%cd` command, along with a
86 persistent bookmark system (using :samp:`%bookmark`) for fast access to
89 87 frequently visited directories.
90 * A lightweight persistence framework via the %store command, which
88 * A lightweight persistence framework via the :samp:`%store` command, which
91 89 allows you to save arbitrary Python variables. These get restored
92 90 automatically when your session restarts.
93 91 * Automatic indentation (optional) of code as you type (through the
94 92 readline library).
95 93 * Macro system for quickly re-executing multiple lines of previous
96 94 input with a single name. Macros can be stored persistently via
97 %store and edited via %edit.
95 :samp:`%store` and edited via :samp:`%edit`.
98 96 * Session logging (you can then later use these logs as code in your
99 97 programs). Logs can optionally timestamp all input, and also store
100 98 session output (marked as comments, so the log remains valid
@@ -106,15 +104,15 b' Main features'
106 104 debugging information (basically a terminal version of the cgitb
107 105 module).
108 106 * Auto-parentheses: callable objects can be executed without
109 parentheses: 'sin 3' is automatically converted to 'sin(3)'.
110 * Auto-quoting: using ',' or ';' as the first character forces
111 auto-quoting of the rest of the line: ',my_function a b' becomes
112 automatically 'my_function("a","b")', while ';my_function a b'
113 becomes 'my_function("a b")'.
107 parentheses: :samp:`sin 3` is automatically converted to :samp:`sin(3)`.
108 * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
109 auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
110 automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
111 becomes :samp:`my_function("a b")`.
114 112 * Extensible input syntax. You can define filters that pre-process
115 113 user input to simplify input in special situations. This allows
116 114 for example pasting multi-line code fragments which start with
117 '>>>' or '...' such as those from other python sessions or the
115 :samp:`>>>` or :samp:`...` such as those from other python sessions or the
118 116 standard Python documentation.
119 117 * Flexible configuration system. It uses a configuration file which
120 118 allows permanent setting of all command-line options, module
@@ -131,59 +129,46 b' Main features'
131 129 uncaught exception. This drops you inside the code which triggered
132 130 the exception with all the data live and it is possible to
133 131 navigate the stack to rapidly isolate the source of a bug. The
134 %run magic command -with the -d option- can run any script under
132 :samp:`%run` magic command (with the :samp:`-d` option) can run any script under
135 133 pdb's control, automatically setting initial breakpoints for you.
136 134 This version of pdb has IPython-specific improvements, including
137 135 tab-completion and traceback coloring support. For even easier
138 debugger access, try %debug after seeing an exception. winpdb is
136 debugger access, try :samp:`%debug` after seeing an exception. winpdb is
139 137 also supported, see ipy_winpdb extension.
140 138 * Profiler support. You can run single statements (similar to
141 profile.run()) or complete programs under the profiler's control.
139 :samp:`profile.run()`) or complete programs under the profiler's control.
142 140 While this is possible with standard cProfile or profile modules,
143 IPython wraps this functionality with magic commands (see '%prun'
144 and '%run -p') convenient for rapid interactive work.
145 * Doctest support. The special %doctest_mode command toggles a mode
146 that allows you to paste existing doctests (with leading '>>>'
141 IPython wraps this functionality with magic commands (see :samp:`%prun`
142 and :samp:`%run -p`) convenient for rapid interactive work.
143 * Doctest support. The special :samp:`%doctest_mode` command toggles a mode
144 that allows you to paste existing doctests (with leading :samp:`>>>`
147 145 prompts and whitespace) and uses doctest-compatible prompts and
148 146 output, so you can use IPython sessions as doctest code.
149 147
148 Interactive parallel computing
149 ==============================
150
151 Increasingly, parallel computer hardware, such as multicore CPUs, clusters and supercomputers, is becoming ubiquitous. Over the last 3 years, we have developed an
152 architecture within IPython that allows such hardware to be used quickly and easily
153 from Python. Moreover, this architecture is designed to support interactive and
154 collaborative parallel computing.
155
156 For more information, see our :ref:`overview <parallel_index>` of using IPython for
157 parallel computing.
150 158
151 159 Portability and Python requirements
152 160 -----------------------------------
153 161
154 Python requirements: IPython requires with Python version 2.3 or newer.
155 If you are still using Python 2.2 and can not upgrade, the last version
156 of IPython which worked with Python 2.2 was 0.6.15, so you will have to
157 use that.
158
159 IPython is developed under Linux, but it should work in any reasonable
160 Unix-type system (tested OK under Solaris and the BSD family, for which
161 a port exists thanks to Dryice Liu).
162
163 Mac OS X: it works, apparently without any problems (thanks to Jim Boyle
164 at Lawrence Livermore for the information). Thanks to Andrea Riciputi,
165 Fink support is available.
166
167 CygWin: it works mostly OK, though some users have reported problems
168 with prompt coloring. No satisfactory solution to this has been found so
169 far, you may want to disable colors permanently in the ipythonrc
170 configuration file if you experience problems. If you have proper color
171 support under cygwin, please post to the IPython mailing list so this
172 issue can be resolved for all users.
173
174 Windows: it works well under Windows Vista/XP/2k, and I suspect NT should
175 behave similarly. Section "Installation under windows" describes
176 installation details for Windows, including some additional tools needed
177 on this platform.
178
179 Windows 9x support is present, and has been reported to work fine (at
180 least on WinME).
181
182 Location
183 --------
184
185 IPython is generously hosted at http://ipython.scipy.org by the
186 Enthought, Inc and the SciPy project. This site offers downloads,
187 subversion access, mailing lists and a bug tracking system. I am very
188 grateful to Enthought (http://www.enthought.com) and all of the SciPy
189 team for their contribution. No newline at end of file
162 As of the 0.9 release, IPython requires Python 2.4 or greater. We have
163 not begun to test IPython on Python 2.6 or 3.0, but we expect it will
164 work with some minor changes.
165
166 IPython is known to work on the following operating systems:
167
168 * Linux
169 * AIX
170 * Most other Unix-like OSs (Solaris, BSD, etc.)
171 * Mac OS X
172 * Windows (CygWin, XP, Vista, etc.)
173
174 See :ref:`here <install_index>` for instructions on how to install IPython. No newline at end of file
@@ -1,3 +1,5 b''
1 .. _parallel_index:
2
1 3 ====================================
2 4 Using IPython for Parallel computing
3 5 ====================================
General Comments 0
You need to be logged in to leave comments. Login now