Debian Codegraph @

doc/features/advanced/remote.rst

raw
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/