Show More
@@ -1,604 +1,606 b'' | |||||
1 | .. _qtconsole: |
|
1 | .. _qtconsole: | |
2 |
|
2 | |||
3 | ========================= |
|
3 | ========================= | |
4 | A Qt Console for IPython |
|
4 | A Qt Console for IPython | |
5 | ========================= |
|
5 | ========================= | |
6 |
|
6 | |||
7 | We now have a version of IPython, using the new two-process :ref:`ZeroMQ Kernel |
|
7 | We now have a version of IPython, using the new two-process :ref:`ZeroMQ Kernel | |
8 | <ipythonzmq>`, running in a PyQt_ GUI. This is a very lightweight widget that |
|
8 | <ipythonzmq>`, running in a PyQt_ GUI. This is a very lightweight widget that | |
9 | largely feels like a terminal, but provides a number of enhancements only |
|
9 | largely feels like a terminal, but provides a number of enhancements only | |
10 | possible in a GUI, such as inline figures, proper multiline editing with syntax |
|
10 | possible in a GUI, such as inline figures, proper multiline editing with syntax | |
11 | highlighting, graphical calltips, and much more. |
|
11 | highlighting, graphical calltips, and much more. | |
12 |
|
12 | |||
13 | .. figure:: ../_static/qtconsole.png |
|
13 | .. figure:: ../_static/qtconsole.png | |
14 | :width: 400px |
|
14 | :width: 400px | |
15 | :alt: IPython Qt console with embedded plots |
|
15 | :alt: IPython Qt console with embedded plots | |
16 | :align: center |
|
16 | :align: center | |
17 | :target: ../_static/qtconsole.png |
|
17 | :target: ../_static/qtconsole.png | |
18 |
|
18 | |||
19 | The Qt console for IPython, using inline matplotlib plots. |
|
19 | The Qt console for IPython, using inline matplotlib plots. | |
20 |
|
20 | |||
21 | To get acquainted with the Qt console, type `%guiref` to see a quick |
|
21 | To get acquainted with the Qt console, type `%guiref` to see a quick | |
22 | introduction of its main features. |
|
22 | introduction of its main features. | |
23 |
|
23 | |||
24 | The Qt frontend has hand-coded emacs-style bindings for text navigation. This |
|
24 | The Qt frontend has hand-coded emacs-style bindings for text navigation. This | |
25 | is not yet configurable. |
|
25 | is not yet configurable. | |
26 |
|
26 | |||
27 | .. tip:: |
|
27 | .. tip:: | |
28 |
|
28 | |||
29 | Since the Qt console tries hard to behave like a terminal, by default it |
|
29 | Since the Qt console tries hard to behave like a terminal, by default it | |
30 | immediately executes single lines of input that are complete. If you want |
|
30 | immediately executes single lines of input that are complete. If you want | |
31 | to force multiline input, hit :kbd:`Ctrl-Enter` at the end of the first line |
|
31 | to force multiline input, hit :kbd:`Ctrl-Enter` at the end of the first line | |
32 | instead of :kbd:`Enter`, and it will open a new line for input. At any |
|
32 | instead of :kbd:`Enter`, and it will open a new line for input. At any | |
33 | point in a multiline block, you can force its execution (without having to |
|
33 | point in a multiline block, you can force its execution (without having to | |
34 | go to the bottom) with :kbd:`Shift-Enter`. |
|
34 | go to the bottom) with :kbd:`Shift-Enter`. | |
35 |
|
35 | |||
36 | ``%load`` |
|
36 | ``%load`` | |
37 | ========= |
|
37 | ========= | |
38 |
|
38 | |||
39 | The new ``%load`` magic (previously ``%loadpy``) takes any script, and pastes |
|
39 | The new ``%load`` magic (previously ``%loadpy``) takes any script, and pastes | |
40 | its contents as your next input, so you can edit it before executing. The |
|
40 | its contents as your next input, so you can edit it before executing. The | |
41 | script may be on your machine, but you can also specify an history range, or a |
|
41 | script may be on your machine, but you can also specify an history range, or a | |
42 | url, and it will download the script from the web. This is particularly useful |
|
42 | url, and it will download the script from the web. This is particularly useful | |
43 | for playing with examples from documentation, such as matplotlib. |
|
43 | for playing with examples from documentation, such as matplotlib. | |
44 |
|
44 | |||
45 | .. sourcecode:: ipython |
|
45 | .. sourcecode:: ipython | |
46 |
|
46 | |||
47 | In [6]: %load http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py |
|
47 | In [6]: %load http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py | |
48 |
|
48 | |||
49 | In [7]: from mpl_toolkits.mplot3d import axes3d |
|
49 | In [7]: from mpl_toolkits.mplot3d import axes3d | |
50 | ...: import matplotlib.pyplot as plt |
|
50 | ...: import matplotlib.pyplot as plt | |
51 | ...: |
|
51 | ...: | |
52 | ...: fig = plt.figure() |
|
52 | ...: fig = plt.figure() | |
53 | ...: ax = fig.add_subplot(111, projection='3d') |
|
53 | ...: ax = fig.add_subplot(111, projection='3d') | |
54 | ...: X, Y, Z = axes3d.get_test_data(0.05) |
|
54 | ...: X, Y, Z = axes3d.get_test_data(0.05) | |
55 | ...: cset = ax.contour(X, Y, Z) |
|
55 | ...: cset = ax.contour(X, Y, Z) | |
56 | ...: ax.clabel(cset, fontsize=9, inline=1) |
|
56 | ...: ax.clabel(cset, fontsize=9, inline=1) | |
57 | ...: |
|
57 | ...: | |
58 | ...: plt.show() |
|
58 | ...: plt.show() | |
59 |
|
59 | |||
60 | Pylab |
|
60 | Pylab | |
61 | ===== |
|
61 | ===== | |
62 |
|
62 | |||
63 | One of the most exciting features of the new console is embedded matplotlib |
|
63 | One of the most exciting features of the new console is embedded matplotlib | |
64 | figures. You can use any standard matplotlib GUI backend |
|
64 | figures. You can use any standard matplotlib GUI backend | |
65 | to draw the figures, and since there is now a two-process model, there is no |
|
65 | to draw the figures, and since there is now a two-process model, there is no | |
66 | longer a conflict between user input and the drawing eventloop. |
|
66 | longer a conflict between user input and the drawing eventloop. | |
67 |
|
67 | |||
68 | .. image:: figs/besselj.png |
|
68 | .. image:: figs/besselj.png | |
69 | :width: 519px |
|
69 | :width: 519px | |
70 |
|
70 | |||
71 | .. display: |
|
71 | .. display: | |
72 |
|
72 | |||
73 | :func:`display` |
|
73 | :func:`display` | |
74 | *************** |
|
74 | *************** | |
75 |
|
75 | |||
76 | An additional function, :func:`display`, will be added to the global namespace |
|
76 | An additional function, :func:`display`, will be added to the global namespace | |
77 | if you specify the ``--pylab`` option at the command line. The IPython display |
|
77 | if you specify the ``--pylab`` option at the command line. The IPython display | |
78 | system provides a mechanism for specifying PNG or SVG (and more) |
|
78 | system provides a mechanism for specifying PNG or SVG (and more) | |
79 | representations of objects for GUI frontends. By default, IPython registers |
|
79 | representations of objects for GUI frontends. By default, IPython registers | |
80 | convenient PNG and SVG renderers for matplotlib figures, so you can embed them |
|
80 | convenient PNG and SVG renderers for matplotlib figures, so you can embed them | |
81 | in your document by calling :func:`display` on one or more of them. This is |
|
81 | in your document by calling :func:`display` on one or more of them. This is | |
82 | especially useful for saving_ your work. |
|
82 | especially useful for saving_ your work. | |
83 |
|
83 | |||
84 | .. sourcecode:: ipython |
|
84 | .. sourcecode:: ipython | |
85 |
|
85 | |||
86 | In [5]: plot(range(5)) # plots in the matplotlib window |
|
86 | In [5]: plot(range(5)) # plots in the matplotlib window | |
87 |
|
87 | |||
88 | In [6]: display(gcf()) # embeds the current figure in the qtconsole |
|
88 | In [6]: display(gcf()) # embeds the current figure in the qtconsole | |
89 |
|
89 | |||
90 | In [7]: display(*getfigs()) # embeds all active figures in the qtconsole |
|
90 | In [7]: display(*getfigs()) # embeds all active figures in the qtconsole | |
91 |
|
91 | |||
92 | If you have a reference to a matplotlib figure object, you can always display |
|
92 | If you have a reference to a matplotlib figure object, you can always display | |
93 | that specific figure: |
|
93 | that specific figure: | |
94 |
|
94 | |||
95 | .. sourcecode:: ipython |
|
95 | .. sourcecode:: ipython | |
96 |
|
96 | |||
97 | In [1]: f = figure() |
|
97 | In [1]: f = figure() | |
98 |
|
98 | |||
99 | In [2]: plot(rand(100)) |
|
99 | In [2]: plot(rand(100)) | |
100 | Out[2]: [<matplotlib.lines.Line2D at 0x7fc6ac03dd90>] |
|
100 | Out[2]: [<matplotlib.lines.Line2D at 0x7fc6ac03dd90>] | |
101 |
|
101 | |||
102 | In [3]: display(f) |
|
102 | In [3]: display(f) | |
103 |
|
103 | |||
104 | # Plot is shown here |
|
104 | # Plot is shown here | |
105 |
|
105 | |||
106 | In [4]: title('A title') |
|
106 | In [4]: title('A title') | |
107 | Out[4]: <matplotlib.text.Text at 0x7fc6ac023450> |
|
107 | Out[4]: <matplotlib.text.Text at 0x7fc6ac023450> | |
108 |
|
108 | |||
109 | In [5]: display(f) |
|
109 | In [5]: display(f) | |
110 |
|
110 | |||
111 | # Updated plot with title is shown here. |
|
111 | # Updated plot with title is shown here. | |
112 |
|
112 | |||
113 | .. _inline: |
|
113 | .. _inline: | |
114 |
|
114 | |||
115 | ``--pylab=inline`` |
|
115 | ``--pylab=inline`` | |
116 | ****************** |
|
116 | ****************** | |
117 |
|
117 | |||
118 | If you want to have all of your figures embedded in your session, instead of |
|
118 | If you want to have all of your figures embedded in your session, instead of | |
119 | calling :func:`display`, you can specify ``--pylab=inline`` when you start the |
|
119 | calling :func:`display`, you can specify ``--pylab=inline`` when you start the | |
120 | console, and each time you make a plot, it will show up in your document, as if |
|
120 | console, and each time you make a plot, it will show up in your document, as if | |
121 | you had called :func:`display(fig)`. |
|
121 | you had called :func:`display(fig)`. | |
122 |
|
122 | |||
123 | The inline backend can use either SVG or PNG figures (PNG being the default). |
|
123 | The inline backend can use either SVG or PNG figures (PNG being the default). | |
124 | To switch between them, set the ``InlineBackend.figure_format`` configurable |
|
124 | To switch between them, set the ``InlineBackend.figure_format`` configurable | |
125 | in a config file, or via the ``%config`` magic: |
|
125 | in a config file, or via the ``%config`` magic: | |
126 |
|
126 | |||
127 | .. sourcecode:: ipython |
|
127 | .. sourcecode:: ipython | |
128 |
|
128 | |||
129 | In [10]: %config InlineBackend.figure_format = 'svg' |
|
129 | In [10]: %config InlineBackend.figure_format = 'svg' | |
130 |
|
130 | |||
131 | .. note:: |
|
131 | .. note:: | |
132 |
|
132 | |||
133 | Changing the inline figure format also affects calls to :func:`display` above, |
|
133 | Changing the inline figure format also affects calls to :func:`display` above, | |
134 | even if you are not using the inline backend for all figures. |
|
134 | even if you are not using the inline backend for all figures. | |
135 |
|
135 | |||
136 | By default, IPython closes all figures at the completion of each execution. This means you |
|
136 | By default, IPython closes all figures at the completion of each execution. This means you | |
137 | don't have to manually close figures, which is less convenient when figures aren't attached |
|
137 | don't have to manually close figures, which is less convenient when figures aren't attached | |
138 | to windows with an obvious close button. It also means that the first matplotlib call in |
|
138 | to windows with an obvious close button. It also means that the first matplotlib call in | |
139 | each cell will always create a new figure: |
|
139 | each cell will always create a new figure: | |
140 |
|
140 | |||
141 | .. sourcecode:: ipython |
|
141 | .. sourcecode:: ipython | |
142 |
|
142 | |||
143 | In [11]: plot(range(100)) |
|
143 | In [11]: plot(range(100)) | |
144 | <single-line plot> |
|
144 | <single-line plot> | |
145 |
|
145 | |||
146 | In [12]: plot([1,3,2]) |
|
146 | In [12]: plot([1,3,2]) | |
147 | <another single-line plot> |
|
147 | <another single-line plot> | |
148 |
|
148 | |||
149 |
|
149 | |||
150 | However, it does prevent the list of active figures surviving from one input cell to the |
|
150 | However, it does prevent the list of active figures surviving from one input cell to the | |
151 | next, so if you want to continue working with a figure, you must hold on to a reference to |
|
151 | next, so if you want to continue working with a figure, you must hold on to a reference to | |
152 | it: |
|
152 | it: | |
153 |
|
153 | |||
154 | .. sourcecode:: ipython |
|
154 | .. sourcecode:: ipython | |
155 |
|
155 | |||
156 | In [11]: fig = gcf() |
|
156 | In [11]: fig = gcf() | |
157 | ....: fig.plot(rand(100)) |
|
157 | ....: fig.plot(rand(100)) | |
158 | <plot> |
|
158 | <plot> | |
159 | In [12]: fig.title('Random Title') |
|
159 | In [12]: fig.title('Random Title') | |
160 | <redraw plot with title> |
|
160 | <redraw plot with title> | |
161 |
|
161 | |||
162 | This behavior is controlled by the :attr:`InlineBackend.close_figures` configurable, and |
|
162 | This behavior is controlled by the :attr:`InlineBackend.close_figures` configurable, and | |
163 | if you set it to False, via %config or config file, then IPython will *not* close figures, |
|
163 | if you set it to False, via %config or config file, then IPython will *not* close figures, | |
164 | and tools like :func:`gcf`, :func:`gca`, :func:`getfigs` will behave the same as they |
|
164 | and tools like :func:`gcf`, :func:`gca`, :func:`getfigs` will behave the same as they | |
165 | do with other backends. You will, however, have to manually close figures: |
|
165 | do with other backends. You will, however, have to manually close figures: | |
166 |
|
166 | |||
167 | .. sourcecode:: ipython |
|
167 | .. sourcecode:: ipython | |
168 |
|
168 | |||
169 | # close all active figures: |
|
169 | # close all active figures: | |
170 | In [13]: [ fig.close() for fig in getfigs() ] |
|
170 | In [13]: [ fig.close() for fig in getfigs() ] | |
171 |
|
171 | |||
172 |
|
172 | |||
173 |
|
173 | |||
174 | .. _saving: |
|
174 | .. _saving: | |
175 |
|
175 | |||
176 | Saving and Printing |
|
176 | Saving and Printing | |
177 | =================== |
|
177 | =================== | |
178 |
|
178 | |||
179 | IPythonQt has the ability to save your current session, as either HTML or |
|
179 | IPythonQt has the ability to save your current session, as either HTML or | |
180 | XHTML. If you have been using :func:`display` or inline_ pylab, your figures |
|
180 | XHTML. If you have been using :func:`display` or inline_ pylab, your figures | |
181 | will be PNG in HTML, or inlined as SVG in XHTML. PNG images have the option to |
|
181 | will be PNG in HTML, or inlined as SVG in XHTML. PNG images have the option to | |
182 | be either in an external folder, as in many browsers' "Webpage, Complete" |
|
182 | be either in an external folder, as in many browsers' "Webpage, Complete" | |
183 | option, or inlined as well, for a larger, but more portable file. |
|
183 | option, or inlined as well, for a larger, but more portable file. | |
184 |
|
184 | |||
185 | .. note:: |
|
185 | .. note:: | |
186 |
|
186 | |||
187 | Export to SVG+XHTML requires that you are using SVG figures, which is *not* |
|
187 | Export to SVG+XHTML requires that you are using SVG figures, which is *not* | |
188 | the default. To switch the inline figure format to use SVG during an active |
|
188 | the default. To switch the inline figure format to use SVG during an active | |
189 | session, do: |
|
189 | session, do: | |
190 |
|
190 | |||
191 | .. sourcecode:: ipython |
|
191 | .. sourcecode:: ipython | |
192 |
|
192 | |||
193 | In [10]: %config InlineBackend.figure_format = 'svg' |
|
193 | In [10]: %config InlineBackend.figure_format = 'svg' | |
194 |
|
194 | |||
195 | Or, you can add the same line (c.Inline... instead of %config Inline...) to |
|
195 | Or, you can add the same line (c.Inline... instead of %config Inline...) to | |
196 | your config files. |
|
196 | your config files. | |
197 |
|
197 | |||
198 | This will only affect figures plotted after making this call |
|
198 | This will only affect figures plotted after making this call | |
199 |
|
199 | |||
200 |
|
200 | |||
201 | The widget also exposes the ability to print directly, via the default print |
|
201 | The widget also exposes the ability to print directly, via the default print | |
202 | shortcut or context menu. |
|
202 | shortcut or context menu. | |
203 |
|
203 | |||
204 |
|
204 | |||
205 | .. Note:: |
|
205 | .. Note:: | |
206 |
|
206 | |||
207 | Saving is only available to richtext Qt widgets, which are used by default, |
|
207 | Saving is only available to richtext Qt widgets, which are used by default, | |
208 | but if you pass the ``--plain`` flag, saving will not be available to you. |
|
208 | but if you pass the ``--plain`` flag, saving will not be available to you. | |
209 |
|
209 | |||
210 |
|
210 | |||
211 | See these examples of :download:`png/html<figs/jn.html>` and |
|
211 | See these examples of :download:`png/html<figs/jn.html>` and | |
212 | :download:`svg/xhtml <figs/jn.xhtml>` output. Note that syntax highlighting |
|
212 | :download:`svg/xhtml <figs/jn.xhtml>` output. Note that syntax highlighting | |
213 | does not survive export. This is a known issue, and is being investigated. |
|
213 | does not survive export. This is a known issue, and is being investigated. | |
214 |
|
214 | |||
215 |
|
215 | |||
216 | Colors and Highlighting |
|
216 | Colors and Highlighting | |
217 | ======================= |
|
217 | ======================= | |
218 |
|
218 | |||
219 | Terminal IPython has always had some coloring, but never syntax |
|
219 | Terminal IPython has always had some coloring, but never syntax | |
220 | highlighting. There are a few simple color choices, specified by the ``colors`` |
|
220 | highlighting. There are a few simple color choices, specified by the ``colors`` | |
221 | flag or ``%colors`` magic: |
|
221 | flag or ``%colors`` magic: | |
222 |
|
222 | |||
223 | * LightBG for light backgrounds |
|
223 | * LightBG for light backgrounds | |
224 | * Linux for dark backgrounds |
|
224 | * Linux for dark backgrounds | |
225 | * NoColor for a simple colorless terminal |
|
225 | * NoColor for a simple colorless terminal | |
226 |
|
226 | |||
227 | The Qt widget has full support for the ``colors`` flag used in the terminal shell. |
|
227 | The Qt widget has full support for the ``colors`` flag used in the terminal shell. | |
228 |
|
228 | |||
229 | The Qt widget, however, has full syntax highlighting as you type, handled by |
|
229 | The Qt widget, however, has full syntax highlighting as you type, handled by | |
230 | the `pygments`_ library. The ``style`` argument exposes access to any style by |
|
230 | the `pygments`_ library. The ``style`` argument exposes access to any style by | |
231 | name that can be found by pygments, and there are several already |
|
231 | name that can be found by pygments, and there are several already | |
232 | installed. The ``colors`` argument, if unspecified, will be guessed based on |
|
232 | installed. The ``colors`` argument, if unspecified, will be guessed based on | |
233 | the chosen style. Similarly, there are default styles associated with each |
|
233 | the chosen style. Similarly, there are default styles associated with each | |
234 | ``colors`` option. |
|
234 | ``colors`` option. | |
235 |
|
235 | |||
236 |
|
236 | |||
237 | Screenshot of ``ipython qtconsole --colors=linux``, which uses the 'monokai' |
|
237 | Screenshot of ``ipython qtconsole --colors=linux``, which uses the 'monokai' | |
238 | theme by default: |
|
238 | theme by default: | |
239 |
|
239 | |||
240 | .. image:: figs/colors_dark.png |
|
240 | .. image:: figs/colors_dark.png | |
241 | :width: 627px |
|
241 | :width: 627px | |
242 |
|
242 | |||
243 | .. Note:: |
|
243 | .. Note:: | |
244 |
|
244 | |||
245 | Calling ``ipython qtconsole -h`` will show all the style names that |
|
245 | Calling ``ipython qtconsole -h`` will show all the style names that | |
246 | pygments can find on your system. |
|
246 | pygments can find on your system. | |
247 |
|
247 | |||
248 | You can also pass the filename of a custom CSS stylesheet, if you want to do |
|
248 | You can also pass the filename of a custom CSS stylesheet, if you want to do | |
249 | your own coloring, via the ``stylesheet`` argument. The default LightBG |
|
249 | your own coloring, via the ``stylesheet`` argument. The default LightBG | |
250 | stylesheet: |
|
250 | stylesheet: | |
251 |
|
251 | |||
252 | .. sourcecode:: css |
|
252 | .. sourcecode:: css | |
253 |
|
253 | |||
254 | QPlainTextEdit, QTextEdit { background-color: white; |
|
254 | QPlainTextEdit, QTextEdit { background-color: white; | |
255 | color: black ; |
|
255 | color: black ; | |
256 | selection-background-color: #ccc} |
|
256 | selection-background-color: #ccc} | |
257 | .error { color: red; } |
|
257 | .error { color: red; } | |
258 | .in-prompt { color: navy; } |
|
258 | .in-prompt { color: navy; } | |
259 | .in-prompt-number { font-weight: bold; } |
|
259 | .in-prompt-number { font-weight: bold; } | |
260 | .out-prompt { color: darkred; } |
|
260 | .out-prompt { color: darkred; } | |
261 | .out-prompt-number { font-weight: bold; } |
|
261 | .out-prompt-number { font-weight: bold; } | |
|
262 | /* .inverted is used to highlight selected completion */ | |||
|
263 | .inverted { background-color: black ; color: white; } | |||
262 |
|
264 | |||
263 | Fonts |
|
265 | Fonts | |
264 | ===== |
|
266 | ===== | |
265 |
|
267 | |||
266 | The QtConsole has configurable via the ConsoleWidget. To change these, set the |
|
268 | The QtConsole has configurable via the ConsoleWidget. To change these, set the | |
267 | ``font_family`` or ``font_size`` traits of the ConsoleWidget. For instance, to |
|
269 | ``font_family`` or ``font_size`` traits of the ConsoleWidget. For instance, to | |
268 | use 9pt Anonymous Pro:: |
|
270 | use 9pt Anonymous Pro:: | |
269 |
|
271 | |||
270 | $> ipython qtconsole --ConsoleWidget.font_family="Anonymous Pro" --ConsoleWidget.font_size=9 |
|
272 | $> ipython qtconsole --ConsoleWidget.font_family="Anonymous Pro" --ConsoleWidget.font_size=9 | |
271 |
|
273 | |||
272 | Process Management |
|
274 | Process Management | |
273 | ================== |
|
275 | ================== | |
274 |
|
276 | |||
275 | With the two-process ZMQ model, the frontend does not block input during |
|
277 | With the two-process ZMQ model, the frontend does not block input during | |
276 | execution. This means that actions can be taken by the frontend while the |
|
278 | execution. This means that actions can be taken by the frontend while the | |
277 | Kernel is executing, or even after it crashes. The most basic such command is |
|
279 | Kernel is executing, or even after it crashes. The most basic such command is | |
278 | via 'Ctrl-.', which restarts the kernel. This can be done in the middle of a |
|
280 | via 'Ctrl-.', which restarts the kernel. This can be done in the middle of a | |
279 | blocking execution. The frontend can also know, via a heartbeat mechanism, that |
|
281 | blocking execution. The frontend can also know, via a heartbeat mechanism, that | |
280 | the kernel has died. This means that the frontend can safely restart the |
|
282 | the kernel has died. This means that the frontend can safely restart the | |
281 | kernel. |
|
283 | kernel. | |
282 |
|
284 | |||
283 | .. _multiple_consoles: |
|
285 | .. _multiple_consoles: | |
284 |
|
286 | |||
285 | Multiple Consoles |
|
287 | Multiple Consoles | |
286 | ***************** |
|
288 | ***************** | |
287 |
|
289 | |||
288 | Since the Kernel listens on the network, multiple frontends can connect to it. |
|
290 | Since the Kernel listens on the network, multiple frontends can connect to it. | |
289 | These do not have to all be qt frontends - any IPython frontend can connect and |
|
291 | These do not have to all be qt frontends - any IPython frontend can connect and | |
290 | run code. When you start ipython qtconsole, there will be an output line, |
|
292 | run code. When you start ipython qtconsole, there will be an output line, | |
291 | like:: |
|
293 | like:: | |
292 |
|
294 | |||
293 | [IPKernelApp] To connect another client to this kernel, use: |
|
295 | [IPKernelApp] To connect another client to this kernel, use: | |
294 | [IPKernelApp] --existing kernel-12345.json |
|
296 | [IPKernelApp] --existing kernel-12345.json | |
295 |
|
297 | |||
296 | Other frontends can connect to your kernel, and share in the execution. This is |
|
298 | Other frontends can connect to your kernel, and share in the execution. This is | |
297 | great for collaboration. The ``--existing`` flag means connect to a kernel |
|
299 | great for collaboration. The ``--existing`` flag means connect to a kernel | |
298 | that already exists. Starting other consoles |
|
300 | that already exists. Starting other consoles | |
299 | with that flag will not try to start their own kernel, but rather connect to |
|
301 | with that flag will not try to start their own kernel, but rather connect to | |
300 | yours. :file:`kernel-12345.json` is a small JSON file with the ip, port, and |
|
302 | yours. :file:`kernel-12345.json` is a small JSON file with the ip, port, and | |
301 | authentication information necessary to connect to your kernel. By default, this file |
|
303 | authentication information necessary to connect to your kernel. By default, this file | |
302 | will be in your default profile's security directory. If it is somewhere else, |
|
304 | will be in your default profile's security directory. If it is somewhere else, | |
303 | the output line will print the full path of the connection file, rather than |
|
305 | the output line will print the full path of the connection file, rather than | |
304 | just its filename. |
|
306 | just its filename. | |
305 |
|
307 | |||
306 | If you need to find the connection info to send, and don't know where your connection file |
|
308 | If you need to find the connection info to send, and don't know where your connection file | |
307 | lives, there are a couple of ways to get it. If you are already running an IPython console |
|
309 | lives, there are a couple of ways to get it. If you are already running an IPython console | |
308 | connected to the kernel, you can use the ``%connect_info`` magic to display the information |
|
310 | connected to the kernel, you can use the ``%connect_info`` magic to display the information | |
309 | necessary to connect another frontend to the kernel. |
|
311 | necessary to connect another frontend to the kernel. | |
310 |
|
312 | |||
311 | .. sourcecode:: ipython |
|
313 | .. sourcecode:: ipython | |
312 |
|
314 | |||
313 | In [2]: %connect_info |
|
315 | In [2]: %connect_info | |
314 | { |
|
316 | { | |
315 | "stdin_port":50255, |
|
317 | "stdin_port":50255, | |
316 | "ip":"127.0.0.1", |
|
318 | "ip":"127.0.0.1", | |
317 | "hb_port":50256, |
|
319 | "hb_port":50256, | |
318 | "key":"70be6f0f-1564-4218-8cda-31be40a4d6aa", |
|
320 | "key":"70be6f0f-1564-4218-8cda-31be40a4d6aa", | |
319 | "shell_port":50253, |
|
321 | "shell_port":50253, | |
320 | "iopub_port":50254 |
|
322 | "iopub_port":50254 | |
321 | } |
|
323 | } | |
322 |
|
324 | |||
323 | Paste the above JSON into a file, and connect with: |
|
325 | Paste the above JSON into a file, and connect with: | |
324 | $> ipython <app> --existing <file> |
|
326 | $> ipython <app> --existing <file> | |
325 | or, if you are local, you can connect with just: |
|
327 | or, if you are local, you can connect with just: | |
326 | $> ipython <app> --existing kernel-12345.json |
|
328 | $> ipython <app> --existing kernel-12345.json | |
327 | or even just: |
|
329 | or even just: | |
328 | $> ipython <app> --existing |
|
330 | $> ipython <app> --existing | |
329 | if this is the most recent IPython session you have started. |
|
331 | if this is the most recent IPython session you have started. | |
330 |
|
332 | |||
331 | Otherwise, you can find a connection file by name (and optionally profile) with |
|
333 | Otherwise, you can find a connection file by name (and optionally profile) with | |
332 | :func:`IPython.lib.kernel.find_connection_file`: |
|
334 | :func:`IPython.lib.kernel.find_connection_file`: | |
333 |
|
335 | |||
334 | .. sourcecode:: bash |
|
336 | .. sourcecode:: bash | |
335 |
|
337 | |||
336 | $> python -c "from IPython.lib.kernel import find_connection_file;\ |
|
338 | $> python -c "from IPython.lib.kernel import find_connection_file;\ | |
337 | print find_connection_file('kernel-12345.json')" |
|
339 | print find_connection_file('kernel-12345.json')" | |
338 | /home/you/.ipython/profile_default/security/kernel-12345.json |
|
340 | /home/you/.ipython/profile_default/security/kernel-12345.json | |
339 |
|
341 | |||
340 | And if you are using a particular IPython profile: |
|
342 | And if you are using a particular IPython profile: | |
341 |
|
343 | |||
342 | .. sourcecode:: bash |
|
344 | .. sourcecode:: bash | |
343 |
|
345 | |||
344 | $> python -c "from IPython.lib.kernel import find_connection_file;\ |
|
346 | $> python -c "from IPython.lib.kernel import find_connection_file;\ | |
345 | print find_connection_file('kernel-12345.json', profile='foo')" |
|
347 | print find_connection_file('kernel-12345.json', profile='foo')" | |
346 | /home/you/.ipython/profile_foo/security/kernel-12345.json |
|
348 | /home/you/.ipython/profile_foo/security/kernel-12345.json | |
347 |
|
349 | |||
348 | You can even launch a standalone kernel, and connect and disconnect Qt Consoles |
|
350 | You can even launch a standalone kernel, and connect and disconnect Qt Consoles | |
349 | from various machines. This lets you keep the same running IPython session |
|
351 | from various machines. This lets you keep the same running IPython session | |
350 | on your work machine (with matplotlib plots and everything), logging in from home, |
|
352 | on your work machine (with matplotlib plots and everything), logging in from home, | |
351 | cafΓ©s, etc.:: |
|
353 | cafΓ©s, etc.:: | |
352 |
|
354 | |||
353 | $> ipython kernel |
|
355 | $> ipython kernel | |
354 | [IPKernelApp] To connect another client to this kernel, use: |
|
356 | [IPKernelApp] To connect another client to this kernel, use: | |
355 | [IPKernelApp] --existing kernel-12345.json |
|
357 | [IPKernelApp] --existing kernel-12345.json | |
356 |
|
358 | |||
357 | This is actually exactly the same as the subprocess launched by the qtconsole, so |
|
359 | This is actually exactly the same as the subprocess launched by the qtconsole, so | |
358 | all the information about connecting to a standalone kernel is identical to that |
|
360 | all the information about connecting to a standalone kernel is identical to that | |
359 | of connecting to the kernel attached to a running console. |
|
361 | of connecting to the kernel attached to a running console. | |
360 |
|
362 | |||
361 | .. _kernel_security: |
|
363 | .. _kernel_security: | |
362 |
|
364 | |||
363 | Security |
|
365 | Security | |
364 | -------- |
|
366 | -------- | |
365 |
|
367 | |||
366 | .. warning:: |
|
368 | .. warning:: | |
367 |
|
369 | |||
368 | Since the ZMQ code currently has no encryption, listening on an |
|
370 | Since the ZMQ code currently has no encryption, listening on an | |
369 | external-facing IP is dangerous. You are giving any computer that can see |
|
371 | external-facing IP is dangerous. You are giving any computer that can see | |
370 | you on the network the ability to connect to your kernel, and view your traffic. |
|
372 | you on the network the ability to connect to your kernel, and view your traffic. | |
371 | Read the rest of this section before listening on external ports |
|
373 | Read the rest of this section before listening on external ports | |
372 | or running an IPython kernel on a shared machine. |
|
374 | or running an IPython kernel on a shared machine. | |
373 |
|
375 | |||
374 | By default (for security reasons), the kernel only listens on localhost, so you |
|
376 | By default (for security reasons), the kernel only listens on localhost, so you | |
375 | can only connect multiple frontends to the kernel from your local machine. You |
|
377 | can only connect multiple frontends to the kernel from your local machine. You | |
376 | can specify to listen on an external interface by specifying the ``ip`` |
|
378 | can specify to listen on an external interface by specifying the ``ip`` | |
377 | argument:: |
|
379 | argument:: | |
378 |
|
380 | |||
379 | $> ipython qtconsole --ip=192.168.1.123 |
|
381 | $> ipython qtconsole --ip=192.168.1.123 | |
380 |
|
382 | |||
381 | If you specify the ip as 0.0.0.0 or '*', that means all interfaces, so any |
|
383 | If you specify the ip as 0.0.0.0 or '*', that means all interfaces, so any | |
382 | computer that can see yours on the network can connect to the kernel. |
|
384 | computer that can see yours on the network can connect to the kernel. | |
383 |
|
385 | |||
384 | Messages are not encrypted, so users with access to the ports your kernel is using will be |
|
386 | Messages are not encrypted, so users with access to the ports your kernel is using will be | |
385 | able to see any output of the kernel. They will **NOT** be able to issue shell commands as |
|
387 | able to see any output of the kernel. They will **NOT** be able to issue shell commands as | |
386 | you due to message signatures, which are enabled by default as of IPython 0.12. |
|
388 | you due to message signatures, which are enabled by default as of IPython 0.12. | |
387 |
|
389 | |||
388 | .. warning:: |
|
390 | .. warning:: | |
389 |
|
391 | |||
390 | If you disable message signatures, then any user with access to the ports your |
|
392 | If you disable message signatures, then any user with access to the ports your | |
391 | kernel is listening on can issue arbitrary code as you. **DO NOT** disable message |
|
393 | kernel is listening on can issue arbitrary code as you. **DO NOT** disable message | |
392 | signatures unless you have a lot of trust in your environment. |
|
394 | signatures unless you have a lot of trust in your environment. | |
393 |
|
395 | |||
394 | The one security feature IPython does provide is protection from unauthorized execution. |
|
396 | The one security feature IPython does provide is protection from unauthorized execution. | |
395 | IPython's messaging system will sign messages with HMAC digests using a shared-key. The key |
|
397 | IPython's messaging system will sign messages with HMAC digests using a shared-key. The key | |
396 | is never sent over the network, it is only used to generate a unique hash for each message, |
|
398 | is never sent over the network, it is only used to generate a unique hash for each message, | |
397 | based on its content. When IPython receives a message, it will check that the digest |
|
399 | based on its content. When IPython receives a message, it will check that the digest | |
398 | matches, and discard the message. You can use any file that only you have access to to |
|
400 | matches, and discard the message. You can use any file that only you have access to to | |
399 | generate this key, but the default is just to generate a new UUID. You can generate a random |
|
401 | generate this key, but the default is just to generate a new UUID. You can generate a random | |
400 | private key with:: |
|
402 | private key with:: | |
401 |
|
403 | |||
402 | # generate 1024b of random data, and store in a file only you can read: |
|
404 | # generate 1024b of random data, and store in a file only you can read: | |
403 | # (assumes IPYTHONDIR is defined, otherwise use your IPython directory) |
|
405 | # (assumes IPYTHONDIR is defined, otherwise use your IPython directory) | |
404 | $> python -c "import os; print os.urandom(128).encode('base64')" > $IPYTHONDIR/sessionkey |
|
406 | $> python -c "import os; print os.urandom(128).encode('base64')" > $IPYTHONDIR/sessionkey | |
405 | $> chmod 600 $IPYTHONDIR/sessionkey |
|
407 | $> chmod 600 $IPYTHONDIR/sessionkey | |
406 |
|
408 | |||
407 | The *contents* of this file will be stored in the JSON connection file, so that file |
|
409 | The *contents* of this file will be stored in the JSON connection file, so that file | |
408 | contains everything you need to connect to and use a kernel. |
|
410 | contains everything you need to connect to and use a kernel. | |
409 |
|
411 | |||
410 | To use this generated key, simply specify the ``Session.keyfile`` configurable |
|
412 | To use this generated key, simply specify the ``Session.keyfile`` configurable | |
411 | in :file:`ipython_config.py` or at the command-line, as in:: |
|
413 | in :file:`ipython_config.py` or at the command-line, as in:: | |
412 |
|
414 | |||
413 | # instruct IPython to sign messages with that key, instead of a new UUID |
|
415 | # instruct IPython to sign messages with that key, instead of a new UUID | |
414 | $> ipython qtconsole --Session.keyfile=$IPYTHONDIR/sessionkey |
|
416 | $> ipython qtconsole --Session.keyfile=$IPYTHONDIR/sessionkey | |
415 |
|
417 | |||
416 | .. _ssh_tunnels: |
|
418 | .. _ssh_tunnels: | |
417 |
|
419 | |||
418 | SSH Tunnels |
|
420 | SSH Tunnels | |
419 | ----------- |
|
421 | ----------- | |
420 |
|
422 | |||
421 | Sometimes you want to connect to machines across the internet, or just across |
|
423 | Sometimes you want to connect to machines across the internet, or just across | |
422 | a LAN that either doesn't permit open ports or you don't trust the other |
|
424 | a LAN that either doesn't permit open ports or you don't trust the other | |
423 | machines on the network. To do this, you can use SSH tunnels. SSH tunnels |
|
425 | machines on the network. To do this, you can use SSH tunnels. SSH tunnels | |
424 | are a way to securely forward ports on your local machine to ports on another |
|
426 | are a way to securely forward ports on your local machine to ports on another | |
425 | machine, to which you have SSH access. |
|
427 | machine, to which you have SSH access. | |
426 |
|
428 | |||
427 | In simple cases, IPython's tools can forward ports over ssh by simply adding the |
|
429 | In simple cases, IPython's tools can forward ports over ssh by simply adding the | |
428 | ``--ssh=remote`` argument to the usual ``--existing...`` set of flags for connecting |
|
430 | ``--ssh=remote`` argument to the usual ``--existing...`` set of flags for connecting | |
429 | to a running kernel, after copying the JSON connection file (or its contents) to |
|
431 | to a running kernel, after copying the JSON connection file (or its contents) to | |
430 | the second computer. |
|
432 | the second computer. | |
431 |
|
433 | |||
432 | .. warning:: |
|
434 | .. warning:: | |
433 |
|
435 | |||
434 | Using SSH tunnels does *not* increase localhost security. In fact, when |
|
436 | Using SSH tunnels does *not* increase localhost security. In fact, when | |
435 | tunneling from one machine to another *both* machines have open |
|
437 | tunneling from one machine to another *both* machines have open | |
436 | ports on localhost available for connections to the kernel. |
|
438 | ports on localhost available for connections to the kernel. | |
437 |
|
439 | |||
438 | There are two primary models for using SSH tunnels with IPython. The first |
|
440 | There are two primary models for using SSH tunnels with IPython. The first | |
439 | is to have the Kernel listen only on localhost, and connect to it from |
|
441 | is to have the Kernel listen only on localhost, and connect to it from | |
440 | another machine on the same LAN. |
|
442 | another machine on the same LAN. | |
441 |
|
443 | |||
442 | First, let's start a kernel on machine **worker**, listening only |
|
444 | First, let's start a kernel on machine **worker**, listening only | |
443 | on loopback:: |
|
445 | on loopback:: | |
444 |
|
446 | |||
445 | user@worker $> ipython kernel |
|
447 | user@worker $> ipython kernel | |
446 | [IPKernelApp] To connect another client to this kernel, use: |
|
448 | [IPKernelApp] To connect another client to this kernel, use: | |
447 | [IPKernelApp] --existing kernel-12345.json |
|
449 | [IPKernelApp] --existing kernel-12345.json | |
448 |
|
450 | |||
449 | In this case, the IP that you would connect |
|
451 | In this case, the IP that you would connect | |
450 | to would still be 127.0.0.1, but you want to specify the additional ``--ssh`` argument |
|
452 | to would still be 127.0.0.1, but you want to specify the additional ``--ssh`` argument | |
451 | with the hostname of the kernel (in this example, it's 'worker'):: |
|
453 | with the hostname of the kernel (in this example, it's 'worker'):: | |
452 |
|
454 | |||
453 | user@client $> ipython qtconsole --ssh=worker --existing /path/to/kernel-12345.json |
|
455 | user@client $> ipython qtconsole --ssh=worker --existing /path/to/kernel-12345.json | |
454 |
|
456 | |||
455 | Which will write a new connection file with the forwarded ports, so you can reuse them:: |
|
457 | Which will write a new connection file with the forwarded ports, so you can reuse them:: | |
456 |
|
458 | |||
457 | [IPythonQtConsoleApp] To connect another client via this tunnel, use: |
|
459 | [IPythonQtConsoleApp] To connect another client via this tunnel, use: | |
458 | [IPythonQtConsoleApp] --existing kernel-12345-ssh.json |
|
460 | [IPythonQtConsoleApp] --existing kernel-12345-ssh.json | |
459 |
|
461 | |||
460 | Note again that this opens ports on the *client* machine that point to your kernel. |
|
462 | Note again that this opens ports on the *client* machine that point to your kernel. | |
461 |
|
463 | |||
462 | .. note:: |
|
464 | .. note:: | |
463 |
|
465 | |||
464 | the ssh argument is simply passed to openssh, so it can be fully specified ``user@host:port`` |
|
466 | the ssh argument is simply passed to openssh, so it can be fully specified ``user@host:port`` | |
465 | but it will also respect your aliases, etc. in :file:`.ssh/config` if you have any. |
|
467 | but it will also respect your aliases, etc. in :file:`.ssh/config` if you have any. | |
466 |
|
468 | |||
467 | The second pattern is for connecting to a machine behind a firewall across the internet |
|
469 | The second pattern is for connecting to a machine behind a firewall across the internet | |
468 | (or otherwise wide network). This time, we have a machine **login** that you have ssh access |
|
470 | (or otherwise wide network). This time, we have a machine **login** that you have ssh access | |
469 | to, which can see **kernel**, but **client** is on another network. The important difference |
|
471 | to, which can see **kernel**, but **client** is on another network. The important difference | |
470 | now is that **client** can see **login**, but *not* **worker**. So we need to forward ports from |
|
472 | now is that **client** can see **login**, but *not* **worker**. So we need to forward ports from | |
471 | client to worker *via* login. This means that the kernel must be started listening |
|
473 | client to worker *via* login. This means that the kernel must be started listening | |
472 | on external interfaces, so that its ports are visible to `login`:: |
|
474 | on external interfaces, so that its ports are visible to `login`:: | |
473 |
|
475 | |||
474 | user@worker $> ipython kernel --ip=0.0.0.0 |
|
476 | user@worker $> ipython kernel --ip=0.0.0.0 | |
475 | [IPKernelApp] To connect another client to this kernel, use: |
|
477 | [IPKernelApp] To connect another client to this kernel, use: | |
476 | [IPKernelApp] --existing kernel-12345.json |
|
478 | [IPKernelApp] --existing kernel-12345.json | |
477 |
|
479 | |||
478 | Which we can connect to from the client with:: |
|
480 | Which we can connect to from the client with:: | |
479 |
|
481 | |||
480 | user@client $> ipython qtconsole --ssh=login --ip=192.168.1.123 --existing /path/to/kernel-12345.json |
|
482 | user@client $> ipython qtconsole --ssh=login --ip=192.168.1.123 --existing /path/to/kernel-12345.json | |
481 |
|
483 | |||
482 | .. note:: |
|
484 | .. note:: | |
483 |
|
485 | |||
484 | The IP here is the address of worker as seen from *login*, and need only be specified if |
|
486 | The IP here is the address of worker as seen from *login*, and need only be specified if | |
485 | the kernel used the ambiguous 0.0.0.0 (all interfaces) address. If it had used |
|
487 | the kernel used the ambiguous 0.0.0.0 (all interfaces) address. If it had used | |
486 | 192.168.1.123 to start with, it would not be needed. |
|
488 | 192.168.1.123 to start with, it would not be needed. | |
487 |
|
489 | |||
488 |
|
490 | |||
489 | Manual SSH tunnels |
|
491 | Manual SSH tunnels | |
490 | ------------------ |
|
492 | ------------------ | |
491 |
|
493 | |||
492 | It's possible that IPython's ssh helper functions won't work for you, for various |
|
494 | It's possible that IPython's ssh helper functions won't work for you, for various | |
493 | reasons. You can still connect to remote machines, as long as you set up the tunnels |
|
495 | reasons. You can still connect to remote machines, as long as you set up the tunnels | |
494 | yourself. The basic format of forwarding a local port to a remote one is:: |
|
496 | yourself. The basic format of forwarding a local port to a remote one is:: | |
495 |
|
497 | |||
496 | [client] $> ssh <server> <localport>:<remoteip>:<remoteport> -f -N |
|
498 | [client] $> ssh <server> <localport>:<remoteip>:<remoteport> -f -N | |
497 |
|
499 | |||
498 | This will forward local connections to **localport** on client to **remoteip:remoteport** |
|
500 | This will forward local connections to **localport** on client to **remoteip:remoteport** | |
499 | *via* **server**. Note that remoteip is interpreted relative to *server*, not the client. |
|
501 | *via* **server**. Note that remoteip is interpreted relative to *server*, not the client. | |
500 | So if you have direct ssh access to the machine to which you want to forward connections, |
|
502 | So if you have direct ssh access to the machine to which you want to forward connections, | |
501 | then the server *is* the remote machine, and remoteip should be server's IP as seen from the |
|
503 | then the server *is* the remote machine, and remoteip should be server's IP as seen from the | |
502 | server itself, i.e. 127.0.0.1. Thus, to forward local port 12345 to remote port 54321 on |
|
504 | server itself, i.e. 127.0.0.1. Thus, to forward local port 12345 to remote port 54321 on | |
503 | a machine you can see, do:: |
|
505 | a machine you can see, do:: | |
504 |
|
506 | |||
505 | [client] $> ssh machine 12345:127.0.0.1:54321 -f -N |
|
507 | [client] $> ssh machine 12345:127.0.0.1:54321 -f -N | |
506 |
|
508 | |||
507 | But if your target is actually on a LAN at 192.168.1.123, behind another machine called **login**, |
|
509 | But if your target is actually on a LAN at 192.168.1.123, behind another machine called **login**, | |
508 | then you would do:: |
|
510 | then you would do:: | |
509 |
|
511 | |||
510 | [client] $> ssh login 12345:192.168.1.16:54321 -f -N |
|
512 | [client] $> ssh login 12345:192.168.1.16:54321 -f -N | |
511 |
|
513 | |||
512 | The ``-f -N`` on the end are flags that tell ssh to run in the background, |
|
514 | The ``-f -N`` on the end are flags that tell ssh to run in the background, | |
513 | and don't actually run any commands beyond creating the tunnel. |
|
515 | and don't actually run any commands beyond creating the tunnel. | |
514 |
|
516 | |||
515 | .. seealso:: |
|
517 | .. seealso:: | |
516 |
|
518 | |||
517 | A short discussion of ssh tunnels: http://www.revsys.com/writings/quicktips/ssh-tunnel.html |
|
519 | A short discussion of ssh tunnels: http://www.revsys.com/writings/quicktips/ssh-tunnel.html | |
518 |
|
520 | |||
519 |
|
521 | |||
520 |
|
522 | |||
521 | Stopping Kernels and Consoles |
|
523 | Stopping Kernels and Consoles | |
522 | ***************************** |
|
524 | ***************************** | |
523 |
|
525 | |||
524 | Since there can be many consoles per kernel, the shutdown mechanism and dialog |
|
526 | Since there can be many consoles per kernel, the shutdown mechanism and dialog | |
525 | are probably more complicated than you are used to. Since you don't always want |
|
527 | are probably more complicated than you are used to. Since you don't always want | |
526 | to shutdown a kernel when you close a window, you are given the option to just |
|
528 | to shutdown a kernel when you close a window, you are given the option to just | |
527 | close the console window or also close the Kernel and *all other windows*. Note |
|
529 | close the console window or also close the Kernel and *all other windows*. Note | |
528 | that this only refers to all other *local* windows, as remote Consoles are not |
|
530 | that this only refers to all other *local* windows, as remote Consoles are not | |
529 | allowed to shutdown the kernel, and shutdowns do not close Remote consoles (to |
|
531 | allowed to shutdown the kernel, and shutdowns do not close Remote consoles (to | |
530 | allow for saving, etc.). |
|
532 | allow for saving, etc.). | |
531 |
|
533 | |||
532 | Rules: |
|
534 | Rules: | |
533 |
|
535 | |||
534 | * Restarting the kernel automatically clears all *local* Consoles, and prompts remote |
|
536 | * Restarting the kernel automatically clears all *local* Consoles, and prompts remote | |
535 | Consoles about the reset. |
|
537 | Consoles about the reset. | |
536 | * Shutdown closes all *local* Consoles, and notifies remotes that |
|
538 | * Shutdown closes all *local* Consoles, and notifies remotes that | |
537 | the Kernel has been shutdown. |
|
539 | the Kernel has been shutdown. | |
538 | * Remote Consoles may not restart or shutdown the kernel. |
|
540 | * Remote Consoles may not restart or shutdown the kernel. | |
539 |
|
541 | |||
540 | Qt and the QtConsole |
|
542 | Qt and the QtConsole | |
541 | ==================== |
|
543 | ==================== | |
542 |
|
544 | |||
543 | An important part of working with the QtConsole when you are writing your own |
|
545 | An important part of working with the QtConsole when you are writing your own | |
544 | Qt code is to remember that user code (in the kernel) is *not* in the same |
|
546 | Qt code is to remember that user code (in the kernel) is *not* in the same | |
545 | process as the frontend. This means that there is not necessarily any Qt code |
|
547 | process as the frontend. This means that there is not necessarily any Qt code | |
546 | running in the kernel, and under most normal circumstances there isn't. If, |
|
548 | running in the kernel, and under most normal circumstances there isn't. If, | |
547 | however, you specify ``--pylab=qt`` at the command-line, then there *will* be a |
|
549 | however, you specify ``--pylab=qt`` at the command-line, then there *will* be a | |
548 | :class:`QCoreApplication` instance running in the kernel process along with |
|
550 | :class:`QCoreApplication` instance running in the kernel process along with | |
549 | user-code. To get a reference to this application, do: |
|
551 | user-code. To get a reference to this application, do: | |
550 |
|
552 | |||
551 | .. sourcecode:: python |
|
553 | .. sourcecode:: python | |
552 |
|
554 | |||
553 | from PyQt4 import QtCore |
|
555 | from PyQt4 import QtCore | |
554 | app = QtCore.QCoreApplication.instance() |
|
556 | app = QtCore.QCoreApplication.instance() | |
555 | # app will be None if there is no such instance |
|
557 | # app will be None if there is no such instance | |
556 |
|
558 | |||
557 | A common problem listed in the PyQt4 Gotchas_ is the fact that Python's garbage |
|
559 | A common problem listed in the PyQt4 Gotchas_ is the fact that Python's garbage | |
558 | collection will destroy Qt objects (Windows, etc.) once there is no longer a |
|
560 | collection will destroy Qt objects (Windows, etc.) once there is no longer a | |
559 | Python reference to them, so you have to hold on to them. For instance, in: |
|
561 | Python reference to them, so you have to hold on to them. For instance, in: | |
560 |
|
562 | |||
561 | .. sourcecode:: python |
|
563 | .. sourcecode:: python | |
562 |
|
564 | |||
563 | def make_window(): |
|
565 | def make_window(): | |
564 | win = QtGui.QMainWindow() |
|
566 | win = QtGui.QMainWindow() | |
565 |
|
567 | |||
566 | def make_and_return_window(): |
|
568 | def make_and_return_window(): | |
567 | win = QtGui.QMainWindow() |
|
569 | win = QtGui.QMainWindow() | |
568 | return win |
|
570 | return win | |
569 |
|
571 | |||
570 | :func:`make_window` will never draw a window, because garbage collection will |
|
572 | :func:`make_window` will never draw a window, because garbage collection will | |
571 | destroy it before it is drawn, whereas :func:`make_and_return_window` lets the |
|
573 | destroy it before it is drawn, whereas :func:`make_and_return_window` lets the | |
572 | caller decide when the window object should be destroyed. If, as a developer, |
|
574 | caller decide when the window object should be destroyed. If, as a developer, | |
573 | you know that you always want your objects to last as long as the process, you |
|
575 | you know that you always want your objects to last as long as the process, you | |
574 | can attach them to the QApplication instance itself: |
|
576 | can attach them to the QApplication instance itself: | |
575 |
|
577 | |||
576 | .. sourcecode:: python |
|
578 | .. sourcecode:: python | |
577 |
|
579 | |||
578 | # do this just once: |
|
580 | # do this just once: | |
579 | app = QtCore.QCoreApplication.instance() |
|
581 | app = QtCore.QCoreApplication.instance() | |
580 | app.references = set() |
|
582 | app.references = set() | |
581 | # then when you create Windows, add them to the set |
|
583 | # then when you create Windows, add them to the set | |
582 | def make_window(): |
|
584 | def make_window(): | |
583 | win = QtGui.QMainWindow() |
|
585 | win = QtGui.QMainWindow() | |
584 | app.references.add(win) |
|
586 | app.references.add(win) | |
585 |
|
587 | |||
586 | Now the QApplication itself holds a reference to ``win``, so it will never be |
|
588 | Now the QApplication itself holds a reference to ``win``, so it will never be | |
587 | garbage collected until the application itself is destroyed. |
|
589 | garbage collected until the application itself is destroyed. | |
588 |
|
590 | |||
589 | .. _Gotchas: http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/gotchas.html#garbage-collection |
|
591 | .. _Gotchas: http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/gotchas.html#garbage-collection | |
590 |
|
592 | |||
591 | Regressions |
|
593 | Regressions | |
592 | =========== |
|
594 | =========== | |
593 |
|
595 | |||
594 | There are some features, where the qt console lags behind the Terminal |
|
596 | There are some features, where the qt console lags behind the Terminal | |
595 | frontend: |
|
597 | frontend: | |
596 |
|
598 | |||
597 | * !cmd input: Due to our use of pexpect, we cannot pass input to subprocesses |
|
599 | * !cmd input: Due to our use of pexpect, we cannot pass input to subprocesses | |
598 | launched using the '!' escape, so you should never call a command that |
|
600 | launched using the '!' escape, so you should never call a command that | |
599 | requires interactive input. For such cases, use the terminal IPython. This |
|
601 | requires interactive input. For such cases, use the terminal IPython. This | |
600 | will not be fixed, as abandoning pexpect would significantly degrade the |
|
602 | will not be fixed, as abandoning pexpect would significantly degrade the | |
601 | console experience. |
|
603 | console experience. | |
602 |
|
604 | |||
603 | .. _PyQt: http://www.riverbankcomputing.co.uk/software/pyqt/download |
|
605 | .. _PyQt: http://www.riverbankcomputing.co.uk/software/pyqt/download | |
604 | .. _pygments: http://pygments.org/ |
|
606 | .. _pygments: http://pygments.org/ |
General Comments 0
You need to be logged in to leave comments.
Login now