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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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