← Back to branch summary

~ellisonbg/ipython/trunk-dev

« back to all changes in this revision

Viewing changes to docs/man/ipython.1

  • Committer: Brian Granger
  • Date: 2010-01-31 23:57:46 UTC
  • mfrom: (1109.1.113 ipython)
  • Revision ID: ellisonbg@gmail.com-20100131235746-rj81qa8klooepq2m
Merging from upstream trunk.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/man/ipython.1
31
31
dynamic object introspection, easier configuration, command
32
32
completion, access to the system shell, integration with numerical and
33
33
scientific computing tools, and more.
34
 
.SH SPECIAL THREADING OPTIONS
35
 
The following special options are ONLY valid at the beginning of the command
36
 
line, and not later.  This is because they control the initialization of
37
 
ipython itself, before the normal option-handling mechanism is active.
38
 
.TP
39
 
.B \-gthread, \-qthread, \-q4thread, \-wthread, \-pylab
40
 
Only ONE of these can be given, and it can only be given as the first option
41
 
passed to IPython (it will have no effect in any other position).  They provide
42
 
threading support for the GTK, QT3, QT4 and WXWidgets toolkits, for the
43
 
matplotlib library and Twisted reactor.
44
 
.br
45
 
.sp 1
46
 
With any of the first four options, IPython starts running a separate thread
47
 
for the graphical toolkit's operation, so that you can open and control
48
 
graphical elements from within an IPython command line, without blocking.  All
49
 
four provide essentially the same functionality, respectively for GTK, QT3, QT4
50
 
and WXWidgets (via their Python interfaces).
51
 
.br
52
 
.sp 1
53
 
Note that with \-wthread, you can additionally use the \-wxversion option to
54
 
request a specific version of wx to be used.  This requires that you have the
55
 
wxversion Python module installed, which is part of recent wxPython
56
 
distributions.
57
 
.br
58
 
.sp 1
59
 
If \-pylab is given, IPython loads special support for the matplotlib library
60
 
(http://matplotlib.sourceforge.net), allowing interactive usage of any of its
61
 
backends as defined in the user's .matplotlibrc file.  It automatically
62
 
activates GTK, QT or WX threading for IPyhton if the choice of matplotlib
63
 
backend requires it.  It also modifies the %run command to correctly execute
64
 
(without blocking) any matplotlib-based script which calls show() at the end.
65
 
.TP
66
 
.B \-tk
67
 
The \-g/q/q4/wthread options, and \-pylab (if matplotlib is configured to use
68
 
GTK, QT or WX), will normally block Tk graphical interfaces.  This means that
69
 
when GTK, QT or WX threading is active, any attempt to open a Tk GUI will
70
 
result in a dead window, and possibly cause the Python interpreter to crash.
71
 
An extra option, \-tk, is available to address this issue.  It can ONLY be
72
 
given as a SECOND option after any of the above (\-gthread, \-qthread,
73
 
\-wthread or \-pylab).
74
 
.br
75
 
.sp 1
76
 
If \-tk is given, IPython will try to coordinate Tk threading with GTK, QT or
77
 
WX.  This is however potentially unreliable, and you will have to test on your
78
 
platform and Python configuration to determine whether it works for you.
79
 
Debian users have reported success, apparently due to the fact that Debian
80
 
builds all of Tcl, Tk, Tkinter and Python with pthreads support.  Under other
81
 
Linux environments (such as Fedora Core 2), this option has caused random
82
 
crashes and lockups of the Python interpreter.  Under other operating systems
83
 
(Mac OSX and Windows), you'll need to try it to find out, since currently no
84
 
user reports are available.
85
 
.br
86
 
.sp 1
87
 
There is unfortunately no way for IPython to determine at runtime whether \-tk
88
 
will work reliably or not, so you will need to do some experiments before
89
 
relying on it for regular work.
90
34
.
91
35
.SH REGULAR OPTIONS
92
36
After the above threading options have been given, regular options can follow
197
141
EDITOR is something like Emacs).
198
142
.TP
199
143
.B \-ipythondir <name>
200
 
The name of your IPython configuration directory IPYTHONDIR.  This can
201
 
also be specified through the environment variable IPYTHONDIR.
 
144
The name of your IPython configuration directory IPYTHON_DIR.  This can
 
145
also be specified through the environment variable IPYTHON_DIR.
202
146
.TP
203
147
.B \-log|l
204
148
Generate a log file of all input. The file is named ipython_log.py in your
253
197
.TP
254
198
.B \-profile|p <name>
255
199
Assume that your config file is ipythonrc-<name> (looks in current dir
256
 
first, then in IPYTHONDIR). This is a quick way to keep and load
 
200
first, then in IPYTHON_DIR). This is a quick way to keep and load
257
201
multiple config files for different tasks, especially if you use the
258
202
include option of config files. You can keep a basic
259
 
IPYTHONDIR/ipythonrc file and then have other 'profiles' which include
 
203
IPYTHON_DIR/ipythonrc file and then have other 'profiles' which include
260
204
this one and load extra things for particular tasks. For example:
261
205
.br
262
206
.sp 1
300
244
.TP
301
245
.B \-rcfile <name>
302
246
Name of your IPython resource configuration file.  normally IPython
303
 
loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc.  If
 
247
loads ipythonrc (from current directory) or IPYTHON_DIR/ipythonrc.  If
304
248
the loading of your config file fails, IPython starts with a bare
305
249
bones configuration (no modules loaded at all).
306
250
.TP
342
286
Simply removes all input/output separators.
343
287
.TP
344
288
.B \-upgrade
345
 
Allows you to upgrade your IPYTHONDIR configuration when you install a
 
289
Allows you to upgrade your IPYTHON_DIR configuration when you install a
346
290
new version of IPython.  Since new versions may include new command
347
291
lines options or example files, this copies updated ipythonrc-type
348
292
files.  However, it backs up (with a .old extension) all files which