This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit 95e5113f18fd2e38982ce97aa8aa31e307933253 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Fri Sep 14 11:10:28 2018 +0200 x2gobroker/uccsjson.py: Improve API documentation. --- x2gobroker/uccsjson.py | 171 ++++++++++++++++++++++++++++++------------------- 1 file changed, 105 insertions(+), 66 deletions(-) diff --git a/x2gobroker/uccsjson.py b/x2gobroker/uccsjson.py index 0d4dc5a..fe09e54 100644 --- a/x2gobroker/uccsjson.py +++ b/x2gobroker/uccsjson.py @@ -17,6 +17,23 @@ # Free Software Foundation, Inc., # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. +"""\ +This modules provides various helper functions and classes for the +UCCS web frontend of the X2Go Session Broker. + +The UCCS protocol was originally brought to life by Canonical and was +part of Unity Greeter in Ubuntu 12.10. + +See early blog posts about that topic: + + * https://sunweavers.net/blog/how-to-for-hi-jacking-the-rdp-remote-login-featu... + * https://sunweavers.net/blog/thoughts-about-canonical-s-uccs-service + * https://sunweavers.net/blog/unity-greeter-with-x2go-remote-login-support + +The UCCS web frontend of the X2Go Session Broker offers remote logon +support to the Unity Greeter fork called Arctica Greeter. + +""" try: import simplejson as json except ImportError: import json import re @@ -43,26 +60,31 @@ def convert_to_builtin_type(obj): class ManagementServer(): """\ - Base class for generating UCCS compatible JSON object. + Generate a UCCS compatible JSON object for a UCCS management server. + + A :class:`ManagementServer` in UCCS terminology is a host offering a + UCCS compliant API for handling remote logons from clients over the + web. + + The :class:`ManagementServer` is the entry point for all clients. + + :param url: URL of the UCCS broker server + :type url: ``str`` + :param name: human-readable, descriptive server name + :type name: ``str`` + :param api_version: API version used between remote logon service and broker + :type api_version: ``int`` """ def __init__(self, url, name, api_version=latest_api_version): """\ - Initializ instance. - - :param url: URL of the UCCS broker server - :type url: ``str`` - :param name: human-readable, descriptive server name - :type name: ``str`` - :param api_version: API version used between remote logon service and broker - :type api_version: ``int`` + Initialize instance. """ self._api_version = api_version self.RemoteDesktopServers = [] self.AdditionalManagementServers = [] - self.URL = url - self.URL = '{url}/'.format(url=self.URL.rstrip('/')) + self.URL = '{url}/'.format(url=url.rstrip('/')) self.Name = name def set_default(self, ts_name): @@ -84,19 +106,26 @@ class ManagementServer(): """\ Add a terminal server to this management server object. - :param server: instance of class L{RDPServer} or L{X2GoServer}. + :param server: instance of class :class:`RDPServer` or :class:`X2GoServer` :type server: ``obj`` """ self.RemoteDesktopServers.append(server) - # NOT USED!!! - #def add_additional_management_server(self, amserver): - # if isinstance(amserver, AdditionalManagementServer): - # self.AdditionalManagementServers.append(amserver) - # else: - # raise TypeError("add_additional_management_server expects a "\ - # "AdditionalManagementServer argument") + def add_additional_management_server(self, amserver): + """\ + Add / cascade a managemnet server to this management server + object. + + :param server: instance of class :class:`AdditionalManagementServer` + :type server: ``obj`` + + """ + if isinstance(amserver, AdditionalManagementServer): + self.AdditionalManagementServers.append(amserver) + else: + raise TypeError("add_additional_management_server expects a "\ + "AdditionalManagementServer argument") def toJson(self): """\ @@ -106,32 +135,41 @@ class ManagementServer(): return json.dumps(self, default=convert_to_builtin_type, sort_keys=True, indent=2) -# NOT USED!!! -#class AdditionalManagementServer(): -# def __init__(self, url, name): -# self.URL = url -# self.Name = name +class AdditionalManagementServer(): + """\ + Instantiate a to-be-cascaded sub-management UCCS server. + + In UCCS, other than terminal servers, you can add + :class:`AdditionalManagementServer` instances and cascade UCCS + setups. + :param url: URL of the UCCS broker server + :type url: ``str`` + :param name: human-readable, descriptive server name + :type name: ``str`` + :param api_version: API version used between remote logon service and broker + :type api_version: ``int`` + + """ + pass class RDPServer(): """\ Instantiate a UCCS compatible RDP server session profile object. + :param host: hostname of RDP server host + :type host: ``str`` + :param name: session profile name + :type name: ``str`` + :param username: username to be used for login + :type username: ``str`` + :param password: password to be used for login + :type password: ``str`` + :param api_version: API version used between remote logon service and broker + :type api_version: ``int`` + """ def __init__(self, host, name, username='', password='', api_version=latest_api_version): - """\ - :param host: hostname of RDP server host - :type host: ``str`` - :param name: session profile name - :type name: ``str`` - :param username: username to be used for login - :type username: ``str`` - :param password: password to be used for login - :type password: ``str`` - :param api_version: API version used between remote logon service and broker - :type api_version: ``int`` - - """ self._api_version = api_version self.URL = 'http://{url}/'.format(url=host) self.Name = name @@ -147,7 +185,7 @@ class RDPServer(): :param domain: the domain name to be set :type domain: ``str`` - :raises TypeError: domain has to be ``str`` or ``str`` + :raises TypeError: domain has to be ``str`` """ if isinstance(domain, str): @@ -169,21 +207,19 @@ class ICAServer(): """\ Instantiate a UCCS compatible ICA server session profile object. + :param host: hostname of ICA server host + :type host: ``str`` + :param name: session profile name + :type name: ``str`` + :param username: username to be used for login + :type username: ``str`` + :param password: password to be used for login + :type password: ``str`` + :param api_version: API version used between remote logon service and broker + :type api_version: ``int`` + """ def __init__(self, host, name, username='', password='', api_version=latest_api_version): - """\ - :param host: hostname of ICA server host - :type host: ``str`` - :param name: session profile name - :type name: ``str`` - :param username: username to be used for login - :type username: ``str`` - :param password: password to be used for login - :type password: ``str`` - :param api_version: API version used between remote logon service and broker - :type api_version: ``int`` - - """ self._api_version = api_version self.URL = 'http://{url}/'.format(url=host) self.Name = name @@ -199,7 +235,7 @@ class ICAServer(): :param domain: the domain name to be set :type domain: ``str`` - :raises TypeError: domain has to be ``str`` or ``str`` + :raises TypeError: domain has to be ``str`` """ if isinstance(domain, str): @@ -221,21 +257,19 @@ class X2GoServer(): """\ Instantiate a UCCS compatible X2Go Server session profile object. + :param host: hostname of X2Go Server host + :type host: ``str`` + :param name: session profile name + :type name: ``str`` + :param username: username to be used for login + :type username: ``str`` + :param password: password to be used for login + :type password: ``str`` + :param api_version: API version used between remote logon service and broker + :type api_version: ``int`` + """ def __init__(self, host, name, username='', password='', api_version=latest_api_version): - """\ - :param host: hostname of X2Go Server host - :type host: ``str`` - :param name: session profile name - :type name: ``str`` - :param username: username to be used for login - :type username: ``str`` - :param password: password to be used for login - :type password: ``str`` - :param api_version: API version used between remote logon service and broker - :type api_version: ``int`` - - """ self._api_version = api_version self.URL = 'http://{url}/'.format(url=host) self.Name = name @@ -250,7 +284,10 @@ class X2GoServer(): # legacy: API v4 (not used in API v5 and higher) def set_session_type(self, session_type): """\ - Set the session_type to be used on this X2Go Server. + Set the session type to be used on this X2Go Server. + + This method is a legacy method formerly used by APIv4 of the UCCS + protocol. In APIv5, the method :func:`set_command()` gets used instead. :param command: the session type to be set :type command: ``str`` @@ -269,6 +306,8 @@ class X2GoServer(): """\ Set the command to be used on this X2Go Server. + Added since APIv5 of the UCCS protocol. + :param command: the session type to be set :type command: ``str`` -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git