Docmenting starting server on background #22

Author: pekkaklarck

README.rst

@@ -81,22 +81,25 @@ Remote server configuration
 
 The remote server accepts following configuration parameters:
 
-    ==============  ================  ========================================
-       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 interfaces.
-    ``port``         ``8270``         Port to listen. Use ``0`` to select a free port automatically. Can be given as an integer or as a string.
-    ``port_file``    ``None``         File to write port that is used. ``None`` means no such file is written.
-    ``allow_stop``   ``True``         Allow/disallow stopping the server using ``Stop Remote Server`` keyword.
-    ==============  ================  ========================================
+    =====================  =================  ========================================
+          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 interfaces.
+    ``port``                ``8270``          Port to listen. Use ``0`` to select a free port automatically. Can be given as an integer or as a string.
+    ``port_file``           ``None``          File to write port that is used. ``None`` means no such file is written.
+    ``allow_stop``          ``'DEPRECATED'``  DEPRECATED. User ``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 ``serve`` or ``start`` methods. New in version 1.1.
+    ``allow_remote_stop``   ``True``          Allow/disallow stopping the server using ``Stop Remote Server`` keyword and ``stop_remote_server`` XML-RPC method. New in version 1.1.
+    =====================  =================  ========================================
 
 Address and port that are used are printed to the console where the server is
 started. Writing port to a file by using ``port_file`` argument is especially
 useful when the server selects a free port automatically. Other tools can then
 easily read the active port from the file. If the file is removed prior to
 starting the server, tools can also wait until the file exists to know that
-the server is up and running.
+the server is up and running. Starting from version 1.1, the server removes
+the port file automatically.
 
 Example:
 
@@ -106,23 +109,23 @@ Example:
     from mylibrary import MyLibrary
 
     RobotRemoteServer(MyLibrary(), host='10.0.0.42', port=0,
-                      port_file='/tmp/remote-port.txt', allow_stop=False)
+                      port_file='/tmp/remote-port.txt')
 
-Testing is server running
--------------------------
+Starting from versoin 1.1, the server can also first be initialized and started
+afterwards:
 
-Starting from version 1.0.1 , ``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::
+.. sourcecode:: python
 
-    $ 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.
+    server = RobotRemoteServer(MyLibrary(), host='10.0.0.42', port=0,
+                               port_file='/tmp/remote-port.txt', serve=False)
+    server.serve()
+
+The above is totally equivalent to the earlier example and both of them result
+with the server starting and running until it is `explicitly stopped`__.
+Alternatively it is possible to `start the server on background`__.
 
-.. tip:: As discussed below, using ``stop`` instead of ``test`` allows stopping
-         the server. Both testing and stopping should work also against other
-         Robot Framework remote server implementations.
+__ `Stopping remote server`_
+__ `Starting server on background`_
 
 Stopping remote server
 ----------------------
@@ -136,19 +139,77 @@ The remote server can be gracefully stopped using several different methods:
   work on Windows. Notice that with Jython you need to send the signal to the
   started Java process, not to the shell typically started by ``jython`` command.
 
-- Using ``Stop Remote Server`` keyword. This can be disabled by using
-  ``allow_stop=False`` when starting the server.
+- Using ``Stop Remote Server`` keyword.
+
+- Using ``stop_remote_server`` function in the XML-RPC interface.
+
+- Running ``python -m robotremoteserver stop [uri]`` or using
+  ``stop_remote_server`` function similarly as when `testing is server running`_.
+
+- Calling ``stop`` method of the running server object.
+
+Using ``Stop Remote Server`` keyword, ``stop_remote_server`` XML-RPC function
+or stopping functionality provided by ``robotremoteserver`` itself can all be
+disabled by using ``allow_remote_stop=False`` when initializing the server.
+
+Starting server on background
+-----------------------------
+
+Sometimes it is useful to start the server on background and keep doing
+something else, like starting more servers, on the main thread. Starting
+from RobotRemoteServer 1.1 this can be accomplished easily:
+
+.. sourcecode:: python
+
+    from robotremoteserver import RobotRemoteServer
+    from mylibrary import MyLibrary
+
+    server = RobotRemoteServer(MyLibrary(), port=0, serve=False)
+    server.start()
+    print('Remote server started on port %d.' % server.server_port)
+    # Do something ...
+    server.stop()
+
+As the above example illustrates, the ``start`` method starts the server on
+background. When the server is started on background, none of the earlier
+methods to `stop the server`__ work. Instead the server can be stopped, as
+shown in the example, by using the ``stop`` method.
+
+__ `Stopping remote server`_
+
+Testing is server running
+-------------------------
+
+Starting from version 1.0.1 , ``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 version 1.1, ``robotremoteserver`` module contains function
+``stop_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!')
 
-- Running ``python -m robotremoteserver stop [uri]`` similarly as when `testing
-  is server running`_. Also this can be disabled using ``allow_stop=False``.
-  New in version 1.0.1.
+``robotremoteserver`` can be also used to stop a remote server by using
+``stop`` argument on the command line or by using ``stop_remote_server``
+function programmatically. Testing and stopping should work also with
+other Robot Framework remote server implementations.
 
 Example
 -------
 
-The remote server project contains an example_ that can be studied and also
+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_.
 
-.. _example: https://github.com/robotframework/PythonRemoteServer/tree/master/example
+__ https://github.com/robotframework/PythonRemoteServer/tree/master/example

src/robotremoteserver.py

@@ -48,7 +48,7 @@
 class RobotRemoteServer(object):
 
     def __init__(self, library, host='127.0.0.1', port=8270, port_file=None,
-                 allow_stop=True, serve=True):
+                 allow_stop='DEPRECATED', serve=True, allow_remote_stop=True):
         """Configure and start-up remote server.
 
         :param library:     Test library instance or module to host.
@@ -59,14 +59,19 @@ def __init__(self, library, host='127.0.0.1', port=8270, port_file=None,
                             a string.
         :param port_file:   File to write port that is used. ``None`` means
                             no such file is written.
-        :param allow_stop:  Allow/disallow stopping the server using ``Stop
-                            Remote Server`` keyword.
-        :param serve:       When ``True`` starts the server automatically.
-                            When ``False``, server can be started with
-                            :meth:`serve` or :meth:`start` methods.
+        :param allow_stop:  DEPRECATED. User ``allow_remote_stop`` instead.
+        :param serve:       If ``True``, start the server automatically and
+                            wait for it to be stopped. If ``False``, server can
+                            be started using :meth:`serve` or :meth:`start`
+                            methods.
+        :param allow_remote_stop:  Allow/disallow stopping the server using
+                            ``Stop Remote Server`` keyword and
+                            ``stop_remote_server`` XML-RPC method.
         """
+        if allow_stop != 'DEPRECATED':
+            allow_remote_stop = allow_stop
         self._server = StoppableXMLRPCServer(host, int(port), port_file,
-                                             allow_stop)
+                                             allow_remote_stop)
         self._library = RemoteLibraryFactory(library)
         self._register_functions(self._server)
         if serve:
@@ -90,7 +95,7 @@ def _register_functions(self, server):
         server.register_function(self._stop_serve, 'stop_remote_server')
 
     def serve(self, log=True):
-        """Start the server and wait for it to finish.
+        """Start the server and wait for it to be stopped.
 
         :param log:  Log message about startup or not.
 
@@ -103,8 +108,9 @@ def serve(self, log=True):
         to start the server on background.
 
         In addition to signals, the server can be stopped with ``Stop Remote
-        Server`` keyword. Using :meth:`stop` method is possible too, but
-        requires running this method in a thread.
+        Server`` keyword, unless disabled when the server is initialized.
+        Using :meth:`stop` method is possible too, but requires running this
+        method in a thread.
         """
         self._server.serve(log=log)
 
@@ -566,7 +572,7 @@ def test_remote_server(uri, log=True):
 
 
 def stop_remote_server(uri, log=True):
-    """Stop remote server.
+    """Stop remote server unless server has disabled stopping.
 
     :param uri:  Server address.
     :param log:  Log status message or not.