/usr/share/doc/python-qtconsole-doc/html/index.html is in python-qtconsole-doc 4.3.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 | <!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>The Qt Console for Jupyter — Jupyter Qt Console 4.3.1 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="Jupyter Qt Console 4.3.1 documentation" href="#"/>
<link rel="next" title="Installation" href="installation.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="#" class="icon icon-home"> Jupyter Qt Console
</a>
<div class="version">
4.3
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="config_options.html">Configuration options</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changes in Jupyter Qt console</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="#">Jupyter Qt Console</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="#">Docs</a> »</li>
<li>The Qt Console for Jupyter</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/index.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="the-qt-console-for-jupyter">
<span id="qtconsole"></span><h1>The Qt Console for Jupyter<a class="headerlink" href="#the-qt-console-for-jupyter" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Release:</th><td class="field-body">4.3.1</td>
</tr>
<tr class="field-even field"><th class="field-name">Date:</th><td class="field-body">October 08, 2017</td>
</tr>
</tbody>
</table>
<p>To start the Qt console:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ jupyter qtconsole
</pre></div>
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="installation.html#install-using-conda">Install using conda</a></li>
<li class="toctree-l2"><a class="reference internal" href="installation.html#install-using-pip">Install using pip</a></li>
<li class="toctree-l2"><a class="reference internal" href="installation.html#installing-qt-if-needed">Installing Qt (if needed)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="config_options.html">Configuration options</a><ul>
<li class="toctree-l2"><a class="reference internal" href="config_options.html#options">Options</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changes in Jupyter Qt console</a><ul>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#id2">4.3</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#id4">4.2</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#id6">4.1</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#id8">4.1.1</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#id12">4.0</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>The Qt console is a very lightweight application that largely feels like a
terminal, but provides a number of enhancements only possible in a GUI, such as
inline figures, proper multi-line editing with syntax highlighting, graphical
calltips, and much more. The Qt console can use any Jupyter kernel.</p>
<div class="figure align-center" id="id3">
<a class="reference external image-reference" href="_images/qtconsole.png"><img alt="Qt console with embedded plots" src="_images/qtconsole.png" style="width: 400px;" /></a>
<p class="caption"><span class="caption-text">The Qt console with IPython, using inline matplotlib plots.</span></p>
</div>
<p>The Qt console frontend has hand-coded emacs-style bindings for text
navigation. This is not yet configurable.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">Since the Qt console tries hard to behave like a terminal, by default it
immediately executes single lines of input that are complete. If you want
to force multi-line input, hit <code class="kbd docutils literal"><span class="pre">Ctrl-Enter</span></code> at the end of the first line
instead of <code class="kbd docutils literal"><span class="pre">Enter</span></code>, and it will open a new line for input. At any
point in a multi-line block, you can force its execution (without having to
go to the bottom) with <code class="kbd docutils literal"><span class="pre">Shift-Enter</span></code>.</p>
</div>
</div>
<div class="section" id="inline-graphics">
<h2>Inline graphics<a class="headerlink" href="#inline-graphics" title="Permalink to this headline">¶</a></h2>
<p>One of the most exciting features of the Qt Console is embedded figures.
You can plot with matplotlib in IPython, or the plotting library of choice
in your kernel.</p>
<a class="reference internal image-reference" href="_images/besselj.png"><img alt="_images/besselj.png" src="_images/besselj.png" style="width: 519px;" /></a>
</div>
<div class="section" id="saving-and-printing">
<span id="saving"></span><h2>Saving and Printing<a class="headerlink" href="#saving-and-printing" title="Permalink to this headline">¶</a></h2>
<p>The Qt Console has the ability to save your current session, as either HTML or
XHTML. Your inline figures will be PNG in HTML, or inlined as SVG in XHTML.
PNG images have the option to be either in an external folder, as in many
browsers’ “Webpage, Complete” option, or inlined as well, for a larger, but
more portable file.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Export to SVG+XHTML requires that you are using SVG figures, which is <em>not</em>
the default. To switch the inline figure format in IPython to use SVG, do:</p>
<div class="highlight-ipython"><div class="highlight"><pre><span></span><span class="gp">In [10]: </span><span class="o">%</span><span class="k">config</span> InlineBackend.figure_format = 'svg'
</pre></div>
</div>
<p>Or, you can add the same line (c.Inline… instead of %config Inline…) to
your config files.</p>
<p class="last">This will only affect figures plotted after making this call</p>
</div>
<p>The widget also exposes the ability to print directly, via the default print
shortcut or context menu.</p>
<p>See these examples of <a class="reference download internal" href="_downloads/jn.html" download=""><code class="xref download docutils literal"><span class="pre">png/html</span></code></a> and
<a class="reference download internal" href="_downloads/jn.xhtml" download=""><code class="xref download docutils literal"><span class="pre">svg/xhtml</span></code></a> output. Note that syntax highlighting
does not survive export. This is a known issue, and is being investigated.</p>
</div>
<div class="section" id="colors-and-highlighting">
<h2>Colors and Highlighting<a class="headerlink" href="#colors-and-highlighting" title="Permalink to this headline">¶</a></h2>
<p>Terminal IPython has always had some coloring, but never syntax
highlighting. There are a few simple color choices, specified by the <code class="docutils literal"><span class="pre">colors</span></code>
flag or <code class="docutils literal"><span class="pre">%colors</span></code> magic:</p>
<ul class="simple">
<li>LightBG for light backgrounds</li>
<li>Linux for dark backgrounds</li>
<li>NoColor for a simple colorless terminal</li>
</ul>
<p>The Qt widget, however, has full syntax highlighting as you type, handled by
the <a class="reference external" href="http://pygments.org/">pygments</a> library. The <code class="docutils literal"><span class="pre">style</span></code> argument exposes access to any style by
name that can be found by pygments, and there are several already
installed.</p>
<p>Screenshot of <code class="docutils literal"><span class="pre">jupyter</span> <span class="pre">qtconsole</span> <span class="pre">--style</span> <span class="pre">monokai</span></code>, which uses the ‘monokai’
theme:</p>
<a class="reference internal image-reference" href="_images/colors_dark.png"><img alt="_images/colors_dark.png" src="_images/colors_dark.png" style="width: 627px;" /></a>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Calling <code class="docutils literal"><span class="pre">jupyter</span> <span class="pre">qtconsole</span> <span class="pre">-h</span></code> will show all the style names that
pygments can find on your system.</p>
</div>
<p>You can also pass the filename of a custom CSS stylesheet, if you want to do
your own coloring, via the <code class="docutils literal"><span class="pre">stylesheet</span></code> argument. The default LightBG
stylesheet:</p>
<div class="highlight-css"><div class="highlight"><pre><span></span><span class="nt">QPlainTextEdit</span><span class="o">,</span> <span class="nt">QTextEdit</span> <span class="p">{</span> <span class="k">background-color</span><span class="p">:</span> <span class="kc">white</span><span class="p">;</span>
<span class="k">color</span><span class="p">:</span> <span class="kc">black</span> <span class="p">;</span>
<span class="n">selection-background-color</span><span class="p">:</span> <span class="mh">#ccc</span><span class="p">}</span>
<span class="p">.</span><span class="nc">error</span> <span class="p">{</span> <span class="k">color</span><span class="p">:</span> <span class="kc">red</span><span class="p">;</span> <span class="p">}</span>
<span class="p">.</span><span class="nc">in-prompt</span> <span class="p">{</span> <span class="k">color</span><span class="p">:</span> <span class="kc">navy</span><span class="p">;</span> <span class="p">}</span>
<span class="p">.</span><span class="nc">in-prompt-number</span> <span class="p">{</span> <span class="k">font-weight</span><span class="p">:</span> <span class="kc">bold</span><span class="p">;</span> <span class="p">}</span>
<span class="p">.</span><span class="nc">out-prompt</span> <span class="p">{</span> <span class="k">color</span><span class="p">:</span> <span class="kc">darkred</span><span class="p">;</span> <span class="p">}</span>
<span class="p">.</span><span class="nc">out-prompt-number</span> <span class="p">{</span> <span class="k">font-weight</span><span class="p">:</span> <span class="kc">bold</span><span class="p">;</span> <span class="p">}</span>
<span class="c">/* .inverted is used to highlight selected completion */</span>
<span class="p">.</span><span class="nc">inverted</span> <span class="p">{</span> <span class="k">background-color</span><span class="p">:</span> <span class="kc">black</span> <span class="p">;</span> <span class="k">color</span><span class="p">:</span> <span class="kc">white</span><span class="p">;</span> <span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="fonts">
<h2>Fonts<a class="headerlink" href="#fonts" title="Permalink to this headline">¶</a></h2>
<p>The Qt console is configurable via the ConsoleWidget. To change these, set the
<code class="docutils literal"><span class="pre">font_family</span></code> or <code class="docutils literal"><span class="pre">font_size</span></code> traits of the ConsoleWidget. For instance, to
use 9pt Anonymous Pro:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$> jupyter qtconsole --ConsoleWidget.font_family="Anonymous Pro" --ConsoleWidget.font_size=9
</pre></div>
</div>
</div>
<div class="section" id="process-management">
<h2>Process Management<a class="headerlink" href="#process-management" title="Permalink to this headline">¶</a></h2>
<p>With the two-process ZMQ model, the frontend does not block input during
execution. This means that actions can be taken by the frontend while the
Kernel is executing, or even after it crashes. The most basic such command is
via ‘Ctrl-.’, which restarts the kernel. This can be done in the middle of a
blocking execution. The frontend can also know, via a heartbeat mechanism, that
the kernel has died. This means that the frontend can safely restart the
kernel.</p>
<div class="section" id="multiple-consoles">
<span id="id1"></span><h3>Multiple Consoles<a class="headerlink" href="#multiple-consoles" title="Permalink to this headline">¶</a></h3>
<p>Since the Kernel listens on the network, multiple frontends can connect to it.
These do not have to all be qt frontends - any Jupyter frontend can connect and
run code.</p>
<p>Other frontends can connect to your kernel, and share in the execution. This is
great for collaboration. The <code class="docutils literal"><span class="pre">--existing</span></code> flag means connect to a kernel
that already exists. Starting other consoles
with that flag will not try to start their own kernel, but rather connect to
yours. <code class="file docutils literal"><span class="pre">kernel-12345.json</span></code> is a small JSON file with the ip, port, and
authentication information necessary to connect to your kernel. By default, this file
will be in your Jupyter runtime directory. If it is somewhere else,
you will need to use the full path of the connection file, rather than
just its filename.</p>
<p>If you need to find the connection info to send, and don’t know where your connection file
lives, there are a couple of ways to get it. If you are already running a console
connected to an IPython kernel, you can use the <code class="docutils literal"><span class="pre">%connect_info</span></code> magic to display the information
necessary to connect another frontend to the kernel.</p>
<div class="highlight-ipython"><div class="highlight"><pre><span></span><span class="gp">In [2]: </span><span class="o">%</span><span class="k">connect_info</span>
<span class="go">{</span>
<span class="go"> "stdin_port":50255,</span>
<span class="go"> "ip":"127.0.0.1",</span>
<span class="go"> "hb_port":50256,</span>
<span class="go"> "key":"70be6f0f-1564-4218-8cda-31be40a4d6aa",</span>
<span class="go"> "shell_port":50253,</span>
<span class="go"> "iopub_port":50254</span>
<span class="go">}</span>
<span class="go">Paste the above JSON into a file, and connect with:</span>
<span class="go"> $> ipython <app> --existing <file></span>
<span class="go">or, if you are local, you can connect with just:</span>
<span class="go"> $> ipython <app> --existing kernel-12345.json</span>
<span class="go">or even just:</span>
<span class="go"> $> ipython <app> --existing</span>
<span class="go">if this is the most recent kernel you have started.</span>
</pre></div>
</div>
<p>Otherwise, you can find a connection file by name (and optionally profile) with
<code class="xref py py-func docutils literal"><span class="pre">jupyter_client.find_connection_file()</span></code>:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>$> python -c <span class="s2">"from jupyter_client import find_connection_file;\</span>
<span class="s2">print(find_connection_file('kernel-12345.json'))"</span>
/home/you/Library/Jupyter/runtime/kernel-12345.json
</pre></div>
</div>
</div>
<div class="section" id="security">
<span id="kernel-security"></span><h3>Security<a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h3>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Since the ZMQ code currently has no encryption, listening on an
external-facing IP is dangerous. You are giving any computer that can see
you on the network the ability to connect to your kernel, and view your traffic.
Read the rest of this section before listening on external ports
or running a kernel on a shared machine.</p>
</div>
<p>By default (for security reasons), the kernel only listens on localhost, so you
can only connect multiple frontends to the kernel from your local machine. You
can specify to listen on an external interface by specifying the <code class="docutils literal"><span class="pre">ip</span></code>
argument:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$> jupyter qtconsole --ip=192.168.1.123
</pre></div>
</div>
<p>If you specify the ip as 0.0.0.0 or ‘*’, that means all interfaces, so any
computer that can see yours on the network can connect to the kernel.</p>
<p>Messages are not encrypted, so users with access to the ports your kernel is using will be
able to see any output of the kernel. They will <strong>NOT</strong> be able to issue shell commands as
you due to message signatures.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you disable message signatures, then any user with access to the ports your
kernel is listening on can issue arbitrary code as you. <strong>DO NOT</strong> disable message
signatures unless you have a lot of trust in your environment.</p>
</div>
<p>The one security feature Jupyter does provide is protection from unauthorized execution.
Jupyter’s messaging system will sign messages with HMAC digests using a shared-key. The key
is never sent over the network, it is only used to generate a unique hash for each message,
based on its content. When the kernel receives a message, it will check that the digest
matches, and discard the message. You can use any file that only you have access to to
generate this key, but the default is just to generate a new UUID.</p>
</div>
<div class="section" id="ssh-tunnels">
<span id="id2"></span><h3>SSH Tunnels<a class="headerlink" href="#ssh-tunnels" title="Permalink to this headline">¶</a></h3>
<p>Sometimes you want to connect to machines across the internet, or just across
a LAN that either doesn’t permit open ports or you don’t trust the other
machines on the network. To do this, you can use SSH tunnels. SSH tunnels
are a way to securely forward ports on your local machine to ports on another
machine, to which you have SSH access.</p>
<p>In simple cases, Jupyter’s tools can forward ports over ssh by simply adding the
<code class="docutils literal"><span class="pre">--ssh=remote</span></code> argument to the usual <code class="docutils literal"><span class="pre">--existing...</span></code> set of flags for connecting
to a running kernel, after copying the JSON connection file (or its contents) to
the second computer.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Using SSH tunnels does <em>not</em> increase localhost security. In fact, when
tunneling from one machine to another <em>both</em> machines have open
ports on localhost available for connections to the kernel.</p>
</div>
<p>There are two primary models for using SSH tunnels with Jupyter. The first
is to have the Kernel listen only on localhost, and connect to it from
another machine on the same LAN.</p>
<p>First, let’s start a kernel on machine <strong>worker</strong>, listening only
on loopback:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>user@worker $> ipython kernel
[IPKernelApp] To connect another client to this kernel, use:
[IPKernelApp] --existing kernel-12345.json
</pre></div>
</div>
<p>In this case, the IP that you would connect
to would still be 127.0.0.1, but you want to specify the additional <code class="docutils literal"><span class="pre">--ssh</span></code> argument
with the hostname of the kernel (in this example, it’s ‘worker’):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>user@client $> jupyter qtconsole --ssh=worker --existing /path/to/kernel-12345.json
</pre></div>
</div>
<p>Which will write a new connection file with the forwarded ports, so you can reuse them:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">JupyterQtConsoleApp</span><span class="p">]</span> <span class="n">To</span> <span class="n">connect</span> <span class="n">another</span> <span class="n">client</span> <span class="n">via</span> <span class="n">this</span> <span class="n">tunnel</span><span class="p">,</span> <span class="n">use</span><span class="p">:</span>
<span class="p">[</span><span class="n">JupyterQtConsoleApp</span><span class="p">]</span> <span class="o">--</span><span class="n">existing</span> <span class="n">kernel</span><span class="o">-</span><span class="mi">12345</span><span class="o">-</span><span class="n">ssh</span><span class="o">.</span><span class="n">json</span>
</pre></div>
</div>
<p>Note again that this opens ports on the <em>client</em> machine that point to your kernel.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">the ssh argument is simply passed to openssh, so it can be fully specified <code class="docutils literal"><span class="pre">user@host:port</span></code>
but it will also respect your aliases, etc. in <code class="file docutils literal"><span class="pre">.ssh/config</span></code> if you have any.</p>
</div>
<p>The second pattern is for connecting to a machine behind a firewall across the internet
(or otherwise wide network). This time, we have a machine <strong>login</strong> that you have ssh access
to, which can see <strong>kernel</strong>, but <strong>client</strong> is on another network. The important difference
now is that <strong>client</strong> can see <strong>login</strong>, but <em>not</em> <strong>worker</strong>. So we need to forward ports from
client to worker <em>via</em> login. This means that the kernel must be started listening
on external interfaces, so that its ports are visible to <code class="docutils literal"><span class="pre">login</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>user@worker $> ipython kernel --ip=0.0.0.0
[IPKernelApp] To connect another client to this kernel, use:
[IPKernelApp] --existing kernel-12345.json
</pre></div>
</div>
<p>Which we can connect to from the client with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>user@client $> jupyter qtconsole --ssh=login --ip=192.168.1.123 --existing /path/to/kernel-12345.json
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The IP here is the address of worker as seen from <em>login</em>, and need only be specified if
the kernel used the ambiguous 0.0.0.0 (all interfaces) address. If it had used
192.168.1.123 to start with, it would not be needed.</p>
</div>
</div>
<div class="section" id="manual-ssh-tunnels">
<h3>Manual SSH tunnels<a class="headerlink" href="#manual-ssh-tunnels" title="Permalink to this headline">¶</a></h3>
<p>It’s possible that Jupyter’s ssh helper functions won’t work for you, for various
reasons. You can still connect to remote machines, as long as you set up the tunnels
yourself. The basic format of forwarding a local port to a remote one is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>[client] $> ssh <server> <localport>:<remoteip>:<remoteport> -f -N
</pre></div>
</div>
<p>This will forward local connections to <strong>localport</strong> on client to <strong>remoteip:remoteport</strong>
<em>via</em> <strong>server</strong>. Note that remoteip is interpreted relative to <em>server</em>, not the client.
So if you have direct ssh access to the machine to which you want to forward connections,
then the server <em>is</em> the remote machine, and remoteip should be server’s IP as seen from the
server itself, i.e. 127.0.0.1. Thus, to forward local port 12345 to remote port 54321 on
a machine you can see, do:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>[client] $> ssh machine 12345:127.0.0.1:54321 -f -N
</pre></div>
</div>
<p>But if your target is actually on a LAN at 192.168.1.123, behind another machine called <strong>login</strong>,
then you would do:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>[client] $> ssh login 12345:192.168.1.16:54321 -f -N
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">-f</span> <span class="pre">-N</span></code> on the end are flags that tell ssh to run in the background,
and don’t actually run any commands beyond creating the tunnel.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">A short discussion of ssh tunnels: <a class="reference external" href="http://www.revsys.com/writings/quicktips/ssh-tunnel.html">http://www.revsys.com/writings/quicktips/ssh-tunnel.html</a></p>
</div>
</div>
<div class="section" id="stopping-kernels-and-consoles">
<h3>Stopping Kernels and Consoles<a class="headerlink" href="#stopping-kernels-and-consoles" title="Permalink to this headline">¶</a></h3>
<p>Since there can be many consoles per kernel, the shutdown mechanism and dialog
are probably more complicated than you are used to. Since you don’t always want
to shutdown a kernel when you close a window, you are given the option to just
close the console window or also close the Kernel and <em>all other windows</em>. Note
that this only refers to all other <em>local</em> windows, as remote Consoles are not
allowed to shutdown the kernel, and shutdowns do not close Remote consoles (to
allow for saving, etc.).</p>
<p>Rules:</p>
<blockquote>
<div><ul class="simple">
<li>Restarting the kernel automatically clears all <em>local</em> Consoles, and prompts remote
Consoles about the reset.</li>
<li>Shutdown closes all <em>local</em> Consoles, and notifies remotes that
the Kernel has been shutdown.</li>
<li>Remote Consoles may not restart or shutdown the kernel.</li>
</ul>
</div></blockquote>
</div>
</div>
<div class="section" id="qt-and-the-repl">
<h2>Qt and the REPL<a class="headerlink" href="#qt-and-the-repl" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This section is relevant regardless of the frontend you use to write Qt
Code. This section is mostly there as it is easy to get confused and assume
that writing Qt code in the QtConsole should change from usual Qt code. It
should not. If you get confused, take a step back, and try writing your
code using the pure terminal based <code class="docutils literal"><span class="pre">jupyter</span> <span class="pre">console</span></code> that does not
involve Qt.</p>
</div>
<p>An important part of working with the REPL – QtConsole, Jupyter notebook,
IPython terminal – when you are writing your own Qt code is to remember that
user code (in the kernel) is <em>not</em> in the same process as the frontend. This
means that there is not necessarily any Qt code running in the kernel, and
under most normal circumstances there isn’t. This is true even if you are
running the QtConsole.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When executing code from the qtconsole prompt, it is <strong>not possible</strong> to
access the QtApplication instance of the QtConsole itself.</p>
</div>
<p>A common problem listed in the PyQt4 <a class="reference external" href="http://pyqt.sourceforge.net/Docs/PyQt4/gotchas.html#garbage-collection">Gotchas</a> is the fact that Python’s garbage
collection will destroy Qt objects (Windows, etc.) once there is no longer a
Python reference to them, so you have to hold on to them. For instance, in:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PyQt4</span> <span class="kn">import</span> <span class="n">QtGui</span>
<span class="k">def</span> <span class="nf">make_window</span><span class="p">():</span>
<span class="n">win</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QMainWindow</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">make_and_return_window</span><span class="p">():</span>
<span class="n">win</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QMainWindow</span><span class="p">()</span>
<span class="k">return</span> <span class="n">win</span>
</pre></div>
</div>
<p><code class="xref py py-func docutils literal"><span class="pre">make_window()</span></code> will never draw a window, because garbage collection will
destroy it before it is drawn, whereas <code class="xref py py-func docutils literal"><span class="pre">make_and_return_window()</span></code> lets the
caller decide when the window object should be destroyed. If, as a developer,
you know that you always want your objects to last as long as the process, you
can attach them to the <code class="docutils literal"><span class="pre">QApplication</span></code> instance itself:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PyQt4</span> <span class="kn">import</span> <span class="n">QtGui</span><span class="p">,</span> <span class="n">QtCore</span>
<span class="c1"># do this just once:</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">QCoreApplication</span><span class="o">.</span><span class="n">instance</span><span class="p">()</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">app</span><span class="p">:</span>
<span class="c1"># we are in the kernel in most of the case there is NO qt code running.</span>
<span class="c1"># we need to create a Gui APP.</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QApplication</span><span class="p">([])</span>
<span class="n">app</span><span class="o">.</span><span class="n">references</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
<span class="c1"># then when you create Windows, add them to the set</span>
<span class="k">def</span> <span class="nf">make_window</span><span class="p">():</span>
<span class="n">win</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QMainWindow</span><span class="p">()</span>
<span class="n">app</span><span class="o">.</span><span class="n">references</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">win</span><span class="p">)</span>
</pre></div>
</div>
<p>Now the <code class="docutils literal"><span class="pre">QApplication</span></code> itself holds a reference to <code class="docutils literal"><span class="pre">win</span></code>, so it will never be
garbage collected until the application itself is destroyed.</p>
<div class="section" id="embedding-the-qtconsole-in-a-qt-application">
<h3>Embedding the QtConsole in a Qt application<a class="headerlink" href="#embedding-the-qtconsole-in-a-qt-application" title="Permalink to this headline">¶</a></h3>
<p>In order to make the QtConsole available to an external Qt GUI application (just as
<code class="xref py py-func docutils literal"><span class="pre">IPython.embed()</span></code> enables one to embed a terminal session of IPython in a
command-line application), there are a few options:</p>
<ul class="simple">
<li>First start IPython, and then start the external Qt application from IPython,
as described above. Effectively, this embeds your application in IPython
rather than the other way round.</li>
<li>Use <code class="xref py py-class docutils literal"><span class="pre">qtconsole.rich_jupyter_widget.RichJupyterWidget</span></code> in your
Qt application. This will embed the console widget in your GUI and start the
kernel in a separate process, so code typed into the console cannot access
objects in your application.</li>
<li>Start a standard IPython kernel in the process of the external Qt
application. See <code class="file docutils literal"><span class="pre">examples/Embedding/ipkernel_qtapp.py</span></code> for an example. Due
to IPython’s two-process model, the QtConsole itself will live in another
process with its own QApplication, and thus cannot be embedded in the main
GUI.</li>
<li>Start a special IPython kernel, the
<code class="xref py py-class docutils literal"><span class="pre">IPython.kernel.inprocess.ipkernel.InProcessKernel</span></code>, that allows a
QtConsole in the same process. See <code class="file docutils literal"><span class="pre">examples/Embedding/inprocess_qtconsole.py</span></code>
for an example. While the QtConsole can now be embedded in the main GUI, one
cannot connect to the kernel from other consoles as there are no real ZMQ
sockets anymore.</li>
</ul>
</div>
</div>
<div class="section" id="regressions">
<h2>Regressions<a class="headerlink" href="#regressions" title="Permalink to this headline">¶</a></h2>
<p>There are some features, where the qt console lags behind the Terminal
frontend:</p>
<ul class="simple">
<li>!cmd input: Due to our use of pexpect, we cannot pass input to subprocesses
launched using the ‘!’ escape, so you should never call a command that
requires interactive input. For such cases, use the terminal IPython. This
will not be fixed, as abandoning pexpect would significantly degrade the
console experience.</li>
</ul>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="installation.html" class="btn btn-neutral float-right" title="Installation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright The Jupyter Development Team.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'4.3.1',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
|