This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository python-x2go. commit 1e11f64157fd36230e5d40f37f589e908be87721 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Mon Oct 20 22:52:18 2014 +0200 Provide API inline documentation for http(s) session broker client implementation. --- debian/changelog | 2 + x2go/backends/profiles/httpbroker.py | 96 ++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) diff --git a/debian/changelog b/debian/changelog index 0273933..7879fd9 100644 --- a/debian/changelog +++ b/debian/changelog @@ -3,6 +3,8 @@ python-x2go (0.5.0.1-0x2go1) UNRELEASED; urgency=medium * New upstream version (0.5.0.1): - Update TODO file. - Update README file. + - Provide API inline documentation for http(s) session + broker client implementation. -- Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Mon, 20 Oct 2014 22:24:21 +0200 diff --git a/x2go/backends/profiles/httpbroker.py b/x2go/backends/profiles/httpbroker.py index 2e17e40..539bbd9 100644 --- a/x2go/backends/profiles/httpbroker.py +++ b/x2go/backends/profiles/httpbroker.py @@ -113,21 +113,77 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): self.broker_my_pubkey, self.broker_my_privkey = genkeypair(local_username=_CURRENT_LOCAL_USER, client_address='127.0.0.1') def get_broker_noauth(self): + """\ + Accessor for the class's C{broker_noauth} property. + + @return: C{True} if the broker probably does not expect authentication. + @rtype: C{bool} + + """ return self.broker_noauth def get_broker_username(self): + """\ + Accessor for the class's C{broker_username} property. + + @return: the username used for authentication against the session broker URL + @rtype: C{str} + + """ return self.broker_username def get_broker_url(self): + """\ + Accessor for the class's C{broker_url} property. + + @return: the session broker URL that was used at broker session instantiation + @rtype: C{str} + + """ return self.broker_url def set_broker_url(self, broker_url): + """\ + Mutator for the class's C{broker_url} property. + + @param broker_url: A new broker URL to use with this instance. Format is + C{<protocol>://<hostname>:<port>/<path>} (where protocol has to be C{http} + or C{https}. + @type broker_url: C{str} + + @return: the session broker URL that was used at broker session instantiation + @rtype: C{str} + + """ self.broker_url = broker_url def get_broker_type(self): + """\ + Accessor of the class's {_broker_type} property. + + @return: either C{http} or C{https}. + @rtype: C{str} + + """ return self._broker_type def broker_simpleauth(self, broker_username, broker_password): + """\ + Attempt a username / password authentication against the instance's + broker URL. + + @param broker_username: username to use for authentication + @type broker_username: C{str} + @param broker_password: password to use for authentication + @type broker_password: C{str} + + @return: C{True} if authentication has been successful + @rtype: C{bool} + + @raise X2GoBrokerConnectionException: Raised on any kind of connection / + authentication failure. + + """ if self.broker_url is not None: request_data = { 'user': broker_username or '', @@ -162,6 +218,14 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): return False def broker_disconnect(self): + """\ + Disconnect from an (already) authenticated broker session. + + All authentication parameters will be dropped (forgotten) and + this instance has to re-authenticate against / re-connect to the + session broker before any new interaction with the broker is possible. + + """ _profile_ids = copy.deepcopy(self.profile_ids) # forget nearly everything... @@ -181,6 +245,17 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): self.broker_noauth = False def is_broker_authenticated(self): + """\ + Detect if an authenticated broker session has already been + initiated. Todo so, a simple re-authentication (username, password) + will be attempted. If that fails, user credentials are not provided / + valid. + + @return: C{True} if the broker session has already been authenticated + and user credentials are known / valid + @rtype: C{bool} + + """ if self._broker_auth_successful is None: # do a test auth against the given broker URL try: @@ -190,6 +265,13 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): return self._broker_auth_successful def broker_listprofiles(self): + """\ + Obtain a session profile list from the X2Go Session Broker. + + @return: session profiles as a Python dictionary. + @rtype: C{dict} + + """ if self.broker_url is not None: request_data = { 'task': 'listprofiles', @@ -222,6 +304,20 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): return {} def broker_selectsession(self, profile_id): + """\ + Select a session from the list of available session profiles (presented by + L{broker_listprofiles}). This method requests a session information dictionary + (server, port, SSH keys, already running / suspended sessions, etc.) from the + session broker for the provided C{profile_id}. + + @param profile_id: profile ID of the selected session profile + @type profile_id: C{str} + + @return: session information (server, port, SSH keys, etc.) for a selected + session profile (i.e. C{profile_id}) + @rtype: C{dict} + + """ if self.broker_url is not None: if not self._broker_profile_cache.has_key(profile_id) or not self._broker_profile_cache[profile_id]: request_data = { -- Alioth's /srv/git/_hooks_/post-receive-email on /srv/git/code.x2go.org/python-x2go.git