/usr/share/doc/python-execnet/html/_sources/basics.txt is in python-execnet 1.0.9-0.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 | ==============================================================================
API in a nutshell
==============================================================================
execnet ad-hoc instantiates local and remote Python interpreters.
Each interpreter is accessible through a **Gateway** which manages
code and data communication. **Channels** allow to exchange
data between the local and the remote end. **Groups**
help to manage creation and termination of sub interpreters.
.. image:: _static/basic1.png
Gateways: bootstrapping Python interpreters
===================================================
.. currentmodule:: execnet
All Gateways are instantiated via a call to ``makegateway()``
passing it a gateway specification or URL.
.. _xspec:
.. autofunction:: execnet.makegateway(spec)
Here is an example which instantiates a simple Python subprocess::
>>> gateway = execnet.makegateway()
gateways allow to `remote execute code`_ and
`exchange data`_ bidirectionally.
examples for valid gateway specifications
-------------------------------------------
* ``ssh=wyvern//python=python2.4//chdir=mycache`` specifies a Python2.4
interpreter on the host ``wyvern``. The remote process will have
``mycache`` as its current working directory.
* ``popen//python=2.5//nice=20`` specification of a python2.5
subprocess; running with the lowest CPU priority ("nice" level).
By default current dir will be the current dir of the instantiator.
* ``popen//env:NAME=value`` specifies a subprocess that uses the
same interpreter as the one it is initiated from and additionally
remotely sets an environment variable ``NAME`` to ``value``.
* ``socket=192.168.1.4:8888`` specifies a Python Socket server
process that listens on 192.168.1.4:8888``
.. _`remote execute code`:
remote_exec: execute source code remotely
===================================================
.. currentmodule:: execnet.gateway
All gateways offer a simple method to execute source code
in the connected interpreter:
.. automethod:: Gateway.remote_exec(source)
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. ``remote_exec`` returns
a channel object whose symmetric counterpart channel
is available to the remotely executing source.
.. method:: Gateway.reconfigure([py2str_as_py3str=True, py3str_as_py2str=False])
reconfigures the string-coercion behaviour of the gateway
.. _`Channel`:
.. _`channel-api`:
.. _`exchange data`:
Channels: exchanging data with remote code
=======================================================
.. currentmodule:: execnet.gateway_base
A channel object allows to send and receive data between
two asynchronously running programs.
.. automethod:: Channel.send(item)
.. automethod:: Channel.receive(timeout)
.. automethod:: Channel.setcallback(callback, endmarker=_NOENDMARKER)
.. automethod:: Channel.makefile(mode, proxyclose=False)
.. automethod:: Channel.close(error)
.. automethod:: Channel.waitclose(timeout)
.. autoattribute:: Channel.RemoteError
.. autoattribute:: Channel.TimeoutError
.. _Group:
Grouped Gateways and robust termination
===============================================
.. currentmodule:: execnet.multi
All created gateway instances are part of a group. If you
call ``execnet.makegateway`` it actually is forwarded to
the ``execnet.default_group``. Group objects are container
objects (see :doc:`group examples <example/test_group>`)
and manage the final termination procedure:
.. automethod:: Group.terminate(timeout=None)
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 ``group.terminate()``
yourself and specify a larger or not timeout.
remote_status: get low-level execution info
===================================================
.. currentmodule:: execnet.gateway
All gateways offer a simple method to obtain some status
information from the remote side.
.. automethod:: Gateway.remote_status(source)
Calling this method tells you e.g. how many execution
tasks are queued, how many are executing and how many
channels are active. Note that ``remote_status()``
works even if the other side is busy executing code
and can thus be used to query status in a non-blocking manner.
rsync: synchronise filesystem with remote
===============================================================
.. currentmodule:: execnet
``execnet`` implements a simple efficient rsyncing protocol.
Here is a basic example for using RSync::
rsync = execnet.RSync('/tmp/source')
gw = execnet.makegateway()
rsync.add_target(gw, '/tmp/dest')
rsync.send()
And here is API info about the RSync class.
.. autoclass:: RSync
:members: add_target,send
Debugging execnet
===============================================================
By setting the environment variable ``EXECNET_DEBUG`` you can
configure a tracing mechanism:
:EXECNET_DEBUG=1: write per-process trace-files to ``execnet-debug-PID``
:EXECNET_DEUBG=2: perform tracing to stderr (popen-gateway slaves will send this to their instantiator)
|