This repository was archived by the owner on Apr 4, 2023. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 29
Expand file tree
/
Copy pathoverview.html
More file actions
381 lines (357 loc) · 23.5 KB
/
overview.html
File metadata and controls
381 lines (357 loc) · 23.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Introduction — IPython 3.2.1 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.2.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="IPython 3.2.1 documentation" href="index.html" />
<link rel="next" title="What’s new in IPython" href="whatsnew/index.html" />
<link rel="prev" title="IPython Documentation" href="index.html" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
</head>
<body role="document">
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="https://ipython.org/"><img src="_static/logo.png" border="0" alt="IPython Documentation"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="whatsnew/index.html" title="What’s new in IPython"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="IPython Documentation"
accesskey="P">previous</a> |</li>
<li><a href="https://ipython.org">home</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Introduction</a><ul>
<li><a class="reference internal" href="#id1">Overview</a></li>
<li><a class="reference internal" href="#enhanced-interactive-python-shell">Enhanced interactive Python shell</a><ul>
<li><a class="reference internal" href="#main-features-of-the-interactive-shell">Main features of the interactive shell</a></li>
</ul>
</li>
<li><a class="reference internal" href="#decoupled-two-process-model">Decoupled two-process model</a></li>
<li><a class="reference internal" href="#interactive-parallel-computing">Interactive parallel computing</a><ul>
<li><a class="reference internal" href="#portability-and-python-requirements">Portability and Python requirements</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">IPython Documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="whatsnew/index.html"
title="next chapter">What’s new in IPython</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/overview.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<blockquote>
<div><div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This documentation is for an old version of IPython.
You can find docs for newer versions <a class="reference external" href="http://ipython.readthedocs.org/en/stable/">here</a>.</p>
</div>
</div></blockquote>
<div class="section" id="introduction">
<span id="overview"></span><h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<div class="section" id="id1">
<h2>Overview<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<p>One of Python’s most useful features is its interactive interpreter.
It allows for 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.</p>
<p>The goal of IPython is to create a comprehensive environment for
interactive and exploratory computing. To support this goal, IPython
has three main components:</p>
<ul class="simple">
<li>An enhanced interactive Python shell.</li>
<li>A decoupled <a class="reference internal" href="#ipythonzmq"><span>two-process communication model</span></a>, which
allows for multiple clients to connect to a computation kernel, most notably
the web-based <a class="reference internal" href="notebook/notebook.html#htmlnotebook"><span>notebook</span></a></li>
<li>An architecture for interactive parallel computing.</li>
</ul>
<p>All of IPython is open source (released under the revised BSD license).</p>
</div>
<div class="section" id="enhanced-interactive-python-shell">
<h2>Enhanced interactive Python shell<a class="headerlink" href="#enhanced-interactive-python-shell" title="Permalink to this headline">¶</a></h2>
<p>IPython’s interactive shell (<strong class="command">ipython</strong>), has the following goals,
amongst others:</p>
<ol class="arabic simple">
<li>Provide an interactive shell superior to Python’s default. IPython
has many features for tab-completion, object introspection, system shell
access, command history retrieval across sessions, 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).</li>
<li>Serve as an embeddable, ready to use interpreter for your own
programs. An interactive IPython shell 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.</li>
<li>Offer a flexible framework which can be used as the base
environment for working with other systems, with Python as the underlying
bridge language. Specifically scientific environments like Mathematica,
IDL and Matlab inspired its design, but similar ideas can be
useful in many fields.</li>
<li>Allow interactive testing of threaded graphical toolkits. IPython
has support for interactive, non-blocking control of GTK, Qt, WX, GLUT, and
OS X applications via special threading flags. The normal Python
shell can only do this for Tkinter applications.</li>
</ol>
<div class="section" id="main-features-of-the-interactive-shell">
<h3>Main features of the interactive shell<a class="headerlink" href="#main-features-of-the-interactive-shell" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>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 (<code class="samp docutils literal"><span class="pre">?</span></code>, and using <code class="samp docutils literal"><span class="pre">??</span></code> provides additional detail).</li>
<li>Searching through modules and namespaces with <code class="samp docutils literal"><span class="pre">*</span></code> wildcards, both
when using the <code class="samp docutils literal"><span class="pre">?</span></code> system and via the <code class="samp docutils literal"><span class="pre">%psearch</span></code> command.</li>
<li>Completion in the local namespace, by typing <code class="kbd docutils literal"><span class="pre">TAB</span></code> at the prompt.
This works for keywords, modules, 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.
Custom completers can be implemented easily for different purposes
(system commands, magic arguments etc.)</li>
<li>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.</li>
<li>User-extensible ‘magic’ commands. A set of commands prefixed with
<code class="samp docutils literal"><span class="pre">%</span></code> is available for controlling IPython itself and provides
directory control, namespace information and many aliases to
common system shell commands.</li>
<li>Alias facility for defining your own system aliases.</li>
<li>Complete system shell access. Lines starting with <code class="samp docutils literal"><span class="pre">!</span></code> are passed
directly to the system shell, and using <code class="samp docutils literal"><span class="pre">!!</span></code> or <code class="samp docutils literal"><span class="pre">var</span> <span class="pre">=</span> <span class="pre">!cmd</span></code>
captures shell output into python variables for further use.</li>
<li>The ability to expand python variables when calling the system shell. In a
shell command, any python variable prefixed with <code class="samp docutils literal"><span class="pre">$</span></code> is expanded. A
double <code class="samp docutils literal"><span class="pre">$$</span></code> allows passing a literal <code class="samp docutils literal"><span class="pre">$</span></code> to the shell (for access
to shell and environment variables like <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal"><span class="pre">PATH</span></code>).</li>
<li>Filesystem navigation, via a magic <code class="samp docutils literal"><span class="pre">%cd</span></code> command, along with a
persistent bookmark system (using <code class="samp docutils literal"><span class="pre">%bookmark</span></code>) for fast access to
frequently visited directories.</li>
<li>A lightweight persistence framework via the <code class="samp docutils literal"><span class="pre">%store</span></code> command, which
allows you to save arbitrary Python variables. These get restored
when you run the <code class="samp docutils literal"><span class="pre">%store</span> <span class="pre">-r</span></code> command.</li>
<li>Automatic indentation (optional) of code as you type (through the
readline library).</li>
<li>Macro system for quickly re-executing multiple lines of previous
input with a single name via the <code class="samp docutils literal"><span class="pre">%macro</span></code> command. Macros can be
stored persistently via <code class="samp docutils literal"><span class="pre">%store</span></code> and edited via <code class="samp docutils literal"><span class="pre">%edit</span></code>.</li>
<li>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).</li>
<li>Session restoring: logs can be replayed to restore a previous
session to the state where you left it.</li>
<li>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).</li>
<li>Auto-parentheses via the <code class="samp docutils literal"><span class="pre">%autocall</span></code> command: callable objects can be
executed without parentheses: <code class="samp docutils literal"><span class="pre">sin</span> <span class="pre">3</span></code> is automatically converted to
<code class="samp docutils literal"><span class="pre">sin(3)</span></code></li>
<li>Auto-quoting: using <code class="samp docutils literal"><span class="pre">,</span></code>, or <code class="samp docutils literal"><span class="pre">;</span></code> as the first character forces
auto-quoting of the rest of the line: <code class="samp docutils literal"><span class="pre">,my_function</span> <span class="pre">a</span> <span class="pre">b</span></code> becomes
automatically <code class="samp docutils literal"><span class="pre">my_function("a","b")</span></code>, while <code class="samp docutils literal"><span class="pre">;my_function</span> <span class="pre">a</span> <span class="pre">b</span></code>
becomes <code class="samp docutils literal"><span class="pre">my_function("a</span> <span class="pre">b")</span></code>.</li>
<li>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
<code class="samp docutils literal"><span class="pre">>>></span></code> or <code class="samp docutils literal"><span class="pre">...</span></code> such as those from other python sessions or the
standard Python documentation.</li>
<li>Flexible <a class="reference internal" href="development/config.html#config-overview"><span>configuration system</span></a>. 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.</li>
<li>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).</li>
<li>Easy debugger access. You can set IPython to call up an enhanced version of
the Python debugger (pdb) 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 <code class="samp docutils literal"><span class="pre">%run</span></code> magic command (with the <code class="samp docutils literal"><span class="pre">-d</span></code> option) can run
any script under pdb’s control, automatically setting initial breakpoints for
you. This version of pdb has IPython-specific improvements, including
tab-completion and traceback coloring support. For even easier debugger
access, try <code class="samp docutils literal"><span class="pre">%debug</span></code> after seeing an exception.</li>
<li>Profiler support. You can run single statements (similar to
<code class="samp docutils literal"><span class="pre">profile.run()</span></code>) or complete programs under the profiler’s control.
While this is possible with standard cProfile or profile modules,
IPython wraps this functionality with magic commands (see <code class="samp docutils literal"><span class="pre">%prun</span></code>
and <code class="samp docutils literal"><span class="pre">%run</span> <span class="pre">-p</span></code>) convenient for rapid interactive work.</li>
<li>Simple timing information. You can use the <code class="samp docutils literal"><span class="pre">%timeit</span></code> command to get
the execution time of a Python statement or expression. This machinery is
intelligent enough to do more repetitions for commands that finish very
quickly in order to get a better estimate of their running time.</li>
</ul>
<div class="highlight-ipython"><div class="highlight"><pre><span class="gp">In [1]: </span><span class="o">%</span><span class="k">timeit</span> 1+1
<span class="go">10000000 loops, best of 3: 25.5 ns per loop</span>
<span class="gp">In [2]: </span><span class="o">%</span><span class="k">timeit</span> [math.sin(x) for x in range(5000)]
<span class="go">1000 loops, best of 3: 719 µs per loop</span>
</pre></div>
</div>
<blockquote>
<div>To get the timing information for more than one expression, use the
<code class="samp docutils literal"><span class="pre">%%timeit</span></code> cell magic command.</div></blockquote>
<ul class="simple">
<li>Doctest support. The special <code class="samp docutils literal"><span class="pre">%doctest_mode</span></code> command toggles a mode
to use doctest-compatible prompts, so you can use IPython sessions as
doctest code. By default, IPython also allows you to paste existing
doctests, and strips out the leading <code class="samp docutils literal"><span class="pre">>>></span></code> and <code class="samp docutils literal"><span class="pre">...</span></code> prompts in
them.</li>
</ul>
</div>
</div>
<div class="section" id="decoupled-two-process-model">
<span id="ipythonzmq"></span><h2>Decoupled two-process model<a class="headerlink" href="#decoupled-two-process-model" title="Permalink to this headline">¶</a></h2>
<p>IPython has abstracted and extended the notion of a traditional
<em>Read-Evaluate-Print Loop</em> (REPL) environment by decoupling the <em>evaluation</em>
into its own process. We call this process a <strong>kernel</strong>: it receives execution
instructions from clients and communicates the results back to them.</p>
<p>This decoupling allows us to have several clients connected to the same
kernel, and even allows clients and kernels to live on different machines.
With the exclusion of the traditional single process terminal-based IPython
(what you start if you run <code class="docutils literal"><span class="pre">ipython</span></code> without any subcommands), all
other IPython machinery uses this two-process model. This includes <code class="docutils literal"><span class="pre">ipython</span>
<span class="pre">console</span></code>, <code class="docutils literal"><span class="pre">ipython</span> <span class="pre">qtconsole</span></code>, and <code class="docutils literal"><span class="pre">ipython</span> <span class="pre">notebook</span></code>.</p>
<p>As an example, this means that when you start <code class="docutils literal"><span class="pre">ipython</span> <span class="pre">qtconsole</span></code>, you’re
really starting two processes, a kernel and a Qt-based client can send
commands to and receive results from that kernel. If there is already a kernel
running that you want to connect to, you can pass the <code class="docutils literal"><span class="pre">--existing</span></code> flag
which will skip initiating a new kernel and connect to the most recent kernel,
instead. To connect to a specific kernel once you have several kernels
running, use the <code class="docutils literal"><span class="pre">%connect_info</span></code> magic to get the unique connection file,
which will be something like <code class="docutils literal"><span class="pre">--existing</span> <span class="pre">kernel-19732.json</span></code> but with
different numbers which correspond to the Process ID of the kernel.</p>
<p>You can read more about using <a class="reference internal" href="interactive/qtconsole.html#qtconsole"><span>ipython qtconsole</span></a>, and
<a class="reference internal" href="notebook/notebook.html#htmlnotebook"><span>ipython notebook</span></a>. There is also a <a class="reference internal" href="development/messaging.html#messaging"><span>message spec</span></a> which documents the protocol for communication between kernels
and clients.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference external" href="http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Frontend-Kernel%20Model.ipynb">Frontend/Kernel Model</a> example notebook</p>
</div>
</div>
<div class="section" id="interactive-parallel-computing">
<h2>Interactive parallel computing<a class="headerlink" href="#interactive-parallel-computing" title="Permalink to this headline">¶</a></h2>
<p>Increasingly, parallel computer hardware, such as multicore CPUs, clusters and
supercomputers, is becoming ubiquitous. Over the last several years, we have
developed an architecture within IPython that allows such hardware to be used
quickly and easily from Python. Moreover, this architecture is designed to
support interactive and collaborative parallel computing.</p>
<p>The main features of this system are:</p>
<ul class="simple">
<li>Quickly parallelize Python code from an interactive Python/IPython session.</li>
<li>A flexible and dynamic process model that be deployed on anything from
multicore workstations to supercomputers.</li>
<li>An architecture that supports many different styles of parallelism, from
message passing to task farming. And all of these styles can be handled
interactively.</li>
<li>Both blocking and fully asynchronous interfaces.</li>
<li>High level APIs that enable many things to be parallelized in a few lines
of code.</li>
<li>Write parallel code that will run unchanged on everything from multicore
workstations to supercomputers.</li>
<li>Full integration with Message Passing libraries (MPI).</li>
<li>Capabilities based security model with full encryption of network connections.</li>
<li>Share live parallel jobs with other users securely. We call this
collaborative parallel computing.</li>
<li>Dynamically load balanced task farming system.</li>
<li>Robust error handling. Python exceptions raised in parallel execution are
gathered and presented to the top-level code.</li>
</ul>
<p>For more information, see our <a class="reference internal" href="parallel/index.html#parallel-index"><span>overview</span></a> of using IPython
for parallel computing.</p>
<div class="section" id="portability-and-python-requirements">
<h3>Portability and Python requirements<a class="headerlink" href="#portability-and-python-requirements" title="Permalink to this headline">¶</a></h3>
<p>As of the 2.0 release, IPython works with Python 2.7 and 3.3 or above.
Version 1.0 additionally worked with Python 2.6 and 3.2.
Version 0.12 was the first version to fully support Python 3.</p>
<p>IPython is known to work on the following operating systems:</p>
<blockquote>
<div><ul class="simple">
<li>Linux</li>
<li>Most other Unix-like OSs (AIX, Solaris, BSD, etc.)</li>
<li>Mac OS X</li>
<li>Windows (CygWin, XP, Vista, etc.)</li>
</ul>
</div></blockquote>
<p>See <a class="reference internal" href="install/index.html#install-index"><span>here</span></a> for instructions on how to install IPython.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The IPython Development Team.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.3.1</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.3</a>
|
<a href="_sources/overview.txt"
rel="nofollow">Page source</a></li>
</div>
</body>
</html>