Python Remote Server for Robot Framework
========================================
`Robot Framework`_ remote servers allow hosting test libraries on different
processes or machines than Robot Framework itself is running on. This project
implements a generic remote server using the Python_ programming language.
See the `remote library interface documentation`_ for more information about
the remote interface in general as well as for a list of remote server
implementations in other programming languages.
This project is hosted on GitHub_ and downloads are available on PyPI_.
.. _Robot Framework: http://robotframework.org
.. _remote library interface documentation: https://github.com/robotframework/RemoteInterface
.. _GitHub: https://github.com/robotframework/PythonRemoteServer
.. _PyPI: http://pypi.python.org/pypi/robotremoteserver
.. contents::
:local:
Supported Python versions
-------------------------
This remote server is implemented with Python_ and supports also Jython_ (JVM),
IronPython_ (.NET) and PyPy_. Remote server version 1.1 supports Python 2.6,
2.7 and 3.3-3.9. Remote server version 1.1.1 supports Python 3.10 and 3.11
as well.
.. _Python: http://python.org
.. _Jython: http://jython.org
.. _IronPython: http://ironpython.net
.. _PyPy: http://pypy.org/
Supported library APIs
----------------------
Starting from the remote server version 1.1, Robot Framework's `static,
hybrid and dynamic library APIs`__ are all supported. This includes setting
custom name and tags for keywords using the `robot.api.deco.keyword`__.
Earlier remote server versions support only the static and hybrid
APIs and do not support the keyword decorator at all.
For most parts these APIs work exactly like when using with Robot Framework
normally. The main limitation is that logging using ``robot.api.logger`` or
Python's ``logging`` module `is currently not supported`__.
__ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-test-libraries
__ http://robot-framework.readthedocs.io/en/latest/autodoc/robot.api.html#robot.api.deco.keyword
__ https://github.com/robotframework/PythonRemoteServer/issues/26
Installation
------------
The easiest installation approach is using `pip`_::
pip install robotremoteserver
Alternatively you can download the source distribution from PyPI_, extract it
and install the remote server using::
python setup.py install
.. _`pip`: http://www.pip-installer.org
Remote server configuration
---------------------------
The remote server is implemented as a class ``RobotRemoteServer`` and it
accepts the following configuration parameters when it is initialized:
===================== ================= ========================================
Argument Default Explanation
===================== ================= ========================================
``library`` Test library instance or module to host. Mandatory argument.
``host`` ``'127.0.0.1'`` Address to listen. Use ``'0.0.0.0'`` to listen to all available IPv4 interfaces.
``port`` ``8270`` Port to listen. Use ``0`` to select a free port automatically. Can be given as an integer or as a string. The default port ``8270`` is `registered by IANA`__ for remote server usage.
``port_file`` ``None`` File to write the port that is used. ``None`` (default) means no such file is written.
``allow_stop`` ``'DEPRECATED'`` Deprecated since version 1.1. Use ``allow_remote_stop`` instead.
``serve`` ``True`` If ``True``, start the server automatically and wait for it to be stopped. If ``False``, server can be started using the ``serve`` method. New in version 1.1.
``allow_remote_stop`` ``True`` Allow/disallow stopping the server remotely using ``Stop Remote Server`` keyword and ``stop_remote_server`` XML-RPC method. New in version 1.1.
===================== ================= ========================================
__ https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=8270
Starting remote server
----------------------
The remote server can be started simply by creating an instance of the server
and passing a test library instance or module to it:
.. sourcecode:: python
from robotremoteserver import RobotRemoteServer
from mylibrary import MyLibrary
RobotRemoteServer(MyLibrary())
By default the server listens to address 127.0.0.1 and port 8270. As `discussed
above`__, the remote server accepts various configuration parameters. Some of
them are used by this example:
__ `Remote server configuration`_
.. sourcecode:: python
from robotremoteserver import RobotRemoteServer
from examplelibrary import ExampleLibrary
RobotRemoteServer(ExampleLibrary(), host='10.0.0.42', port=0,
port_file='/tmp/remote-port.txt')
Starting from version 1.1, the server can be initialized without starting it by
using the argument ``serve=False``. The server can then started afterwards by
calling its ``serve`` method explicitly. This example is functionally
equivalent to the example above:
.. sourcecode:: python
from robotremoteserver import RobotRemoteServer
from examplelibrary import ExampleLibrary
server = RobotRemoteServer(ExampleLibrary(), host='10.0.0.42', port=0,
port_file='/tmp/remote-port.txt', serve=False)
server.serve()
Starting server on background
-----------------------------
The main benefit of separately initializing and starting the server is that
it makes it easier to start the server in a background thread. Servers started
in a thread work exactly like servers running in the main tread except that
`stopping the server`__ gracefully using ``Ctrl-C`` or signals is not
supported automatically. Users must thus register signal handlers separately
if needed.
Also this following example is functionally nearly equivalent to the earlier
examples except. The main difference is that not all same signals are handled.
.. sourcecode:: python
import signal
import threading
from examplelibrary import ExampleLibrary
from robotremoteserver import RobotRemoteServer
server = RobotRemoteServer(ExampleLibrary(), port=0, serve=False)
signal.signal(signal.SIGINT, lambda signum, frame: server.stop())
server_thread = threading.Thread(target=server.serve)
server_thread.start()
while server_thread.is_alive():
server_thread.join(0.1)
__ `Stopping remote server`_
Getting active server port
--------------------------
If the server uses the default port ``8270`` or some other port is given
explicitly when `configuring the server`__, you obviously know which port
to use when connecting the server. When using the port ``0``, the server
selects a free port automatically, but there are various ways how to find
out the actual port:
- Address and port that are used are printed into the console where the server
is started.
- If ``port_file`` argument is used, the server writes the port into the
specified file where other tools can easily read it. Starting from the
remote server version 1.1, the server removes the port file automatically
when the server is stopped.
- Starting from the version 1.1, the server has ``activate`` method that can
be called to activate the server without starting it. This method returns
the port that the server binds and also sets it available via the attributes
discussed below.
- A started or actived server instance has ``server_address`` attribute that
contains the address and the port as a tuple. Starting from the version 1.1
there is also ``server_port`` attribute that contains just the port as
an integer.
__ `Remote server configuration`__
Stopping remote server
----------------------
The remote server can be gracefully stopped using several different methods:
- Hitting ``Ctrl-C`` on the console where the server is running. Not supported
automatically if the server is `started on a background thread`__.
- Sending the process ``SIGINT``, ``SIGTERM``, or ``SIGHUP`` signal. Does not
work on Windows and not supported if the server is started on a background
thread.
- Using the``Stop Remote Server`` keyword. Can be disabled by using
``allow_remote_stop=False`` when `initializing the server`__.
- Using the ``stop_remote_server`` function in the XML-RPC interface.
Can be disabled with the ``allow_remote_stop=False`` initialization parameter.
- Running ``python -m robotremoteserver stop [uri]`` which uses the
aforementioned ``stop_remote_server`` XML-RPC function internally.
Can be disabled with the ``allow_remote_stop=False`` initialization parameter.
- Using the ``stop_remote_server`` function provided by the
``robotremoteserver`` module similarly as when `testing is server running`_.
Uses the ``stop_remote_server`` XML-RPC function internally and
can be disabled with the ``allow_remote_stop=False`` initialization parameter.
- Calling the ``stop`` method of the running server instance. Mainly useful when
`running the server on background`__.
__ `Starting server on background`_
__ `Remote server configuration`_
__ `Starting server on background`_
Testing is server running
-------------------------
Starting from the version 1.0.1, the ``robotremoteserver`` module supports
testing is a remote server running. This can be accomplished by running
the module as a script with ``test`` argument and an optional URI::
$ python -m robotremoteserver test
Remote server running at http://127.0.0.1:8270.
$ python -m robotremoteserver test http://10.0.0.42:57347
No remote server running at http://10.0.0.42:57347.
Starting from the version 1.1, the ``robotremoteserver`` module contains
function ``test_remote_server`` that can be used programmatically:
.. sourcecode:: python
from robotremoteserver import test_remote_server
if test_remote_server('http://localhost:8270'):
print('Remote server running!')
The ``robotremoteserver`` module can be also used to stop a remote server by
using ``stop`` argument on the command line or by using the
``stop_remote_server`` function programmatically. Testing and stopping should
work also with other Robot Framework remote server implementations.
Listing keywords and viewing documentation
------------------------------------------
Using the built-in Libdoc__ tool you can list the keywords available on the server::
$ python -m robot.libdoc Remote::http://127.0.0.1:8270 list
Count Items In Directory
Stop Remote Server
Strings Should Be Equal
It is also possible to show the documentation on the command line by using
argument ``show``. HTML documentation can be created by providing name of
an output file::
$ python -m robot.libdoc Remote::http://127.0.0.1:8270 MyLibrary.html
/path/to/MyLibrary.html
__ http://robotframework.org/robotframework/#built-in-tools
Example
-------
The remote server project contains an example__ that can be studied and also
executed once the library is installed. You can get the example by cloning
the project on GitHub_, and it is also included in the source distribution
available on PyPI_.
__ https://github.com/robotframework/PythonRemoteServer/tree/master/example
Raw data
{
"_id": null,
"home_page": "https://github.com/robotframework/PythonRemoteServer",
"name": "robotremoteserver",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "robotframework testing testautomation remoteinterface",
"author": "Pekka Kl\u00e4rck and contributors",
"author_email": "robotframework@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ab/7f/ca08c86a23bf4ea260ba640855db95e6daf044942e2e51bda0d59ed81573/robotremoteserver-1.1.1.tar.gz",
"platform": "any",
"description": "Python Remote Server for Robot Framework\n========================================\n\n`Robot Framework`_ remote servers allow hosting test libraries on different\nprocesses or machines than Robot Framework itself is running on. This project\nimplements a generic remote server using the Python_ programming language.\nSee the `remote library interface documentation`_ for more information about\nthe remote interface in general as well as for a list of remote server\nimplementations in other programming languages.\n\nThis project is hosted on GitHub_ and downloads are available on PyPI_.\n\n.. _Robot Framework: http://robotframework.org\n.. _remote library interface documentation: https://github.com/robotframework/RemoteInterface\n.. _GitHub: https://github.com/robotframework/PythonRemoteServer\n.. _PyPI: http://pypi.python.org/pypi/robotremoteserver\n\n.. contents::\n :local:\n\nSupported Python versions\n-------------------------\n\nThis remote server is implemented with Python_ and supports also Jython_ (JVM),\nIronPython_ (.NET) and PyPy_. Remote server version 1.1 supports Python 2.6,\n2.7 and 3.3-3.9. Remote server version 1.1.1 supports Python 3.10 and 3.11\nas well.\n\n.. _Python: http://python.org\n.. _Jython: http://jython.org\n.. _IronPython: http://ironpython.net\n.. _PyPy: http://pypy.org/\n\nSupported library APIs\n----------------------\n\nStarting from the remote server version 1.1, Robot Framework's `static,\nhybrid and dynamic library APIs`__ are all supported. This includes setting\ncustom name and tags for keywords using the `robot.api.deco.keyword`__.\nEarlier remote server versions support only the static and hybrid\nAPIs and do not support the keyword decorator at all.\n\nFor most parts these APIs work exactly like when using with Robot Framework\nnormally. The main limitation is that logging using ``robot.api.logger`` or\nPython's ``logging`` module `is currently not supported`__.\n\n__ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-test-libraries\n__ http://robot-framework.readthedocs.io/en/latest/autodoc/robot.api.html#robot.api.deco.keyword\n__ https://github.com/robotframework/PythonRemoteServer/issues/26\n\nInstallation\n------------\n\nThe easiest installation approach is using `pip`_::\n\n pip install robotremoteserver\n\nAlternatively you can download the source distribution from PyPI_, extract it\nand install the remote server using::\n\n python setup.py install\n\n.. _`pip`: http://www.pip-installer.org\n\nRemote server configuration\n---------------------------\n\nThe remote server is implemented as a class ``RobotRemoteServer`` and it\naccepts the following configuration parameters when it is initialized:\n\n ===================== ================= ========================================\n Argument Default Explanation\n ===================== ================= ========================================\n ``library`` Test library instance or module to host. Mandatory argument.\n ``host`` ``'127.0.0.1'`` Address to listen. Use ``'0.0.0.0'`` to listen to all available IPv4 interfaces.\n ``port`` ``8270`` Port to listen. Use ``0`` to select a free port automatically. Can be given as an integer or as a string. The default port ``8270`` is `registered by IANA`__ for remote server usage.\n ``port_file`` ``None`` File to write the port that is used. ``None`` (default) means no such file is written.\n ``allow_stop`` ``'DEPRECATED'`` Deprecated since version 1.1. Use ``allow_remote_stop`` instead.\n ``serve`` ``True`` If ``True``, start the server automatically and wait for it to be stopped. If ``False``, server can be started using the ``serve`` method. New in version 1.1.\n ``allow_remote_stop`` ``True`` Allow/disallow stopping the server remotely using ``Stop Remote Server`` keyword and ``stop_remote_server`` XML-RPC method. New in version 1.1.\n ===================== ================= ========================================\n\n__ https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=8270\n\nStarting remote server\n----------------------\n\nThe remote server can be started simply by creating an instance of the server\nand passing a test library instance or module to it:\n\n.. sourcecode:: python\n\n from robotremoteserver import RobotRemoteServer\n from mylibrary import MyLibrary\n\n RobotRemoteServer(MyLibrary())\n\nBy default the server listens to address 127.0.0.1 and port 8270. As `discussed\nabove`__, the remote server accepts various configuration parameters. Some of\nthem are used by this example:\n\n__ `Remote server configuration`_\n\n.. sourcecode:: python\n\n from robotremoteserver import RobotRemoteServer\n from examplelibrary import ExampleLibrary\n\n RobotRemoteServer(ExampleLibrary(), host='10.0.0.42', port=0,\n port_file='/tmp/remote-port.txt')\n\nStarting from version 1.1, the server can be initialized without starting it by\nusing the argument ``serve=False``. The server can then started afterwards by\ncalling its ``serve`` method explicitly. This example is functionally\nequivalent to the example above:\n\n.. sourcecode:: python\n\n from robotremoteserver import RobotRemoteServer\n from examplelibrary import ExampleLibrary\n\n server = RobotRemoteServer(ExampleLibrary(), host='10.0.0.42', port=0,\n port_file='/tmp/remote-port.txt', serve=False)\n server.serve()\n\nStarting server on background\n-----------------------------\n\nThe main benefit of separately initializing and starting the server is that\nit makes it easier to start the server in a background thread. Servers started\nin a thread work exactly like servers running in the main tread except that\n`stopping the server`__ gracefully using ``Ctrl-C`` or signals is not\nsupported automatically. Users must thus register signal handlers separately\nif needed.\n\nAlso this following example is functionally nearly equivalent to the earlier\nexamples except. The main difference is that not all same signals are handled.\n\n.. sourcecode:: python\n\n import signal\n import threading\n from examplelibrary import ExampleLibrary\n from robotremoteserver import RobotRemoteServer\n\n server = RobotRemoteServer(ExampleLibrary(), port=0, serve=False)\n signal.signal(signal.SIGINT, lambda signum, frame: server.stop())\n server_thread = threading.Thread(target=server.serve)\n server_thread.start()\n while server_thread.is_alive():\n server_thread.join(0.1)\n\n__ `Stopping remote server`_\n\nGetting active server port\n--------------------------\n\nIf the server uses the default port ``8270`` or some other port is given\nexplicitly when `configuring the server`__, you obviously know which port\nto use when connecting the server. When using the port ``0``, the server\nselects a free port automatically, but there are various ways how to find\nout the actual port:\n\n- Address and port that are used are printed into the console where the server\n is started.\n\n- If ``port_file`` argument is used, the server writes the port into the\n specified file where other tools can easily read it. Starting from the\n remote server version 1.1, the server removes the port file automatically\n when the server is stopped.\n\n- Starting from the version 1.1, the server has ``activate`` method that can\n be called to activate the server without starting it. This method returns\n the port that the server binds and also sets it available via the attributes\n discussed below.\n\n- A started or actived server instance has ``server_address`` attribute that\n contains the address and the port as a tuple. Starting from the version 1.1\n there is also ``server_port`` attribute that contains just the port as\n an integer.\n\n__ `Remote server configuration`__\n\nStopping remote server\n----------------------\n\nThe remote server can be gracefully stopped using several different methods:\n\n- Hitting ``Ctrl-C`` on the console where the server is running. Not supported\n automatically if the server is `started on a background thread`__.\n\n- Sending the process ``SIGINT``, ``SIGTERM``, or ``SIGHUP`` signal. Does not\n work on Windows and not supported if the server is started on a background\n thread.\n\n- Using the``Stop Remote Server`` keyword. Can be disabled by using\n ``allow_remote_stop=False`` when `initializing the server`__.\n\n- Using the ``stop_remote_server`` function in the XML-RPC interface.\n Can be disabled with the ``allow_remote_stop=False`` initialization parameter.\n\n- Running ``python -m robotremoteserver stop [uri]`` which uses the\n aforementioned ``stop_remote_server`` XML-RPC function internally.\n Can be disabled with the ``allow_remote_stop=False`` initialization parameter.\n\n- Using the ``stop_remote_server`` function provided by the\n ``robotremoteserver`` module similarly as when `testing is server running`_.\n Uses the ``stop_remote_server`` XML-RPC function internally and\n can be disabled with the ``allow_remote_stop=False`` initialization parameter.\n\n- Calling the ``stop`` method of the running server instance. Mainly useful when\n `running the server on background`__.\n\n__ `Starting server on background`_\n__ `Remote server configuration`_\n__ `Starting server on background`_\n\nTesting is server running\n-------------------------\n\nStarting from the version 1.0.1, the ``robotremoteserver`` module supports\ntesting is a remote server running. This can be accomplished by running\nthe module as a script with ``test`` argument and an optional URI::\n\n $ python -m robotremoteserver test\n Remote server running at http://127.0.0.1:8270.\n $ python -m robotremoteserver test http://10.0.0.42:57347\n No remote server running at http://10.0.0.42:57347.\n\nStarting from the version 1.1, the ``robotremoteserver`` module contains\nfunction ``test_remote_server`` that can be used programmatically:\n\n.. sourcecode:: python\n\n from robotremoteserver import test_remote_server\n\n if test_remote_server('http://localhost:8270'):\n print('Remote server running!')\n\nThe ``robotremoteserver`` module can be also used to stop a remote server by\nusing ``stop`` argument on the command line or by using the\n``stop_remote_server`` function programmatically. Testing and stopping should\nwork also with other Robot Framework remote server implementations.\n\nListing keywords and viewing documentation\n------------------------------------------\n\nUsing the built-in Libdoc__ tool you can list the keywords available on the server::\n\n $ python -m robot.libdoc Remote::http://127.0.0.1:8270 list\n Count Items In Directory\n Stop Remote Server\n Strings Should Be Equal\n\nIt is also possible to show the documentation on the command line by using\nargument ``show``. HTML documentation can be created by providing name of\nan output file::\n\n $ python -m robot.libdoc Remote::http://127.0.0.1:8270 MyLibrary.html\n /path/to/MyLibrary.html\n\n__ http://robotframework.org/robotframework/#built-in-tools\n\nExample\n-------\n\nThe remote server project contains an example__ that can be studied and also\nexecuted once the library is installed. You can get the example by cloning\nthe project on GitHub_, and it is also included in the source distribution\navailable on PyPI_.\n\n__ https://github.com/robotframework/PythonRemoteServer/tree/master/example\n\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Robot Framework remote server implemented with Python",
"version": "1.1.1",
"split_keywords": [
"robotframework",
"testing",
"testautomation",
"remoteinterface"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "cbdc4782d53875957485e274c0438f19",
"sha256": "a344051d4e2bf435e0970365d4051cda13100395e072ff88cb740f9c363206bf"
},
"downloads": -1,
"filename": "robotremoteserver-1.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "cbdc4782d53875957485e274c0438f19",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 15218,
"upload_time": "2022-12-23T13:44:40",
"upload_time_iso_8601": "2022-12-23T13:44:40.855693Z",
"url": "https://files.pythonhosted.org/packages/ce/77/532abf69fe4107cf0dea47c84816cb4ed65e15f376cee93690fe89b0ec78/robotremoteserver-1.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "dda055599e8cdf540370e3d21b2f7f11",
"sha256": "378c5a93275f1277369426aba3c9cdfafbed75f9e926ed7ba54c92c948b29411"
},
"downloads": -1,
"filename": "robotremoteserver-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "dda055599e8cdf540370e3d21b2f7f11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20205,
"upload_time": "2022-12-23T13:44:42",
"upload_time_iso_8601": "2022-12-23T13:44:42.466489Z",
"url": "https://files.pythonhosted.org/packages/ab/7f/ca08c86a23bf4ea260ba640855db95e6daf044942e2e51bda0d59ed81573/robotremoteserver-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-23 13:44:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "robotframework",
"github_project": "PythonRemoteServer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "robotremoteserver"
}
JSON
