/usr/share/doc/execnet-doc/html/basics.html is in execnet-doc 1.4.1-4.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>API in a nutshell — execnet 1.4.0.dev1 documentation</title>
<link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.4.0.dev1',
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>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="execnet CHANGELOG" href="changelog.html" />
<link rel="prev" title="Receive file contents from remote SSH account" href="example/test_ssh_fileserver.html" />
</head>
<body role="document">
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<!--<img src="_static/codespeak2.png" target="http://codespeak.net" alt="codespeak projects" />
-->
<h1>execnet: Distributed Python deployment and communication</h1>
<code style="font-size: 130%; vertical-align: middle;">
<a href="index.html">home</a> |
<a href="install.html">install</a> |
<a href="examples.html">examples</a> |
<a href="#">basic API</a> |
<a href="support.html">support</a>
</code>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="changelog.html" title="execnet CHANGELOG"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="example/test_ssh_fileserver.html" title="Receive file contents from remote SSH account"
accesskey="P">previous</a> |</li>
<!-- <a href="index.html">index</a>»</li> -->
<li class="nav-item nav-item-1"><a href="install.html" accesskey="U">Info in a nutshell</a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">API in a nutshell</a><ul>
<li><a class="reference internal" href="#gateways-bootstrapping-python-interpreters">Gateways: bootstrapping Python interpreters</a><ul>
<li><a class="reference internal" href="#examples-for-valid-gateway-specifications">examples for valid gateway specifications</a></li>
</ul>
</li>
<li><a class="reference internal" href="#remote-exec-execute-source-code-remotely">remote_exec: execute source code remotely</a></li>
<li><a class="reference internal" href="#channels-exchanging-data-with-remote-code">Channels: exchanging data with remote code</a></li>
<li><a class="reference internal" href="#grouped-gateways-and-robust-termination">Grouped Gateways and robust termination</a></li>
<li><a class="reference internal" href="#threading-models-gevent-eventlet-thread">threading models: gevent, eventlet, thread</a><ul>
<li><a class="reference internal" href="#how-to-execute-in-the-main-thread">How to execute in the main thread</a></li>
</ul>
</li>
<li><a class="reference internal" href="#remote-status-get-low-level-execution-info">remote_status: get low-level execution info</a></li>
<li><a class="reference internal" href="#rsync-synchronise-filesystem-with-remote">rsync: synchronise filesystem with remote</a></li>
<li><a class="reference internal" href="#debugging-execnet">Debugging execnet</a></li>
<li><a class="reference internal" href="#cross-interpreter-serialization-of-python-objects">cross-interpreter serialization of python objects</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="example/test_ssh_fileserver.html"
title="previous chapter">Receive file contents from remote SSH account</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="changelog.html"
title="next chapter">execnet CHANGELOG</a></p>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="api-in-a-nutshell">
<h1>API in a nutshell<a class="headerlink" href="#api-in-a-nutshell" title="Permalink to this headline">¶</a></h1>
<p>execnet ad-hoc instantiates local and remote Python interpreters.
Each interpreter is accessible through a <strong>Gateway</strong> which manages
code and data communication. <strong>Channels</strong> allow to exchange
data between the local and the remote end. <strong>Groups</strong>
help to manage creation and termination of sub interpreters.</p>
<img alt="_images/basic1.png" src="_images/basic1.png" />
<div class="section" id="gateways-bootstrapping-python-interpreters">
<h2>Gateways: bootstrapping Python interpreters<a class="headerlink" href="#gateways-bootstrapping-python-interpreters" title="Permalink to this headline">¶</a></h2>
<p>All Gateways are instantiated via a call to <code class="docutils literal"><span class="pre">makegateway()</span></code>
passing it a gateway specification or URL.</p>
<span class="target" id="xspec"></span><dl class="function">
<dt id="execnet.makegateway">
<code class="descclassname">execnet.</code><code class="descname">makegateway</code><span class="sig-paren">(</span><em>spec</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.makegateway" title="Permalink to this definition">¶</a></dt>
<dd><p>create and configure a gateway to a Python interpreter.
The <code class="docutils literal"><span class="pre">spec</span></code> string encodes the target gateway type
and configuration information. The general format is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">key1</span><span class="o">=</span><span class="n">value1</span><span class="o">//</span><span class="n">key2</span><span class="o">=</span><span class="n">value2</span><span class="o">//...</span>
</pre></div>
</div>
<p>If you leave out the <code class="docutils literal"><span class="pre">=value</span></code> part a True value is assumed.
Valid types: <code class="docutils literal"><span class="pre">popen</span></code>, <code class="docutils literal"><span class="pre">ssh=hostname</span></code>, <code class="docutils literal"><span class="pre">socket=host:port</span></code>.
Valid configuration:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">id</span><span class="o">=<</span><span class="n">string</span><span class="o">></span> <span class="n">specifies</span> <span class="n">the</span> <span class="n">gateway</span> <span class="nb">id</span>
<span class="n">python</span><span class="o">=<</span><span class="n">path</span><span class="o">></span> <span class="n">specifies</span> <span class="n">which</span> <span class="n">python</span> <span class="n">interpreter</span> <span class="n">to</span> <span class="n">execute</span>
<span class="n">execmodel</span><span class="o">=</span><span class="n">model</span> <span class="s1">'thread'</span><span class="p">,</span> <span class="s1">'eventlet'</span><span class="p">,</span> <span class="s1">'gevent'</span> <span class="n">model</span> <span class="k">for</span> <span class="n">execution</span>
<span class="n">chdir</span><span class="o">=<</span><span class="n">path</span><span class="o">></span> <span class="n">specifies</span> <span class="n">to</span> <span class="n">which</span> <span class="n">directory</span> <span class="n">to</span> <span class="n">change</span>
<span class="n">nice</span><span class="o">=<</span><span class="n">path</span><span class="o">></span> <span class="n">specifies</span> <span class="n">process</span> <span class="n">priority</span> <span class="n">of</span> <span class="n">new</span> <span class="n">process</span>
<span class="n">env</span><span class="p">:</span><span class="n">NAME</span><span class="o">=</span><span class="n">value</span> <span class="n">specifies</span> <span class="n">a</span> <span class="n">remote</span> <span class="n">environment</span> <span class="n">variable</span> <span class="n">setting</span><span class="o">.</span>
</pre></div>
</div>
<p>If no spec is given, self.defaultspec is used.</p>
</dd></dl>
<p>Here is an example which instantiates a simple Python subprocess:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">gateway</span> <span class="o">=</span> <span class="n">execnet</span><span class="o">.</span><span class="n">makegateway</span><span class="p">()</span>
</pre></div>
</div>
<p>gateways allow to <a class="reference internal" href="#remote-execute-code">remote execute code</a> and
<a class="reference internal" href="#exchange-data">exchange data</a> bidirectionally.</p>
<div class="section" id="examples-for-valid-gateway-specifications">
<h3>examples for valid gateway specifications<a class="headerlink" href="#examples-for-valid-gateway-specifications" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">ssh=wyvern//python=python3.3//chdir=mycache</span></code> specifies a Python3.3
interpreter on the host <code class="docutils literal"><span class="pre">wyvern</span></code>. The remote process will have
<code class="docutils literal"><span class="pre">mycache</span></code> as its current working directory.</li>
<li><code class="docutils literal"><span class="pre">ssh=-p</span> <span class="pre">5000</span> <span class="pre">myhost</span></code> makes execnet pass “-p 5000 myhost” arguments
to the underlying ssh client binary, effectively specifying a custom port.</li>
<li><code class="docutils literal"><span class="pre">vagrant_ssh=default</span></code> makes execnet connect to a Vagrant VM named
<code class="docutils literal"><span class="pre">default</span></code> via SSH through Vagrant’s <code class="docutils literal"><span class="pre">vagrant</span> <span class="pre">ssh</span></code> command. It supports
the same additional parameters as regular SSH connections.</li>
<li><code class="docutils literal"><span class="pre">popen//python=python2.6//nice=20</span></code> specification of
a python subprocess using the <code class="docutils literal"><span class="pre">python2.6</span></code> executable which must be
discoverable through the system <code class="docutils literal"><span class="pre">PATH</span></code>; running with the lowest
CPU priority (“nice” level). By default current dir will be the
current dir of the instantiator.</li>
<li><code class="docutils literal"><span class="pre">popen//dont_write_bytecode</span></code> uses the same executable as the current
Python, and also passes the <code class="docutils literal"><span class="pre">-B</span></code> flag on startup, which tells Python not
write <code class="docutils literal"><span class="pre">.pyc</span></code> or <code class="docutils literal"><span class="pre">.pyo</span></code> files. Note that this only works under CPython
2.6 and newer.</li>
<li><code class="docutils literal"><span class="pre">popen//env:NAME=value</span></code> specifies a subprocess that uses the
same interpreter as the one it is initiated from and additionally
remotely sets an environment variable <code class="docutils literal"><span class="pre">NAME</span></code> to <code class="docutils literal"><span class="pre">value</span></code>.</li>
<li><code class="docutils literal"><span class="pre">popen//execmodel=eventlet</span></code> specifies a subprocess that uses the
same interpreter as the one it is initiated from but will run the
other side using eventlet for handling IO and dispatching threads.</li>
<li><code class="docutils literal"><span class="pre">socket=192.168.1.4:8888</span></code> specifies a Python Socket server
process that listens on <code class="docutils literal"><span class="pre">192.168.1.4:8888</span></code></li>
</ul>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">vagarant_ssh</span></code> opens a python interpreter via the vagarant ssh command</li>
</ul>
</div>
</div>
<div class="section" id="remote-exec-execute-source-code-remotely">
<span id="remote-execute-code"></span><h2>remote_exec: execute source code remotely<a class="headerlink" href="#remote-exec-execute-source-code-remotely" title="Permalink to this headline">¶</a></h2>
<p>All gateways offer a simple method to execute source code
in the instantiated subprocess-interpreter:</p>
<dl class="method">
<dt id="execnet.gateway.Gateway.remote_exec">
<code class="descclassname">Gateway.</code><code class="descname">remote_exec</code><span class="sig-paren">(</span><em>source</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway.Gateway.remote_exec" title="Permalink to this definition">¶</a></dt>
<dd><p>return channel object and connect it to a remote
execution thread where the given <code class="docutils literal"><span class="pre">source</span></code> executes.</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">source</span></code> is a string: execute source string remotely
with a <code class="docutils literal"><span class="pre">channel</span></code> put into the global namespace.</li>
<li><code class="docutils literal"><span class="pre">source</span></code> is a pure function: serialize source and
call function with <code class="docutils literal"><span class="pre">**kwargs</span></code>, adding a
<code class="docutils literal"><span class="pre">channel</span></code> object to the keyword arguments.</li>
<li><code class="docutils literal"><span class="pre">source</span></code> is a pure module: execute source of module
with a <code class="docutils literal"><span class="pre">channel</span></code> in its global namespace</li>
</ul>
<p>In all cases the binding <code class="docutils literal"><span class="pre">__name__='__channelexec__'</span></code>
will be available in the global namespace of the remotely
executing code.</p>
</dd></dl>
<p>It is allowed to pass a module object as source code
in which case it’s source code will be obtained and
get sent for remote execution. <code class="docutils literal"><span class="pre">remote_exec</span></code> returns
a channel object whose symmetric counterpart channel
is available to the remotely executing source.</p>
<dl class="method">
<dt id="execnet.gateway.Gateway.reconfigure">
<code class="descclassname">Gateway.</code><code class="descname">reconfigure</code><span class="sig-paren">(</span><span class="optional">[</span><em>py2str_as_py3str=True</em>, <em>py3str_as_py2str=False</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway.Gateway.reconfigure" title="Permalink to this definition">¶</a></dt>
<dd><p>reconfigures the string-coercion behaviour of the gateway</p>
</dd></dl>
</div>
<div class="section" id="channels-exchanging-data-with-remote-code">
<span id="exchange-data"></span><span id="channel-api"></span><span id="channel"></span><h2>Channels: exchanging data with remote code<a class="headerlink" href="#channels-exchanging-data-with-remote-code" title="Permalink to this headline">¶</a></h2>
<p>A channel object allows to send and receive data between
two asynchronously running programs.</p>
<blockquote>
<div><dl class="method">
<dt id="execnet.gateway_base.Channel.send">
<code class="descclassname">Channel.</code><code class="descname">send</code><span class="sig-paren">(</span><em>item</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway_base.Channel.send" title="Permalink to this definition">¶</a></dt>
<dd><p>sends the given item to the other side of the channel,
possibly blocking if the sender queue is full.
The item must be a simple python type and will be
copied to the other side by value. IOError is
raised if the write pipe was prematurely closed.</p>
</dd></dl>
<dl class="method">
<dt id="execnet.gateway_base.Channel.receive">
<code class="descclassname">Channel.</code><code class="descname">receive</code><span class="sig-paren">(</span><em>timeout</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway_base.Channel.receive" title="Permalink to this definition">¶</a></dt>
<dd><p>receive a data item that was sent from the other side.
timeout: None [default] blocked waiting. A positive number
indicates the number of seconds after which a channel.TimeoutError
exception will be raised if no item was received.
Note that exceptions from the remotely executing code will be
reraised as channel.RemoteError exceptions containing
a textual representation of the remote traceback.</p>
</dd></dl>
<dl class="method">
<dt id="execnet.gateway_base.Channel.setcallback">
<code class="descclassname">Channel.</code><code class="descname">setcallback</code><span class="sig-paren">(</span><em>callback</em>, <em>endmarker=_NOENDMARKER</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway_base.Channel.setcallback" title="Permalink to this definition">¶</a></dt>
<dd><p>set a callback function for receiving items.</p>
<p>All already queued items will immediately trigger the callback.
Afterwards the callback will execute in the receiver thread
for each received data item and calls to <code class="docutils literal"><span class="pre">receive()</span></code> will
raise an error.
If an endmarker is specified the callback will eventually
be called with the endmarker when the channel closes.</p>
</dd></dl>
<dl class="method">
<dt id="execnet.gateway_base.Channel.makefile">
<code class="descclassname">Channel.</code><code class="descname">makefile</code><span class="sig-paren">(</span><em>mode</em>, <em>proxyclose=False</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway_base.Channel.makefile" title="Permalink to this definition">¶</a></dt>
<dd><p>return a file-like object.
mode can be ‘w’ or ‘r’ for writeable/readable files.
if proxyclose is true file.close() will also close the channel.</p>
</dd></dl>
<dl class="method">
<dt id="execnet.gateway_base.Channel.close">
<code class="descclassname">Channel.</code><code class="descname">close</code><span class="sig-paren">(</span><em>error</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway_base.Channel.close" title="Permalink to this definition">¶</a></dt>
<dd><p>close down this channel with an optional error message.
Note that closing of a channel tied to remote_exec happens
automatically at the end of execution and cannot
be done explicitely.</p>
</dd></dl>
<dl class="method">
<dt id="execnet.gateway_base.Channel.waitclose">
<code class="descclassname">Channel.</code><code class="descname">waitclose</code><span class="sig-paren">(</span><em>timeout</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway_base.Channel.waitclose" title="Permalink to this definition">¶</a></dt>
<dd><p>wait until this channel is closed (or the remote side
otherwise signalled that no more data was being sent).
The channel may still hold receiveable items, but not receive
any more after waitclose() has returned. Exceptions from executing
code on the other side are reraised as local channel.RemoteErrors.
EOFError is raised if the reading-connection was prematurely closed,
which often indicates a dying process.
self.TimeoutError is raised after the specified number of seconds
(default is None, i.e. wait indefinitely).</p>
</dd></dl>
<dl class="attribute">
<dt id="execnet.gateway_base.Channel.RemoteError">
<code class="descclassname">Channel.</code><code class="descname">RemoteError</code><em class="property"> = <class 'execnet.gateway_base.RemoteError'></em><a class="headerlink" href="#execnet.gateway_base.Channel.RemoteError" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="execnet.gateway_base.Channel.TimeoutError">
<code class="descclassname">Channel.</code><code class="descname">TimeoutError</code><em class="property"> = <class 'execnet.gateway_base.TimeoutError'></em><a class="headerlink" href="#execnet.gateway_base.Channel.TimeoutError" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</div></blockquote>
</div>
<div class="section" id="grouped-gateways-and-robust-termination">
<span id="group"></span><h2>Grouped Gateways and robust termination<a class="headerlink" href="#grouped-gateways-and-robust-termination" title="Permalink to this headline">¶</a></h2>
<p>All created gateway instances are part of a group. If you
call <code class="docutils literal"><span class="pre">execnet.makegateway</span></code> it actually is forwarded to
the <code class="docutils literal"><span class="pre">execnet.default_group</span></code>. Group objects are container
objects (see <a class="reference internal" href="example/test_group.html"><span class="doc">group examples</span></a>)
and manage the final termination procedure:</p>
<dl class="method">
<dt id="execnet.multi.Group.terminate">
<code class="descclassname">Group.</code><code class="descname">terminate</code><span class="sig-paren">(</span><em>timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.multi.Group.terminate" title="Permalink to this definition">¶</a></dt>
<dd><p>trigger exit of member gateways and wait for termination
of member gateways and associated subprocesses. After waiting
timeout seconds try to to kill local sub processes of popen-
and ssh-gateways. Timeout defaults to None meaning
open-ended waiting and no kill attempts.</p>
</dd></dl>
<p>This method is implicitely called for each gateway group at
process-exit, using a small timeout. This is fine
for interactive sessions or random scripts which
you rather like to error out than hang. If you start many
processes then you often want to call <code class="docutils literal"><span class="pre">group.terminate()</span></code>
yourself and specify a larger or not timeout.</p>
</div>
<div class="section" id="threading-models-gevent-eventlet-thread">
<h2>threading models: gevent, eventlet, thread<a class="headerlink" href="#threading-models-gevent-eventlet-thread" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2: </span>(status: experimental!)</p>
</div>
<p>execnet supports “thread”, “eventlet” and “gevent” as thread models
on each of the two sides. You need to decide which model to use
before you create any gateways:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of threadmodel.py</span>
<span class="kn">import</span> <span class="nn">execnet</span>
<span class="c1"># locally use "eventlet", remotely use "thread" model</span>
<span class="n">execnet</span><span class="o">.</span><span class="n">set_execmodel</span><span class="p">(</span><span class="s2">"eventlet"</span><span class="p">,</span> <span class="s2">"thread"</span><span class="p">)</span>
<span class="n">gw</span> <span class="o">=</span> <span class="n">execnet</span><span class="o">.</span><span class="n">makegateway</span><span class="p">()</span>
<span class="nb">print</span> <span class="p">(</span><span class="n">gw</span><span class="p">)</span>
<span class="nb">print</span> <span class="p">(</span><span class="n">gw</span><span class="o">.</span><span class="n">remote_status</span><span class="p">())</span>
<span class="nb">print</span> <span class="p">(</span><span class="n">gw</span><span class="o">.</span><span class="n">remote_exec</span><span class="p">(</span><span class="s2">"channel.send(1)"</span><span class="p">)</span><span class="o">.</span><span class="n">receive</span><span class="p">())</span>
</pre></div>
</div>
<p>You need to have eventlet installed in your environment and then
you can execute this little test file:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ python threadmodel.py
<Gateway id='gw0' receive-live, eventlet model, 0 active channels>
<RInfo 'numchannels=0, numexecuting=0, execmodel=thread'>
1
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">With python3 you can (as of December 2013) only use the thread model
because neither eventlet-0.14.0 nor gevent-1.0 support Python3.
When they start to support Python3, execnet will probably just work
because it is itself Python3 compatible.</p>
</div>
<div class="section" id="how-to-execute-in-the-main-thread">
<h3>How to execute in the main thread<a class="headerlink" href="#how-to-execute-in-the-main-thread" title="Permalink to this headline">¶</a></h3>
<p>When the remote side of a gateway uses the ‘thread’ model, execution
will preferably run in the main thread. This allows GUI loops
or other code to behave correctly. If you, however, start multiple
executions concurrently, they will run in non-main threads.</p>
</div>
</div>
<div class="section" id="remote-status-get-low-level-execution-info">
<h2>remote_status: get low-level execution info<a class="headerlink" href="#remote-status-get-low-level-execution-info" title="Permalink to this headline">¶</a></h2>
<p>All gateways offer a simple method to obtain some status
information from the remote side.</p>
<dl class="method">
<dt id="execnet.gateway.Gateway.remote_status">
<code class="descclassname">Gateway.</code><code class="descname">remote_status</code><span class="sig-paren">(</span><em>source</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.gateway.Gateway.remote_status" title="Permalink to this definition">¶</a></dt>
<dd><p>return information object about remote execution status.</p>
</dd></dl>
<p>Calling this method tells you e.g. how many execution
tasks are queued, how many are executing and how many
channels are active.</p>
</div>
<div class="section" id="rsync-synchronise-filesystem-with-remote">
<h2>rsync: synchronise filesystem with remote<a class="headerlink" href="#rsync-synchronise-filesystem-with-remote" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">execnet</span></code> implements a simple efficient rsyncing protocol.
Here is a basic example for using RSync:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rsync</span> <span class="o">=</span> <span class="n">execnet</span><span class="o">.</span><span class="n">RSync</span><span class="p">(</span><span class="s1">'/tmp/source'</span><span class="p">)</span>
<span class="n">gw</span> <span class="o">=</span> <span class="n">execnet</span><span class="o">.</span><span class="n">makegateway</span><span class="p">()</span>
<span class="n">rsync</span><span class="o">.</span><span class="n">add_target</span><span class="p">(</span><span class="n">gw</span><span class="p">,</span> <span class="s1">'/tmp/dest'</span><span class="p">)</span>
<span class="n">rsync</span><span class="o">.</span><span class="n">send</span><span class="p">()</span>
</pre></div>
</div>
<p>And here is API info about the RSync class.</p>
<dl class="class">
<dt id="execnet.RSync">
<em class="property">class </em><code class="descclassname">execnet.</code><code class="descname">RSync</code><span class="sig-paren">(</span><em>sourcedir</em>, <em>callback=None</em>, <em>verbose=True</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.RSync" title="Permalink to this definition">¶</a></dt>
<dd><p>This class allows to send a directory structure (recursively)
to one or multiple remote filesystems.</p>
<p>There is limited support for symlinks, which means that symlinks
pointing to the sourcetree will be send “as is” while external
symlinks will be just copied (regardless of existance of such
a path on remote side).</p>
<dl class="method">
<dt id="execnet.RSync.add_target">
<code class="descname">add_target</code><span class="sig-paren">(</span><em>gateway</em>, <em>destdir</em>, <em>finishedcallback=None</em>, <em>**options</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.RSync.add_target" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds a remote target specified via a gateway
and a remote destination directory.</p>
</dd></dl>
<dl class="method">
<dt id="execnet.RSync.send">
<code class="descname">send</code><span class="sig-paren">(</span><em>raises=True</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.RSync.send" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a sourcedir to all added targets. Flag indicates
whether to raise an error or return in case of lack of
targets</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="debugging-execnet">
<h2>Debugging execnet<a class="headerlink" href="#debugging-execnet" title="Permalink to this headline">¶</a></h2>
<p>By setting the environment variable <code class="docutils literal"><span class="pre">EXECNET_DEBUG</span></code> you can
configure a tracing mechanism:</p>
<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" colspan="2">EXECNET_DEBUG=1:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">write per-process trace-files to <code class="docutils literal"><span class="pre">execnet-debug-PID</span></code></td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">EXECNET_DEUBG=2:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">perform tracing to stderr (popen-gateway slaves will send this to their instantiator)</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="cross-interpreter-serialization-of-python-objects">
<span id="dumps-loads-api"></span><span id="dumps-loads"></span><h2>cross-interpreter serialization of python objects<a class="headerlink" href="#cross-interpreter-serialization-of-python-objects" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.1.</span></p>
</div>
<p>Execnet exposes a function pair which you can safely use to
store and load values from different Python interpreters
(e.g. Python2 and Python3, PyPy and Jython). Here is
a basic example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">execnet</span>
<span class="gp">>>> </span><span class="n">dump</span> <span class="o">=</span> <span class="n">execnet</span><span class="o">.</span><span class="n">dumps</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">execnet</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">dump</span><span class="p">)</span>
<span class="go">[1,2,3]</span>
</pre></div>
</div>
<p>For more examples see <a class="reference internal" href="example/hybridpython.html#dumps-loads-examples"><span class="std std-ref">Dumping and loading values across interpreter versions</span></a>.</p>
<dl class="function">
<dt id="execnet.dumps">
<code class="descclassname">execnet.</code><code class="descname">dumps</code><span class="sig-paren">(</span><em>spec</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.dumps" title="Permalink to this definition">¶</a></dt>
<dd><p>return a serialized bytestring of the given obj.</p>
<p>The obj and all contained objects must be of a builtin
python type (so nested dicts, sets, etc. are all ok but
not user-level instances).</p>
</dd></dl>
<dl class="function">
<dt id="execnet.loads">
<code class="descclassname">execnet.</code><code class="descname">loads</code><span class="sig-paren">(</span><em>spec</em><span class="sig-paren">)</span><a class="headerlink" href="#execnet.loads" title="Permalink to this definition">¶</a></dt>
<dd><p>return the object as deserialized from the given bytestring.</p>
<dl class="docutils">
<dt>py2str_as_py3str: if true then string (str) objects previously</dt>
<dd>dumped on Python2 will be loaded as Python3
strings which really are text objects.</dd>
<dt>py3str_as_py2str: if true then string (str) objects previously</dt>
<dd>dumped on Python3 will be loaded as Python2
strings instead of unicode objects.</dd>
</dl>
<p>if the bytestring was dumped with an incompatible protocol
version or if the bytestring is corrupted, the
<code class="docutils literal"><span class="pre">execnet.DataFormatError</span></code> will be raised.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="changelog.html" title="execnet CHANGELOG"
>next</a> |</li>
<li class="right" >
<a href="example/test_ssh_fileserver.html" title="Receive file contents from remote SSH account"
>previous</a> |</li>
<!-- <a href="index.html">index</a>»</li> -->
<li class="nav-item nav-item-1"><a href="install.html" >Info in a nutshell</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2017, holger krekel and others.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
</div>
</body>
</html>
|