| 1 |
.. _ref-to-remote-control: |
| 2 |
|
| 3 |
Remote controlling (XML-RPC) |
| 4 |
============================ |
| 5 |
|
| 6 |
.. meta:: |
| 7 |
:description: How to remote control DataLab using XML-RPC |
| 8 |
:keywords: DataLab, remote control, XML-RPC, Python, IDE, Spyder, Jupyter, third-party application, signal, image, HDF5, calculation, processor |
| 9 |
|
| 10 |
.. note:: |
| 11 |
|
| 12 |
**For new projects, we recommend using the** :ref:`Web API <ref-to-webapi>` **instead |
| 13 |
of XML-RPC.** The Web API provides better performance for large arrays, token-based |
| 14 |
authentication, and compatibility with browser environments (WASM/Pyodide). |
| 15 |
|
| 16 |
XML-RPC remains available for backward compatibility with existing integrations. |
| 17 |
|
| 18 |
DataLab may be controlled remotely using the `XML-RPC`_ protocol which is |
| 19 |
natively supported by Python (and many other languages). Remote controlling |
| 20 |
allows to access DataLab main features from a separate process. |
| 21 |
|
| 22 |
.. note:: |
| 23 |
|
| 24 |
If you are looking for a lighweight alternative solution to remote control |
| 25 |
DataLab (i.e. without having to install the whole DataLab package and its |
| 26 |
dependencies on your environment), you may use the `Sigima`_ package that |
| 27 |
provides a simple remote client for DataLab. To install it, just run: |
| 28 |
``pip install sigima``. |
| 29 |
|
| 30 |
.. _Sigima: https://github.com/DataLab-Platform/Sigima |
| 31 |
|
| 32 |
From an IDE |
| 33 |
^^^^^^^^^^^ |
| 34 |
|
| 35 |
DataLab may be controlled remotely from an IDE (e.g. `Spyder`_ or any other |
| 36 |
IDE, or even a Jupyter Notebook) that runs a Python script. It allows to |
| 37 |
connect to a running DataLab instance, adds a signal and an image, and then |
| 38 |
runs calculations. This feature is exposed by the `RemoteProxy` class that |
| 39 |
is provided in module ``datalab.control.proxy``. |
| 40 |
|
| 41 |
From a third-party application |
| 42 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 43 |
|
| 44 |
DataLab may also be controlled remotely from a third-party application, for the |
| 45 |
same purpose. |
| 46 |
|
| 47 |
If the third-party application is written in Python 3, it may directly use the |
| 48 |
`RemoteProxy` class as mentioned above. From another language, it is also |
| 49 |
achievable, but it requires to implement a XML-RPC client in this language |
| 50 |
using the same methods of proxy server as in the `RemoteProxy` class. |
| 51 |
|
| 52 |
Data (signals and images) may also be exchanged between DataLab and the remote |
| 53 |
client application, in both directions. |
| 54 |
|
| 55 |
The remote client application may be written in any language that supports |
| 56 |
XML-RPC. For example, it is possible to write a remote client application in |
| 57 |
Python, Java, C++, C#, etc. The remote client application may be a graphical |
| 58 |
application or a command line application. |
| 59 |
|
| 60 |
The remote client application may be run on the same computer as DataLab or on |
| 61 |
a different computer. In the latter case, the remote client application must |
| 62 |
know the IP address of the computer running DataLab. |
| 63 |
|
| 64 |
The remote client application may be run before or after DataLab. In the latter |
| 65 |
case, the remote client application must try to connect to DataLab until it |
| 66 |
succeeds. |
| 67 |
|
| 68 |
Supported features |
| 69 |
^^^^^^^^^^^^^^^^^^ |
| 70 |
|
| 71 |
Supported features are the following: |
| 72 |
|
| 73 |
- Switch to signal or image panel |
| 74 |
- Remove all signals and images |
| 75 |
- Save current session to a HDF5 file |
| 76 |
- Open HDF5 files into current session |
| 77 |
- Browse HDF5 file |
| 78 |
- Open a signal or an image from file |
| 79 |
- Add a signal |
| 80 |
- Add an image |
| 81 |
- Get object list |
| 82 |
- Run calculation with parameters |
| 83 |
|
| 84 |
.. note:: |
| 85 |
|
| 86 |
The signal and image objects are described on this section: :ref:`ref-to-model`. |
| 87 |
|
| 88 |
Some examples are provided to help implementing such a communication |
| 89 |
between your application and DataLab: |
| 90 |
|
| 91 |
- See module: ``datalab.tests.features.control.remoteclient_app_test`` |
| 92 |
- See module: ``datalab.tests.features.control.remoteclient_unit`` |
| 93 |
|
| 94 |
.. figure:: /images/shots/remote_control_test.png |
| 95 |
|
| 96 |
Screenshot of remote client application test (``datalab.tests.features.control.remoteclient_app_test``) |
| 97 |
|
| 98 |
Examples |
| 99 |
^^^^^^^^ |
| 100 |
|
| 101 |
When using Python 3, you may directly use the `RemoteProxy` class as in |
| 102 |
examples cited above or below. |
| 103 |
|
| 104 |
Here is an example in Python 3 of a script that connects to a running DataLab |
| 105 |
instance, adds a signal and an image, and then runs calculations (the cell |
| 106 |
structure of the script make it convenient to be used in `Spyder`_ IDE): |
| 107 |
|
| 108 |
.. literalinclude:: ../../remote_example.py |
| 109 |
|
| 110 |
Here is a Python 2.7 reimplementation of this class: |
| 111 |
|
| 112 |
.. literalinclude:: ../../remotecontrol_py27.py |
| 113 |
|
| 114 |
Connection dialog |
| 115 |
^^^^^^^^^^^^^^^^^ |
| 116 |
|
| 117 |
The DataLab package also provides a connection dialog that may be used |
| 118 |
to connect to a running DataLab instance. It is exposed by the |
| 119 |
:py:class:`datalab.widgets.connection.ConnectionDialog` class. |
| 120 |
|
| 121 |
.. figure:: ../../images/shots/connect_dialog.png |
| 122 |
|
| 123 |
Screenshot of connection dialog (``datalab.widgets.connection.ConnectionDialog``) |
| 124 |
|
| 125 |
Example of use: |
| 126 |
|
| 127 |
.. literalinclude:: ../../../datalab/tests/features/control/connect_dialog.py |
| 128 |
|
| 129 |
Public API |
| 130 |
^^^^^^^^^^ |
| 131 |
|
| 132 |
.. autoclass:: datalab.control.remote.RemoteClient |
| 133 |
:inherited-members: |
| 134 |
|
| 135 |
.. _XML-RPC: https://docs.python.org/3/library/xmlrpc.html |
| 136 |
|
| 137 |
.. _Spyder: https://www.spyder-ide.org/ |