##// END OF EJS Templates
use `ipython qtconsole` instead of `ipython-qtconsole` in qt doc
MinRK -
Show More
@@ -1,222 +1,222 b''
1 .. _qtconsole:
1 .. _qtconsole:
2
2
3 =========================
3 =========================
4 IPython as a QtGUI widget
4 IPython as a QtGUI widget
5 =========================
5 =========================
6
6
7 We now have a version of IPython, using the new two-process :ref:`ZeroMQ Kernel <ipythonzmq>`,
7 We now have a version of IPython, using the new two-process :ref:`ZeroMQ Kernel <ipythonzmq>`,
8 running in a PyQt_ GUI.
8 running in a PyQt_ GUI.
9
9
10 Overview
10 Overview
11 ========
11 ========
12
12
13 The Qt frontend has hand-coded emacs-style bindings for text navigation. This is not yet
13 The Qt frontend has hand-coded emacs-style bindings for text navigation. This is not yet
14 configurable.
14 configurable.
15
15
16 .. seealso::
16 .. seealso::
17
17
18 :ref:`The original IPython-Qt project description. <ipython_qt>`
18 :ref:`The original IPython-Qt project description. <ipython_qt>`
19
19
20 ``%loadpy``
20 ``%loadpy``
21 ===========
21 ===========
22
22
23 The ``%loadpy`` magic has been added, just for the GUI frontend. It takes any python
23 The ``%loadpy`` magic has been added, just for the GUI frontend. It takes any python
24 script (must end in '.py'), and pastes its contents as your next input, so you can edit it
24 script (must end in '.py'), and pastes its contents as your next input, so you can edit it
25 before executing. The script may be on your machine, but you can also specify a url, and
25 before executing. The script may be on your machine, but you can also specify a url, and
26 it will download the script from the web. This is particularly useful for playing with
26 it will download the script from the web. This is particularly useful for playing with
27 examples from documentation, such as matplotlib.
27 examples from documentation, such as matplotlib.
28
28
29 .. sourcecode:: ipython
29 .. sourcecode:: ipython
30
30
31 In [6]: %loadpy
31 In [6]: %loadpy
32 http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py
32 http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py
33
33
34 In [7]: from mpl_toolkits.mplot3d import axes3d
34 In [7]: from mpl_toolkits.mplot3d import axes3d
35 ...: import matplotlib.pyplot as plt
35 ...: import matplotlib.pyplot as plt
36 ...:
36 ...:
37 ...: fig = plt.figure()
37 ...: fig = plt.figure()
38 ...: ax = fig.add_subplot(111, projection='3d')
38 ...: ax = fig.add_subplot(111, projection='3d')
39 ...: X, Y, Z = axes3d.get_test_data(0.05)
39 ...: X, Y, Z = axes3d.get_test_data(0.05)
40 ...: cset = ax.contour(X, Y, Z)
40 ...: cset = ax.contour(X, Y, Z)
41 ...: ax.clabel(cset, fontsize=9, inline=1)
41 ...: ax.clabel(cset, fontsize=9, inline=1)
42 ...:
42 ...:
43 ...: plt.show()
43 ...: plt.show()
44
44
45 Pylab
45 Pylab
46 =====
46 =====
47
47
48 One of the most exciting features of the new console is embedded matplotlib figures. You
48 One of the most exciting features of the new console is embedded matplotlib figures. You
49 can use any standard matplotlib GUI backend (Except native MacOSX) to draw the figures,
49 can use any standard matplotlib GUI backend (Except native MacOSX) to draw the figures,
50 and since there is now a two-process model, there is no longer a conflict between user
50 and since there is now a two-process model, there is no longer a conflict between user
51 input and the drawing eventloop.
51 input and the drawing eventloop.
52
52
53 .. image:: figs/besselj.png
53 .. image:: figs/besselj.png
54 :width: 519px
54 :width: 519px
55
55
56 .. pastefig:
56 .. pastefig:
57
57
58 :func:`pastefig`
58 :func:`pastefig`
59 ****************
59 ****************
60
60
61 An additional function, :func:`pastefig`, will be added to the global namespace if you
61 An additional function, :func:`pastefig`, will be added to the global namespace if you
62 specify the ``pylab`` argument. This takes the active figures in matplotlib, and embeds
62 specify the ``pylab`` argument. This takes the active figures in matplotlib, and embeds
63 them in your document. This is especially useful for saving_ your work.
63 them in your document. This is especially useful for saving_ your work.
64
64
65 .. _inline:
65 .. _inline:
66
66
67 ``pylab=inline``
67 ``pylab=inline``
68 ******************
68 ******************
69
69
70 If you want to have all of your figures embedded in your session, instead of calling
70 If you want to have all of your figures embedded in your session, instead of calling
71 :func:`pastefig`, you can specify ``pylab=inline``, and each time you make a plot, it
71 :func:`pastefig`, you can specify ``pylab=inline``, and each time you make a plot, it
72 will show up in your document, as if you had called :func:`pastefig`.
72 will show up in your document, as if you had called :func:`pastefig`.
73
73
74
74
75 .. _saving:
75 .. _saving:
76
76
77 Saving and Printing
77 Saving and Printing
78 ===================
78 ===================
79
79
80 IPythonQt has the ability to save your current session, as either HTML or XHTML. If you
80 IPythonQt has the ability to save your current session, as either HTML or XHTML. If you
81 have been using :func:`pastefig` or inline_ pylab, your figures will be PNG
81 have been using :func:`pastefig` or inline_ pylab, your figures will be PNG
82 in HTML, or inlined as SVG in XHTML. PNG images have the option to be either in an
82 in HTML, or inlined as SVG in XHTML. PNG images have the option to be either in an
83 external folder, as in many browsers' "Webpage, Complete" option, or inlined as well, for
83 external folder, as in many browsers' "Webpage, Complete" option, or inlined as well, for
84 a larger, but more portable file.
84 a larger, but more portable file.
85
85
86 The widget also exposes the ability to print directly, via the default print shortcut or
86 The widget also exposes the ability to print directly, via the default print shortcut or
87 context menu.
87 context menu.
88
88
89
89
90 .. Note::
90 .. Note::
91
91
92 Saving is only available to richtext Qt widgets, which are used by default, but
92 Saving is only available to richtext Qt widgets, which are used by default, but
93 if you pass the ``--plain`` flag, saving will not be available to you.
93 if you pass the ``--plain`` flag, saving will not be available to you.
94
94
95
95
96 See these examples of :download:`png/html<figs/jn.html>` and :download:`svg/xhtml
96 See these examples of :download:`png/html<figs/jn.html>` and :download:`svg/xhtml
97 <figs/jn.xhtml>` output. Note that syntax highlighting does not survive export. This is a known
97 <figs/jn.xhtml>` output. Note that syntax highlighting does not survive export. This is a known
98 issue, and is being investigated.
98 issue, and is being investigated.
99
99
100 Colors and Highlighting
100 Colors and Highlighting
101 =======================
101 =======================
102
102
103 Terminal IPython has always had some coloring, but never syntax highlighting. There are a
103 Terminal IPython has always had some coloring, but never syntax highlighting. There are a
104 few simple color choices, specified by the ``colors`` flag or ``%colors`` magic:
104 few simple color choices, specified by the ``colors`` flag or ``%colors`` magic:
105
105
106 * LightBG for light backgrounds
106 * LightBG for light backgrounds
107 * Linux for dark backgrounds
107 * Linux for dark backgrounds
108 * NoColor for a simple colorless terminal
108 * NoColor for a simple colorless terminal
109
109
110 The Qt widget has full support for the ``colors`` flag used in the terminal shell.
110 The Qt widget has full support for the ``colors`` flag used in the terminal shell.
111
111
112 The Qt widget, however, has full syntax highlighting as you type, handled by the
112 The Qt widget, however, has full syntax highlighting as you type, handled by the
113 `pygments`_ library. The ``style`` argument exposes access to any style by name that can
113 `pygments`_ library. The ``style`` argument exposes access to any style by name that can
114 be found by pygments, and there are several already installed. The ``colors`` argument,
114 be found by pygments, and there are several already installed. The ``colors`` argument,
115 if unspecified, will be guessed based on the chosen style. Similarly, there are default
115 if unspecified, will be guessed based on the chosen style. Similarly, there are default
116 styles associated with each ``colors`` option.
116 styles associated with each ``colors`` option.
117
117
118
118
119 Screenshot of ``ipython-qtconsole colors=linux``, which uses the 'monokai' theme by
119 Screenshot of ``ipython qtconsole colors=linux``, which uses the 'monokai' theme by
120 default:
120 default:
121
121
122 .. image:: figs/colors_dark.png
122 .. image:: figs/colors_dark.png
123 :width: 627px
123 :width: 627px
124
124
125 .. Note::
125 .. Note::
126
126
127 Calling ``ipython-qtconsole -h`` will show all the style names that pygments can find
127 Calling ``ipython qtconsole -h`` will show all the style names that pygments can find
128 on your system.
128 on your system.
129
129
130 You can also pass the filename of a custom CSS stylesheet, if you want to do your own
130 You can also pass the filename of a custom CSS stylesheet, if you want to do your own
131 coloring, via the ``stylesheet`` argument. The default LightBG stylesheet:
131 coloring, via the ``stylesheet`` argument. The default LightBG stylesheet:
132
132
133 .. sourcecode:: css
133 .. sourcecode:: css
134
134
135 QPlainTextEdit, QTextEdit { background-color: white;
135 QPlainTextEdit, QTextEdit { background-color: white;
136 color: black ;
136 color: black ;
137 selection-background-color: #ccc}
137 selection-background-color: #ccc}
138 .error { color: red; }
138 .error { color: red; }
139 .in-prompt { color: navy; }
139 .in-prompt { color: navy; }
140 .in-prompt-number { font-weight: bold; }
140 .in-prompt-number { font-weight: bold; }
141 .out-prompt { color: darkred; }
141 .out-prompt { color: darkred; }
142 .out-prompt-number { font-weight: bold; }
142 .out-prompt-number { font-weight: bold; }
143
143
144 Fonts
144 Fonts
145 =====
145 =====
146
146
147 The QtConsole has configurable via the ConsoleWidget. To change these, set the ``font_family``
147 The QtConsole has configurable via the ConsoleWidget. To change these, set the ``font_family``
148 or ``font_size`` traits of the ConsoleWidget. For instance, to use 9pt Anonymous Pro::
148 or ``font_size`` traits of the ConsoleWidget. For instance, to use 9pt Anonymous Pro::
149
149
150 $> ipython-qtconsole ConsoleWidget.font_family="Anonymous Pro" ConsoleWidget.font_size=9
150 $> ipython qtconsole ConsoleWidget.font_family="Anonymous Pro" ConsoleWidget.font_size=9
151
151
152 Process Management
152 Process Management
153 ==================
153 ==================
154
154
155 With the two-process ZMQ model, the frontend does not block input during execution. This
155 With the two-process ZMQ model, the frontend does not block input during execution. This
156 means that actions can be taken by the frontend while the Kernel is executing, or even
156 means that actions can be taken by the frontend while the Kernel is executing, or even
157 after it crashes. The most basic such command is via 'Ctrl-.', which restarts the kernel.
157 after it crashes. The most basic such command is via 'Ctrl-.', which restarts the kernel.
158 This can be done in the middle of a blocking execution. The frontend can also know, via a
158 This can be done in the middle of a blocking execution. The frontend can also know, via a
159 heartbeat mechanism, that the kernel has died. This means that the frontend can safely
159 heartbeat mechanism, that the kernel has died. This means that the frontend can safely
160 restart the kernel.
160 restart the kernel.
161
161
162 Multiple Consoles
162 Multiple Consoles
163 *****************
163 *****************
164
164
165 Since the Kernel listens on the network, multiple frontends can connect to it. These
165 Since the Kernel listens on the network, multiple frontends can connect to it. These
166 do not have to all be qt frontends - any IPython frontend can connect and run code.
166 do not have to all be qt frontends - any IPython frontend can connect and run code.
167 When you start ipython-qtconsole, there will be an output line, like::
167 When you start ipython qtconsole, there will be an output line, like::
168
168
169 To connect another client to this kernel, use:
169 To connect another client to this kernel, use:
170 --external shell=62109 iopub=62110 stdin=62111 hb=62112
170 --external shell=62109 iopub=62110 stdin=62111 hb=62112
171
171
172 Other frontends can connect to your kernel, and share in the execution. This is great for
172 Other frontends can connect to your kernel, and share in the execution. This is great for
173 collaboration. The `-e` flag is for 'external'. Starting other consoles with that flag
173 collaboration. The `-e` flag is for 'external'. Starting other consoles with that flag
174 will not try to start their own, but rather connect to yours. Ultimately, you will not
174 will not try to start their own, but rather connect to yours. Ultimately, you will not
175 have to specify each port individually, but for now this copy-paste method is best.
175 have to specify each port individually, but for now this copy-paste method is best.
176
176
177 By default (for security reasons), the kernel only listens on localhost, so you can only
177 By default (for security reasons), the kernel only listens on localhost, so you can only
178 connect multiple frontends to the kernel from your local machine. You can specify to
178 connect multiple frontends to the kernel from your local machine. You can specify to
179 listen on an external interface by specifying the ``ip`` argument::
179 listen on an external interface by specifying the ``ip`` argument::
180
180
181 $> ipython-qtconsole ip=192.168.1.123
181 $> ipython qtconsole ip=192.168.1.123
182
182
183 If you specify the ip as 0.0.0.0, that refers to all interfaces, so any computer that can
183 If you specify the ip as 0.0.0.0, that refers to all interfaces, so any computer that can
184 see yours can connect to the kernel.
184 see yours can connect to the kernel.
185
185
186 .. warning::
186 .. warning::
187
187
188 Since the ZMQ code currently has no security, listening on an external-facing IP
188 Since the ZMQ code currently has no security, listening on an external-facing IP
189 is dangerous. You are giving any computer that can see you on the network the ability
189 is dangerous. You are giving any computer that can see you on the network the ability
190 to issue arbitrary shell commands as you on your machine. Be very careful with this.
190 to issue arbitrary shell commands as you on your machine. Be very careful with this.
191
191
192
192
193 Stopping Kernels and Consoles
193 Stopping Kernels and Consoles
194 *****************************
194 *****************************
195
195
196 Since there can be many consoles per kernel, the shutdown mechanism and dialog are
196 Since there can be many consoles per kernel, the shutdown mechanism and dialog are
197 probably more complicated than you are used to. Since you don't always want to shutdown a
197 probably more complicated than you are used to. Since you don't always want to shutdown a
198 kernel when you close a window, you are given the option to just close the console window
198 kernel when you close a window, you are given the option to just close the console window
199 or also close the Kernel and *all other windows*. Note that this only refers to all other
199 or also close the Kernel and *all other windows*. Note that this only refers to all other
200 *local* windows, as remote Consoles are not allowed to shutdown the kernel, and shutdowns
200 *local* windows, as remote Consoles are not allowed to shutdown the kernel, and shutdowns
201 do not close Remote consoles (to allow for saving, etc.).
201 do not close Remote consoles (to allow for saving, etc.).
202
202
203 Rules:
203 Rules:
204
204
205 * Restarting the kernel automatically clears all *local* Consoles, and prompts remote
205 * Restarting the kernel automatically clears all *local* Consoles, and prompts remote
206 Consoles about the reset.
206 Consoles about the reset.
207 * Shutdown closes all *local* Consoles, and notifies remotes that
207 * Shutdown closes all *local* Consoles, and notifies remotes that
208 the Kernel has been shutdown.
208 the Kernel has been shutdown.
209 * Remote Consoles may not restart or shutdown the kernel.
209 * Remote Consoles may not restart or shutdown the kernel.
210
210
211
211
212 Regressions
212 Regressions
213 ===========
213 ===========
214
214
215 There are some features, where the qt console lags behind the Terminal frontend. We hope
215 There are some features, where the qt console lags behind the Terminal frontend. We hope
216 to have these fixed by 0.11 release.
216 to have these fixed by 0.11 release.
217
217
218 * !cmd input: Due to our use of pexpect, we cannot pass input to subprocesses launched
218 * !cmd input: Due to our use of pexpect, we cannot pass input to subprocesses launched
219 using the '!' escape. (this will not be fixed).
219 using the '!' escape. (this will not be fixed).
220
220
221 .. [PyQt] PyQt4 http://www.riverbankcomputing.co.uk/software/pyqt/download
221 .. [PyQt] PyQt4 http://www.riverbankcomputing.co.uk/software/pyqt/download
222 .. [pygments] Pygments http://pygments.org/
222 .. [pygments] Pygments http://pygments.org/
General Comments 0
You need to be logged in to leave comments. Login now