[X2Go-Commits] [x2gobroker] 01/03: x2gobroker/uccsjson.py: Improve API documentation.
git-admin at x2go.org
git-admin at x2go.org
Fri Sep 14 11:35:19 CEST 2018
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 at 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-feature-introduced-in-ubuntu-12-10-with-x2go
+ * 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
More information about the x2go-commits
mailing list