[X2Go-Commits] [python-x2go] 04/07: API __doc__ strings: Rough / automated switch from Epydoc to Sphinx/reST.

This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository python-x2go. commit f96c17e01f2ff99df1536d257c268dbe01ffe3e5 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Mon Mar 5 22:10:25 2018 +0100 API __doc__ strings: Rough / automated switch from Epydoc to Sphinx/reST. --- x2go/_paramiko.py | 36 +- x2go/backends/control/plain.py | 526 +++++------ x2go/backends/info/plain.py | 92 +- x2go/backends/printing/file.py | 57 +- x2go/backends/printing/winreg.py | 4 +- x2go/backends/profiles/base.py | 301 ++++--- x2go/backends/profiles/file.py | 43 +- x2go/backends/profiles/httpbroker.py | 60 +- x2go/backends/proxy/base.py | 16 +- x2go/backends/proxy/nx3.py | 10 +- x2go/backends/terminal/plain.py | 308 ++++--- x2go/cache.py | 101 ++- x2go/checkhosts.py | 84 +- x2go/cleanup.py | 18 +- x2go/client.py | 1611 +++++++++++++++++----------------- x2go/forward.py | 56 +- x2go/guardian.py | 2 +- x2go/inifiles.py | 61 +- x2go/log.py | 20 +- x2go/mimebox.py | 31 +- x2go/mimeboxactions.py | 54 +- x2go/printactions.py | 116 +-- x2go/printqueue.py | 39 +- x2go/pulseaudio.py | 3 +- x2go/registry.py | 503 +++++------ x2go/rforward.py | 60 +- x2go/session.py | 733 ++++++++-------- x2go/sftpserver.py | 180 ++-- x2go/sshproxy.py | 18 +- x2go/telekinesis.py | 14 +- x2go/tests/test_printing.py | 117 +-- x2go/utils.py | 206 ++--- x2go/xserver.py | 29 +- 33 files changed, 2824 insertions(+), 2685 deletions(-) diff --git a/x2go/_paramiko.py b/x2go/_paramiko.py index 8d93ad7..f74b0dd 100644 --- a/x2go/_paramiko.py +++ b/x2go/_paramiko.py @@ -48,18 +48,18 @@ PARAMIKO_FEATURE = { def _SSHClient_save_host_keys(self, filename): """\ Available since paramiko 1.11.0... - + This method has been taken from SSHClient class in Paramiko and has been improved and adapted to latest SSH implementations. - + Save the host keys back to a file. Only the host keys loaded with L{load_host_keys} (plus any added directly) will be saved -- not any host keys loaded with L{load_system_host_keys}. - @param filename: the filename to save to - @type filename: str - @raise IOError: if the file could not be written + :param filename: the filename to save to + :type filename: str + :raises IOError: if the file could not be written """ # update local host keys from file (in case other SSH clients @@ -81,19 +81,19 @@ def _SSHClient_save_host_keys(self, filename): def _HostKeys_load(self, filename): """\ Available since paramiko 1.11.0... - + Read a file of known SSH host keys, in the format used by openssh. This type of file unfortunately doesn't exist on Windows, but on posix, it will usually be stored in C{os.path.expanduser("~/.ssh/known_hosts")}. - + If this method is called multiple times, the host keys are merged, not cleared. So multiple calls to C{load} will just call L{add}, replacing any existing entries and adding new ones. - @param filename: name of the file to read host keys from - @type filename: str - @raise IOError: if there was an error reading the file + :param filename: name of the file to read host keys from + :type filename: str + :raises IOError: if there was an error reading the file """ f = open(filename, 'r') @@ -117,14 +117,14 @@ def _HostKeys_add(self, hostname, keytype, key, hash_hostname=True): Add a host key entry to the table. Any existing entry for a C{(hostname, keytype)} pair will be replaced. - @param hostname: the hostname (or IP) to add - @type hostname: str - @param keytype: key type (C{"ssh-rsa"}, C{"ssh-dss"} or C{"ecdsa-sha2-nistp256"}) - @type keytype: str - @param key: the key to add - @type key: L{PKey} - @param hash_hostname: hash the system's hostname (Default value = True) - @type hash_hostname: C{bool} + :param hostname: the hostname (or IP) to add + :type hostname: str + :param keytype: key type (C{"ssh-rsa"}, C{"ssh-dss"} or C{"ecdsa-sha2-nistp256"}) + :type keytype: str + :param key: the key to add + :type key: L{PKey} + :param hash_hostname: hash the system's hostname (Default value = True) + :type hash_hostname: C{bool} """ # IPv4 and IPv6 addresses using the SSH default port need to be stripped off the port number diff --git a/x2go/backends/control/plain.py b/x2go/backends/control/plain.py index d34af67..202c5a0 100644 --- a/x2go/backends/control/plain.py +++ b/x2go/backends/control/plain.py @@ -67,10 +67,10 @@ def _rerewrite_blanks(cmd): Commands get rewritten in the terminal sessions. This re-rewrite function helps displaying command string in log output. - @param cmd: command that has to be rewritten for log output - @type cmd: C{str} - @return: the command with ,,X2GO_SPACE_CHAR'' re-replaced by blanks - @rtype: C{str} + :param cmd: command that has to be rewritten for log output + :type cmd: C{str} + :returns: the command with ,,X2GO_SPACE_CHAR'' re-replaced by blanks + :rtype: C{str} """ # X2Go run command replace X2GO_SPACE_CHAR string with blanks @@ -81,20 +81,20 @@ def _rerewrite_blanks(cmd): def _rewrite_password(cmd, user=None, password=None): """\ In command strings Python X2Go replaces some macros with actual values: - + - X2GO_USER -> the user name under which the user is authenticated via SSH - X2GO_PASSWORD -> the password being used for SSH authentication - + Both macros can be used to on-the-fly authenticate via RDP. - @param cmd: command that is to be sent to an X2Go server script - @type cmd: C{str} - @param user: the SSH authenticated user name (Default value = None) - @type user: C{str} - @param password: the password being used for SSH authentication (Default value = None) - @type password: C{str} - @return: the command with macros replaced - @rtype: C{str} + :param cmd: command that is to be sent to an X2Go server script + :type cmd: C{str} + :param user: the SSH authenticated user name (Default value = None) + :type user: C{str} + :param password: the password being used for SSH authentication (Default value = None) + :type password: C{str} + :returns: the command with macros replaced + :rtype: C{str} """ # if there is a ,,-u X2GO_USER'' parameter in RDP options then we will replace @@ -111,7 +111,7 @@ def _rewrite_password(cmd, user=None, password=None): class X2GoControlSession(paramiko.SSHClient): """\ In the Python X2Go concept, X2Go sessions fall into two parts: a control session and one to many terminal sessions. - + The control session handles the SSH based communication between server and client. It is mainly derived from C{paramiko.SSHClient} and adds on X2Go related functionality. @@ -242,8 +242,9 @@ class X2GoControlSession(paramiko.SSHClient): Get the hostname as stored in the properties of this control session. - @return: the hostname of the connected X2Go server - @rtype: C{str} + :returns: the hostname of the connected X2Go server + + :rtype: C{str} """ return self.hostname @@ -253,8 +254,9 @@ class X2GoControlSession(paramiko.SSHClient): Get the port number of the SSH connection as stored in the properties of this control session. - @return: the server-side port number of the control session's SSH connection - @rtype: C{str} + :returns: the server-side port number of the control session's SSH connection + + :rtype: C{str} """ return self.port @@ -262,7 +264,7 @@ class X2GoControlSession(paramiko.SSHClient): def load_session_host_keys(self): """\ Load known SSH host keys from the C{known_hosts} file. - + If the file does not exist, create it first. @@ -288,16 +290,16 @@ class X2GoControlSession(paramiko.SSHClient): def _x2go_sftp_put(self, local_path, remote_path, timeout=20): """\ Put a local file on the remote server via sFTP. - + During sFTP operations, remote command execution gets blocked. - @param local_path: full local path name of the file to be put on the server - @type local_path: C{str} - @param remote_path: full remote path name of the server-side target location, path names have to be Unix-compliant - @type remote_path: C{str} - @param timeout: this SFTP put action should not take longer then the given value (Default value = 20) - @type timeout: C{int} - @raise X2GoControlSessionException: if the SSH connection dropped out + :param local_path: full local path name of the file to be put on the server + :type local_path: C{str} + :param remote_path: full remote path name of the server-side target location, path names have to be Unix-compliant + :type remote_path: C{str} + :param timeout: this SFTP put action should not take longer then the given value (Default value = 20) + :type timeout: C{int} + :raises X2GoControlSessionException: if the SSH connection dropped out """ ssh_transport = self.get_transport() @@ -339,16 +341,16 @@ class X2GoControlSession(paramiko.SSHClient): def _x2go_sftp_write(self, remote_path, content, timeout=20): """\ Create a text file on the remote server via sFTP. - + During sFTP operations, remote command execution gets blocked. - @param remote_path: full remote path name of the server-side target location, path names have to be Unix-compliant - @type remote_path: C{str} - @param content: a text file, multi-line files use Unix-link EOL style - @type content: C{str} - @param timeout: this SFTP write action should not take longer then the given value (Default value = 20) - @type timeout: C{int} - @raise X2GoControlSessionException: if the SSH connection dropped out + :param remote_path: full remote path name of the server-side target location, path names have to be Unix-compliant + :type remote_path: C{str} + :param content: a text file, multi-line files use Unix-link EOL style + :type content: C{str} + :param timeout: this SFTP write action should not take longer then the given value (Default value = 20) + :type timeout: C{int} + :raises X2GoControlSessionException: if the SSH connection dropped out """ ssh_transport = self.get_transport() @@ -395,14 +397,14 @@ class X2GoControlSession(paramiko.SSHClient): def _x2go_sftp_remove(self, remote_path, timeout=20): """\ Remote a remote file from the server via sFTP. - + During sFTP operations, remote command execution gets blocked. - @param remote_path: full remote path name of the server-side file to be removed, path names have to be Unix-compliant - @type remote_path: C{str} - @param timeout: this SFTP remove action should not take longer then the given value (Default value = 20) - @type timeout: C{int} - @raise X2GoControlSessionException: if the SSH connection dropped out + :param remote_path: full remote path name of the server-side file to be removed, path names have to be Unix-compliant + :type remote_path: C{str} + :param timeout: this SFTP remove action should not take longer then the given value (Default value = 20) + :type timeout: C{int} + :raises X2GoControlSessionException: if the SSH connection dropped out """ ssh_transport = self.get_transport() @@ -446,21 +448,22 @@ class X2GoControlSession(paramiko.SSHClient): def _x2go_exec_command(self, cmd_line, loglevel=log.loglevel_INFO, timeout=20, **kwargs): """\ Execute an X2Go server-side command via SSH. - + During SSH command executions, sFTP operations get blocked. - @param cmd_line: the command to be executed on the remote server - @type cmd_line: C{str} or C{list} - @param loglevel: use this loglevel for reporting about remote command execution (Default value = log.loglevel_INFO) - @type loglevel: C{int} - @param timeout: if commands take longer than C{<timeout>} to be executed, consider the control session connection + :param cmd_line: the command to be executed on the remote server + :type cmd_line: C{str} or C{list} + :param loglevel: use this loglevel for reporting about remote command execution (Default value = log.loglevel_INFO) + :type loglevel: C{int} + :param timeout: if commands take longer than C{<timeout>} to be executed, consider the control session connection to have died. (Default value = 20) - @type timeout: C{int} - @param kwargs: parameters that get passed through to the C{paramiko.SSHClient.exec_command()} method. - @type kwargs: C{dict} - @return: C{True} if the command could be successfully executed on the remote X2Go server - @rtype: C{bool} - @raise X2GoControlSessionException: if the command execution failed (due to a lost connection) + :type timeout: C{int} + :param kwargs: parameters that get passed through to the C{paramiko.SSHClient.exec_command()} method. + :type kwargs: C{dict} + :param **kwargs: + :returns: C{True} if the command could be successfully executed on the remote X2Go server + :rtype: C{bool} + :raises X2GoControlSessionException: if the command execution failed (due to a lost connection) """ if type(cmd_line) == list: @@ -582,10 +585,10 @@ class X2GoControlSession(paramiko.SSHClient): """\ Do a query for the server-side list of X2Go components and their versions. - @param force: do not use the cached component list, really ask the server (again) (Default value = False) - @type force: C{bool} - @return: dictionary of X2Go components (as keys) and their versions (as values) - @rtype: C{list} + :param force: do not use the cached component list, really ask the server (again) (Default value = False) + :type force: C{bool} + :returns: dictionary of X2Go components (as keys) and their versions (as values) + :rtype: C{list} """ if force: @@ -612,10 +615,10 @@ class X2GoControlSession(paramiko.SSHClient): """\ Do a query for the server-side list of X2Go features. - @param force: do not use the cached feature list, really ask the server (again) (Default value = False) - @type force: C{bool} - @return: list of X2Go feature names - @rtype: C{list} + :param force: do not use the cached feature list, really ask the server (again) (Default value = False) + :type force: C{bool} + :returns: list of X2Go feature names + :rtype: C{list} """ if force: @@ -644,10 +647,10 @@ class X2GoControlSession(paramiko.SSHClient): """\ Retrieve and cache the members of a server-side POSIX group. - @param group: remote POSIX group name - @type group: C{str} - @return: list of POSIX group members - @rtype: C{list} + :param group: remote POSIX group name + :type group: C{str} + :returns: list of POSIX group members + :rtype: C{list} """ if group not in self._remote_group: @@ -661,13 +664,13 @@ class X2GoControlSession(paramiko.SSHClient): def is_x2gouser(self, username): """\ Is the remote user allowed to launch X2Go sessions? - + FIXME: this method is currently non-functional. - @param username: remote user name - @type username: C{str} - @return: C{True} if the remote user is allowed to launch X2Go sessions - @rtype: C{bool} + :param username: remote user name + :type username: C{str} + :returns: C{True} if the remote user is allowed to launch X2Go sessions + :rtype: C{bool} """ ### @@ -683,8 +686,9 @@ class X2GoControlSession(paramiko.SSHClient): Check if the remote user is allowed to use SSHFS mounts. - @return: C{True} if the user is allowed to connect client-side shares to the X2Go session - @rtype: C{bool} + :returns: C{True} if the user is allowed to connect client-side shares to the X2Go session + + :rtype: C{bool} """ (stdin, stdout, stderr) = self._x2go_exec_command('which fusermount') @@ -697,9 +701,10 @@ class X2GoControlSession(paramiko.SSHClient): Returns (and caches) the control session's remote username. - @return: SSH transport's user name - @rtype: C{str} - @raise X2GoControlSessionException: on SSH connection loss + :returns: SSH transport's user name + + :rtype: C{str} + :raises X2GoControlSessionException: on SSH connection loss """ if self._remote_username is None: @@ -716,9 +721,10 @@ class X2GoControlSession(paramiko.SSHClient): Returns (and caches) the control session's remote host (name or ip). - @return: SSH transport's peer name - @rtype: C{tuple} - @raise X2GoControlSessionException: on SSH connection loss + :returns: SSH transport's peer name + + :rtype: C{tuple} + :raises X2GoControlSessionException: on SSH connection loss """ if self._remote_peername is None: @@ -745,8 +751,8 @@ class X2GoControlSession(paramiko.SSHClient): """\ Manipulate the control session's profile name. - @param profile_name: new profile name for this control session - @type profile_name: C{str} + :param profile_name: new profile name for this control session + :type profile_name: C{str} """ self.profile_name = profile_name @@ -755,12 +761,12 @@ class X2GoControlSession(paramiko.SSHClient): """\ Wraps around a Paramiko/SSH host key check. - @param hostname: the remote X2Go server's hostname - @type hostname: C{str} - @param port: the SSH port of the remote X2Go server (Default value = 22) - @type port: C{int} - @return: C{True} if the host key check succeeded, C{False} otherwise - @rtype: C{bool} + :param hostname: the remote X2Go server's hostname + :type hostname: C{str} + :param port: the SSH port of the remote X2Go server (Default value = 22) + :type port: C{int} + :returns: C{True} if the host key check succeeded, C{False} otherwise + :rtype: C{bool} """ # trailing whitespace tolerance @@ -789,106 +795,106 @@ class X2GoControlSession(paramiko.SSHClient): SSH client connect method are recited here. The parameters C{add_to_known_hosts}, C{force_password_auth}, C{session_instance} and all SSH proxy related parameters have been added as X2Go specific parameters - + The server's host key is checked against the system host keys (see C{load_system_host_keys}) and any local host keys (C{load_host_keys}). If the server's hostname is not found in either set of host keys, the missing host key policy is used (see C{set_missing_host_key_policy}). The default policy is to reject the key and raise an C{SSHException}. - + Authentication is attempted in the following order of priority: - + - The C{pkey} or C{key_filename} passed in (if any) - Any key we can find through an SSH agent - Any "id_rsa" or "id_dsa" key discoverable in C{~/.ssh/} - Plain username/password auth, if a password was given - + If a private key requires a password to unlock it, and a password is passed in, that password will be used to attempt to unlock the key. - @param hostname: the server to connect to - @type hostname: C{str} - @param port: the server port to connect to (Default value = 22) - @type port: C{int} - @param username: the username to authenticate as (defaults to the + :param hostname: the server to connect to + :type hostname: C{str} + :param port: the server port to connect to (Default value = 22) + :type port: C{int} + :param username: the username to authenticate as (defaults to the current local username) - @type username: C{str} - @param password: a password to use for authentication or for unlocking + :type username: C{str} + :param password: a password to use for authentication or for unlocking a private key (Default value = None) - @type password: C{str} - @param passphrase: a passphrase to use for unlocking + :type password: C{str} + :param passphrase: a passphrase to use for unlocking a private key in case the password is already needed for two-factor authentication (Default value = None) - @type passphrase: C{str} - @param key_filename: the filename, or list of filenames, of optional + :type passphrase: C{str} + :param key_filename: the filename, or list of filenames, of optional private key(s) to try for authentication (Default value = None) - @type key_filename: C{str} or list(str) - @param pkey: an optional private key to use for authentication (Default value = None) - @type pkey: C{PKey} - @param forward_sshagent: forward SSH agent authentication requests to the X2Go client-side + :type key_filename: C{str} or list(str) + :param pkey: an optional private key to use for authentication (Default value = None) + :type pkey: C{PKey} + :param forward_sshagent: forward SSH agent authentication requests to the X2Go client-side (will update the class property of the same name) (Default value = None) - @type forward_sshagent: C{bool} - @param unique_hostkey_aliases: update the unique_hostkey_aliases class property (Default value = None) - @type unique_hostkey_aliases: C{bool} - @param timeout: an optional timeout (in seconds) for the TCP connect (Default value = None) - @type timeout: float - @param look_for_keys: set to C{True} to enable searching for discoverable + :type forward_sshagent: C{bool} + :param unique_hostkey_aliases: update the unique_hostkey_aliases class property (Default value = None) + :type unique_hostkey_aliases: C{bool} + :param timeout: an optional timeout (in seconds) for the TCP connect (Default value = None) + :type timeout: float + :param look_for_keys: set to C{True} to enable searching for discoverable private key files in C{~/.ssh/} (Default value = False) - @type look_for_keys: C{bool} - @param allow_agent: set to C{True} to enable connecting to a local SSH agent + :type look_for_keys: C{bool} + :param allow_agent: set to C{True} to enable connecting to a local SSH agent for acquiring authentication information (Default value = False) - @type allow_agent: C{bool} - @param add_to_known_hosts: non-paramiko option, if C{True} paramiko.AutoAddPolicy() + :type allow_agent: C{bool} + :param add_to_known_hosts: non-paramiko option, if C{True} paramiko.AutoAddPolicy() is used as missing-host-key-policy. If set to C{False} paramiko.RejectPolicy() is used (Default value = None) - @type add_to_known_hosts: C{bool} - @param force_password_auth: non-paramiko option, disable pub/priv key authentication + :type add_to_known_hosts: C{bool} + :param force_password_auth: non-paramiko option, disable pub/priv key authentication completely, even if the C{pkey} or the C{key_filename} parameter is given (Default value = False) - @type force_password_auth: C{bool} - @param session_instance: an instance L{X2GoSession} using this L{X2GoControlSession} + :type force_password_auth: C{bool} + :param session_instance: an instance L{X2GoSession} using this L{X2GoControlSession} instance. (Default value = None) - @type session_instance: C{obj} - @param use_sshproxy: connect through an SSH proxy (Default value = False) - @type use_sshproxy: C{True} if an SSH proxy is to be used for tunneling the connection - @param sshproxy_host: hostname of the SSH proxy server (Default value = None) - @type sshproxy_host: C{str} - @param sshproxy_port: port of the SSH proxy server (Default value = 22) - @type sshproxy_port: C{int} - @param sshproxy_user: username that we use for authenticating against C{<sshproxy_host>} (Default value = None) - @type sshproxy_user: C{str} - @param sshproxy_password: a password to use for SSH proxy authentication or for unlocking + :type session_instance: C{obj} + :param use_sshproxy: connect through an SSH proxy (Default value = False) + :type use_sshproxy: C{True} if an SSH proxy is to be used for tunneling the connection + :param sshproxy_host: hostname of the SSH proxy server (Default value = None) + :type sshproxy_host: C{str} + :param sshproxy_port: port of the SSH proxy server (Default value = 22) + :type sshproxy_port: C{int} + :param sshproxy_user: username that we use for authenticating against C{<sshproxy_host>} (Default value = None) + :type sshproxy_user: C{str} + :param sshproxy_password: a password to use for SSH proxy authentication or for unlocking a private key (Default value = None) - @type sshproxy_password: C{str} - @param sshproxy_passphrase: a passphrase to use for unlocking + :type sshproxy_password: C{str} + :param sshproxy_passphrase: a passphrase to use for unlocking a private key needed for the SSH proxy host in case the sshproxy_password is already needed for two-factor authentication (Default value = '') - @type sshproxy_passphrase: C{str} - @param sshproxy_force_password_auth: enforce using a given C{sshproxy_password} even if a key(file) is given (Default value = False) - @type sshproxy_force_password_auth: C{bool} - @param sshproxy_key_filename: local file location of the private key file (Default value = None) - @type sshproxy_key_filename: C{str} - @param sshproxy_pkey: an optional private key to use for SSH proxy authentication (Default value = None) - @type sshproxy_pkey: C{PKey} - @param sshproxy_look_for_keys: set to C{True} to enable connecting to a local SSH agent + :type sshproxy_passphrase: C{str} + :param sshproxy_force_password_auth: enforce using a given C{sshproxy_password} even if a key(file) is given (Default value = False) + :type sshproxy_force_password_auth: C{bool} + :param sshproxy_key_filename: local file location of the private key file (Default value = None) + :type sshproxy_key_filename: C{str} + :param sshproxy_pkey: an optional private key to use for SSH proxy authentication (Default value = None) + :type sshproxy_pkey: C{PKey} + :param sshproxy_look_for_keys: set to C{True} to enable connecting to a local SSH agent for acquiring authentication information (for SSH proxy authentication) (Default value = False) - @type sshproxy_look_for_keys: C{bool} - @param sshproxy_allow_agent: set to C{True} to enable connecting to a local SSH agent + :type sshproxy_look_for_keys: C{bool} + :param sshproxy_allow_agent: set to C{True} to enable connecting to a local SSH agent for acquiring authentication information (for SSH proxy authentication) (Default value = False) - @type sshproxy_allow_agent: C{bool} - @param sshproxy_tunnel: the SSH proxy tunneling parameters, format is: <local-address>:<local-port>:<remote-address>:<remote-port> (Default value = None) - @type sshproxy_tunnel: C{str} - @return: C{True} if an authenticated SSH transport could be retrieved by this method - @rtype: C{bool} - @raise BadHostKeyException: if the server's host key could not be + :type sshproxy_allow_agent: C{bool} + :param sshproxy_tunnel: the SSH proxy tunneling parameters, format is: <local-address>:<local-port>:<remote-address>:<remote-port> (Default value = None) + :type sshproxy_tunnel: C{str} + :returns: C{True} if an authenticated SSH transport could be retrieved by this method + :rtype: C{bool} + :raises BadHostKeyException: if the server's host key could not be verified - @raise AuthenticationException: if authentication failed - @raise SSHException: if there was any other error connecting or + :raises AuthenticationException: if authentication failed + :raises SSHException: if there was any other error connecting or establishing an SSH session - @raise socket.error: if a socket error occurred while connecting - @raise X2GoSSHProxyException: any SSH proxy exception is passed through while establishing the SSH proxy connection and tunneling setup - @raise X2GoSSHAuthenticationException: any SSH proxy authentication exception is passed through while establishing the SSH proxy connection and tunneling setup - @raise X2GoRemoteHomeException: if the remote home directory does not exist or is not accessible - @raise X2GoControlSessionException: if the remote peer has died unexpectedly + :raises socket.error: if a socket error occurred while connecting + :raises X2GoSSHProxyException: any SSH proxy exception is passed through while establishing the SSH proxy connection and tunneling setup + :raises X2GoSSHAuthenticationException: any SSH proxy authentication exception is passed through while establishing the SSH proxy connection and tunneling setup + :raises X2GoRemoteHomeException: if the remote home directory does not exist or is not accessible + :raises X2GoControlSessionException: if the remote peer has died unexpectedly """ _fake_hostname = None @@ -1173,8 +1179,8 @@ class X2GoControlSession(paramiko.SSHClient): """\ Drop an associated terminal session. - @param terminal_session: the terminal session object to remove from the list of associated terminals - @type terminal_session: C{X2GoTerminalSession*} + :param terminal_session: the terminal session object to remove from the list of associated terminals + :type terminal_session: C{X2GoTerminalSession*} """ for t_name in list(self.associated_terminals.keys()): @@ -1188,8 +1194,9 @@ class X2GoControlSession(paramiko.SSHClient): Disconnect this control session from the remote server. - @return: report success or failure after having disconnected - @rtype: C{bool} + :returns: report success or failure after having disconnected + + :rtype: C{bool} """ if self.associated_terminals: @@ -1252,8 +1259,9 @@ class X2GoControlSession(paramiko.SSHClient): Test if the remote home directory exists. - @return: C{True} if the home directory exists, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if the home directory exists, C{False} otherwise + + :rtype: C{bool} """ (_stdin, _stdout, _stderr) = self._x2go_exec_command('stat -tL "%s"' % self._x2go_remote_home, loglevel=log.loglevel_DEBUG) @@ -1267,8 +1275,9 @@ class X2GoControlSession(paramiko.SSHClient): Test if the connection to the remote X2Go server is still alive. - @return: C{True} if the connection is still alive, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if the connection is still alive, C{False} otherwise + + :rtype: C{bool} """ try: @@ -1284,8 +1293,9 @@ class X2GoControlSession(paramiko.SSHClient): Test if the connection to the remote X2Go server died on the way. - @return: C{True} if the connection has died, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if the connection has died, C{False} otherwise + + :rtype: C{bool} """ return self.session_died @@ -1293,26 +1303,26 @@ class X2GoControlSession(paramiko.SSHClient): def get_published_applications(self, lang=None, refresh=False, raw=False, very_raw=False, max_no_submenus=defaults.PUBAPP_MAX_NO_SUBMENUS): """\ Retrieve the menu tree of published applications from the remote X2Go server. - + The C{raw} option lets this method return a C{list} of C{dict} elements. Each C{dict} elements has a C{desktop} key containing a shortened version of the text output of a .desktop file and an C{icon} key which contains the desktop base64-encoded icon data. - + The {very_raw} lets this method return the output of the C{x2gogetapps} script as is. - @param lang: locale/language identifier (Default value = None) - @type lang: C{str} - @param refresh: force reload of the menu tree from X2Go server (Default value = False) - @type refresh: C{bool} - @param raw: retrieve a raw output of the server list of published applications (Default value = False) - @type raw: C{bool} - @param very_raw: retrieve a very raw output of the server list of published applications (Default value = False) - @type very_raw: C{bool} - @param max_no_submenus: Number of applications before applications are put into XDG category submenus + :param lang: locale/language identifier (Default value = None) + :type lang: C{str} + :param refresh: force reload of the menu tree from X2Go server (Default value = False) + :type refresh: C{bool} + :param raw: retrieve a raw output of the server list of published applications (Default value = False) + :type raw: C{bool} + :param very_raw: retrieve a very raw output of the server list of published applications (Default value = False) + :type very_raw: C{bool} + :param max_no_submenus: Number of applications before applications are put into XDG category submenus (Default value = defaults.PUBAPP_MAX_NO_SUBMENUS) - @type max_no_submenus: C{int} - @return: an i18n capable menu tree packed as a Python dictionary - @rtype: C{list} + :type max_no_submenus: C{int} + :returns: an i18n capable menu tree packed as a Python dictionary + :rtype: C{list} """ self._already_querying_published_applications.acquire() @@ -1491,18 +1501,19 @@ class X2GoControlSession(paramiko.SSHClient): def start(self, **kwargs): """\ Start a new X2Go session. - + The L{X2GoControlSession.start()} method accepts any parameter that can be passed to any of the C{X2GoTerminalSession} backend class constructors. - @param kwargs: parameters that get passed through to the control session's + :param kwargs: parameters that get passed through to the control session's L{resume()} method, only the C{session_name} parameter will get removed before pass-through - @type kwargs: C{dict} - @return: return value of the cascaded L{resume()} method, denoting the success or failure + :type kwargs: C{dict} + :param **kwargs: + :returns: return: return value of the cascaded L{resume()} method, denoting the success or failure of the session startup - @rtype: C{bool} + :rtype: C{bool} """ if 'session_name' in list(kwargs.keys()): @@ -1512,20 +1523,21 @@ class X2GoControlSession(paramiko.SSHClient): def resume(self, session_name=None, session_instance=None, session_list=None, **kwargs): """\ Resume a running/suspended X2Go session. - + The L{X2GoControlSession.resume()} method accepts any parameter that can be passed to any of the C{X2GoTerminalSession*} backend class constructors. - @param session_name: the X2Go session name (Default value = None) - @type session_name: C{str} - @param session_instance: a Python X2Go session instance (Default value = None) - @type session_instance: L{X2GoSession} - @param session_list: (Default value = None) - @param kwargs: catch any non-defined param in kwargs - @type kwargs: C{dict} - @return: True if the session could be successfully resumed - @rtype: C{bool} - @raise X2GoUserException: if the remote user is not allowed to launch/resume X2Go sessions. + :param session_name: the X2Go session name (Default value = None) + :type session_name: C{str} + :param session_instance: a Python X2Go session instance (Default value = None) + :type session_instance: L{X2GoSession} + :param session_list: Default value = None) + :param kwargs: catch any non-defined param in kwargs + :type kwargs: C{dict} + :param **kwargs: + :returns: True if the session could be successfully resumed + :rtype: C{bool} + :raises X2GoUserException: if the remote user is not allowed to launch/resume X2Go sessions. """ if self.get_transport() is not None: @@ -1583,19 +1595,20 @@ class X2GoControlSession(paramiko.SSHClient): Share another already running desktop session. Desktop sharing can be run in two different modes: view-only and full-access mode. - @param desktop: desktop ID of a sharable desktop in format C{<user>@<display>} (Default value = None) - @type desktop: C{str} - @param user: user name and display number can be given separately, here give the + :param desktop: desktop ID of a sharable desktop in format C{<user>@<display>} (Default value = None) + :type desktop: C{str} + :param user: user name and display number can be given separately, here give the name of the user who wants to share a session with you (Default value = None) - @type user: C{str} - @param display: user name and display number can be given separately, here give the + :type user: C{str} + :param display: user name and display number can be given separately, here give the number of the display that a user allows you to be shared with (Default value = None) - @type display: C{str} - @param share_mode: desktop sharing mode, 0 stands for VIEW-ONLY, 1 for FULL-ACCESS mode (Default value = 0) - @type share_mode: C{int} - @return: True if the session could be successfully shared - @rtype: C{bool} - @raise X2GoDesktopSharingException: if C{username} and C{dislpay} do not relate to a + :type display: C{str} + :param share_mode: desktop sharing mode, 0 stands for VIEW-ONLY, 1 for FULL-ACCESS mode (Default value = 0) + :type share_mode: C{int} + :param **kwargs: + :returns: True if the session could be successfully shared + :rtype: C{bool} + :raises X2GoDesktopSharingException: if C{username} and C{dislpay} do not relate to a sharable desktop session """ @@ -1617,14 +1630,14 @@ class X2GoControlSession(paramiko.SSHClient): List all desktop-like sessions of current user (or of users that have granted desktop sharing) on the connected server. - @param raw: if C{True}, the raw output of the server-side X2Go command + :param raw: if C{True}, the raw output of the server-side X2Go command C{x2golistdesktops} is returned. (Default value = False) - @type raw: C{bool} - @param maxwait: time in secs to wait for server query to reply (Default value = 20) - @type maxwait: C{int} - @return: a list of X2Go desktops available for sharing - @rtype: C{list} - @raise X2GoTimeOutException: on command execution timeouts, with the server-side C{x2golistdesktops} + :type raw: C{bool} + :param maxwait: time in secs to wait for server query to reply (Default value = 20) + :type maxwait: C{int} + :returns: a list of X2Go desktops available for sharing + :rtype: C{list} + :raises X2GoTimeOutException: on command execution timeouts, with the server-side C{x2golistdesktops} command this can sometimes happen. Make sure you ignore these time-outs and to try again """ @@ -1660,16 +1673,16 @@ class X2GoControlSession(paramiko.SSHClient): """\ List all mounts for a given session of the current user on the connected server. - @param session_name: name of a session to query a list of mounts for - @type session_name: C{str} - @param raw: if C{True}, the raw output of the server-side X2Go command + :param session_name: name of a session to query a list of mounts for + :type session_name: C{str} + :param raw: if C{True}, the raw output of the server-side X2Go command C{x2golistmounts} is returned. (Default value = False) - @type raw: C{bool} - @param maxwait: stop processing C{x2golistmounts} after C{<maxwait>} seconds (Default value = 20) - @type maxwait: C{int} - @return: a list of client-side mounts for X2Go session C{<session_name>} on the server - @rtype: C{list} - @raise X2GoTimeOutException: on command execution timeouts, queries with the server-side + :type raw: C{bool} + :param maxwait: stop processing C{x2golistmounts} after C{<maxwait>} seconds (Default value = 20) + :type maxwait: C{int} + :returns: a list of client-side mounts for X2Go session C{<session_name>} on the server + :rtype: C{list} + :raises X2GoTimeOutException: on command execution timeouts, queries with the server-side C{x2golistmounts} query should normally be processed quickly, a time-out may hint that the control session has lost its connection to the X2Go server @@ -1704,14 +1717,14 @@ class X2GoControlSession(paramiko.SSHClient): """\ List all sessions of current user on the connected server. - @param raw: if C{True}, the raw output of the server-side X2Go command + :param raw: if C{True}, the raw output of the server-side X2Go command C{x2golistsessions} is returned. (Default value = False) - @type raw: C{bool} - @return: normally an instance of a C{X2GoServerSessionList*} backend is returned. However, + :type raw: C{bool} + :returns: normally an instance of a C{X2GoServerSessionList*} backend is returned. However, if the raw argument is set, the plain text output of the server-side C{x2golistsessions} command is returned - @rtype: C{X2GoServerSessionList} instance or str - @raise X2GoControlSessionException: on command execution timeouts, if this happens the control session will + :rtype: C{X2GoServerSessionList} instance or str + :raises X2GoControlSessionException: on command execution timeouts, if this happens the control session will be interpreted as disconnected due to connection loss """ @@ -1779,10 +1792,10 @@ class X2GoControlSession(paramiko.SSHClient): Find X2Go terminals that have previously been started by the connected user on the remote X2Go server and terminate them. - @param destroy_terminals: destroy the terminal session instances after cleanup (Default value = True) - @type destroy_terminals: C{bool} - @param published_applications: also clean up published applications providing sessions (Default value = False) - @type published_applications: C{bool} + :param destroy_terminals: destroy the terminal session instances after cleanup (Default value = True) + :type destroy_terminals: C{bool} + :param published_applications: also clean up published applications providing sessions (Default value = False) + :type published_applications: C{bool} """ session_list = self.list_sessions() @@ -1807,8 +1820,9 @@ class X2GoControlSession(paramiko.SSHClient): is: if it has a valid Paramiko/SSH transport object). - @return: X2Go session connected? - @rtype: C{bool} + :returns: X2Go session connected? + + :rtype: C{bool} """ return self.get_transport() is not None and self.get_transport().is_authenticated() @@ -1818,10 +1832,10 @@ class X2GoControlSession(paramiko.SSHClient): Returns C{True} if the given X2Go session is in running state, C{False} else. - @param session_name: X2Go name of the session to be queried - @type session_name: C{str} - @return: X2Go session running? If C{<session_name>} is not listable by the L{list_sessions()} method then C{None} is returned - @rtype: C{bool} or C{None} + :param session_name: X2Go name of the session to be queried + :type session_name: C{str} + :returns: X2Go session running? If C{<session_name>} is not listable by the L{list_sessions()} method then C{None} is returned + :rtype: C{bool} or C{None} """ session_infos = self.list_sessions() @@ -1834,10 +1848,10 @@ class X2GoControlSession(paramiko.SSHClient): Returns C{True} if the given X2Go session is in suspended state, C{False} else. - @param session_name: X2Go name of the session to be queried - @type session_name: C{str} - @return: X2Go session suspended? If C{<session_name>} is not listable by the L{list_sessions()} method then C{None} is returned - @rtype: C{bool} or C{None} + :param session_name: X2Go name of the session to be queried + :type session_name: C{str} + :returns: X2Go session suspended? If C{<session_name>} is not listable by the L{list_sessions()} method then C{None} is returned + :rtype: C{bool} or C{None} """ session_infos = self.list_sessions() @@ -1849,13 +1863,13 @@ class X2GoControlSession(paramiko.SSHClient): """\ Returns C{True} if the X2Go session with name C{<session_name>} has been seen by this control session and--in the meantime--has been terminated. - + If C{<session_name>} has not been seen, yet, the method will return C{None}. - @param session_name: X2Go name of the session to be queried - @type session_name: C{str} - @return: X2Go session has terminated? - @rtype: C{bool} or C{None} + :param session_name: X2Go name of the session to be queried + :type session_name: C{str} + :returns: X2Go session has terminated? + :rtype: C{bool} or C{None} """ session_infos = self.list_sessions() @@ -1875,10 +1889,10 @@ class X2GoControlSession(paramiko.SSHClient): Suspend X2Go session with name C{<session_name>} on the connected server. - @param session_name: X2Go name of the session to be suspended - @type session_name: C{str} - @return: C{True} if the session could be successfully suspended - @rtype: C{bool} + :param session_name: X2Go name of the session to be suspended + :type session_name: C{str} + :returns: C{True} if the session could be successfully suspended + :rtype: C{bool} """ _ret = False @@ -1911,12 +1925,12 @@ class X2GoControlSession(paramiko.SSHClient): Terminate X2Go session with name C{<session_name>} on the connected server. - @param session_name: X2Go name of the session to be terminated - @type session_name: C{str} - @param destroy_terminals: destroy all terminal sessions associated to this control session (Default value = True) - @type destroy_terminals: C{bool} - @return: C{True} if the session could be successfully terminated - @rtype: C{bool} + :param session_name: X2Go name of the session to be terminated + :type session_name: C{str} + :param destroy_terminals: destroy all terminal sessions associated to this control session (Default value = True) + :type destroy_terminals: C{bool} + :returns: C{True} if the session could be successfully terminated + :rtype: C{bool} """ diff --git a/x2go/backends/info/plain.py b/x2go/backends/info/plain.py index 2d02596..659a177 100644 --- a/x2go/backends/info/plain.py +++ b/x2go/backends/info/plain.py @@ -59,8 +59,8 @@ class X2GoServerSessionInfo(object): """\ Parse a single line of X2Go's listsessions output. - @param x2go_output: output from ,,x2golistsessions'' command (as list of strings/lines) - @type x2go_output: C{list} + :param x2go_output: output from ,,x2golistsessions'' command (as list of strings/lines) + :type x2go_output: C{list} """ try: @@ -102,8 +102,9 @@ class X2GoServerSessionInfo(object): Detect from session info if this session is a published applications provider. - @return: returns C{True} if this session is a published applications provider - @rtype: C{bool} + :returns: returns C{True} if this session is a published applications provider + + :rtype: C{bool} """ return bool(re.match('.*_stRPUBLISHED_.*', self.name)) @@ -113,8 +114,9 @@ class X2GoServerSessionInfo(object): Is this session running? - @return: C{True} if the session is running, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if the session is running, C{False} otherwise + + :rtype: C{bool} """ return self.status == 'R' @@ -124,8 +126,9 @@ class X2GoServerSessionInfo(object): Get the session type (i.e. 'D', 'R', 'S' or 'P'). - @return: session type - @rtype: C{str} + :returns: session type + + :rtype: C{str} """ cmd = self.name.split('_')[1] @@ -140,8 +143,9 @@ class X2GoServerSessionInfo(object): Get the share mode of a shadow session. - @return: share mode (0: view-only, 1: full access), C{None} when used for non-desktop-sharing sessions - @rtype: C{str} + :returns: share mode (0: view-only, 1: full access), C{None} when used for non-desktop-sharing sessions + + :rtype: C{str} """ share_mode = None @@ -156,8 +160,9 @@ class X2GoServerSessionInfo(object): Is this session suspended? - @return: C{True} if the session is suspended, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if the session is suspended, C{False} otherwise + + :rtype: C{bool} """ return self.status == 'S' @@ -167,8 +172,9 @@ class X2GoServerSessionInfo(object): Is this session a desktop session? - @return: C{True} if this session is a desktop session, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if this session is a desktop session, C{False} otherwise + + :rtype: C{bool} """ return self.get_session_type() == 'D' @@ -177,8 +183,8 @@ class X2GoServerSessionInfo(object): """\ Parse x2gostartagent output. - @param x2go_output: output from ,,x2gostartagent'' command (as list of strings/lines) - @type x2go_output: C{list} + :param x2go_output: output from ,,x2gostartagent'' command (as list of strings/lines) + :type x2go_output: C{list} """ try: @@ -220,17 +226,17 @@ class X2GoServerSessionInfo(object): """\ Setup a a session info data block, includes parsing of X2Go server's C{x2gostartagent} stdout values. - @param x2go_output: X2Go server's C{x2gostartagent} command output, each value + :param x2go_output: X2Go server's C{x2gostartagent} command output, each value separated by a newline character. - @type x2go_output: str - @param username: session user name (Default value = '') - @type username: str - @param hostname: hostname of X2Go server (Default value = '') - @type hostname: str - @param local_container: X2Go client session directory for config files, cache and session logs (Default value = '') - @type local_container: str - @param remote_container: X2Go server session directory for config files, cache and session logs (Default value = '') - @type remote_container: str + :type x2go_output: str + :param username: session user name (Default value = '') + :type username: str + :param hostname: hostname of X2Go server (Default value = '') + :type hostname: str + :param local_container: X2Go client session directory for config files, cache and session logs (Default value = '') + :type local_container: str + :param remote_container: X2Go server session directory for config files, cache and session logs (Default value = '') + :type remote_container: str """ self.protect() @@ -260,6 +266,7 @@ class X2GoServerSessionInfo(object): """\ Check if this session info data structure is Write-protected. + """ return self.protected @@ -268,8 +275,9 @@ class X2GoServerSessionInfo(object): Retrieve the session's status from this session info data structure. - @return: session status - @rtype: C{str} + :returns: session status + + :rtype: C{str} """ return self.status @@ -302,8 +310,8 @@ class X2GoServerSessionInfo(object): """\ Update all properties of a L{X2GoServerSessionInfo} object. - @param session_info: a provided session info data structure - @type session_info: C{X2GoServerSessionInfo*} + :param session_info: a provided session info data structure + :type session_info: C{X2GoServerSessionInfo*} """ if type(session_info) == type(self): @@ -357,8 +365,8 @@ class X2GoServerSessionList(object): """\ Set the sessions property directly by parsing a complete data structure. - @param sessions: set this instance's list of sessions directly - @type sessions: C{dict} + :param sessions: set this instance's list of sessions directly + :type sessions: C{dict} """ self.sessions = sessions @@ -367,10 +375,10 @@ class X2GoServerSessionList(object): """\ Retrieve the session information for C{<session_name>}. - @param session_name: the queried session name - @type session_name: C{str} - @return: the session info of C{<session_name>} - @rtype: C{X2GoServerSessionInfo*} or C{None} + :param session_name: the queried session name + :type session_name: C{str} + :returns: the session info of C{<session_name>} + :rtype: C{X2GoServerSessionInfo*} or C{None} """ try: @@ -382,12 +390,12 @@ class X2GoServerSessionList(object): """\ Find session with a given display number on a given host. - @param property_name: match a session based on this property name - @type property_name: C{str} - @param value: the resulting session has to match this value for C{<property_name>} - @type value: C{str} - @param hostname: the result has to match this hostname (Default value = None) - @type hostname: C{str} + :param property_name: match a session based on this property name + :type property_name: C{str} + :param value: the resulting session has to match this value for C{<property_name>} + :type value: C{str} + :param hostname: the result has to match this hostname (Default value = None) + :type hostname: C{str} """ if property_name == 'display': diff --git a/x2go/backends/printing/file.py b/x2go/backends/printing/file.py index 4df2c88..d2f2bd6 100644 --- a/x2go/backends/printing/file.py +++ b/x2go/backends/printing/file.py @@ -68,11 +68,11 @@ class X2GoClientPrinting(inifiles.X2GoIniFile): L{x2go.backends.printing.file.X2GoClientPrinting} provides access to the X2Go ini-like file »printing« as stored in C{~/.x2goclient/printing} resp. globally C{/etc/x2goclient/printing}. - + An instance of L{x2go.backends.printing.file.X2GoClientPrinting} is created on each incoming print job. This facilitates that on every print job the print action for this job is derived from the »printing« configuration file. - + Thus, changes on the file are active for the next incoming print job. @@ -136,11 +136,13 @@ class X2GoClientPrinting(inifiles.X2GoIniFile): def print_action(self): """\ Return the print action described by the »printing« configuration file. - + This method has property status and wraps around the L{get_print_action} - @return: Returns the print action object - @rtype: C{obj} or C{str} + + :returns: Returns the print action object + + :rtype: C{obj} or C{str} """ return self.get_print_action() @@ -149,14 +151,14 @@ class X2GoClientPrinting(inifiles.X2GoIniFile): """\ Return the print action described by the »printing« configuration file. - @param reload: reload the configuration file before retrieving the print action? (Default value = False) - @type reload: C{bool} - @param reinit: re-detect the print action from what is stored in cache? (Default value = False) - @type reinit: C{bool} - @param return_name: return the print action name, not the class (Default value = False) - @type return_name: C{bool} - @return: the configured print action - @rtype: C{obj} or C{str} + :param reload: reload the configuration file before retrieving the print action? (Default value = False) + :type reload: C{bool} + :param reinit: re-detect the print action from what is stored in cache? (Default value = False) + :type reinit: C{bool} + :param return_name: return the print action name, not the class (Default value = False) + :type return_name: C{bool} + :returns: the configured print action + :rtype: C{obj} or C{str} """ if reload: @@ -174,11 +176,11 @@ class X2GoClientPrinting(inifiles.X2GoIniFile): """\ Retrieve a printing property as mapped by the L{_print_property_map} dictionary. - @param print_property: a printing property - @type print_property: C{str} - @return: the stored value for C{<print_property>} - @rtype: C{str} - @raise X2GoClientPrintingException: if the printing property does not exist + :param print_property: a printing property + :type print_property: C{str} + :returns: the stored value for C{<print_property>} + :rtype: C{str} + :raises X2GoClientPrintingException: if the printing property does not exist """ if print_property in list(_print_property_map.keys()): @@ -192,11 +194,11 @@ class X2GoClientPrinting(inifiles.X2GoIniFile): """\ Set a printing property as mapped by the L{_print_property_map} dictionary. - @param print_property: a printing property - @type print_property: C{str} - @param value: the value to be stored as C{<print_property>} - @type value: C{str} - @raise X2GoClientPrintingException: if the printing property does not exist or if there is a type mismatch + :param print_property: a printing property + :type print_property: C{str} + :param value: the value to be stored as C{<print_property>} + :type value: C{str} + :raises X2GoClientPrintingException: if the printing property does not exist or if there is a type mismatch """ if print_property in list(_print_property_map.keys()): @@ -217,10 +219,11 @@ class X2GoClientPrinting(inifiles.X2GoIniFile): itself (DIALOG, PDFVIEW, PDFSAVE, PRINT or PRINTCMD) and related printing properties as mapped by the L{_print_property_map} dictionary. - @param print_action: the print action name - @type print_action: C{str} - @param print_properties: the printing properties to set for the given print action - @type print_properties: C{dict} + :param print_action: the print action name + :type print_action: C{str} + :param print_properties: the printing properties to set for the given print action + :type print_properties: C{dict} + :param **print_properties: """ if print_action == 'DIALOG': diff --git a/x2go/backends/printing/winreg.py b/x2go/backends/printing/winreg.py index 0dde572..75109bd 100644 --- a/x2go/backends/printing/winreg.py +++ b/x2go/backends/printing/winreg.py @@ -46,11 +46,11 @@ class X2GoClientPrinting(object): """\ L{x2go.backends.printing.winreg.X2GoClientPrinting} provides access to the Windows registry based configuration of the X2Go client printing setup. - + An instance of L{x2go.backends.printing.winreg.X2GoClientPrinting} is created on each incoming print job. This facilitates that on every print job the print action for this job is derived from the »printing« configuration file. - + Thus, changes on the file are active for the next incoming print job. diff --git a/x2go/backends/profiles/base.py b/x2go/backends/profiles/base.py index 50453b2..fde4abc 100644 --- a/x2go/backends/profiles/base.py +++ b/x2go/backends/profiles/base.py @@ -102,8 +102,8 @@ class X2GoSessionProfiles(object): dynamic session profile data). On new connections, it is recommented to (re-)initialize these caches. - @param profile_id_or_name: profile ID or profile name - @type profile_id_or_name: C{str} + :param profile_id_or_name: profile ID or profile name + :type profile_id_or_name: C{str} """ profile_id = self.check_profile_id_or_name(profile_id_or_name) @@ -116,8 +116,8 @@ class X2GoSessionProfiles(object): Inherit from this class to (re-)initialize profile ID based cache storage. - @param profile_id: profile ID - @type profile_id: C{str} + :param profile_id: profile ID + :type profile_id: C{str} """ pass @@ -128,8 +128,9 @@ class X2GoSessionProfiles(object): backend and make it available for this class. - @return: a set of session profiles - @rtype: C{dict} + :returns: a set of session profiles + + :rtype: C{dict} """ self.session_profiles = self. _populate_session_profiles() @@ -158,8 +159,9 @@ class X2GoSessionProfiles(object): populating a set of session profile via this method. - @return: a set of session profiles - @rtype: C{dict} + :returns: a set of session profiles + + :rtype: C{dict} """ return {} @@ -168,12 +170,12 @@ class X2GoSessionProfiles(object): """\ Detect a human readable session profile type from the session profile configuration. - @param profile_id_or_name: profile ID or profile name - @type profile_id_or_name: C{str} - @param force: re-detect the meta type, otherwise use a cached result (Default value = False) - @type force: C{bool} - @return: the profile ID's / name's meta type - @rtype: C{str} + :param profile_id_or_name: profile ID or profile name + :type profile_id_or_name: C{str} + :param force: re-detect the meta type, otherwise use a cached result (Default value = False) + :type force: C{bool} + :returns: the profile ID's / name's meta type + :rtype: C{str} """ _profile_id = self.check_profile_id_or_name(profile_id_or_name) @@ -211,14 +213,14 @@ class X2GoSessionProfiles(object): """\ Check if a given profile name (or ID) is mutable or not. - @param profile_id_or_name: profile name or profile ID (Default value = None) - @type profile_id_or_name: C{str} - @param profile_id: if the profile ID is known, pass it in directly and skip + :param profile_id_or_name: profile name or profile ID (Default value = None) + :type profile_id_or_name: C{str} + :param profile_id: if the profile ID is known, pass it in directly and skip the L{check_profile_id_or_name()} call (Default value = None) - @type profile_id: C{str} - @return: C{True} if the session profile of the specified name/ID is mutable - @rtype: C{bool} - @raise X2GoProfileException: if no such session profile exists + :type profile_id: C{str} + :returns: C{True} if the session profile of the specified name/ID is mutable + :rtype: C{bool} + :raises X2GoProfileException: if no such session profile exists """ try: @@ -232,10 +234,10 @@ class X2GoSessionProfiles(object): Inherit from this base class and provide your own decision making code here if a given profile ID is mutable or not. - @param profile_id: profile ID - @type profile_id: C{str} - @return: C{True} if the session profile of the specified ID is mutable - @rtype: C{bool} + :param profile_id: profile ID + :type profile_id: C{str} + :returns: C{True} if the session profile of the specified ID is mutable + :rtype: C{bool} """ return False @@ -246,8 +248,9 @@ class X2GoSessionProfiles(object): mutable session profiles. - @return: list of mutable profiles - @rtype: C{list} + :returns: list of mutable profiles + + :rtype: C{list} """ return self._supports_mutable_profiles() @@ -259,8 +262,9 @@ class X2GoSessionProfiles(object): session profiles or not. - @return: list of mutable profiles - @rtype: C{list} + :returns: list of mutable profiles + + :rtype: C{list} """ return False @@ -270,8 +274,9 @@ class X2GoSessionProfiles(object): List all mutable session profiles. - @return: List up all session profile IDs of mutable session profiles. - @rtype: C{bool} + :returns: List up all session profile IDs of mutable session profiles. + + :rtype: C{bool} """ return [ p for p in self.profile_ids if self._is_mutable(p) ] @@ -281,8 +286,9 @@ class X2GoSessionProfiles(object): Store session profile data to the storage backend. - @return: C{True} if the write process has been successfull, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if the write process has been successfull, C{False} otherwise + + :rtype: C{bool} """ # then update profile IDs for profiles that have a renamed host attribute... @@ -313,10 +319,10 @@ class X2GoSessionProfiles(object): """\ Get the data type for a specific session profile option. - @param option: the option to get the data type for - @type option: will be detected by this method - @return: the data type of C{option} - @rtype: C{type} + :param option: the option to get the data type for + :type option: will be detected by this method + :returns: the data type of C{option} + :rtype: C{type} """ try: @@ -328,14 +334,14 @@ class X2GoSessionProfiles(object): """\ The configuration options for a single session profile. - @param profile_id_or_name: either profile ID or profile name is accepted (Default value = None) - @type profile_id_or_name: C{str} - @param parameter: if specified, only the value for the given parameter is returned (Default value = None) - @type parameter: C{str} - @param profile_id: profile ID (faster than specifying C{profile_id_or_name}) (Default value = None) - @type profile_id: C{str} - @return: the session profile configuration for the given profile ID (or name) - @rtype: C{dict} + :param profile_id_or_name: either profile ID or profile name is accepted (Default value = None) + :type profile_id_or_name: C{str} + :param parameter: if specified, only the value for the given parameter is returned (Default value = None) + :type parameter: C{str} + :param profile_id: profile ID (faster than specifying C{profile_id_or_name}) (Default value = None) + :type profile_id: C{str} + :returns: the session profile configuration for the given profile ID (or name) + :rtype: C{dict} """ _profile_id = profile_id or self.check_profile_id_or_name(profile_id_or_name) @@ -379,8 +385,9 @@ class X2GoSessionProfiles(object): Return a default session profile. - @return: default session profile - @rtype: C{dict} + :returns: default session profile + + :rtype: C{dict} """ return copy.deepcopy(self.defaultSessionProfile) @@ -389,10 +396,10 @@ class X2GoSessionProfiles(object): """\ Does a session profile of a given profile ID or profile name exist? - @param profile_id_or_name: profile ID or profile name - @type profile_id_or_name: C{str} - @return: C{True} if there is such a session profile, C{False} otherwise - @rtype: C{bool} + :param profile_id_or_name: profile ID or profile name + :type profile_id_or_name: C{str} + :returns: C{True} if there is such a session profile, C{False} otherwise + :rtype: C{bool} """ try: @@ -423,8 +430,9 @@ class X2GoSessionProfiles(object): a list of session profile IDs from the storage backend via this method. - @return: list of available session profile IDs - @rtype: C{list} + :returns: list of available session profile IDs + + :rtype: C{list} """ return [] @@ -433,10 +441,10 @@ class X2GoSessionProfiles(object): """\ Does a session profile of a given profile ID exist? (Faster than L{has_profile()}.) - @param profile_id: profile ID - @type profile_id: C{str} - @return: C{True} if there is such a session profile, C{False} otherwise - @rtype: C{bool} + :param profile_id: profile ID + :type profile_id: C{str} + :returns: C{True} if there is such a session profile, C{False} otherwise + :rtype: C{bool} """ return str(profile_id) in self.profile_ids @@ -456,10 +464,10 @@ class X2GoSessionProfiles(object): """\ Does a session profile of a given profile name exist? (Faster than L{has_profile()}.) - @param profile_name: profile name - @type profile_name: C{str} - @return: C{True} if there is such a session profile, C{False} otherwise - @rtype: C{bool} + :param profile_name: profile name + :type profile_name: C{str} + :returns: C{True} if there is such a session profile, C{False} otherwise + :rtype: C{bool} """ return str(profile_name) in self.profile_names @@ -468,10 +476,10 @@ class X2GoSessionProfiles(object): """\ Convert profile name to profile ID. - @param profile_name: profile name - @type profile_name: C{str} - @return: profile ID - @rtype: C{str} + :param profile_name: profile name + :type profile_name: C{str} + :returns: profile ID + :rtype: C{str} """ _profile_ids = [ p for p in self.profile_ids if self._cached_profile_ids[p] == profile_name ] @@ -486,10 +494,10 @@ class X2GoSessionProfiles(object): """\ Convert profile ID to profile name. - @param profile_id: profile ID - @type profile_id: C{str} - @return: profile name - @rtype: C{str} + :param profile_id: profile ID + :type profile_id: C{str} + :returns: profile name + :rtype: C{str} """ try: @@ -502,14 +510,15 @@ class X2GoSessionProfiles(object): """\ Add a new session profile. - @param profile_id: a custom profile ID--if left empty a profile ID will be auto-generated (Default value = None) - @type profile_id: C{str} - @param kwargs: session profile options for this new session profile - @type kwargs: C{dict} - @param force_add: enforce adding of the given profile (Default value = False) - @type force_add: C{bool} - @return: the (auto-generated) profile ID of the new session profile - @rtype: C{str} + :param profile_id: a custom profile ID--if left empty a profile ID will be auto-generated (Default value = None) + :type profile_id: C{str} + :param kwargs: session profile options for this new session profile + :type kwargs: C{dict} + :param force_add: enforce adding of the given profile (Default value = False) + :type force_add: C{bool} + :param **kwargs: + :returns: the (auto-generated) profile ID of the new session profile + :rtype: C{str} """ if profile_id is None or profile_id in self.profile_ids: @@ -540,8 +549,8 @@ class X2GoSessionProfiles(object): """\ Delete a session profile from the configuration file. - @param profile_id_or_name: profile ID or profile name - @type profile_id_or_name: C{str} + :param profile_id_or_name: profile ID or profile name + :type profile_id_or_name: C{str} """ _profile_id = self.check_profile_id_or_name(profile_id_or_name) @@ -557,8 +566,8 @@ class X2GoSessionProfiles(object): Inherit from this class and provide a way for actually deleting a complete session profile from the storage backend via this method. - @param profile_id: Profile ID of the profile to be deleted - @type profile_id: C{str} + :param profile_id: Profile ID of the profile to be deleted + :type profile_id: C{str} """ pass @@ -567,15 +576,15 @@ class X2GoSessionProfiles(object): """\ Update a value in a session profile. - @param profile_id_or_name: the profile ID - @type profile_id_or_name: C{str} - @param option: the session profile option of the given profile ID - @type option: C{str} - @param value: the value to update the session profile option with - @type value: any type, depends on the session profile option - @param profile_id: if the profile ID is known, pass it in directly and skip + :param profile_id_or_name: the profile ID + :type profile_id_or_name: C{str} + :param option: the session profile option of the given profile ID + :type option: C{str} + :param value: the value to update the session profile option with + :type value: any type, depends on the session profile option + :param profile_id: if the profile ID is known, pass it in directly and skip the L{check_profile_id_or_name()} call (Default value = None) - @type profile_id: C{str} + :type profile_id: C{str} """ try: @@ -623,12 +632,12 @@ class X2GoSessionProfiles(object): Inherit from this class and provide for actually updating a session profile's value in the storage backend via this method. - @param profile_id: the profile ID of the profile to be updated - @type profile_id: C{str} - @param option: the option to be updated - @type option: C{str} - @param value: the value to be updated for the given option - @type value: C{str} or C{list} or C{int} or C{bool} + :param profile_id: the profile ID of the profile to be updated + :type profile_id: C{str} + :param option: the option to be updated + :type option: C{str} + :param value: the value to be updated for the given option + :type value: C{str} or C{list} or C{int} or C{bool} """ pass @@ -637,11 +646,11 @@ class X2GoSessionProfiles(object): """\ Detect the profile ID from a given string which maybe profile ID or profile name. - @param profile_id_or_name: profile ID or profile name - @type profile_id_or_name: C{str} - @return: profile ID - @rtype: C{str} - @raise X2GoProfileException: if no such session profile exists + :param profile_id_or_name: profile ID or profile name + :type profile_id_or_name: C{str} + :returns: profile ID + :rtype: C{str} + :raises X2GoProfileException: if no such session profile exists """ _profile_id = None @@ -661,12 +670,12 @@ class X2GoSessionProfiles(object): """\ Convert session profile options to L{X2GoSession} constructor method parameters. - @param profile_id_or_name: either profile ID or profile name is accepted (Default value = None) - @type profile_id_or_name: C{str} - @param profile_id: profile ID (fast than specifying C{profile_id_or_name}) (Default value = None) - @type profile_id: C{str} - @return: a dictionary of L{X2GoSession} constructor method parameters - @rtype: C{dict} + :param profile_id_or_name: either profile ID or profile name is accepted (Default value = None) + :type profile_id_or_name: C{str} + :param profile_id: profile ID (fast than specifying C{profile_id_or_name}) (Default value = None) + :type profile_id: C{str} + :returns: a dictionary of L{X2GoSession} constructor method parameters + :rtype: C{dict} """ _profile_id = profile_id or self.check_profile_id_or_name(profile_id_or_name) @@ -676,12 +685,12 @@ class X2GoSessionProfiles(object): """\ Get a single L{X2GoSession} parameter from a specific session profile. - @param profile_id_or_name: either profile ID or profile name is accepted - @type profile_id_or_name: C{str} - @param param: the parameter name in the L{X2GoSession} constructor method - @type param: C{str} - @return: the value of the session profile option represented by C{param} - @rtype: depends on the session profile option requested + :param profile_id_or_name: either profile ID or profile name is accepted + :type profile_id_or_name: C{str} + :param param: the parameter name in the L{X2GoSession} constructor method + :type param: C{str} + :returns: the value of the session profile option represented by C{param} + :rtype: depends on the session profile option requested """ return self.to_session_params(profile_id_or_name)[param] @@ -691,14 +700,14 @@ class X2GoSessionProfiles(object): Inherit from this class and provide a way for actually obtaining the value of a specific profile parameter. - @param profile_id: the profile's unique ID - @type profile_id: C{str} - @param option: the session profile option for which to retrieve its value - @type option: C{str} - @param key_type: type of the value to return - @type key_type: C{typeobject} - @return: value of a session profile parameter - @rtype: C{various types} + :param profile_id: the profile's unique ID + :type profile_id: C{str} + :param option: the session profile option for which to retrieve its value + :type option: C{str} + :param key_type: type of the value to return + :type key_type: C{typeobject} + :returns: value of a session profile parameter + :rtype: C{various types} """ return None @@ -708,10 +717,10 @@ class X2GoSessionProfiles(object): Inherit from this class and provide a way for actually obtaining a list of available profile options of a given session profile. - @param profile_id: the profile ID of the profile to operate on - @type profile_id: C{str} - @return: list of available option is the given session profile - @rtype: C{list} + :param profile_id: the profile ID of the profile to operate on + :type profile_id: C{str} + :returns: list of available option is the given session profile + :rtype: C{list} """ return [] @@ -720,11 +729,11 @@ class X2GoSessionProfiles(object): """\ Retrieve host name of the X2Go Server configured in a session profile. - @param profile_id: the profile's unique ID - @type profile_id: C{str} - @return: the host name of the X2Go Server configured by the session profile + :param profile_id: the profile's unique ID + :type profile_id: C{str} + :returns: the host name of the X2Go Server configured by the session profile of the given profile ID - @rtype: C{list} + :rtype: C{list} """ return str(self._get_server_hostname(profile_id)) @@ -734,11 +743,11 @@ class X2GoSessionProfiles(object): Inherit from this class and provide a way for actually obtaining a the server host name for a given profile ID. - @param profile_id: the profile's unique ID - @type profile_id: C{str} - @return: the host name of the X2Go Server configured by the session profile + :param profile_id: the profile's unique ID + :type profile_id: C{str} + :returns: the host name of the X2Go Server configured by the session profile of the given profile ID - @rtype: C{list} + :rtype: C{list} """ return 'localhost' @@ -747,11 +756,11 @@ class X2GoSessionProfiles(object): """\ Retrieve SSH port of the X2Go Server configured in a session profile. - @param profile_id: the profile's unique ID - @type profile_id: C{str} - @return: the SSH port of the X2Go Server configured by the session profile + :param profile_id: the profile's unique ID + :type profile_id: C{str} + :returns: the SSH port of the X2Go Server configured by the session profile of the given profile ID - @rtype: C{list} + :rtype: C{list} """ return self._get_server_port(profile_id) @@ -761,11 +770,11 @@ class X2GoSessionProfiles(object): Inherit from this class and provide a way for actually obtaining a the server SSH port for a given profile ID. - @param profile_id: the profile's unique ID - @type profile_id: C{str} - @return: the SSH port of the X2Go Server configured by the session profile + :param profile_id: the profile's unique ID + :type profile_id: C{str} + :returns: the SSH port of the X2Go Server configured by the session profile of the given profile ID - @rtype: C{list} + :rtype: C{list} """ return 22 @@ -774,10 +783,10 @@ class X2GoSessionProfiles(object): """\ If available, return a PKey (Paramiko/SSH private key) object. - @param profile_id: the profile's unique ID - @type profile_id: C{str} - @return: a Paramiko/SSH PKey object - @rtype: C{obj} + :param profile_id: the profile's unique ID + :type profile_id: C{str} + :returns: a Paramiko/SSH PKey object + :rtype: C{obj} """ return self._get_pkey_object(profile_id) @@ -787,8 +796,8 @@ class X2GoSessionProfiles(object): Inherit from this class and provide a way for actually providing such a PKey object. - @param profile_id: the profile ID for which to retrieve the PKey object - @type profile_id: C{str} + :param profile_id: the profile ID for which to retrieve the PKey object + :type profile_id: C{str} """ return None diff --git a/x2go/backends/profiles/file.py b/x2go/backends/profiles/file.py index 5c42389..c4a0761 100644 --- a/x2go/backends/profiles/file.py +++ b/x2go/backends/profiles/file.py @@ -40,21 +40,21 @@ import x2go.log as log class X2GoSessionProfiles(base.X2GoSessionProfiles, inifiles.X2GoIniFile): def __init__(self, config_files=_X2GO_SESSIONPROFILES_CONFIGFILES, session_profile_defaults=None, logger=None, loglevel=log.loglevel_DEFAULT, **kwargs): - """\ + """\ Retrieve X2Go session profiles from a file, typically C{~/.x2goclient/sessions}. - @param config_files: a list of config file locations, the first file name in this list the user has write access to will be the user configuration file - @type config_files: C{list} - @param session_profile_defaults: a default session profile - @type session_profile_defaults: C{dict} - @param logger: you can pass an L{X2GoLogger} object to the - L{x2go.backends.profiles.file.X2GoSessionProfiles} constructor - @type logger: L{X2GoLogger} instance - @param loglevel: if no L{X2GoLogger} object has been supplied a new one will be - constructed with the given loglevel - @type loglevel: C{int} - - """ + :param config_files: a list of config file locations, the first file name in this list the user has write access to will be the user configuration file + :type config_files: C{list} + :param session_profile_defaults: a default session profile + :type session_profile_defaults: C{dict} + :param logger: you can pass an L{X2GoLogger} object to the + L{x2go.backends.profiles.file.X2GoSessionProfiles} constructor + :type logger: L{X2GoLogger} instance + :param loglevel: if no L{X2GoLogger} object has been supplied a new one will be + constructed with the given loglevel + :type loglevel: C{int} + + """ # providing defaults for an X2GoSessionProfiles instance will---in the worst case---override your # existing sessions file in your home directory once you write the sessions back to file... inifiles.X2GoIniFile.__init__(self, config_files=config_files, logger=logger, loglevel=loglevel) @@ -65,12 +65,12 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles, inifiles.X2GoIniFile): Override the inifile class's get_type method due to the special layout of the session profile class. - @param section: INI file section - @type section: C{str} - @param key: key in INI file section - @type key: C{str} - @return: the data type of C{key} in C{section} - @rtype: C{type} + :param section: INI file section + :type section: C{str} + :param key: key in INI file section + :type key: C{str} + :returns: the data type of C{key} in C{section} + :rtype: C{type} """ # we have to handle the get_type method separately... @@ -82,8 +82,9 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles, inifiles.X2GoIniFile): profile configuration from a file in INI format. - @return: a set of session profiles - @rtype: C{dict} + :returns: a set of session profiles + + :rtype: C{dict} """ session_profiles = [ p for p in self.iniConfig.sections() if p not in self._non_profile_sections and p != 'none' ] diff --git a/x2go/backends/profiles/httpbroker.py b/x2go/backends/profiles/httpbroker.py index 77b09bf..60cd7f4 100644 --- a/x2go/backends/profiles/httpbroker.py +++ b/x2go/backends/profiles/httpbroker.py @@ -124,9 +124,9 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): Accessor for the class's C{broker_noauth} property. - @return: C{True} if the broker probably does not expect authentication. + :returns: C{True} if the broker probably does not expect authentication. - @rtype: C{bool} + :rtype: C{bool} """ return self.broker_noauth @@ -136,9 +136,9 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): Accessor for the class's C{broker_username} property. - @return: the username used for authentication against the session broker URL + :returns: the username used for authentication against the session broker URL - @rtype: C{str} + :rtype: C{str} """ return self.broker_username @@ -148,9 +148,9 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): Accessor for the class's C{broker_url} property. - @return: the session broker URL that was used at broker session instantiation + :returns: the session broker URL that was used at broker session instantiation - @rtype: C{str} + :rtype: C{str} """ return self.broker_url @@ -159,12 +159,12 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): """\ Mutator for the class's C{broker_url} property. - @param broker_url: A new broker URL to use with this instance. Format is + :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} + :type broker_url: C{str} + :returns: the session broker URL that was used at broker session instantiation + :rtype: C{str} """ self.broker_url = broker_url @@ -174,9 +174,9 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): Accessor of the class's {_broker_type} property. - @return: either C{http} or C{https}. + :returns: either C{http} or C{https}. - @rtype: C{str} + :rtype: C{str} """ return self._broker_type @@ -186,13 +186,13 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): 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 / + :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} + :returns: C{True} if authentication has been successful + :rtype: C{bool} + :raises X2GoBrokerConnectionException: Raised on any kind of connection / authentication failure. """ @@ -232,7 +232,7 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): 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. @@ -265,10 +265,10 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): valid. - @return: C{True} if the broker session has already been authenticated + :returns: C{True} if the broker session has already been authenticated and user credentials are known / valid - @rtype: C{bool} + :rtype: C{bool} """ if self._broker_auth_successful is None: @@ -284,9 +284,9 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): Obtain a session profile list from the X2Go Session Broker. - @return: session profiles as a Python dictionary. + :returns: session profiles as a Python dictionary. - @rtype: C{dict} + :rtype: C{dict} """ if self.broker_url is not None: @@ -327,11 +327,11 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): (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 + :param profile_id: profile ID of the selected session profile + :type profile_id: C{str} + :returns: session information (server, port, SSH keys, etc.) for a selected session profile (i.e. C{profile_id}) - @rtype: C{dict} + :rtype: C{dict} """ if self.broker_url is not None: @@ -379,9 +379,9 @@ class X2GoSessionProfiles(base.X2GoSessionProfiles): profile configuration from a file in INI format. - @return: a set of session profiles + :returns: a set of session profiles - @rtype: C{dict} + :rtype: C{dict} """ if self.is_broker_authenticated() and \ diff --git a/x2go/backends/proxy/base.py b/x2go/backends/proxy/base.py index 0dbcbb2..403fead 100644 --- a/x2go/backends/proxy/base.py +++ b/x2go/backends/proxy/base.py @@ -54,7 +54,7 @@ from x2go.defaults import X2GO_SESSIONS_ROOTDIR as _X2GO_SESSIONS_ROOTDIR class X2GoProxy(threading.Thread): """\ X2GoProxy is an abstract class for X2Go proxy connections. - + This class needs to be inherited from a concrete proxy class. Only currently available proxy class is: L{x2go.backends.proxy.nx3.X2GoProxy}. @@ -251,12 +251,12 @@ class X2GoProxy(threading.Thread): """\ Override this method to incorporate elements from C{proxy_options} into actual proxy subprocess execution. - + This method (if overridden) should (by design) never fail nor raise an exception. Make sure to catch all possible errors appropriately. - + If you want to log ignored proxy_options then - + 1. remove processed proxy_options from self.proxy_options 2. once you have finished processing the proxy_options call the parent class method L{x2go.backends.proxy.base.X2GoProxy.process_proxy_options()} @@ -278,9 +278,9 @@ class X2GoProxy(threading.Thread): Start the thread runner and wait for the proxy to come up. - @return: a subprocess instance that knows about the externally started proxy command. + :returns: a subprocess instance that knows about the externally started proxy command. - @rtype: C{obj} + :rtype: C{obj} """ threading.Thread.start(self) @@ -310,9 +310,9 @@ class X2GoProxy(threading.Thread): Check if a proxy instance is up and running. - @return: Proxy state, C{True} for proxy being up-and-running, C{False} otherwise + :returns: Proxy state, C{True} for proxy being up-and-running, C{False} otherwise - @rtype: C{bool} + :rtype: C{bool} """ return bool(self.proxy and self.proxy.poll() is None) and self.fw_tunnel.is_active diff --git a/x2go/backends/proxy/nx3.py b/x2go/backends/proxy/nx3.py index a514e48..0660667 100644 --- a/x2go/backends/proxy/nx3.py +++ b/x2go/backends/proxy/nx3.py @@ -38,7 +38,7 @@ from x2go.defaults import X2GOCLIENT_OS as _X2GOCLIENT_OS class X2GoProxy(base.X2GoProxy): """\ This L{X2GoProxy} class is a NX version 3 based X2Go proxy connection class. - + It basically fills L{x2go.backends.proxy.base.X2GoProxy} variables with sensible content. Its methods mostly wrap around the corresponding methods of the parent class. @@ -102,8 +102,8 @@ class X2GoProxy(base.X2GoProxy): """\ Update the local proxy socket on port changes due to already-bound-to local TCP/IP port sockets. - @param port: new local TCP/IP socket port - @type port: C{int} + :param port: new local TCP/IP socket port + :type port: C{int} """ @@ -138,9 +138,9 @@ class X2GoProxy(base.X2GoProxy): Start the thread runner and wait for the proxy to come up. - @return: a subprocess instance that knows about the externally started proxy command. + :returns: a subprocess instance that knows about the externally started proxy command. - @rtype: C{obj} + :rtype: C{obj} """ self.logger('starting local NX3 proxy...', loglevel=log.loglevel_INFO) diff --git a/x2go/backends/terminal/plain.py b/x2go/backends/terminal/plain.py index cf0c37f..e7a7e69 100644 --- a/x2go/backends/terminal/plain.py +++ b/x2go/backends/terminal/plain.py @@ -70,12 +70,12 @@ def _rewrite_cmd(cmd, params=None): Mechansim that rewrites X2Go server commands into something that gets understood by the server-side script C{x2goruncommand}. - @param cmd: the current command for execution (as found in the session profile parameter C{cmd}) - @type cmd: C{str} - @param params: an session paramter object (Default value = None) - @type params: L{X2GoSessionParams} - @return: the rewritten command for server-side execution - @rtype: C{str} + :param cmd: the current command for execution (as found in the session profile parameter C{cmd}) + :type cmd: C{str} + :param params: an session paramter object (Default value = None) + :type params: L{X2GoSessionParams} + :returns: the rewritten command for server-side execution + :rtype: C{str} """ # start with an empty string @@ -108,10 +108,10 @@ def _rewrite_blanks(cmd): """\ In command strings X2Go server scripts expect blanks being rewritten to ,,X2GO_SPACE_CHAR''. - @param cmd: command that has to be rewritten for passing to the server - @type cmd: C{str} - @return: the command with blanks rewritten to ,,X2GO_SPACE_CHAR'' - @rtype: C{str} + :param cmd: command that has to be rewritten for passing to the server + :type cmd: C{str} + :returns: the command with blanks rewritten to ,,X2GO_SPACE_CHAR'' + :rtype: C{str} """ # X2Go run command replace X2GO_SPACE_CHAR string with blanks @@ -131,17 +131,17 @@ class X2GoSessionParams(object): """\ Rewrite the X2Go session type, so that the X2Go server can understand it (C{desktop} -> C{D}, etc.). - + Also if the object's C{command} property is a known window manager, the session type will be set to 'D' (i.e. desktop). - @return: D' if session should probably a desktop session, + :returns: D' if session should probably a desktop session, 'R' for rootless sessions, 'P' for sessions providing published applications, and 'S' for desktop sharing sessions - @rtype: C{str} + :rtype: C{str} """ cmd = self.cmd @@ -177,10 +177,11 @@ class X2GoSessionParams(object): Update all properties in the object L{X2GoSessionParams} object from the passed on dictionary. - @param properties_to_be_updated: a dictionary with L{X2GoSessionParams} + :param properties_to_be_updated: a dictionary with L{X2GoSessionParams} property names as keys und their values to be update in L{X2GoSessionParams} object. - @type properties_to_be_updated: C{dict} + :type properties_to_be_updated: C{dict} + :param **properties_to_be_updated: """ for key in list(properties_to_be_updated.keys()): @@ -191,19 +192,19 @@ class X2GoSessionParams(object): class X2GoTerminalSession(object): """\ Class for managing X2Go terminal sessions on a remote X2Go server via Paramiko/SSH. - + With the L{x2go.backends.terminal.plain.X2GoTerminalSession} class you can start new X2Go sessions, resume suspended sessions or suspend resp. terminate currently running sessions on a connected X2Go server. - + An L{x2go.backends.terminal.plain.X2GoTerminalSession} object uses two main data structure classes: - + - L{X2GoSessionParams}: stores all parameters that have been passed to the constructor method. - + - C{X2GoServerSessionInfo*} backend class: when starting or resuming a session, an object of this class will be used to store all information retrieved from the X2Go server. - + The terminal session instance works closely together (i.e. depends on) a connected control session instance (e.g. L{x2go.backends.control.plain.X2GoControlSession}). You never should use either of them as a standalone instance. Both, control session and terminal session(s) get managed/controlled via L{X2GoSession} instances. @@ -462,8 +463,8 @@ class X2GoTerminalSession(object): """\ Create the server-side session root dir (normally ~/.x2go). - @param rootdir: server-side session root directory - @type rootdir: C{str} + :param rootdir: server-side session root directory + :type rootdir: C{str} """ try: @@ -498,9 +499,9 @@ class X2GoTerminalSession(object): Retrieve the X2Go session's name from the session info object. - @return: the session name + :returns: the session name - @rtype: C{str} + :rtype: C{str} """ return self.session_info.name @@ -510,9 +511,9 @@ class X2GoTerminalSession(object): Retrieve the X2Go session's session info object. - @return: the session info object + :returns: the session info object - @rtype: C{X2GoServerSessionInfo*} + :rtype: C{X2GoServerSessionInfo*} """ return self.session_info @@ -522,9 +523,9 @@ class X2GoTerminalSession(object): Retrieve the X2Go session's command as stored in the session parameter object. - @return: the session command + :returns: the session command - @rtype: C{str} + :rtype: C{str} """ return self.params.cmd @@ -534,9 +535,9 @@ class X2GoTerminalSession(object): Retrieve the X2Go session's session type as stored in the session parameter object. - @return: the session type + :returns: the session type - @rtype: C{str} + :rtype: C{str} """ return self.params.session_type @@ -544,14 +545,14 @@ class X2GoTerminalSession(object): def start_sound(self): """\ Initialize Paramiko/SSH reverse forwarding tunnel for X2Go sound. - + Currently supported audio protocols: - + - PulseAudio - Esound (not tested very much) - @raise X2GoControlSessionException: if the control session of this terminal session is not connected + :raises X2GoControlSessionException: if the control session of this terminal session is not connected """ _tunnel = None @@ -653,8 +654,8 @@ class X2GoTerminalSession(object): """\ Pause reverse SSH tunnel of name <name>. - @param name: tunnel name (either of C{sshfs}, C{snd}) - @type name: C{str} + :param name: tunnel name (either of C{sshfs}, C{snd}) + :type name: C{str} """ _tunnel = self.reverse_tunnels[self.session_info.name][name][1] @@ -682,7 +683,7 @@ class X2GoTerminalSession(object): Initialize X2Go print spooling. - @raise X2GoUserException: if the X2Go printing feature is not available to this user + :raises X2GoUserException: if the X2Go printing feature is not available to this user """ if not self.control_session.is_sshfs_available(): @@ -707,13 +708,14 @@ class X2GoTerminalSession(object): def set_print_action(self, print_action, **kwargs): """\ Set a print action for the next incoming print jobs. - + This method is a wrapper for L{X2GoPrintQueue}C{.set_print_action()}. - @param print_action: print action name or object (i.e. an instance of C{X2GoPrintAction*} classes) - @type print_action: C{str} or C{X2GoPrintAction*} - @param kwargs: print action specific parameters - @type kwargs: C{dict} + :param print_action: print action name or object (i.e. an instance of C{X2GoPrintAction*} classes) + :type print_action: C{str} or C{X2GoPrintAction*} + :param kwargs: print action specific parameters + :type kwargs: C{dict} + :param **kwargs: """ self.print_queue.set_print_action(print_action, logger=self.logger, **kwargs) @@ -732,9 +734,9 @@ class X2GoTerminalSession(object): Return the server-side printing spooldir path. - @return: the directory for remote print job spooling + :returns: the directory for remote print job spooling - @rtype: C{str} + :rtype: C{str} """ return '%s/%s' % (self.session_info.remote_container, 'spool') @@ -743,11 +745,11 @@ class X2GoTerminalSession(object): """\ Initialize the X2Go MIME box. Open/process incoming files from the server-side locally. - @param mimebox_extensions: file name extensions that are allowed for local opening/processing (Default value = []) - @type mimebox_extensions: C{list} - @param mimebox_action: MIME box action given as name or object (i.e. an instance of C{X2GoMIMEboxAction*} classes). (Default value = None) - @type mimebox_action: C{str} or C{obj} - @raise X2GoUserException: if the X2Go MIME box feature is not available to this user + :param mimebox_extensions: file name extensions that are allowed for local opening/processing (Default value = []) + :type mimebox_extensions: C{list} + :param mimebox_action: MIME box action given as name or object (i.e. an instance of C{X2GoMIMEboxAction*} classes). (Default value = None) + :type mimebox_action: C{str} or C{obj} + :raises X2GoUserException: if the X2Go MIME box feature is not available to this user """ if not self.control_session.is_sshfs_available(): @@ -771,13 +773,14 @@ class X2GoTerminalSession(object): def set_mimebox_action(self, mimebox_action, **kwargs): """\ Set a MIME box action for the next incoming MIME jobs. - + This method is a wrapper for L{X2GoMIMEboxQueue}C{set_mimebox_action()}. - @param mimebox_action: MIME box action name or object (i.e. an instance of C{X2GoMIMEboxAction*} classes) - @type mimebox_action: C{str} or C{X2GoMIMEboxAction*} - @param kwargs: MIME box action specific parameters - @type kwargs: C{dict} + :param mimebox_action: MIME box action name or object (i.e. an instance of C{X2GoMIMEboxAction*} classes) + :type mimebox_action: C{str} or C{X2GoMIMEboxAction*} + :param kwargs: MIME box action specific parameters + :type kwargs: C{dict} + :param **kwargs: """ self.mimebox_queue.set_mimebox_action(mimebox_action, logger=self.logger, **kwargs) @@ -796,9 +799,9 @@ class X2GoTerminalSession(object): Return the server-side MIME box spooldir path. - @return: the directory where remote MIME box jobs are placed + :returns: the directory where remote MIME box jobs are placed - @rtype: C{str} + :rtype: C{str} """ return '%s/%s' % (self.session_info.remote_container, 'mimebox') @@ -831,9 +834,9 @@ class X2GoTerminalSession(object): Test if this terminal's session info object is write-protected. - @return: C{True}, if session info object is read-only, C{False} for read-write. + :returns: C{True}, if session info object is read-only, C{False} for read-write. - @rtype: C{bool} + :rtype: C{bool} """ self.session_info.is_protected() @@ -858,16 +861,16 @@ class X2GoTerminalSession(object): """\ Share a local folder with the X2Go session. - @param local_path: the full path to an existing folder on the local + :param local_path: the full path to an existing folder on the local file system (Default value = None) - @type local_path: C{str} - @param folder_type: one of 'disk' (a folder on your local hard drive), 'rm' (removeable device), + :type local_path: C{str} + :param folder_type: one of 'disk' (a folder on your local hard drive), 'rm' (removeable device), 'cdrom' (CD/DVD Rom) or 'spool' (for X2Go print spooling) (Default value = 'disk') - @type folder_type: C{str} - @return: returns C{True} if the local folder has been successfully mounted within the X2Go server session - @rtype: C{bool} - @raise X2GoUserException: if local folder sharing is not available to this user - @raise Exception: any other exception occuring on the way is passed through by this method + :type folder_type: C{str} + :returns: returns C{True} if the local folder has been successfully mounted within the X2Go server session + :rtype: C{bool} + :raises X2GoUserException: if local folder sharing is not available to this user + :raises Exception: any other exception occuring on the way is passed through by this method """ if not self.control_session.is_sshfs_available(): @@ -988,9 +991,9 @@ class X2GoTerminalSession(object): Unshare all local folders mount in the X2Go session. - @return: returns C{True} if all local folders could be successfully unmounted from the X2Go server session + :returns: returns C{True} if all local folders could be successfully unmounted from the X2Go server session - @rtype: C{bool} + :rtype: C{bool} """ self.logger('unsharing all local folders from session %s' % self.session_info, log.loglevel_INFO) @@ -1012,10 +1015,10 @@ class X2GoTerminalSession(object): """\ Unshare local folder given as <local_path> from X2Go session. - @param local_path: the full path to an existing folder on the local + :param local_path: the full path to an existing folder on the local file system (Default value = None) - @return: returns C{True} if the local folder <local_path> could be successfully unmounted from the X2Go server session - @rtype: C{bool} + :returns: returns C{True} if the local folder <local_path> could be successfully unmounted from the X2Go server session + :rtype: C{bool} """ self.logger('unsharing local folder from session %s' % self.session_info, log.loglevel_INFO) @@ -1039,9 +1042,9 @@ class X2GoTerminalSession(object): Retrieve the session's color depth. - @return: the session's color depth + :returns: the session's color depth - @rtype: C{int} + :rtype: C{int} """ return self.params.depth @@ -1049,12 +1052,12 @@ class X2GoTerminalSession(object): def auto_session_window_title(self, dont_set=False): """\ Automatically generate an appropriate human-readable session window title. - + The session window title will be provider in the C{session_title} property of this method. - @param dont_set: generate the session window title, but do not actually set it (Default value = False) - @type dont_set: C{bool} + :param dont_set: generate the session window title, but do not actually set it (Default value = False) + :type dont_set: C{bool} """ _generic_title = 'X2GO-%s' % self.session_info.name @@ -1095,11 +1098,11 @@ class X2GoTerminalSession(object): """\ Try for <timeout> seconds to find the X2Go session window of this terminal session. - + A background thread will get spawned for this operation. - @param timeout: try for <timeout> seconds to find the session window (Default value = 60) - @type timeout: C{int} + :param timeout: try for <timeout> seconds to find the session window (Default value = 60) + :type timeout: C{int} """ gevent.spawn(self._find_session_window, timeout=timeout) @@ -1109,8 +1112,8 @@ class X2GoTerminalSession(object): Try for <timeout> seconds to find the X2Go session window of this terminal session. - @param timeout: try for <timeout> seconds to find the session window (Default value = 0) - @type timeout: C{int} + :param timeout: try for <timeout> seconds to find the session window (Default value = 0) + :type timeout: C{int} """ self.session_window = None @@ -1164,13 +1167,13 @@ class X2GoTerminalSession(object): def set_session_window_title(self, title, timeout=60): """\ Modify the session window title. - + A background thread will get spawned for this operation. - @param title: new title for the terminal session's session window - @type title: C{str} - @param timeout: try for <timeout> seconds to find the session window (Default value = 60) - @type timeout: C{int} + :param title: new title for the terminal session's session window + :type title: C{str} + :param timeout: try for <timeout> seconds to find the session window (Default value = 60) + :type timeout: C{int} """ gevent.spawn(self._set_session_window_title, title=title.strip(), timeout=timeout) @@ -1179,10 +1182,10 @@ class X2GoTerminalSession(object): """\ Modify the session window title. - @param title: new title for the terminal session's session window - @type title: C{str} - @param timeout: try for <timeout> seconds to find the session window (Default value = 0) - @type timeout: C{int} + :param title: new title for the terminal session's session window + :type title: C{str} + :param timeout: try for <timeout> seconds to find the session window (Default value = 0) + :type timeout: C{int} """ self.session_title = title @@ -1206,11 +1209,11 @@ class X2GoTerminalSession(object): """\ Try for <timeout> seconds to raise the X2Go session window of this terminal session to the top and bring it to focus. - + A background thread will get spawned for this operation. - @param timeout: try for <timeout> seconds to raise the session window (Default value = 60) - @type timeout: C{int} + :param timeout: try for <timeout> seconds to raise the session window (Default value = 60) + :type timeout: C{int} """ gevent.spawn(self._raise_session_window, timeout=timeout) @@ -1220,8 +1223,8 @@ class X2GoTerminalSession(object): Try for <timeout> seconds to raise the X2Go session window of this terminal session to the top and bring it to focus. - @param timeout: try for <timeout> seconds to raise the session window (Default value = 0) - @type timeout: C{int} + :param timeout: try for <timeout> seconds to raise the session window (Default value = 0) + :type timeout: C{int} """ timeout += 1 @@ -1242,10 +1245,10 @@ class X2GoTerminalSession(object): The expected result is not 100% safe, however, it comes with a high probability to be correct. - @param cmd: session command - @type cmd: C{str} - @return: C{True} if this method reckons that the command is executable on the remote X2Go server - @rtype: C{bool} + :param cmd: session command + :type cmd: C{str} + :returns: C{True} if this method reckons that the command is executable on the remote X2Go server + :rtype: C{bool} """ test_cmd = None; @@ -1279,18 +1282,18 @@ class X2GoTerminalSession(object): def run_command(self, cmd=None, env={}): """\ Run a command in this session. - + After L{x2go.backends.terminal.plain.X2GoTerminalSession.start()} has been called one or more commands can be executed with L{x2go.backends.terminal.plain.X2GoTerminalSession.run_command()} within the current X2Go session. - @param cmd: Command to be run (Default value = None) - @type cmd: C{str} - @param env: add server-side environment variables (Default value = {}) - @type env: C{dict} - @return: stdout.read() and stderr.read() as returned by the run command + :param cmd: Command to be run (Default value = None) + :type cmd: C{str} + :param env: add server-side environment variables (Default value = {}) + :type env: C{dict} + :returns: stdout.read() and stderr.read() as returned by the run command on the X2Go server - @rtype: C{tuple} of C{str} + :rtype: C{tuple} of C{str} """ if not self.has_command(_rewrite_cmd(str(self.params.cmd), params=self.params)): @@ -1348,8 +1351,9 @@ class X2GoTerminalSession(object): Is this (terminal) session a desktop session? - @return: Returns C{True} is this session is a desktop session. - @rtype: C{bool} + :returns: Returns C{True} is this session is a desktop session. + + :rtype: C{bool} """ if self.session_info: @@ -1361,8 +1365,9 @@ class X2GoTerminalSession(object): Is this (terminal) session a published applications provider? - @return: Returns C{True} is this session is a provider session for published applications. - @rtype: C{bool} + :returns: Returns C{True} is this session is a provider session for published applications. + + :rtype: C{bool} """ if self.session_info and self.is_running(): @@ -1373,12 +1378,12 @@ class X2GoTerminalSession(object): """\ Set the keyboard layout and variant for this (running) session. - @param layout: keyboard layout to be set (Default value = 'null') - @type layout: C{str} - @param variant: keyboard variant to be set (Default value = 'null') - @type variant: C{str} - @return: returns C{True} if the {setxkbmap} command could be executed successfully. - @rtype: C{bool} + :param layout: keyboard layout to be set (Default value = 'null') + :type layout: C{str} + :param variant: keyboard variant to be set (Default value = 'null') + :type variant: C{str} + :returns: returns C{True} if the {setxkbmap} command could be executed successfully. + :rtype: C{bool} """ if not self.is_running(): @@ -1410,12 +1415,12 @@ class X2GoTerminalSession(object): """\ Executed a published application. - @param exec_name: application to be executed - @type exec_name: C{str} - @param timeout: execution timeout (Default value = 20) - @type timeout: C{int} - @param env: session environment dictionary (Default value = {}) - @type env: C{dict} + :param exec_name: application to be executed + :type exec_name: C{str} + :param timeout: execution timeout (Default value = 20) + :type timeout: C{int} + :param env: session environment dictionary (Default value = {}) + :type env: C{dict} """ cmd_line = [ @@ -1445,9 +1450,10 @@ class X2GoTerminalSession(object): X2Go session OK? - @return: Returns C{True} if this X2Go (terminal) session is up and running, + :returns: Returns C{True} if this X2Go (terminal) session is up and running, C{False} otherwise. - @rtype: C{bool} + + :rtype: C{bool} """ _ok = bool(self.session_info.name and self.proxy.ok()) @@ -1458,9 +1464,10 @@ class X2GoTerminalSession(object): X2Go session running? - @return: Returns C{True} if this X2Go (terminal) session is in running state, + :returns: Returns C{True} if this X2Go (terminal) session is in running state, C{False} otherwise. - @rtype: C{bool} + + :rtype: C{bool} """ return self.session_info.is_running() @@ -1470,9 +1477,10 @@ class X2GoTerminalSession(object): X2Go session suspended? - @return: Returns C{True} if this X2Go (terminal) session is in suspended state, + :returns: Returns C{True} if this X2Go (terminal) session is in suspended state, C{False} otherwise. - @rtype: C{bool} + + :rtype: C{bool} """ return self.session_info.is_suspended() @@ -1482,9 +1490,10 @@ class X2GoTerminalSession(object): X2Go session connected? - @return: Returns C{True} if this X2Go session's Paramiko/SSH transport is + :returns: Returns C{True} if this X2Go session's Paramiko/SSH transport is connected/authenticated, C{False} else. - @rtype: C{bool} + + :rtype: C{bool} """ return self.control_session.is_connected() @@ -1494,10 +1503,11 @@ class X2GoTerminalSession(object): Start a new X2Go session. - @return: C{True} if session startup has been successful and the X2Go proxy is up-and-running - @rtype: C{bool} - @raise X2GoTerminalSessionException: if the session startup failed - @raise X2GoDesktopSharingDenied: if desktop sharing fails because of denial by the user running the desktop to be shared + :returns: C{True} if session startup has been successful and the X2Go proxy is up-and-running + + :rtype: C{bool} + :raises X2GoTerminalSessionException: if the session startup failed + :raises X2GoDesktopSharingDenied: if desktop sharing fails because of denial by the user running the desktop to be shared """ self.params.rewrite_session_type() @@ -1613,9 +1623,10 @@ class X2GoTerminalSession(object): Resume a running/suspended X2Go session. - @return: C{True} if the session could successfully be resumed - @rtype: C{bool} - @raise X2GoTerminalSessionException: if the terminal session failed to update server-side reported port changes + :returns: C{True} if the session could successfully be resumed + + :rtype: C{bool} + :raises X2GoTerminalSessionException: if the terminal session failed to update server-side reported port changes """ setkbd = "0" @@ -1719,8 +1730,9 @@ class X2GoTerminalSession(object): Suspend this X2Go (terminal) session. - @return: C{True} if the session terminal could be successfully suspended - @rtype: C{bool} + :returns: C{True} if the session terminal could be successfully suspended + + :rtype: C{bool} """ self.release_telekinesis() @@ -1737,8 +1749,9 @@ class X2GoTerminalSession(object): Terminate this X2Go (terminal) session. - @return: C{True} if the session could be successfully terminated - @rtype: C{bool} + :returns: C{True} if the session could be successfully terminated + + :rtype: C{bool} """ self.release_telekinesis() @@ -1799,8 +1812,9 @@ class X2GoTerminalSession(object): Test if this terminal session is a rootless session. - @return: C{True} if this session is of session type rootless ('R'). - @rtype: C{bool} + :returns: C{True} if this session is of session type rootless ('R'). + + :rtype: C{bool} """ self.params.rewrite_session_type() @@ -1811,8 +1825,9 @@ class X2GoTerminalSession(object): Test if this terminal session is a desktop sharing (aka shadow) session. - @return: C{True} if this session is of session type shadow ('S'). - @rtype: C{bool} + :returns: C{True} if this session is of session type shadow ('S'). + + :rtype: C{bool} """ self.params.rewrite_session_type() @@ -1823,8 +1838,9 @@ class X2GoTerminalSession(object): Test if this terminal session is a published applications session. - @return: C{True} if this session is of session type published applications ('P'). - @rtype: C{bool} + :returns: C{True} if this session is of session type published applications ('P'). + + :rtype: C{bool} """ self.params.rewrite_session_type() diff --git a/x2go/cache.py b/x2go/cache.py index 02d2f7c..d092ec3 100644 --- a/x2go/cache.py +++ b/x2go/cache.py @@ -41,12 +41,12 @@ class X2GoListSessionsCache(object): For non-blocking operations in client applications using Python X2Go, it is recommended to enable the L{X2GoListSessionsCache}. This can be done by calling the constructor of the L{X2GoClient} class. - + The session list and desktop cache gets updated in regular intervals by a threaded L{X2GoSessionGuardian} instance. For the session list and desktop list update, the X2Go server commands C{x2golistsessions} and C{x2godesktopsessions} are called and the command's stdout is cached in the session list cache. - + Whenever your client application needs access to either the server's session list or the server's desktop list the session cache is queried instead. This assures that the server's session/desktop list is available without delay, even on slow internet @@ -83,8 +83,8 @@ class X2GoListSessionsCache(object): """\ Remove session list from cache for a given profile. - @param profile_name: name of profile to operate on - @type profile_name: C{str} + :param profile_name: name of profile to operate on + :type profile_name: C{str} """ while self.protected: @@ -108,10 +108,10 @@ class X2GoListSessionsCache(object): """\ Update L{X2GoListSessionsCache} for all connected session profiles. - @param update_sessions: cache recent session lists from all connected servers (Default value = True) - @type update_sessions: C{bool} - @param update_desktops: cache recent desktop lists from all connected servers (Default value = False) - @type update_desktops: C{bool} + :param update_sessions: cache recent session lists from all connected servers (Default value = True) + :type update_sessions: C{bool} + :param update_desktops: cache recent desktop lists from all connected servers (Default value = False) + :type update_desktops: C{bool} """ for profile_name in self.client_instance.client_connected_profiles(return_profile_names=True): @@ -123,14 +123,14 @@ class X2GoListSessionsCache(object): """\ Update L{X2GoListSessionsCache} (i.e. session/desktops) for session profile C{profile_name}. - @param profile_name: name of profile to update - @type profile_name: C{str} - @param update_sessions: cache recent session list from server (Default value = True) - @type update_sessions: C{bool} - @param update_desktops: cache recent desktop list from server (Default value = False) - @type update_desktops: C{bool} - @param update_mounts: cache list of client-side mounts on server (Default value = False) - @type update_mounts: C{bool} + :param profile_name: name of profile to update + :type profile_name: C{str} + :param update_sessions: cache recent session list from server (Default value = True) + :type update_sessions: C{bool} + :param update_desktops: cache recent desktop list from server (Default value = False) + :type update_desktops: C{bool} + :param update_mounts: cache list of client-side mounts on server (Default value = False) + :type update_mounts: C{bool} """ self.protected = True @@ -150,11 +150,10 @@ class X2GoListSessionsCache(object): """\ Update mounts list of L{X2GoListSessionsCache} for session profile C{profile_name}. - @param profile_name: name of profile to update - @type profile_name: C{str} - @param control_session: X2Go control session instance - @type control: L{X2GoControlSession} - @raise X2GoControlSessionException: if the control session's C{list_mounts} method fails + :param profile_name: name of profile to update + :type profile_name: C{str} + :param control_session: X2Go control session instance + :raises X2GoControlSessionException: if the control session's C{list_mounts} method fails """ try: @@ -179,11 +178,11 @@ class X2GoListSessionsCache(object): """\ Update session lists of L{X2GoListSessionsCache} for session profile C{profile_name}. - @param profile_name: name of profile to update - @type profile_name: C{str} - @param control_session: X2Go control session instance - @type control_session: C{obj} - @raise X2GoControlSessionException: if the control session's C{list_desktop} method fails + :param profile_name: name of profile to update + :type profile_name: C{str} + :param control_session: X2Go control session instance + :type control_session: C{obj} + :raises X2GoControlSessionException: if the control session's C{list_desktop} method fails """ try: @@ -203,11 +202,11 @@ class X2GoListSessionsCache(object): """\ Update desktop list of L{X2GoListSessionsCache} for session profile C{profile_name}. - @param profile_name: name of profile to update - @type profile_name: C{str} - @param control_session: X2Go control session instance - @type control_session: C{obj} - @raise X2GoControlSessionException: if the control session's C{list_sessions} method fails + :param profile_name: name of profile to update + :type profile_name: C{str} + :param control_session: X2Go control session instance + :type control_session: C{obj} + :raises X2GoControlSessionException: if the control session's C{list_sessions} method fails """ try: @@ -226,10 +225,10 @@ class X2GoListSessionsCache(object): Retrieve a session list from the current cache content of L{X2GoListSessionsCache} for a given L{X2GoSession} instance (specified by its unique session UUID). - @param session_uuid: unique identifier of session to query cache for - @type session_uuid: C{str} - @return: a data object containing available session information - @rtype: C{X2GoServerSessionList*} instance (or C{None}) + :param session_uuid: unique identifier of session to query cache for + :type session_uuid: C{str} + :returns: a data object containing available session information + :rtype: C{X2GoServerSessionList*} instance (or C{None}) """ profile_name = self.client_instance.get_session_profile_name(session_uuid) @@ -244,10 +243,10 @@ class X2GoListSessionsCache(object): L{X2GoListSessionsCache} for a given L{X2GoSession} instance (specified by its unique session UUID). - @param session_uuid: unique identifier of session to query cache for - @type session_uuid: C{str} - @return: a list of strings representing X2Go desktop sessions available for sharing - @rtype: C{list} (or C{None}) + :param session_uuid: unique identifier of session to query cache for + :type session_uuid: C{str} + :returns: a list of strings representing X2Go desktop sessions available for sharing + :rtype: C{list} (or C{None}) """ profile_name = self.client_instance.get_session_profile_name(session_uuid) @@ -262,10 +261,10 @@ class X2GoListSessionsCache(object): L{X2GoListSessionsCache} for a given L{X2GoSession} instance (specified by its unique session UUID). - @param session_uuid: unique identifier of session to query cache for - @type session_uuid: C{str} - @return: a list of strings representing mounted client shares - @rtype: C{list} (or C{None}) + :param session_uuid: unique identifier of session to query cache for + :type session_uuid: C{str} + :returns: a list of strings representing mounted client shares + :rtype: C{list} (or C{None}) """ profile_name = self.client_instance.get_session_profile_name(session_uuid) @@ -278,14 +277,14 @@ class X2GoListSessionsCache(object): """\ Check if session information is cached. - @param profile_name: name of profile to update (Default value = None) - @type profile_name: C{str} - @param session_uuid: unique identifier of session to query cache for (Default value = None) - @type session_uuid: C{str} - @param cache_type: cache type (e.g. 'mounts', 'desktops', 'sessions') (Default value = None) - @type cache_type: C{str} - @return: C{True} if session information is cached - @rtype: C{bool} + :param profile_name: name of profile to update (Default value = None) + :type profile_name: C{str} + :param session_uuid: unique identifier of session to query cache for (Default value = None) + :type session_uuid: C{str} + :param cache_type: cache type (e.g. 'mounts', 'desktops', 'sessions') (Default value = None) + :type cache_type: C{str} + :returns: C{True} if session information is cached + :rtype: C{bool} """ if profile_name is None and session_uuid and self.client_instance: diff --git a/x2go/checkhosts.py b/x2go/checkhosts.py index 6345063..ed21b76 100644 --- a/x2go/checkhosts.py +++ b/x2go/checkhosts.py @@ -61,8 +61,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): Retrieve the Paramiko SSH/Client. - @return: the associated X2Go control session instance. - @rtype: C{X2GoControlSession*} instance + :returns: the associated X2Go control session instance. + + :rtype: C{X2GoControlSession*} instance """ return self.client @@ -72,8 +73,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): Retrieve the server hostname:port expression of the server to be validated. - @return: hostname:port - @rtype: C{str} + :returns: hostname:port + + :rtype: C{str} """ return self.fake_hostname or self.hostname @@ -83,8 +85,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): Retrieve the server hostname string of the server to be validated. - @return: hostname - @rtype: C{str} + :returns: hostname + + :rtype: C{str} """ if ":" in self.get_hostname(): @@ -97,8 +100,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): Retrieve the server port of the server to be validated. - @return: port - @rtype: C{str} + :returns: port + + :rtype: C{str} """ if ":" in self.get_hostname(): @@ -111,8 +115,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): Retrieve the host key of the server to be validated. - @return: host key - @rtype: Paramiko/SSH key instance + :returns: host key + + :rtype: Paramiko/SSH key instance """ return self.key @@ -122,8 +127,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): Retrieve the host key name of the server to be validated. - @return: host key name (RSA, DSA, ECDSA...) - @rtype: C{str} + :returns: host key name (RSA, DSA, ECDSA...) + + :rtype: C{str} """ return self.key.get_name().upper() @@ -133,8 +139,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): Retrieve the host key fingerprint of the server to be validated. - @return: host key fingerprint - @rtype: C{str} + :returns: host key fingerprint + + :rtype: C{str} """ return binascii.hexlify(self.key.get_fingerprint()) @@ -145,8 +152,9 @@ class X2GoMissingHostKeyPolicy(paramiko.MissingHostKeyPolicy): to be validated. - @return: host key fingerprint (with colons) - @rtype: C{str} + :returns: host key fingerprint (with colons) + + :rtype: C{str} """ _fingerprint = self.get_key_fingerprint() @@ -181,12 +189,12 @@ class X2GoInteractiveAddPolicy(X2GoMissingHostKeyPolicy): Policy for making host key information available to Python X2Go after a Paramiko/SSH connect has been attempted. This class needs information about the associated L{X2GoSession} instance. - + Once called, the L{missing_host_key} method of this class will try to call L{X2GoSession.HOOK_check_host_dialog()}. This hook method---if not re-defined in your application---will then try to call the L{X2GoClient.HOOK_check_host_dialog()}, which then will return C{True} by default if not customized in your application. - + To accept host key checks, make sure to either customize the L{X2GoClient.HOOK_check_host_dialog()} method or the L{X2GoSession.HOOK_check_host_dialog()} method and hook some interactive user dialog to either of them. @@ -196,25 +204,25 @@ class X2GoInteractiveAddPolicy(X2GoMissingHostKeyPolicy): def missing_host_key(self, client, hostname, key): """\ Handle a missing host key situation. This method calls - + Once called, the L{missing_host_key} method will try to call L{X2GoSession.HOOK_check_host_dialog()}. This hook method---if not re-defined in your application---will then try to call the L{X2GoClient.HOOK_check_host_dialog()}, which then will return C{True} by default if not customized in your application. - + To accept host key checks, make sure to either customize the L{X2GoClient.HOOK_check_host_dialog()} method or the L{X2GoSession.HOOK_check_host_dialog()} method and hook some interactive user dialog to either of them. - @param client: SSH client (C{X2GoControlSession*}) instance - @type client: C{X2GoControlSession*} instance - @param hostname: remote hostname - @type hostname: C{str} - @param key: host key to validate - @type key: Paramiko/SSH key instance - @raise X2GoHostKeyException: if the X2Go server host key is not in the C{known_hosts} file - @raise X2GoSSHProxyHostKeyException: if the SSH proxy host key is not in the C{known_hosts} file - @raise SSHException: if this instance does not know its {self.session_instance} + :param client: SSH client (C{X2GoControlSession*}) instance + :type client: C{X2GoControlSession*} instance + :param hostname: remote hostname + :type hostname: C{str} + :param key: host key to validate + :type key: Paramiko/SSH key instance + :raises X2GoHostKeyException: if the X2Go server host key is not in the C{known_hosts} file + :raises X2GoSSHProxyHostKeyException: if the SSH proxy host key is not in the C{known_hosts} file + :raises SSHException: if this instance does not know its {self.session_instance} """ self.client = client @@ -270,15 +278,15 @@ def check_ssh_host_key(x2go_sshclient_instance, hostname, port=22): validating the results (i.e. by validating raised exceptions during the connect process). - @param x2go_sshclient_instance: a Paramiko/SSH client instance to be used for testing host key validity. - @type x2go_sshclient_instance: C{X2GoControlSession*} instance - @param hostname: hostname of server to validate - @type hostname: C{str} - @param port: port of server to validate (Default value = 22) - @type port: C{int} - @return: returns a tuple with the following components (<host_ok>, <hostname>, <port>, <fingerprint>, <fingerprint_type>) - @rtype: C{tuple} - @raise SSHException: if an SSH exception occurred, that we did not provocate in L{X2GoInteractiveAddPolicy.missing_host_key()} + :param x2go_sshclient_instance: a Paramiko/SSH client instance to be used for testing host key validity. + :type x2go_sshclient_instance: C{X2GoControlSession*} instance + :param hostname: hostname of server to validate + :type hostname: C{str} + :param port: port of server to validate (Default value = 22) + :type port: C{int} + :returns: returns a tuple with the following components (<host_ok>, <hostname>, <port>, <fingerprint>, <fingerprint_type>) + :rtype: C{tuple} + :raises SSHException: if an SSH exception occurred, that we did not provocate in L{X2GoInteractiveAddPolicy.missing_host_key()} """ _hostname = hostname diff --git a/x2go/cleanup.py b/x2go/cleanup.py index d003ff5..a4b1704 100644 --- a/x2go/cleanup.py +++ b/x2go/cleanup.py @@ -42,26 +42,26 @@ def x2go_cleanup(e=None, threads=None): For every Python X2Go application you write, please make sure to capture the C{KeyboardInterrupt} and the C{SystemExit} exceptions and call this function if either of the exceptions occurs. - + Example:: - + import x2go - + try: my_x2goclient = x2go.X2GoClient(...) - + [... your code ...] - + sys.exit(0) except (KeyboardInterrupt, SystemExit): x2go.x2go_cleanup() - @param e: if L{x2go_cleanup} got called as you caught an exception in your code this can be the + :param e: if L{x2go_cleanup} got called as you caught an exception in your code this can be the C{Exception} that we will process at the end of the clean-up (or if clean-up failed or was not appropriate) (Default value = None) - @type e: C{exception} - @param threads: a list of threads to clean up (Default value = None) - @type threads: C{list} + :type e: C{exception} + :param threads: a list of threads to clean up (Default value = None) + :type threads: C{list} """ try: diff --git a/x2go/client.py b/x2go/client.py index 28d3b9b..aa3f43f 100644 --- a/x2go/client.py +++ b/x2go/client.py @@ -160,7 +160,7 @@ class X2GoClient(object): """\ The X2GoClient implements _THE_ public Python X2Go API. With it you can construct your own X2Go client application in Python. - + Most methods in this class require that you have registered a session with a remote X2Go server (passing of session options, initialization of the session object etc.) and connected to it (authentication). For these two steps @@ -379,8 +379,8 @@ class X2GoClient(object): """\ HOOK method: called if a session demands to auto connect the session profile. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} """ self.logger('HOOK_profile_auto_connect: profile ,,%s'' wants to be auto-connected to the X2Go server.' % profile_name, loglevel=log.loglevel_WARN) @@ -389,8 +389,8 @@ class X2GoClient(object): """\ HOOK method: called if a session demands to auto connect the session profile. - @param profile_name: profile name of a session that triggered this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} + :param profile_name: profile name of a session that triggered this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} """ self.logger('HOOK_broker_connection_exception: a broker connection problem occurred triggered by an action on profile ,,%s''.' % profile_name, loglevel=log.loglevel_WARN) @@ -400,13 +400,13 @@ class X2GoClient(object): HOOK method: called after a broker connection failed for a certain profile. This hook can be used to allow the user to decide how to proceed after connection problems with the broker. - @param profile_name: profile name of a session that triggered this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param is_profile_connected: C{True} if the given session profile is already conneced to the server (Default value = False) - @type is_profile_connected: C{bool} - @return: If this hook returns C{True}, the session startup/resumption will be continued, even if the + :param profile_name: profile name of a session that triggered this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param is_profile_connected: C{True} if the given session profile is already conneced to the server (Default value = False) + :type is_profile_connected: C{bool} + :returns: If this hook returns C{True}, the session startup/resumption will be continued, even if the broker connection is down. (Default: broker connection problems cause session start-up to fail). - @rtype: C{bool} + :rtype: C{bool} """ self.logger('HOOK_broker_ignore_connection_problems: use this hook to let the user to decide how to proceed on connection failures (profile name: %s, connected: %s)' % (profile_name, is_profile_connected), loglevel=log.loglevel_WARN) @@ -416,8 +416,8 @@ class X2GoClient(object): """\ HOOK method: called if the startup of a session failed. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} """ self.logger('HOOK_session_startup_failed: session startup for session profile ,,%s'' failed.' % profile_name, loglevel=log.loglevel_WARN) @@ -426,8 +426,8 @@ class X2GoClient(object): """\ HOOK method: called if the startup of a shadow session was denied by the other user. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} """ self.logger('HOOK_desktop_sharing_failed: desktop sharing for profile ,,%s'' was denied by the other user.' % profile_name, loglevel=log.loglevel_WARN) @@ -436,8 +436,8 @@ class X2GoClient(object): """\ HOOK method: called if the x2golistdesktops command generates a timeout due to long execution time. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} """ self.logger('HOOK_list_desktops_timeout: the server-side x2golistdesktops command for session profile %s took too long to return results. This can happen from time to time, please try again.' % profile_name, loglevel=log.loglevel_WARN) @@ -446,10 +446,10 @@ class X2GoClient(object): """\ HOOK method: called if it is tried to connect to a (seen before) sharable desktop that's not available (anymore). - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param desktop: desktop identifier (the X session's $DISPLAY) (Default value = 'UNKNOWN') - @type desktop: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param desktop: desktop identifier (the X session's $DISPLAY) (Default value = 'UNKNOWN') + :type desktop: C{str} """ self.logger('HOOK_no_such_desktop: the desktop %s (via session profile %s) is not available for sharing (anymore).' % (desktop, profile_name), loglevel=log.loglevel_WARN) @@ -472,10 +472,10 @@ class X2GoClient(object): HOOK method: called if an incoming print job has been detected by L{X2GoPrintQueue} and a print dialog box is requested. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_open_print_dialog: incoming print job detected by X2GoClient hook method', loglevel=log.loglevel_WARN) @@ -484,12 +484,12 @@ class X2GoClient(object): """\ HOOK: the command <cmd> is not available on the connected X2Go server. - @param cmd: the command that failed - @type cmd: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param cmd: the command that failed + :type cmd: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_no_such_command: the command %s is not available for X2Go server (profile: %s, session: %s)' % (cmd, profile_name, session_name), loglevel=log.loglevel_WARN) @@ -498,12 +498,12 @@ class X2GoClient(object): """\ HOOK method: called on detection of an incoming MIME box job ,,<filename>''. - @param filename: file name of the incoming MIME box job - @type filename: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param filename: file name of the incoming MIME box job + :type filename: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_open_mimebox_saveas_dialog: incoming MIME box job ,, %s'' detected by X2GoClient hook method' % filename, loglevel=log.loglevel_WARN) @@ -512,16 +512,16 @@ class X2GoClient(object): """\ HOOK method: called if an incoming print job caused an error. - @param filename: file name of the print job that failed - @type filename: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} - @param err_msg: if available, an appropriate error message (Default value = 'GENERIC_ERROR') - @type err_msg: C{str} - @param printer: if available, the printer name the print job failed on (Default value = None) - @type printer: C{str} + :param filename: file name of the print job that failed + :type filename: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} + :param err_msg: if available, an appropriate error message (Default value = 'GENERIC_ERROR') + :type err_msg: C{str} + :param printer: if available, the printer name the print job failed on (Default value = None) + :type printer: C{str} """ if printer: @@ -533,18 +533,18 @@ class X2GoClient(object): """\ HOOK method: called if a host check is requested. This hook has to either return C{True} (default) or C{False}. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param host: SSH server name to validate (Default value = 'UNKNOWN') - @type host: C{str} - @param port: SSH server port to validate (Default value = 22) - @type port: C{int} - @param fingerprint: the server's fingerprint (Default value = 'no fingerprint') - @type fingerprint: C{str} - @param fingerprint_type: finger print type (like RSA, DSA, ...) (Default value = 'UNKNOWN') - @type fingerprint_type: C{str} - @return: if host validity is verified, this hook method should return C{True} - @rtype: C{bool} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param host: SSH server name to validate (Default value = 'UNKNOWN') + :type host: C{str} + :param port: SSH server port to validate (Default value = 22) + :type port: C{int} + :param fingerprint: the server's fingerprint (Default value = 'no fingerprint') + :type fingerprint: C{str} + :param fingerprint_type: finger print type (like RSA, DSA, ...) (Default value = 'UNKNOWN') + :type fingerprint_type: C{str} + :returns: if host validity is verified, this hook method should return C{True} + :rtype: C{bool} """ self.logger('HOOK_check_host_dialog: host check requested for session profile %s: Automatically adding host [%s]:%s with fingerprint: ,,%s\'\' as a known host.' % (profile_name, host, port, fingerprint), loglevel=log.loglevel_WARN) @@ -555,8 +555,8 @@ class X2GoClient(object): """\ HOOK method: called if a control session (server connection) has unexpectedly encountered a failure. - @param profile_name: profile name of session that called this hook method - @type profile_name: C{str} + :param profile_name: profile name of session that called this hook method + :type profile_name: C{str} """ self.logger('HOOK_on_control_session_death: the control session of profile %s has died unexpectedly' % profile_name, loglevel=log.loglevel_WARN) @@ -565,10 +565,10 @@ class X2GoClient(object): """\ HOOK method: called SFTP client support is unavailable for the session. - @param profile_name: profile name of the session that experiences failing SFTP client support - @type profile_name: C{str} - @param session_name: name of session experiencing failing SFTP client support - @type session_name: C{str} + :param profile_name: profile name of the session that experiences failing SFTP client support + :type profile_name: C{str} + :param session_name: name of session experiencing failing SFTP client support + :type session_name: C{str} """ self.logger('HOOK_on_failing_SFTP_client: new session for profile %s will lack SFTP client support. Check your server setup. Avoid echoing ~/.bashrc files on server.' % profile_name, loglevel=log.loglevel_ERROR) @@ -589,10 +589,10 @@ class X2GoClient(object): """\ HOOK method: called if a sound tunnel setup failed. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_on_sound_tunnel_failed: setting up X2Go sound for %s (%s) support failed' % (profile_name, session_name)) @@ -601,12 +601,12 @@ class X2GoClient(object): """\ HOOK method: called if a reverse port forwarding request has been denied. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} - @param server_port: remote server port (starting point of reverse forwarding tunnel) (Default value = 0) - @type server_port: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} + :param server_port: remote server port (starting point of reverse forwarding tunnel) (Default value = 0) + :type server_port: C{str} """ self.logger('TCP port (reverse) forwarding request for session %s to server port %s has been denied by the X2Go server. This is a common issue with SSH, it might help to restart the X2Go server\'s SSH daemon.' % (session_name, server_port), loglevel=log.loglevel_WARN) @@ -615,16 +615,16 @@ class X2GoClient(object): """\ HOOK method: called if a port forwarding tunnel setup failed. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} - @param chain_host: hostname of chain host (forwarding tunnel end point) (Default value = 'UNKNOWN') - @type chain_host: C{str} - @param chain_port: port of chain host (forwarding tunnel end point) (Default value = 0) - @type chain_port: C{str} - @param subsystem: information on the subsystem that provoked this hook call (Default value = None) - @type subsystem: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} + :param chain_host: hostname of chain host (forwarding tunnel end point) (Default value = 'UNKNOWN') + :type chain_host: C{str} + :param chain_port: port of chain host (forwarding tunnel end point) (Default value = 0) + :type chain_port: C{str} + :param subsystem: information on the subsystem that provoked this hook call (Default value = None) + :type subsystem: C{str} """ if type(subsystem) in (bytes, str): @@ -638,12 +638,12 @@ class X2GoClient(object): """\ HOOK method: called if a session has been started by this instance of L{X2GoClient}. - @param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') - @type session_uuid: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') + :type session_uuid: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_on_session_has_started_by_me (session_uuid: %s, profile_name: %s): a new session %s has been started by this application' % (session_uuid, profile_name, session_name), loglevel=log.loglevel_NOTICE) @@ -652,12 +652,12 @@ class X2GoClient(object): """\ HOOK method: called if a session has been started by another C{x2goclient}. - @param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') - @type session_uuid: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') + :type session_uuid: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_on_session_has_started (session_uuid: %s, profile_name: %s): a new session %s has started been started by other application' % (session_uuid, profile_name, session_name), loglevel=log.loglevel_NOTICE) @@ -666,12 +666,12 @@ class X2GoClient(object): """\ HOOK method: called if a session has been resumed by this instance of L{X2GoClient}. - @param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') - @type session_uuid: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') + :type session_uuid: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_on_session_has_resumed_by_me (session_uuid: %s, profile_name: %s): suspended session %s has been resumed by this application' % (session_uuid, profile_name, session_name), loglevel=log.loglevel_NOTICE) @@ -680,12 +680,12 @@ class X2GoClient(object): """\ HOOK method: called if a session has been resumed by another C{x2goclient}. - @param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') - @type session_uuid: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') + :type session_uuid: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_on_session_has_resumed_by_other (session_uuid: %s, profile_name: %s): suspended session %s has been resumed by other application' % (session_uuid, profile_name, session_name), loglevel=log.loglevel_NOTICE) @@ -694,12 +694,12 @@ class X2GoClient(object): """\ HOOK method: called after server connect if an already running session has been found. - @param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') - @type session_uuid: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') + :type session_uuid: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_found_session_running_after_connect (session_uuid: %s, profile_name: %s): running session %s has been found after connecting to session profile %s' % (session_uuid, profile_name, session_name, profile_name), loglevel=log.loglevel_NOTICE) @@ -708,12 +708,12 @@ class X2GoClient(object): """\ HOOK method: called if a session has been suspended by this instance of L{X2GoClient}. - @param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') - @type session_uuid: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') + :type session_uuid: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_on_session_has_been_suspended (session_uuid: %s, profile_name: %s): session %s has been suspended' % (session_uuid, profile_name, session_name), loglevel=log.loglevel_NOTICE) @@ -722,12 +722,12 @@ class X2GoClient(object): """\ HOOK method: called if a session has been suspended by another C{x2goclient}. - @param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') - @type session_uuid: C{str} - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param session_uuid: unique session identifier of the calling session (Default value = 'UNKNOWN') + :type session_uuid: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_on_session_has_terminated (session_uuid: %s, profile_name: %s): session %s has terminated' % (session_uuid, profile_name, session_name), loglevel=log.loglevel_NOTICE) @@ -736,10 +736,10 @@ class X2GoClient(object): """\ HOOK method: called if X2Go client-side printing is not available. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_foldersharing_not_available: X2Go\'s client-side printing feature is not available with this session (%s) of profile %s.' % (session_name, profile_name), loglevel=log.loglevel_WARN) @@ -748,10 +748,10 @@ class X2GoClient(object): """\ HOOK method: called if the X2Go MIME box is not available. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_mimebox_not_available: X2Go\'s MIME box feature is not available with this session (%s) of profile %s.' % (session_name, profile_name), loglevel=log.loglevel_WARN) @@ -760,10 +760,10 @@ class X2GoClient(object): """\ HOOK method: called if X2Go client-side folder-sharing is not available. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_foldersharing_not_available: X2Go\'s client-side folder sharing feature is not available with this session (%s) of profile %s.' % (session_name, profile_name), loglevel=log.loglevel_WARN) @@ -772,10 +772,10 @@ class X2GoClient(object): """\ HOOK method: called if the X2Go server denies SSHFS access. - @param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') - @type profile_name: C{str} - @param session_name: X2Go session name (Default value = 'UNKNOWN') - @type session_name: C{str} + :param profile_name: profile name of session that called this hook method (Default value = 'UNKNOWN') + :type profile_name: C{str} + :param session_name: X2Go session name (Default value = 'UNKNOWN') + :type session_name: C{str} """ self.logger('HOOK_sshfs_not_available: the remote X2Go server (%s) denies SSHFS access for session %s. This will result in client-side folder sharing, printing and the MIME box feature being unavailable' % (session_name, profile_name), loglevel=log.loglevel_WARN) @@ -785,8 +785,9 @@ class X2GoClient(object): Retrieve the settings root directory of this L{X2GoClient} instance. - @return: X2Go client root directory - @rtype: C{str} + :returns: X2Go client root directory + + :rtype: C{str} """ return os.path.normpath(self.client_rootdir) @@ -808,8 +809,9 @@ class X2GoClient(object): Retrieve the sessions root directory of this L{X2GoClient} instance. - @return: X2Go sessions root directory - @rtype: C{str} + :returns: X2Go sessions root directory + + :rtype: C{str} """ return os.path.normpath(self.sessions_rootdir) @@ -820,8 +822,9 @@ class X2GoClient(object): Retrieve the SSH client root dir used with this L{X2GoClient} instance. - @return: SSH client root directory - @rtype: C{str} + :returns: SSH client root directory + + :rtype: C{str} """ return os.path.normpath(self.ssh_rootdir) @@ -832,8 +835,9 @@ class X2GoClient(object): Query the local user's username (i.e. the user running the X2Go client). - @return: the local username this L{X2GoClient} instance runs as - @rtype: C{str} + :returns: the local username this L{X2GoClient} instance runs as + + :rtype: C{str} """ return _CURRENT_LOCAL_USER @@ -844,14 +848,14 @@ class X2GoClient(object): Register all session profiles found in the C{sessions} configuration node as potential X2Go sessions. - @param return_objects: if set to C{True} this methods returns a list of L{X2GoSession} + :param return_objects: if set to C{True} this methods returns a list of L{X2GoSession} instances, otherwise a list of session UUIDs representing the corresponding registered sessions is returned (Default value = False) - @type return_objects: C{bool} - @return: a Python dictionary containing one registered session for each available session profile + :type return_objects: C{bool} + :returns: a Python dictionary containing one registered session for each available session profile configuration, whereas the profile names are used as dictionary keys and L{X2GoSession} instances as their values - @rtype: C{list} + :rtype: C{list} """ sessions = {} @@ -872,23 +876,23 @@ class X2GoClient(object): Register a new L{X2GoSession}. Within one L{X2GoClient} instance you can manage several L{X2GoSession} instances on serveral remote X2Go servers under different user names. - + These sessions can be instantiated by passing direct L{X2GoSession} parameters to this method or by specifying the name of an existing session profile (as found in the L{X2GoClient}'s C{sessions} configuration node. - + A session profile is a pre-defined set of session options stored in a sessions profile node (e.g. a configuration file). With the FILE backend such session profiles are stored as a file (by default: C{~/.x2goclient/sessions} or globally (for all users on the client) in C{/etc/x2goclient/sessions}). - + Python X2Go also supports starting multiple X2Go sessions for the same session profile simultaneously. - + This method (L{X2GoClient.register_session()}) accepts a similar set of parameters as the L{X2GoSession} constructor itself. For a complete set of session options refer there. - + Alternatively, you can also pass a profile name or a profile id to this method. If you do this, Python X2Go tries to find the specified session in the C{sessions} configuration node and then derives the necessary session parameters @@ -896,48 +900,49 @@ class X2GoClient(object): also be passed to this method---they will override the option values retrieved from the session profile. - @param server: hostname of the remote X2Go server (Default value = None) - @type server: C{str} - @param profile_id: id (config section name) of a session profile to load + :param server: hostname of the remote X2Go server (Default value = None) + :type server: C{str} + :param profile_id: id (config section name) of a session profile to load from your session config (Default value = None) - @type profile_id: C{str} - @param profile_name: name of a session profile to load from your session + :type profile_id: C{str} + :param profile_name: name of a session profile to load from your session config (Default value = None) - @type profile_name: C{str} - @param session_name:session name to register (by its name) (Default value = None) - @type session_name: C{str} - @param allow_printing: enable X2Go printing support for the to-be-registered X2Go session (Default value = False) - @type allow_printing: C{bool} - @param allow_share_local_folders: set local folder sharing to enabled/disabled (Default value = False) - @type allow_share_local_folders: C{bool} - @param share_local_folders: a list of local folders (as strings) to be shared directly + :type profile_name: C{str} + :param session_name: session name to register (by its name) (Default value = None) + :type session_name: C{str} + :param allow_printing: enable X2Go printing support for the to-be-registered X2Go session (Default value = False) + :type allow_printing: C{bool} + :param allow_share_local_folders: set local folder sharing to enabled/disabled (Default value = False) + :type allow_share_local_folders: C{bool} + :param share_local_folders: a list of local folders (as strings) to be shared directly after session start up (Default value = []) - @type share_local_folders: C{list} - @param allow_mimebox: enable X2Go MIME box support for the to-be-registered X2Go session (Default value = False) - @type allow_mimebox: C{bool} - @param mimebox_extensions: MIME box support is only allowed for the given file extensions (Default value = []) - @type mimebox_extensions: C{list} - @param mimebox_action: MIME box action to use on incoming MIME job files (Default value = 'OPEN') - @type mimebox_action: C{str} - @param add_to_known_hosts: add unknown host keys to the C{known_hosts} file and accept the connection + :type share_local_folders: C{list} + :param allow_mimebox: enable X2Go MIME box support for the to-be-registered X2Go session (Default value = False) + :type allow_mimebox: C{bool} + :param mimebox_extensions: MIME box support is only allowed for the given file extensions (Default value = []) + :type mimebox_extensions: C{list} + :param mimebox_action: MIME box action to use on incoming MIME job files (Default value = 'OPEN') + :type mimebox_action: C{str} + :param add_to_known_hosts: add unknown host keys to the C{known_hosts} file and accept the connection automatically (Default value = False) - @type add_to_known_hosts: C{bool} - @param known_hosts: full path to C{known_hosts} file (Default value = None) - @type known_hosts: C{str} - @param forward_sshagent: forward SSH agent authentication requests to the X2Go client-side (Default value = False) - @type forward_sshagent: C{bool} - @param proxy_options: a set of very C{X2GoProxy*} backend specific options; any option that is not known + :type add_to_known_hosts: C{bool} + :param known_hosts: full path to C{known_hosts} file (Default value = None) + :type known_hosts: C{str} + :param forward_sshagent: forward SSH agent authentication requests to the X2Go client-side (Default value = False) + :type forward_sshagent: C{bool} + :param proxy_options: a set of very C{X2GoProxy*} backend specific options; any option that is not known to the C{X2GoProxy*} backend will simply be ignored (Default value = {}) - @type proxy_options: C{dict} - @param return_object: normally this method returns a unique session UUID. If + :type proxy_options: C{dict} + :param return_object: normally this method returns a unique session UUID. If C{return_object} is set to C{True} an X2GoSession object will be returned instead (Default value = False) - @type return_object: C{bool} - @param kwargs: any option that is also valid for the L{X2GoSession} constructor - @type kwargs: C{dict} - @return: a unique identifier (UUID) for the newly registered X2Go session (or an + :type return_object: C{bool} + :param kwargs: any option that is also valid for the L{X2GoSession} constructor + :type kwargs: C{dict} + :param **kwargs: + :returns: a unique identifier (UUID) for the newly registered X2Go session (or an X2GoSession object if C{return_object} is set to True - @rtype: C{str} + :rtype: C{str} """ _p = None @@ -1057,8 +1062,8 @@ class X2GoClient(object): """\ Retrieves a Python dictionary, containing a short session summary (session status, names, etc.) - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} """ return self.session_registry.session_summary(session_uuid) @@ -1073,10 +1078,10 @@ class X2GoClient(object): After an L{X2GoSession} has been set up you can query the username that the remote sessions runs as. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: the remote username the X2Go session runs as - @rtype: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: the remote username the X2Go session runs as + :rtype: C{str} """ return self.session_registry(session_uuid).get_username() @@ -1088,11 +1093,11 @@ class X2GoClient(object): hostname of the host the session is connected to (or about to connect to). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: the host an X2Go session is connected to + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: the host an X2Go session is connected to (as an C{(addr,port)} tuple) - @rtype: tuple + :rtype: tuple """ return self.session_registry(session_uuid).get_server_peername() @@ -1104,11 +1109,11 @@ class X2GoClient(object): application (e.g. like it has been specified in the session profile). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: the hostname for the queried X2Go session as specified + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: the hostname for the queried X2Go session as specified by the calling application - @rtype: str + :rtype: str """ return self.session_registry(session_uuid).get_server_hostname() @@ -1119,10 +1124,10 @@ class X2GoClient(object): Retrieve the complete L{X2GoSession} object that has been registered under the given session registry hash. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: the L{X2GoSession} instance - @rtype: obj + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: the L{X2GoSession} instance + :rtype: obj """ return self.session_registry(session_uuid) @@ -1135,14 +1140,14 @@ class X2GoClient(object): Retrieve session UUID or L{X2GoSession} for session name <session_name> from the session registry. - @param session_name: the X2Go session's UUID registry hash - @type session_name: C{str} - @param return_object: session UUID hash or L{X2GoSession} instance wanted? (Default value = False) - @type return_object: C{bool} - @param match_profile_name: only return sessions that match this profile name (Default value = None) - @type match_profile_name: C{str} - @return: the X2Go session's UUID registry hash or L{X2GoSession} instance - @rtype: C{str} or L{X2GoSession} instance + :param session_name: the X2Go session's UUID registry hash + :type session_name: C{str} + :param return_object: session UUID hash or L{X2GoSession} instance wanted? (Default value = False) + :type return_object: C{bool} + :param match_profile_name: only return sessions that match this profile name (Default value = None) + :type match_profile_name: C{str} + :returns: the X2Go session's UUID registry hash or L{X2GoSession} instance + :rtype: C{str} or L{X2GoSession} instance """ try: @@ -1156,10 +1161,10 @@ class X2GoClient(object): Retrieve the server-side X2Go session name for the session that has been registered under C{session_uuid}. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: X2Go session name - @rtype: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: X2Go session name + :rtype: C{str} """ return self.session_registry(session_uuid).get_session_name() @@ -1170,10 +1175,10 @@ class X2GoClient(object): Retrieve the server-side X2Go session information object for the session that has been registered under C{session_uuid}. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: X2Go session info - @rtype: C{obj} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: X2Go session info + :rtype: C{obj} """ return self.session_registry(session_uuid).get_session_info() @@ -1184,23 +1189,23 @@ class X2GoClient(object): Retrieve the server-side X2Go published applications menu for the session registered under C{session_uuid} or for profile name C{profile_name}. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: a valid session profile name (Default value = None) - @type profile_name: C{str} - @param lang: locale/language identifier (Default value = None) - @type lang: C{str} - @param refresh: force reload of the menu tree from X2Go server (Default value = False) - @type refresh: C{bool} - @param raw: retrieve a raw output of the server list of published applications (Default value = False) - @type raw: C{bool} - @param very_raw: retrieve a very raw output of the server list of published applications (Default value = False) - @type very_raw: C{bool} - @param max_no_submenus: Number of applications before applications are put into XDG category submenus + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: a valid session profile name (Default value = None) + :type profile_name: C{str} + :param lang: locale/language identifier (Default value = None) + :type lang: C{str} + :param refresh: force reload of the menu tree from X2Go server (Default value = False) + :type refresh: C{bool} + :param raw: retrieve a raw output of the server list of published applications (Default value = False) + :type raw: C{bool} + :param very_raw: retrieve a very raw output of the server list of published applications (Default value = False) + :type very_raw: C{bool} + :param max_no_submenus: Number of applications before applications are put into XDG category submenus (Default value = defaults.PUBAPP_MAX_NO_SUBMENUS) - @type max_no_submenus: C{int} - @return: an i18n capable menu tree packed as a Python dictionary - @rtype: C{list} + :type max_no_submenus: C{int} + :returns: an i18n capable menu tree packed as a Python dictionary + :rtype: C{list} """ if session_uuid is None and profile_name: @@ -1224,12 +1229,12 @@ class X2GoClient(object): Set the session username for the L{X2GoSession} that has been registered under C{session_uuid}. This can be helpful for modifying user credentials during an authentication phase. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param username: new user name to be used for session authentication - @type username: C{str} - @return: returns C{True} on success - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param username: new user name to be used for session authentication + :type username: C{str} + :returns: returns C{True} on success + :rtype: C{bool} """ return self.session_registry(session_uuid).set_username(username=username) @@ -1239,10 +1244,10 @@ class X2GoClient(object): """\ Provide a mechanism to evaluate the validity of an X2Go server host. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: returns C{True} if host validation has been successful. - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: returns C{True} if host validation has been successful. + :rtype: C{bool} """ return self.session_registry(session_uuid).check_host() @@ -1253,10 +1258,10 @@ class X2GoClient(object): Check if session with unique identifier <session_uuid> is configured to re-use the X2Go session's password / key for proxy authentication, as well. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: returns C{True} if the session is configured to re-use session password / key for proxy authentication - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: returns C{True} if the session is configured to re-use session password / key for proxy authentication + :rtype: C{bool} """ return self.session_registry(session_uuid).reuses_sshproxy_authinfo() @@ -1267,10 +1272,10 @@ class X2GoClient(object): Check if session with unique identifier <session_uuid> is configured to use an intermediate SSH proxy server. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: returns C{True} if the session is configured to use an SSH proxy, C{False} otherwise. - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: returns C{True} if the session is configured to use an SSH proxy, C{False} otherwise. + :rtype: C{bool} """ return self.session_registry(session_uuid).uses_sshproxy() @@ -1281,11 +1286,11 @@ class X2GoClient(object): Check if the SSH proxy of session with unique identifier <session_uuid> is configured adequately to be able to auto-connect to the SSH proxy server (e.g. by public key authentication). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: returns C{True} if the session's SSH proxy can auto-connect, C{False} otherwise, C{None} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: returns C{True} if the session's SSH proxy can auto-connect, C{False} otherwise, C{None} if no control session has been set up yet. - @rtype: C{bool} + :rtype: C{bool} """ return self.session_registry(session_uuid).can_sshproxy_auto_connect() @@ -1296,11 +1301,11 @@ class X2GoClient(object): Check if session with unique identifier <session_uuid> is configured adequately to be able to auto-connect to the X2Go server (e.g. by public key authentication). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: returns C{True} if the session can auto-connect, C{False} otherwise, C{None} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: returns C{True} if the session can auto-connect, C{False} otherwise, C{None} if no control session has been set up yet. - @rtype: C{bool} + :rtype: C{bool} """ return self.session_registry(session_uuid).can_auto_connect() @@ -1313,10 +1318,10 @@ class X2GoClient(object): and can be used to override the auto-connect procedure from within your client implementation. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: returns C{True} if the session could be auto-connected. - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: returns C{True} if the session could be auto-connected. + :rtype: C{bool} """ self.session_registry(session_uuid).do_auto_connect(redirect_to_client=False) @@ -1338,37 +1343,37 @@ class X2GoClient(object): This method basically wraps around paramiko.SSHClient.connect() for the corresponding session. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param username: user name to be used for session authentication (Default value = None) - @type username: C{str} - @param password: the user's password for the X2Go server that is going to be + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param username: user name to be used for session authentication (Default value = None) + :type username: C{str} + :param password: the user's password for the X2Go server that is going to be connected to (Default value = None) - @type password: C{str} - @param passphrase: a passphrase to use for unlocking + :type password: C{str} + :param passphrase: a passphrase to use for unlocking a private key in case the password is already needed for two-factor authentication (Default value = None) - @type passphrase: C{str} - @param sshproxy_user: user name to be used for SSH proxy authentication (Default value = None) - @type sshproxy_user: C{str} - @param sshproxy_password: the SSH proxy user's password (Default value = None) - @type sshproxy_password: C{str} - @param sshproxy_passphrase: a passphrase to use for unlocking + :type passphrase: C{str} + :param sshproxy_user: user name to be used for SSH proxy authentication (Default value = None) + :type sshproxy_user: C{str} + :param sshproxy_password: the SSH proxy user's password (Default value = None) + :type sshproxy_password: C{str} + :param sshproxy_passphrase: a passphrase to use for unlocking a private key needed for the SSH proxy host in case the sshproxy_password is already needed for two-factor authentication (Default value = None) - @type sshproxy_passphrase: C{str} - @param add_to_known_hosts: non-Paramiko option, if C{True} paramiko.AutoAddPolicy() + :type sshproxy_passphrase: C{str} + :param add_to_known_hosts: non-Paramiko option, if C{True} paramiko.AutoAddPolicy() is used as missing-host-key-policy. If set to C{False} L{checkhosts.X2GoInteractiveAddPolicy()} is used (Default value = False) - @type add_to_known_hosts: C{bool} - @param force_password_auth: disable SSH pub/priv key authentication mechanisms + :type add_to_known_hosts: C{bool} + :param force_password_auth: disable SSH pub/priv key authentication mechanisms completely (Default value = False) - @type force_password_auth: C{bool} - @param sshproxy_force_password_auth: disable SSH pub/priv key authentication mechanisms + :type force_password_auth: C{bool} + :param sshproxy_force_password_auth: disable SSH pub/priv key authentication mechanisms completely for SSH proxy connection (Default value = False) - @type sshproxy_force_password_auth: C{bool} - @return: returns True if this method has been successful - @rtype: C{bool} + :type sshproxy_force_password_auth: C{bool} + :returns: returns True if this method has been successful + :rtype: C{bool} """ _success = self.session_registry(session_uuid).connect(username=username, @@ -1392,8 +1397,8 @@ class X2GoClient(object): """\ Disconnect an L{X2GoSession} by closing down its Paramiko/SSH Transport thread. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} """ self.session_registry(session_uuid).disconnect() @@ -1405,10 +1410,10 @@ class X2GoClient(object): """\ If X2Go client-side printing is enable within an X2Go session you can use this method to alter the way how incoming print spool jobs are handled/processed. - + Currently, there are five different print actions available, each defined as an individual print action class: - + - B{PDFVIEW} (L{X2GoPrintActionPDFVIEW}): view an incoming spool job (a PDF file) locally in a PDF viewer - B{PDFSAVE} (L{X2GoPrintActionPDFSAVE}): save an incoming spool job (a PDF file) @@ -1419,19 +1424,20 @@ class X2GoClient(object): print job (PDF) file - B{DIALOG} (L{X2GoPrintActionDIALOG}): on each incoming spool job this print action will call L{X2GoClient.HOOK_open_print_dialog()} - + Each of the print action classes accepts different print action arguments. For detail information on these print action arguments please refer to the constructor methods of each class individually. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param print_action: one of the named above print actions, either as string or class instance - @type print_action: C{str} or C{instance} - @param kwargs: additional information for the given print action (print + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param print_action: one of the named above print actions, either as string or class instance + :type print_action: C{str} or C{instance} + :param kwargs: additional information for the given print action (print action arguments), for possible print action arguments and their values see each individual print action class - @type kwargs: C{dict} + :type kwargs: C{dict} + :param **kwargs: """ self.session_registry(session_uuid).set_print_action(print_action=print_action, **kwargs) @@ -1443,10 +1449,10 @@ class X2GoClient(object): given title, it will be prepended, so that every X2Go session window always contains the X2Go session ID of that window. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param title: new title for session window (Default value = '') - @type title: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param title: new title for session window (Default value = '') + :type title: C{str} """ self.session_registry(session_uuid).set_session_window_title(title=title) @@ -1457,8 +1463,8 @@ class X2GoClient(object): Try to lift the session window above all other windows and bring it to focus. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} """ self.session_registry(session_uuid).raise_session_window() @@ -1467,20 +1473,20 @@ class X2GoClient(object): def session_auto_start_or_resume(self, session_uuid, newest=True, oldest=False, all_suspended=False, start=True): """\ Automatically start or resume one or several sessions. - + This method is called from within the session itself on session registration, so this method can be used to handle auto-start/-resume events. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param newest: if resuming, only resume newest/youngest session (Default value = True) - @type newest: C{bool} - @param oldest: if resuming, only resume oldest session (Default value = False) - @type oldest: C{bool} - @param all_suspended: if resuming, resume all suspended sessions (Default value = False) - @type all_suspended: C{bool} - @param start: if no session is to be resumed, start a new session (Default value = True) - @type start: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param newest: if resuming, only resume newest/youngest session (Default value = True) + :type newest: C{bool} + :param oldest: if resuming, only resume oldest session (Default value = False) + :type oldest: C{bool} + :param all_suspended: if resuming, resume all suspended sessions (Default value = False) + :type all_suspended: C{bool} + :param start: if no session is to be resumed, start a new session (Default value = True) + :type start: C{bool} """ self.session_registry(session_uuid).do_auto_start_or_resume(newest=newest, oldest=oldest, all_suspended=all_suspended, start=start, redirect_to_client=False) @@ -1491,17 +1497,18 @@ class X2GoClient(object): Start a new X2Go session on the remote X2Go server. This method will open---if everything has been successful till here---the X2Go session window. - + Before calling this method you have to register your desired session with L{register_session} (initialization of session parameters) and connect to it with L{connect_session} (authentication). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.start()} method - @type sessionopts: C{dict} - @return: returns True if this method has been successful - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.start()} method + :type sessionopts: C{dict} + :param **sessionopts: + :returns: returns True if this method has been successful + :rtype: C{bool} """ # prevent the newly started session from being registered twice @@ -1525,25 +1532,26 @@ class X2GoClient(object): a to-be-shared session has be registered first with the L{X2GoClient} instance. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param desktop: desktop ID of a sharable desktop in format <user>@<display> (Default value = None) - @type desktop: C{str} - @param user: user name and display number can be given separately, here give the + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param desktop: desktop ID of a sharable desktop in format <user>@<display> (Default value = None) + :type desktop: C{str} + :param user: user name and display number can be given separately, here give the name of the user who wants to share a session with you. (Default value = None) - @type user: C{str} - @param display: user name and display number can be given separately, here give the + :type user: C{str} + :param display: user name and display number can be given separately, here give the number of the display that a user allows you to be shared with. (Default value = None) - @type display: C{str} - @param share_mode: desktop sharing mode, 0 is VIEW-ONLY, 1 is FULL-ACCESS. (Default value = 0) - @type share_mode: C{int} - @param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.share_desktop()} method - @type sessionopts: C{dict} - @param check_desktop_list: check if the given desktop is available on the X2Go server; handle with care as + :type display: C{str} + :param share_mode: desktop sharing mode, 0 is VIEW-ONLY, 1 is FULL-ACCESS. (Default value = 0) + :type share_mode: C{int} + :param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.share_desktop()} method + :type sessionopts: C{dict} + :param check_desktop_list: check if the given desktop is available on the X2Go server; handle with care as the server-side C{x2golistdesktops} command might block client I/O. (Default value = False) - @return: True if the session could be successfully shared. - @rtype: C{bool} - @raise X2GoDesktopSharingException: if a given desktop ID does not specify an available desktop session + :param **sessionopts: + :returns: True if the session could be successfully shared. + :rtype: C{bool} + :raises X2GoDesktopSharingException: if a given desktop ID does not specify an available desktop session """ @@ -1567,17 +1575,18 @@ class X2GoClient(object): remote X2Go server (as specified when L{register_session} was called). - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param session_name: the server-side name of an X2Go session (Default value = None) - @type session_name: C{str} - @param match_profile_name: only resume a session if this profile name matches (Default value = None) - @type match_profile_name: C{str} - @param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.resume()} method - @type sessionopts: C{dict} - @return: returns True if this method has been successful - @rtype: C{bool} - @raise X2GoClientException: if the method does not know what session to resume + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param session_name: the server-side name of an X2Go session (Default value = None) + :type session_name: C{str} + :param match_profile_name: only resume a session if this profile name matches (Default value = None) + :type match_profile_name: C{str} + :param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.resume()} method + :type sessionopts: C{dict} + :param **sessionopts: + :returns: returns True if this method has been successful + :rtype: C{bool} + :raises X2GoClientException: if the method does not know what session to resume """ try: @@ -1599,13 +1608,13 @@ class X2GoClient(object): def suspend_session(self, session_uuid, session_name=None, match_profile_name=None, **sessionopts): """\ Suspend an X2Go session. - + Normally, you will use this method to suspend a registered session that you have formerly started/resumed from within your recent L{X2GoClient} instance. For this you simply call this method using the session's C{session_uuid}, leave the C{session_name} empty. - + Alternatively, you can suspend a non-associated X2Go session: To do this you simply neeed to register (with the L{register_session} method) an X2Go session on the to-be-addressed remote X2Go server and @@ -1613,17 +1622,18 @@ class X2GoClient(object): the freshly obtained C{session_uuid} and the remote X2Go session name (as shown e.g. in x2golistsessions output). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param session_name: the server-side name of an X2Go session (for + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param session_name: the server-side name of an X2Go session (for non-associated session suspend) (Default value = None) - @type session_name: C{str} - @param match_profile_name: only suspend a session if this profile name matches (Default value = None) - @type match_profile_name: C{str} - @param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.suspend()} method - @type sessionopts: C{dict} - @return: returns True if this method has been successful - @rtype: C{bool} + :type session_name: C{str} + :param match_profile_name: only suspend a session if this profile name matches (Default value = None) + :type match_profile_name: C{str} + :param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.suspend()} method + :type sessionopts: C{dict} + :param **sessionopts: + :returns: returns True if this method has been successful + :rtype: C{bool} """ try: @@ -1651,13 +1661,13 @@ class X2GoClient(object): def terminate_session(self, session_uuid, session_name=None, match_profile_name=None, **sessionopts): """\ Terminate an X2Go session. - + Normally you will use this method to terminate a registered session that you have formerly started/resumed from within your recent L{X2GoClient} instance. For this you simply call this method using the session's C{session_uuid}, leave the C{session_name} empty. - + Alternatively, you can terminate a non-associated X2Go session: To do this you simply neeed to register (L{register_session}) an X2Go session on the to-be-addressed remote X2Go server and @@ -1665,16 +1675,17 @@ class X2GoClient(object): the freshly obtained C{session_uuid} and the remote X2Go session name (as shown in e.g. x2golistsessions output). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param session_name: the server-side name of an X2Go session (Default value = None) - @type session_name: C{str} - @param match_profile_name: only terminate a session if this profile name matches (Default value = None) - @type match_profile_name: C{str} - @param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.terminate()} method - @type sessionopts: C{dict} - @return: returns True if this method has been successful - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param session_name: the server-side name of an X2Go session (Default value = None) + :type session_name: C{str} + :param match_profile_name: only terminate a session if this profile name matches (Default value = None) + :type match_profile_name: C{str} + :param sessionopts: pass-through of options directly to the session instance's L{X2GoSession.terminate()} method + :type sessionopts: C{dict} + :param **sessionopts: + :returns: returns True if this method has been successful + :rtype: C{bool} """ try: @@ -1703,18 +1714,18 @@ class X2GoClient(object): """\ Retrieve the profile name of the session that has been registered under C{session_uuid}. - + For profile based sessions this will be the profile name as used in x2goclient's »sessions« configuration file. - + For non-profile based session this will either be a C{profile_name} that was passed to L{register_session} or it will be the application that instantiated this L{X2GoClient} instance. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: X2Go session profile name - @rtype: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: X2Go session profile name + :rtype: C{str} """ return self.session_registry(session_uuid).get_profile_name() @@ -1724,19 +1735,19 @@ class X2GoClient(object): """\ Retrieve the profile id of the session that has been registered under C{session_uuid}. - + For profile based sessions this will be the profile id as used in x2goclient's »sessions« configuration node (section header of a session profile in the config, normally a timestamp created on session profile creation/modification). - + For non-profile based sessions this will be a timestamp created on X2Go session registration by C{register_session}. - @param session_uuid: the session profile name - @type session_uuid: C{str} - @return: the X2Go session profile's id - @rtype: C{str} + :param session_uuid: the session profile name + :type session_uuid: C{str} + :returns: the X2Go session profile's id + :rtype: C{str} """ return self.session_registry(session_uuid).profile_id @@ -1747,10 +1758,10 @@ class X2GoClient(object): Test if the X2Go session registered as C{session_uuid} is in a healthy state. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: C{True} if session is ok, C{False} otherwise - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: C{True} if session is ok, C{False} otherwise + :rtype: C{bool} """ return self.session_registry(session_uuid).session_ok() @@ -1761,10 +1772,10 @@ class X2GoClient(object): Test if the X2Go session registered as C{session_uuid} connected to the X2Go server. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: C{True} if session is connected, C{False} otherwise - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: C{True} if session is connected, C{False} otherwise + :rtype: C{bool} """ return self.session_registry(session_uuid).is_connected() @@ -1775,10 +1786,10 @@ class X2GoClient(object): Test if the X2Go given session profile has open connections to the X2Go server. - @param profile_name: a valid session profile name - @type profile_name: C{str} - @return: C{True} if profile has a connected session, C{False} otherwise - @rtype: C{bool} + :param profile_name: a valid session profile name + :type profile_name: C{str} + :returns: C{True} if profile has a connected session, C{False} otherwise + :rtype: C{bool} """ return bool(self.client_connected_sessions_of_profile_name(profile_name=profile_name)) @@ -1788,10 +1799,10 @@ class X2GoClient(object): """\ Test if the X2Go given session profile is configured in the client's C{sessions} file. - @param profile_id_or_name: test existence of this session profile name (or id) - @type profile_id_or_name: C{str} - @return: C{True} if session profile exists, C{False} otherwise - @rtype: C{bool} + :param profile_id_or_name: test existence of this session profile name (or id) + :type profile_id_or_name: C{str} + :returns: C{True} if session profile exists, C{False} otherwise + :rtype: C{bool} """ return self.session_profiles.has_profile(profile_id_or_name) @@ -1802,12 +1813,12 @@ class X2GoClient(object): Test if the X2Go session registered as C{session_uuid} is up and running. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param session_name: the server-side name of an X2Go session (Default value = None) - @type session_name: C{str} - @return: C{True} if session is running, C{False} otherwise - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param session_name: the server-side name of an X2Go session (Default value = None) + :type session_name: C{str} + :returns: C{True} if session is running, C{False} otherwise + :rtype: C{bool} """ if session_name is None: @@ -1821,12 +1832,12 @@ class X2GoClient(object): Test if the X2Go session registered as C{session_uuid} is in suspended state. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param session_name: the server-side name of an X2Go session (Default value = None) - @type session_name: C{str} - @return: C{True} if session is suspended, C{False} otherwise - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param session_name: the server-side name of an X2Go session (Default value = None) + :type session_name: C{str} + :returns: C{True} if session is suspended, C{False} otherwise + :rtype: C{bool} """ if session_name is None: @@ -1840,12 +1851,12 @@ class X2GoClient(object): Test if the X2Go session registered as C{session_uuid} has terminated. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param session_name: the server-side name of an X2Go session (Default value = None) - @type session_name: C{str} - @return: C{True} if session has terminated, C{False} otherwise - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param session_name: the server-side name of an X2Go session (Default value = None) + :type session_name: C{str} + :returns: C{True} if session has terminated, C{False} otherwise + :rtype: C{bool} """ if session_name is None: @@ -1859,12 +1870,12 @@ class X2GoClient(object): Test if local folder sharing is available for X2Go session with unique ID <session_uuid> or session profile <profile_name>. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: alternatively, the profile name can be used to perform this query (Default value = None) - @type profile_name: C{str} - @return: returns C{True} if the profile/session supports local folder sharing - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: alternatively, the profile name can be used to perform this query (Default value = None) + :type profile_name: C{str} + :returns: returns C{True} if the profile/session supports local folder sharing + :rtype: C{bool} """ if session_uuid is None and profile_name: @@ -1884,22 +1895,22 @@ class X2GoClient(object): def share_local_folder(self, session_uuid=None, local_path=None, profile_name=None, folder_name=None): """\ Share a local folder with the X2Go session registered as C{session_uuid}. - + When calling this method the given client-side folder is mounted on the X2Go server (via sshfs) and (if in desktop mode) provided as a desktop icon on your remote session's desktop. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param local_path: the full path to an existing folder on the local (client-side) + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param local_path: the full path to an existing folder on the local (client-side) file system (Default value = None) - @type local_path: C{str} - @param folder_name: synonymous to C{local_path} (Default value = None) - @type folder_name: C{str} - @param profile_name: alternatively, the profile name can be used to share local folders (Default value = None) - @type profile_name: C{str} - @return: returns C{True} if the local folder has been successfully mounted - @rtype: C{bool} + :type local_path: C{str} + :param folder_name: synonymous to C{local_path} (Default value = None) + :type folder_name: C{str} + :param profile_name: alternatively, the profile name can be used to share local folders (Default value = None) + :type profile_name: C{str} + :returns: returns C{True} if the local folder has been successfully mounted + :rtype: C{bool} """ # compat for Python-X2Go (<=0.1.1.6) @@ -1923,18 +1934,18 @@ class X2GoClient(object): """\ Unshare all local folders mounted in X2Go session registered as C{session_uuid}. - + When calling this method all client-side mounted folders on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: alternatively, the profile name can be used to unshare + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: alternatively, the profile name can be used to unshare mounted folders (Default value = None) - @type profile_name: C{str} - @return: returns C{True} if all local folders could be successfully unmounted - @rtype: C{bool} + :type profile_name: C{str} + :returns: returns C{True} if all local folders could be successfully unmounted + :rtype: C{bool} """ if session_uuid is None and profile_name: @@ -1953,22 +1964,22 @@ class X2GoClient(object): """\ Unshare local folder that is mounted in the X2Go session registered as C{session_uuid}. - + When calling this method the given client-side mounted folder on the X2Go server (via sshfs) for session with ID <session_uuid> will get unmounted. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: alternatively, the profile name can be used to unshare + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: alternatively, the profile name can be used to unshare mounted folders (Default value = None) - @type profile_name: C{str} - @param local_path: the full path of a local folder that is mounted within X2Go + :type profile_name: C{str} + :param local_path: the full path of a local folder that is mounted within X2Go session with session ID <session_uuid> (or recognized via profile name) and that shall be unmounted from that session. (Default value = None) - @type local_path: C{str} - @return: returns C{True} if all local folders could be successfully unmounted - @rtype: C{bool} + :type local_path: C{str} + :returns: returns C{True} if all local folders could be successfully unmounted + :rtype: C{bool} """ if session_uuid is None and profile_name: @@ -1988,14 +1999,14 @@ class X2GoClient(object): Get a list of local folders mounted within X2Go session with session hash <session_uuid> from this client. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: alternatively, the profile name can be used to get mounted folders of a session connected profile (Default value = None) - @type profile_name: C{str} - @param check_list_mounts: query the server-side mount list for up-to-date information (Default value = False) - @type check_list_mounts: C{bool} - @return: returns a C{list} of those local folder names that are mounted within X2Go session <session_uuid>. - @rtype: C{list} + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: alternatively, the profile name can be used to get mounted folders of a session connected profile (Default value = None) + :type profile_name: C{str} + :param check_list_mounts: query the server-side mount list for up-to-date information (Default value = False) + :type check_list_mounts: C{bool} + :returns: returns a C{list} of those local folder names that are mounted within X2Go session <session_uuid>. + :rtype: C{list} """ if session_uuid is None and profile_name: @@ -2024,14 +2035,14 @@ class X2GoClient(object): """\ Retrieve the master session of a specific profile. - @param profile_name: the profile name that we query the master session of - @type profile_name: C{str} - @param return_object: return L{X2GoSession} instance (Default value = True) - @type return_object: C{bool} - @param return_session_name: return X2Go session name (Default value = False) - @type return_session_name: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param profile_name: the profile name that we query the master session of + :type profile_name: C{str} + :param return_object: return L{X2GoSession} instance (Default value = True) + :type return_object: C{bool} + :param return_session_name: return X2Go session name (Default value = False) + :type return_session_name: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self.session_registry.get_master_session(profile_name, return_object=return_object, return_session_name=return_session_name) @@ -2047,16 +2058,16 @@ class X2GoClient(object): """\ Retrieve a list of X2Go sessions that this L{X2GoClient} instance is connected to. - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_profile_names: return as list of session profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of session profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of connected sessions - @rtype: C{list} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_profile_names: return as list of session profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of session profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of connected sessions + :rtype: C{list} """ return self.session_registry.connected_sessions(return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -2076,16 +2087,16 @@ class X2GoClient(object): """\ Retrieve a list of X2Go sessions associated to this L{X2GoClient} instance. - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_profile_names: return as list of session profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of session profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of associated sessions - @rtype: C{list} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_profile_names: return as list of session profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of session profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of associated sessions + :rtype: C{list} """ return self.session_registry.associated_sessions(return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -2105,16 +2116,16 @@ class X2GoClient(object): """\ Retrieve a list of running X2Go sessions. - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_profile_names: return as list of session profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of session profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of running sessions - @rtype: C{list} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_profile_names: return as list of session profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of session profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of running sessions + :rtype: C{list} """ return self.session_registry.running_sessions(return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -2134,16 +2145,16 @@ class X2GoClient(object): """\ Retrieve a list of suspended X2Go sessions. - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_profile_names: return as list of session profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of session profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of suspended sessions - @rtype: C{list} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_profile_names: return as list of session profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of session profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of suspended sessions + :rtype: C{list} """ return self.session_registry.running_sessions(return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -2163,16 +2174,16 @@ class X2GoClient(object): """\ Retrieve a list of registered X2Go sessions. - @param return_objects: return as list of X2Go session objects (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of session profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of session profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of registered sessions - @rtype: C{list} + :param return_objects: return as list of X2Go session objects (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of session profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of session profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of registered sessions + :rtype: C{list} """ return self.session_registry.registered_sessions(return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -2192,10 +2203,10 @@ class X2GoClient(object): """\ Retrieve control session for profile name <profile_name>. - @param profile_name: profile name - @type profile_name: C{str} - @return: control session instance - @rtype: C{X2GoControlSession} instance + :param profile_name: profile name + :type profile_name: C{str} + :returns: control session instance + :rtype: C{X2GoControlSession} instance """ return self.session_registry.control_session_of_profile_name(profile_name) @@ -2206,15 +2217,15 @@ class X2GoClient(object): Query the server configured in session profile <profile_name> for the list of install X2Go components and its versions. - @param profile_name: use the control session of this profile to query the X2Go server for its component list - @type profile_name: C{str} - @param component: only return the version of a specific component (Default value = None) - @type component: C{str} - @param force: refresh component/version data by a query to the server (Default value = False) - @type force: C{bool} - @return: dictionary of server components (as keys) and their versions (as values) or the version of the given <component> - @rtype: C{dict} or C{str} - @raise X2GoClientException: if component is not available on the X2Go Server. + :param profile_name: use the control session of this profile to query the X2Go server for its component list + :type profile_name: C{str} + :param component: only return the version of a specific component (Default value = None) + :type component: C{str} + :param force: refresh component/version data by a query to the server (Default value = False) + :type force: C{bool} + :returns: dictionary of server components (as keys) and their versions (as values) or the version of the given <component> + :rtype: C{dict} or C{str} + :raises X2GoClientException: if component is not available on the X2Go Server. """ control_session = self.client_control_session_of_profile_name(profile_name) @@ -2234,12 +2245,12 @@ class X2GoClient(object): Query the server configured in session profile <profile_name> for the list of server-side X2Go features. - @param profile_name: use the control session of this profile to query the X2Go server for its feature list - @type profile_name: C{str} - @param force: refresh feature list by a query to the server (Default value = False) - @type force: C{bool} - @return: list of server feature names (as returned by server-side command ,,x2gofeaturelist'' - @rtype: C{list} + :param profile_name: use the control session of this profile to query the X2Go server for its feature list + :type profile_name: C{str} + :param force: refresh feature list by a query to the server (Default value = False) + :type force: C{bool} + :returns: list of server feature names (as returned by server-side command ,,x2gofeaturelist'' + :rtype: C{list} """ control_session = self.client_control_session_of_profile_name(profile_name) @@ -2251,12 +2262,12 @@ class X2GoClient(object): Query the server configured in session profile <profile_name> for the availability of a certain server feature. - @param profile_name: use the control session of this profile to query the X2Go server for its feature - @type profile_name: C{str} - @param feature: test the availability of this feature on the X2Go server - @type feature: C{str} - @return: C{True} if the feature is available on the queried server - @rtype: C{bool} + :param profile_name: use the control session of this profile to query the X2Go server for its feature + :type profile_name: C{str} + :param feature: test the availability of this feature on the X2Go server + :type feature: C{str} + :returns: C{True} if the feature is available on the queried server + :rtype: C{bool} """ control_session = self.client_control_session_of_profile_name(profile_name) @@ -2267,12 +2278,12 @@ class X2GoClient(object): """\ Retrieve X2Go session of a given session name. - @param session_name: session name - @type session_name: C{str} - @param return_object: return as X2Go session object (Default value = False) - @type return_object: C{bool} - @return: session instance of the given name - @rtype: C{X2GoSession} or C{str} + :param session_name: session name + :type session_name: C{str} + :param return_object: return as X2Go session object (Default value = False) + :type return_object: C{bool} + :returns: session instance of the given name + :rtype: C{X2GoSession} or C{str} """ return self.session_registry.get_session_of_session_name(session_name, return_object=return_object) @@ -2282,10 +2293,10 @@ class X2GoClient(object): """\ Equals C{True} if there is a registered session of name <session_name>. - @param session_name: session name - @type session_name: C{str} - @return: C{True} if the given session is registered - @rtype: C{bool} + :param session_name: session name + :type session_name: C{str} + :returns: C{True} if the given session is registered + :rtype: C{bool} """ return self.client_registered_session_of_name(session_name) is not None @@ -2295,14 +2306,14 @@ class X2GoClient(object): """\ Retrieve registered X2Go sessions of profile name <profile_name>. - @param profile_name: profile name - @type profile_name: C{str} - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of registered sessions of profile name - @rtype: C{list} + :param profile_name: profile name + :type profile_name: C{str} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of registered sessions of profile name + :rtype: C{list} """ return self.session_registry.registered_sessions_of_profile_name(profile_name, return_objects=return_objects, return_session_names=return_session_names) @@ -2312,14 +2323,14 @@ class X2GoClient(object): """\ Retrieve connected X2Go sessions of profile name <profile_name>. - @param profile_name: profile name - @type profile_name: C{str} - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of connected sessions of profile name - @rtype: C{list} + :param profile_name: profile name + :type profile_name: C{str} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of connected sessions of profile name + :rtype: C{list} """ return self.session_registry.connected_sessions_of_profile_name(profile_name, return_objects=return_objects, return_session_names=return_session_names) @@ -2329,14 +2340,14 @@ class X2GoClient(object): """\ Retrieve associated X2Go sessions of profile name <profile_name>. - @param profile_name: profile name - @type profile_name: C{str} - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of associated sessions of profile name - @rtype: C{list} + :param profile_name: profile name + :type profile_name: C{str} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of associated sessions of profile name + :rtype: C{list} """ return self.session_registry.associated_sessions_of_profile_name(profile_name, return_objects=return_objects, return_session_names=return_session_names) @@ -2346,14 +2357,14 @@ class X2GoClient(object): """\ Retrieve X2Go sessions of profile name <profile_name> that provide published applications. - @param profile_name: profile name - @type profile_name: C{str} - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of application publishing sessions of profile name - @rtype: C{list} + :param profile_name: profile name + :type profile_name: C{str} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of application publishing sessions of profile name + :rtype: C{list} """ return self.session_registry.pubapp_sessions_of_profile_name(profile_name, return_objects=return_objects, return_session_names=return_session_names) @@ -2364,14 +2375,14 @@ class X2GoClient(object): """\ Retrieve running X2Go sessions of profile name <profile_name>. - @param profile_name: profile name - @type profile_name: C{str} - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of running sessions of profile name - @rtype: C{list} + :param profile_name: profile name + :type profile_name: C{str} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of running sessions of profile name + :rtype: C{list} """ return self.session_registry.running_sessions_of_profile_name(profile_name, return_objects=return_objects, return_session_names=return_session_names) @@ -2381,14 +2392,14 @@ class X2GoClient(object): """\ Retrieve suspended X2Go sessions of profile name <profile_name>. - @param profile_name: profile name - @type profile_name: C{str} - @param return_objects: return as list of X2Go session objects (Default value = False) - @type return_objects: C{bool} - @param return_session_names: return as list of session names (Default value = False) - @type return_session_names: C{bool} - @return: list of suspended sessions of profile name - @rtype: C{list} + :param profile_name: profile name + :type profile_name: C{str} + :param return_objects: return as list of X2Go session objects (Default value = False) + :type return_objects: C{bool} + :param return_session_names: return as list of session names (Default value = False) + :type return_session_names: C{bool} + :returns: list of suspended sessions of profile name + :rtype: C{list} """ return self.session_registry.suspended_sessions_of_profile_name(profile_name, return_objects=return_objects, return_session_names=return_session_names) @@ -2401,14 +2412,14 @@ class X2GoClient(object): def server_is_alive(self, session_uuid): """\ Test if server that corresponds to the terminal session C{session_uuid} is alive. - + If the session is not connected anymore the L{X2GoClient.HOOK_on_control_session_death()} gets called. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: C{True} if X2Go server connection for L{X2GoSession} instance with <session_uuid> is alive. - @rtype: C{bool} - @raise X2GoControlSessionException: if the session is not connected anymore; in that case the L{HOOK_on_control_session_death} gets called. + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: C{True} if X2Go server connection for L{X2GoSession} instance with <session_uuid> is alive. + :rtype: C{bool} + :raises X2GoControlSessionException: if the session is not connected anymore; in that case the L{HOOK_on_control_session_death} gets called. """ try: @@ -2425,8 +2436,9 @@ class X2GoClient(object): Test vitality of all connected X2Go servers. - @return: C{True} if all connected X2Go servers are alive. - @rtype: C{bool} + :returns: C{True} if all connected X2Go servers are alive. + + :rtype: C{bool} """ _all_alive = True @@ -2439,12 +2451,12 @@ class X2GoClient(object): """\ Check if user is allowed to start an X2Go session on a remote server. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param username: user name to test validity for (Default value = None) - @type username: C{str} - @return: Is remote user allowed to start an X2Go session? - @rtype: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param username: user name to test validity for (Default value = None) + :type username: C{str} + :returns: Is remote user allowed to start an X2Go session? + :rtype: C{str} """ return self.session_registry(session_uuid).user_is_x2gouser(username=username) @@ -2455,11 +2467,11 @@ class X2GoClient(object): Retrieve a list of session names of all server-side running sessions (including those not instantiated by our L{X2GoClient} instance). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: list of session names - @rtype: C{list} - @raise X2GoClientException: if the session with UUID C{session_uuid} is not connected + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: list of session names + :rtype: C{list} + :raises X2GoClientException: if the session with UUID C{session_uuid} is not connected """ if self._X2GoClient__is_session_connected(session_uuid): @@ -2473,10 +2485,10 @@ class X2GoClient(object): """\ Equals C{True} if the X2Go server has any running sessions. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: C{True}, if there are running sessions - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: C{True}, if there are running sessions + :rtype: C{bool} """ return len(self._X2GoClient__server_running_sessions(session_uuid)) > 0 @@ -2486,10 +2498,10 @@ class X2GoClient(object): """\ Equals C{True} if the X2Go server has a running session of name <session_name>. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param session_name: session name - @type session_name: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param session_name: session name + :type session_name: C{str} """ return session_name in self._X2GoClient__server_running_sessions(session_uuid) @@ -2500,11 +2512,11 @@ class X2GoClient(object): Retrieve a list of session names of all server-side suspended sessions (including those not instantiated by our L{X2GoClient} instance). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: list of session names - @rtype: C{list} - @raise X2GoClientException: if the session with UUID C{session_uuid} is not connected + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: list of session names + :rtype: C{list} + :raises X2GoClientException: if the session with UUID C{session_uuid} is not connected """ if self._X2GoClient__is_session_connected(session_uuid): @@ -2518,8 +2530,8 @@ class X2GoClient(object): """\ Equals C{True} if the X2Go server has any suspended sessions. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} """ return len(self._X2GoClient__server_suspended_sessions(session_uuid)) > 0 @@ -2529,12 +2541,12 @@ class X2GoClient(object): """\ Equals C{True} if the X2Go server has a suspended session of name <session_name>. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param session_name: session name - @type session_name: C{str} - @return: C{True}, if there are running sessions - @rtype: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param session_name: session name + :type session_name: C{str} + :returns: C{True}, if there are running sessions + :rtype: C{bool} """ return session_name in self._X2GoClient__server_suspended_sessions(session_uuid) @@ -2548,17 +2560,17 @@ class X2GoClient(object): """\ Find running X2Go sessions that have previously been started by the connected user on the remote X2Go server and terminate them. - + Before calling this method you have to setup a pro forma remote X2Go session with L{X2GoClient.register_session()} (even if you do not intend to open a real X2Go session window on the remote server) and connect to this session (with L{X2GoClient.connect_session()}. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param published_applications: if C{True}, also terminate sessions that are published applications + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param published_applications: if C{True}, also terminate sessions that are published applications provider (Default value = False) - @type published_applications: C{bool} + :type published_applications: C{bool} """ _destroy_terminals = not ( self.auto_update_sessionregistry == True) @@ -2580,32 +2592,32 @@ class X2GoClient(object): Use the X2Go session registered under C{session_uuid} to retrieve a list of running or suspended X2Go sessions from the connected X2Go server (for the authenticated user). - + Before calling this method you have to setup a pro forma remote X2Go session with L{X2GoClient.register_session()} (even if you do not intend to open a real X2Go session window on the remote server) and connect to this session (with L{X2GoClient.connect_session()}. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: use profile name instead of <session_uuid> (Default value = None) - @type profile_name: C{str} - @param profile_id: use profile id instead of <profile_name> or <session_uuid> (Default value = None) - @type profile_id: C{str} - @param no_cache: do not get the session list from cache, query the X2Go server directly (Default value = False) - @type no_cache: C{bool} - @param refresh_cache: query the X2Go server directly and update the session list cache + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: use profile name instead of <session_uuid> (Default value = None) + :type profile_name: C{str} + :param profile_id: use profile id instead of <profile_name> or <session_uuid> (Default value = None) + :type profile_id: C{str} + :param no_cache: do not get the session list from cache, query the X2Go server directly (Default value = False) + :type no_cache: C{bool} + :param refresh_cache: query the X2Go server directly and update the session list cache with the new information (Default value = False) - @type refresh_cache: C{bool} - @param update_sessionregistry: query the X2Go server directly and update the + :type refresh_cache: C{bool} + :param update_sessionregistry: query the X2Go server directly and update the session registry according to the obtained information (Default value = True) - @type update_sessionregistry: C{bool} - @param register_sessions: query the X2Go server directly and register newly found X2Go session + :type update_sessionregistry: C{bool} + :param register_sessions: query the X2Go server directly and register newly found X2Go session as L{X2GoSession} instances associated to this L{X2GoClient} instance (Default value = False) - @type register_sessions: C{bool} - @param raw: output the session list in X2Go's raw C{x2golistsessions} format (Default value = False) - @type raw: C{bool} - @raise X2GoClientException: if the session profile specified by C{session_uuid}, C{profile_name} or C{profile_id} is not connected + :type register_sessions: C{bool} + :param raw: output the session list in X2Go's raw C{x2golistsessions} format (Default value = False) + :type raw: C{bool} + :raises X2GoClientException: if the session profile specified by C{session_uuid}, C{profile_name} or C{profile_id} is not connected or if none of the named parameters has been specified """ @@ -2661,32 +2673,32 @@ class X2GoClient(object): Use the X2Go session registered under C{session_uuid} to retrieve a list of X2Go desktop sessions that are available for desktop sharing. - + Before calling this method you have to setup a pro forma remote X2Go session with L{X2GoClient.register_session()} (even if you do not intend to open a real X2Go session window on the remote server) and connect to this session (with L{X2GoClient.connect_session()}. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: use profile name instead of <session_uuid> (Default value = None) - @type profile_name: C{str} - @param profile_id: use profile id instead of <profile_name> or <session_uuid> (Default value = None) - @type profile_id: C{str} - @param no_cache: do not get the desktop list from cache, query the X2Go server directly (Default value = False) - @type no_cache: C{bool} - @param refresh_cache: query the X2Go server directly and update the desktop list cache + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: use profile name instead of <session_uuid> (Default value = None) + :type profile_name: C{str} + :param profile_id: use profile id instead of <profile_name> or <session_uuid> (Default value = None) + :type profile_id: C{str} + :param no_cache: do not get the desktop list from cache, query the X2Go server directly (Default value = False) + :type no_cache: C{bool} + :param refresh_cache: query the X2Go server directly and update the desktop list cache with the new information (Default value = False) - @type refresh_cache: C{bool} - @param exclude_session_types: session types (e.g. "D", "R", "S" or "P") to be excluded from the + :type refresh_cache: C{bool} + :param exclude_session_types: session types (e.g. "D", "R", "S" or "P") to be excluded from the returned list of sharable desktops (this only works for sharing someone's own sessions, for sharing other users' sessions, the X2Go Desktop Sharing decides on what is sharable and what not). (Default value = []) - @type exclude_session_types: C{list} - @param raw: output the session list in X2Go's raw C{x2golistdesktops} format (Default value = False) - @type raw: C{bool} - @return: a list of available desktops to be shared - @rtype: C{list} - @raise X2GoClientException: if the session profile specified by C{session_uuid}, C{profile_name} or C{profile_id} is not connected + :type exclude_session_types: C{list} + :param raw: output the session list in X2Go's raw C{x2golistdesktops} format (Default value = False) + :type raw: C{bool} + :returns: a list of available desktops to be shared + :rtype: C{list} + :raises X2GoClientException: if the session profile specified by C{session_uuid}, C{profile_name} or C{profile_id} is not connected or if none of the named parameters has been specified """ @@ -2745,15 +2757,15 @@ class X2GoClient(object): For a given profil C{profile_name} to retrieve its list of mounted client shares for that session. - @param profile_name: a valid profile name - @type profile_name: C{str} - @param no_cache: do not get the session list from cache, query the X2Go server directly (Default value = False) - @type no_cache: C{bool} - @param raw: output the session list in X2Go's raw C{x2golistmounts} format (Default value = False) - @type raw: C{bool} - @param refresh_cache: (Default value = False) - @return: list of server-side mounted shares for a given profile name - @rtype: C{list} + :param profile_name: a valid profile name + :type profile_name: C{str} + :param no_cache: do not get the session list from cache, query the X2Go server directly (Default value = False) + :type no_cache: C{bool} + :param raw: output the session list in X2Go's raw C{x2golistmounts} format (Default value = False) + :type raw: C{bool} + :param refresh_cache: Default value = False) + :returns: list of server-side mounted shares for a given profile name + :rtype: C{list} """ sessions = [ s for s in self.client_running_sessions(return_objects=True) if s.get_profile_name() == profile_name ] @@ -2776,15 +2788,15 @@ class X2GoClient(object): Use the X2Go session registered under C{session_uuid} to retrieve its list of mounted client shares for that session. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param no_cache: do not get the session list from cache, query the X2Go server directly (Default value = False) - @type no_cache: C{bool} - @param raw: output the session list in X2Go's raw C{x2golistmounts} format (Default value = False) - @type raw: C{bool} - @param refresh_cache: (Default value = False) - @return: list of server-side mounted shares for a given session UUID - @rtype: C{list} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param no_cache: do not get the session list from cache, query the X2Go server directly (Default value = False) + :type no_cache: C{bool} + :param raw: output the session list in X2Go's raw C{x2golistmounts} format (Default value = False) + :type raw: C{bool} + :param refresh_cache: Default value = False) + :returns: list of server-side mounted shares for a given session UUID + :rtype: C{list} """ if raw: @@ -2807,14 +2819,15 @@ class X2GoClient(object): def get_profiles(self): """\ Returns the L{X2GoClient} instance's C{X2GoSessionProfiles*} object. - + Use this method for object retrieval if you want to modify the »sessions« configuration node (e.g. in ~/.x2goclient with the FILE backend) from within your Python X2Go based application. - @return: a C{X2GoSessionProfiles*} instance - @rtype: C{obj} + :returns: a C{X2GoSessionProfiles*} instance + + :rtype: C{obj} """ return self.session_profiles @@ -2835,14 +2848,15 @@ class X2GoClient(object): def get_client_settings(self): """\ Returns the L{X2GoClient} instance's C{X2GoClientSettings*} object. - + Use this method for object retrieval if you want to modify the »settings« configuration node (e.g. in ~/.x2goclient with the FILE backend) from within your Python X2Go based application. - @return: a C{X2GoClientSettings*} instance - @rtype: C{obj} + :returns: a C{X2GoClientSettings*} instance + + :rtype: C{obj} """ return self.client_settings @@ -2851,14 +2865,15 @@ class X2GoClient(object): def get_client_printing(self): """\ Returns the L{X2GoClient} instance's C{X2GoClientPrinting*} object. - + Use this method for object retrieval if you want to modify the printing configuration node (e.g. in ~/.x2goclient with the FILE backend) from within your Python X2Go based application. - @return: a C{X2GoClientPrinting*} instance - @rtype: C{bool} + :returns: a C{X2GoClientPrinting*} instance + + :rtype: C{bool} """ return self.client_printing @@ -2873,13 +2888,13 @@ class X2GoClient(object): Returns a dictionary with session options and values that represent the session profile for C{profile_id_or_name}. - @param profile_id_or_name: name or id of an X2Go session profile as found + :param profile_id_or_name: name or id of an X2Go session profile as found in the sessions configuration file - @type profile_id_or_name: C{str} - @param parameter: if specified, only the value for the given parameter is returned (Default value = None) - @type parameter: C{str} - @return: a Python dictionary with session profile options - @rtype: C{dict} or C{bool}, C{int}, C{str} + :type profile_id_or_name: C{str} + :param parameter: if specified, only the value for the given parameter is returned (Default value = None) + :type parameter: C{str} + :returns: a Python dictionary with session profile options + :rtype: C{dict} or C{bool}, C{int}, C{str} """ return self.session_profiles.get_profile_config(profile_id_or_name, parameter=parameter) @@ -2890,15 +2905,15 @@ class X2GoClient(object): """\ Set individual session profile parameters for session profile C{profile_id_or_name}. - @param profile_id_or_name: name or id of an X2Go session profile as found + :param profile_id_or_name: name or id of an X2Go session profile as found in the sessions configuration file - @type profile_id_or_name: C{str} - @param parameter: set this parameter with the given C{value} - @type parameter: C{str} - @param value: set this value for the given C{parameter} - @type value: C{bool}, C{int}, C{str}, C{list} or C{dict} - @return: returns C{True} if this operation has been successful - @rtype: C{dict} + :type profile_id_or_name: C{str} + :param parameter: set this parameter with the given C{value} + :type parameter: C{str} + :param value: set this value for the given C{parameter} + :type value: C{bool}, C{int}, C{str}, C{list} or C{dict} + :returns: returns C{True} if this operation has been successful + :rtype: C{dict} """ self.session_profiles.update_value(profile_id_or_name, parameter, value) @@ -2911,10 +2926,10 @@ class X2GoClient(object): Retrieve the session profile ID of the session whose profile name is C{profile_name} - @param profile_name: the session profile name - @type profile_name: C{str} - @return: the session profile's ID - @rtype: C{str} + :param profile_name: the session profile name + :type profile_name: C{str} + :returns: the session profile's ID + :rtype: C{str} """ return self.session_profiles.to_profile_id(profile_name) @@ -2925,10 +2940,10 @@ class X2GoClient(object): Retrieve the session profile name of the session whose profile ID is C{profile_id} - @param profile_id: the session profile ID - @type profile_id: C{str} - @return: the session profile's name - @rtype: C{str} + :param profile_id: the session profile ID + :type profile_id: C{str} + :returns: the session profile's name + :rtype: C{str} """ return self.session_profiles.to_profile_name(profile_id) @@ -2939,10 +2954,10 @@ class X2GoClient(object): Evaluate a session profile and return a human readable meta type (classification) for the session profile C{profile_name}. - @param profile_name: a profile name - @type profile_name: C{str} - @return: the profile's meta type - @rtype: C{str} + :param profile_name: a profile name + :type profile_name: C{str} + :returns: the profile's meta type + :rtype: C{str} """ return self.session_profiles.get_profile_metatype(profile_name) @@ -2952,10 +2967,10 @@ class X2GoClient(object): """\ Retrieve a list of session profiles that are currently connected to an X2Go server. - @param return_profile_names: return as list of session profile names (Default value = False) - @type return_profile_names: C{bool} - @return: a list of profile names or IDs - @rtype: C{list} + :param return_profile_names: return as list of session profile names (Default value = False) + :type return_profile_names: C{bool} + :returns: a list of profile names or IDs + :rtype: C{list} """ if return_profile_names: @@ -2969,10 +2984,10 @@ class X2GoClient(object): Disconnect all L{X2GoSession} instances that relate to C{profile_name} by closing down their Paramiko/SSH Transport thread. - @param profile_name: the X2Go session profile name - @type profile_name: C{str} - @return: a return value - @rtype: C{bool} + :param profile_name: the X2Go session profile name + :type profile_name: C{str} + :returns: a return value + :rtype: C{bool} """ _retval = False @@ -2996,10 +3011,10 @@ class X2GoClient(object): """\ Update the session registry stati by profile name. - @param profile_name: the X2Go session profile name - @type profile_name: C{str} - @param session_list: a manually passed on list of X2Go sessions (Default value = None) - @type session_list: C{X2GoServerList*} instances + :param profile_name: the X2Go session profile name + :type profile_name: C{str} + :param session_list: a manually passed on list of X2Go sessions (Default value = None) + :type session_list: C{X2GoServerList*} instances """ session_uuids = self.client_registered_sessions_of_profile_name(profile_name, return_objects=False) @@ -3021,8 +3036,8 @@ class X2GoClient(object): Update the session registry status of a specific L{X2GoSession} instance with session identifier <session_uuid>. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} """ session_list = self._X2GoClient__list_sessions(session_uuid, update_sessionregistry=False, register_sessions=False) @@ -3045,19 +3060,19 @@ class X2GoClient(object): """\ Update the session list cache by profile name. - @param profile_name: the X2Go session profile name - @type profile_name: C{str} - @param cache_types: specify what cache type to update (available: C{sessions}, C{desktops}, C{mounts}) (Default value = ('sessions') - @type cache_types: C{tuple} or C{list} - @param update_sessions: instead of giving a list of cache types, plainly say C{True} here, if + :param profile_name: the X2Go session profile name + :type profile_name: C{str} + :param cache_types: specify what cache type to update (available: C{sessions}, C{desktops}, C{mounts}) (Default value = ('sessions') + :type cache_types: C{tuple} or C{list} + :param update_sessions: instead of giving a list of cache types, plainly say C{True} here, if you want to update sessions in the session list cache. - @type update_sessions: C{bool} - @param update_desktops: instead of giving a list of cache types, plainly say C{True} here, if + :type update_sessions: C{bool} + :param update_desktops: instead of giving a list of cache types, plainly say C{True} here, if you want to update available desktops in the desktop list cache. - @type update_desktops: C{bool} - @param update_mounts: instead of giving a list of cache types, plainly say C{True} here, if + :type update_desktops: C{bool} + :param update_mounts: instead of giving a list of cache types, plainly say C{True} here, if you want to update mounted shares in the mount list cache. - @type update_mounts: C{bool} + :type update_mounts: C{bool} """ if self.listsessions_cache is not None: @@ -3077,19 +3092,19 @@ class X2GoClient(object): Update the session list cache of a specific L{X2GoSession} instance with session identifier <session_uuid>. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param cache_types: specify what cache type to update (available: C{sessions}, C{desktops}, C{mounts}) (Default value = ('sessions') - @type cache_types: C{tuple} or C{list} - @param update_sessions: instead of giving a list of cache types, plainly say C{True} here, if + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param cache_types: specify what cache type to update (available: C{sessions}, C{desktops}, C{mounts}) (Default value = ('sessions') + :type cache_types: C{tuple} or C{list} + :param update_sessions: instead of giving a list of cache types, plainly say C{True} here, if you want to update sessions in the session list cache. - @type update_sessions: C{bool} - @param update_desktops: instead of giving a list of cache types, plainly say C{True} here, if + :type update_sessions: C{bool} + :param update_desktops: instead of giving a list of cache types, plainly say C{True} here, if you want to update available desktops in the desktop list cache. - @type update_desktops: C{bool} - @param update_mounts: instead of giving a list of cache types, plainly say C{True} here, if + :type update_desktops: C{bool} + :param update_mounts: instead of giving a list of cache types, plainly say C{True} here, if you want to update mounted shares in the mount list cache. - @type update_mounts: C{bool} + :type update_mounts: C{bool} """ profile_name = self.get_session_profile_name(session_uuid) @@ -3105,17 +3120,17 @@ class X2GoClient(object): """\ Update the session list cache of all session profiles. - @param cache_types: specify what cache type to update (available: C{sessions}, C{desktops}, C{mounts}) (Default value = ('sessions') - @type cache_types: C{tuple} or C{list} - @param update_sessions: instead of giving a list of cache types, plainly say C{True} here, if + :param cache_types: specify what cache type to update (available: C{sessions}, C{desktops}, C{mounts}) (Default value = ('sessions') + :type cache_types: C{tuple} or C{list} + :param update_sessions: instead of giving a list of cache types, plainly say C{True} here, if you want to update sessions in the session list cache. - @type update_sessions: C{bool} - @param update_desktops: instead of giving a list of cache types, plainly say C{True} here, if + :type update_sessions: C{bool} + :param update_desktops: instead of giving a list of cache types, plainly say C{True} here, if you want to update available desktops in the desktop list cache. - @type update_desktops: C{bool} - @param update_mounts: instead of giving a list of cache types, plainly say C{True} here, if + :type update_desktops: C{bool} + :param update_mounts: instead of giving a list of cache types, plainly say C{True} here, if you want to update mounted shares in the mount list cache. - @type update_mounts: C{bool} + :type update_mounts: C{bool} """ if self.listsessions_cache is not None: @@ -3137,12 +3152,12 @@ class X2GoClient(object): Register available sessions that are found on the X2Go server the profile of name C{profile_name} is connected to. - @param profile_name: the X2Go session profile name - @type profile_name: C{str} - @param re_register: re-register available sessions, needs to be done after session profile changes (Default value = False) - @type re_register: C{bool} - @param skip_pubapp_sessions: Do not auto-register published applications sessions. (Default value = False) - @type skip_pubapp_sessions: C{bool} + :param profile_name: the X2Go session profile name + :type profile_name: C{str} + :param re_register: re-register available sessions, needs to be done after session profile changes (Default value = False) + :type re_register: C{bool} + :param skip_pubapp_sessions: Do not auto-register published applications sessions. (Default value = False) + :type skip_pubapp_sessions: C{bool} """ if profile_name not in self.client_connected_profiles(return_profile_names=True): @@ -3165,10 +3180,10 @@ class X2GoClient(object): Register available sessions that are found on the X2Go server that the L{X2GoSession} instance with session identifier <session_uuid> is connected to. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param skip_pubapp_sessions: Do not auto-register published applications sessions. (Default value = False) - @type skip_pubapp_sessions: C{bool} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param skip_pubapp_sessions: Do not auto-register published applications sessions. (Default value = False) + :type skip_pubapp_sessions: C{bool} """ profile_name = self.get_session_profile_name(session_uuid) @@ -3179,8 +3194,8 @@ class X2GoClient(object): """\ Register all available sessions found on an X2Go server for each session profile. - @param skip_pubapp_sessions: Do not auto-register published applications sessions. (Default value = False) - @type skip_pubapp_sessions: C{bool} + :param skip_pubapp_sessions: Do not auto-register published applications sessions. (Default value = False) + :type skip_pubapp_sessions: C{bool} """ for profile_name in self.client_connected_profiles(return_profile_names=True): diff --git a/x2go/forward.py b/x2go/forward.py index 39f52ef..1e10b17 100644 --- a/x2go/forward.py +++ b/x2go/forward.py @@ -41,7 +41,7 @@ class X2GoFwServer(StreamServer): """\ L{X2GoFwServer} implements a gevent's StreamServer based Paramiko/SSH port forwarding server. - + An L{X2GoFwServer} class object is used to tunnel graphical trafic through an external proxy command launched by a C{X2GoProxy*} backend. @@ -103,10 +103,10 @@ class X2GoFwServer(StreamServer): """\ Handle for SSH/Paramiko forwarding tunnel. - @param fw_socket: local end of the forwarding tunnel - @type fw_socket: C{obj} - @param address: unused/ignored - @type address: C{tuple} + :param fw_socket: local end of the forwarding tunnel + :type fw_socket: C{obj} + :param address: unused/ignored + :type address: C{tuple} """ self.fw_socket = fw_socket @@ -237,29 +237,29 @@ def start_forward_tunnel(local_host='127.0.0.1', local_port=22022, logger=None, ): """\ Setup up a Paramiko/SSH port forwarding tunnel (like openssh -L option). - + The tunnel is used to transport X2Go graphics data through a proxy application like nxproxy. - @param local_host: local starting point of the forwarding tunnel (Default value = '127.0.0.1') - @type local_host: C{int} - @param local_port: listen port of the local starting point (Default value = 22022) - @type local_port: C{int} - @param remote_host: from the endpoint of the tunnel, connect to host C{<remote_host>}... (Default value = '127.0.0.1') - @type remote_host: C{str} - @param remote_port: on port C{<remote_port>} (Default value = 22) - @type remote_port: C{int} - @param ssh_transport: the Paramiko/SSH transport (i.e. the X2Go session's Paramiko/SSH transport object) (Default value = None) - @type ssh_transport: C{obj} - @param session_instance: the L{X2GoSession} instance that initiates this tunnel (Default value = None) - @type session_instance: C{obj} - @param session_name: the session name of the X2Go session this port forwarding server belongs to (Default value = None) - @type session_name: C{str} - @param subsystem: a custom string with a component name that tries to evoke a new tunnel setup (Default value = None) - @type subsystem: C{str} - @param logger: an X2GoLogger object (Default value = None) - @type logger: C{obj} - @return: returns an L{X2GoFwServer} instance - @rtype: C{obj} + :param local_host: local starting point of the forwarding tunnel (Default value = '127.0.0.1') + :type local_host: C{int} + :param local_port: listen port of the local starting point (Default value = 22022) + :type local_port: C{int} + :param remote_host: from the endpoint of the tunnel, connect to host C{<remote_host>}... (Default value = '127.0.0.1') + :type remote_host: C{str} + :param remote_port: on port C{<remote_port>} (Default value = 22) + :type remote_port: C{int} + :param ssh_transport: the Paramiko/SSH transport (i.e. the X2Go session's Paramiko/SSH transport object) (Default value = None) + :type ssh_transport: C{obj} + :param session_instance: the L{X2GoSession} instance that initiates this tunnel (Default value = None) + :type session_instance: C{obj} + :param session_name: the session name of the X2Go session this port forwarding server belongs to (Default value = None) + :type session_name: C{str} + :param subsystem: a custom string with a component name that tries to evoke a new tunnel setup (Default value = None) + :type subsystem: C{str} + :param logger: an X2GoLogger object (Default value = None) + :type logger: C{obj} + :returns: returns an L{X2GoFwServer} instance + :rtype: C{obj} """ fw_server = X2GoFwServer(listener=(local_host, local_port), @@ -281,8 +281,8 @@ def stop_forward_tunnel(fw_server): """\ Tear down a given Paramiko/SSH port forwarding tunnel. - @param fw_server: an L{X2GoFwServer} instance as returned by the L{start_forward_tunnel()} function - @type fw_server: C{obj} + :param fw_server: an L{X2GoFwServer} instance as returned by the L{start_forward_tunnel()} function + :type fw_server: C{obj} """ if fw_server is not None: diff --git a/x2go/guardian.py b/x2go/guardian.py index 14928cd..c860e91 100644 --- a/x2go/guardian.py +++ b/x2go/guardian.py @@ -42,7 +42,7 @@ class X2GoSessionGuardian(threading.Thread): L{X2GoSessionGuardian} thread controls X2Go session threads and their sub-threads (like reverse forwarding tunnels, Paramiko transport threads, etc.). Its main function is to tidy up once a session gets interrupted (SIGTERM, SIGINT). - + There is one L{X2GoSessionGuardian} for each L{X2GoClient} instance (thus: for normal setups there should be _one_ L{X2GoClient} and _one_ L{X2GoSessionGuardian} in use). diff --git a/x2go/inifiles.py b/x2go/inifiles.py index 61179b0..010c2d0 100644 --- a/x2go/inifiles.py +++ b/x2go/inifiles.py @@ -52,7 +52,7 @@ class X2GoIniFile(object): Base class for processing the different ini files used by X2Go clients. Primarily used to standardize the content of the different X2Go client ini file (settings, printing, sessions, xconfig). - + If entries are omitted in an ini file, they are filled with default values (as hard coded in Python X2Go), so the resulting objects always contain the same fields. @@ -148,18 +148,18 @@ class X2GoIniFile(object): def _storeValue(self, section, key, value): """\ Stores a value for a given section and key. - + This methods affects a SafeConfigParser object held in RAM. No configuration file is affected by this method. To write the configuration to disk use the L{write()} method. - @param section: the ini file section - @type section: C{str} - @param key: the ini file key in the given section - @type key: C{str} - @param value: the value for the given section and key - @type value: C{str}, C{list}, C{booAl}, ... + :param section: the ini file section + :type section: C{str} + :param key: the ini file key in the given section + :type key: C{str} + :param value: the value for the given section and key + :type value: C{str}, C{list}, C{booAl}, ... """ if type(value) is bool: @@ -190,12 +190,12 @@ class X2GoIniFile(object): Change a value for a given section and key. This method does not have any effect on configuration files. - @param section: the ini file section - @type section: C{str} - @param key: the ini file key in the given section - @type key: C{str} - @param value: the value for the given section and key - @type value: C{str}, C{list}, C{bool}, ... + :param section: the ini file section + :type section: C{str} + :param key: the ini file key in the given section + :type key: C{str} + :param value: the value for the given section and key + :type value: C{str}, C{list}, C{bool}, ... """ if not self.iniConfig.has_section(section): @@ -207,14 +207,14 @@ class X2GoIniFile(object): def write(self): """\ Write the ini file modifications (SafeConfigParser object) from RAM to disk. - + For writing the first of the C{config_files} specified on instance construction that is writable will be used. - @return: C{True} if the user config file has been successfully written, C{False} otherwise. + :returns: C{True} if the user config file has been successfully written, C{False} otherwise. - @rtype: C{bool} + :rtype: C{bool} """ if self.user_config_file and self._write_user_config: @@ -234,12 +234,12 @@ class X2GoIniFile(object): Retrieve a value type for a given section and key. The returned value type is based on the default values dictionary. - @param section: the ini file section - @type section: C{str} - @param key: the ini file key in the given section - @type key: C{str} - @return: a Python variable type - @rtype: class + :param section: the ini file section + :type section: C{str} + :param key: the ini file key in the given section + :type key: C{str} + :returns: a Python variable type + :rtype: class """ return type(self.defaultValues[section][key]) @@ -248,14 +248,13 @@ class X2GoIniFile(object): """\ Retrieve a value for a given section and key. - @param section: the ini file section - @type section: C{str} - @param key: the ini file key in the given section - @type key: C{str} - @param key_type: Python data type of the given key (Default value = None) - @type: a valid Python type - @return: the value for the given section and key - @rtype: class + :param section: the ini file section + :type section: C{str} + :param key: the ini file key in the given section + :type key: C{str} + :param key_type: Python data type of the given key (Default value = None) + :returns: the value for the given section and key + :rtype: class """ if key_type is None: diff --git a/x2go/log.py b/x2go/log.py index aacc742..834750c 100644 --- a/x2go/log.py +++ b/x2go/log.py @@ -87,12 +87,12 @@ class X2GoLogger(object): """\ Log a message. - @param msg: log message text - @type msg: C{str} - @param loglevel: log level of this message (Default value = loglevel_NONE) - @type loglevel: C{int} - @param tag: additional tag for this log entry (Default value = None) - @type tag: C{str} + :param msg: log message text + :type msg: C{str} + :param loglevel: log level of this message (Default value = loglevel_NONE) + :type loglevel: C{int} + :param tag: additional tag for this log entry (Default value = None) + :type tag: C{str} """ if tag is None: @@ -113,9 +113,9 @@ class X2GoLogger(object): Get the current loglevel. - @return: current log level + :returns: current log level - @rtype: C{int} + :rtype: C{int} """ return self.loglevel @@ -124,8 +124,8 @@ class X2GoLogger(object): """\ Set log level by name. - @param loglevel_name: name of loglevel to be set (Default value = 'none') - @type loglevel_name: C{str} + :param loglevel_name: name of loglevel to be set (Default value = 'none') + :type loglevel_name: C{str} """ if type(loglevel_name) is types.IntegerType: diff --git a/x2go/mimebox.py b/x2go/mimebox.py index 2378dc5..0475e64 100644 --- a/x2go/mimebox.py +++ b/x2go/mimebox.py @@ -168,10 +168,11 @@ class X2GoMIMEboxQueue(threading.Thread): change of the MIME box action will be valid for the next incoming file in the MIME box directory. - @param mimebox_action: the MIME box action to execute for incoming files - @type mimebox_action: C{str} or C{obj} - @param kwargs: extra options for the specified MIME box action - @type kwargs: C{dict} + :param mimebox_action: the MIME box action to execute for incoming files + :type mimebox_action: C{str} or C{obj} + :param kwargs: extra options for the specified MIME box action + :type kwargs: C{dict} + :param **kwargs: """ if mimebox_action in list(defaults.X2GO_MIMEBOX_ACTIONS.keys()): @@ -222,16 +223,16 @@ def x2go_mimeboxjob_handler(mimebox_file=None, This function is called as a handler function for each incoming X2Go MIME box file represented by the class L{X2GoMIMEboxJob}. - @param mimebox_file: MIME box file name as placed in to the X2Go MIME box spool directory (Default value = None) - @type mimebox_file: C{str} - @param mimebox_action: an instance of either of the possible C{X2GoMIMEboxActionXXX} classes (Default value = None) - @type mimebox_action: C{X2GoMIMEboxActionXXX} nstance - @param mimebox_extensions: filter out files whose file extension is not in this list (Default value = [], means: no filtering) - @type mimebox_extensions: C{list} - @param parent_thread: the L{X2GoMIMEboxQueue} thread that actually created this handler's L{X2GoMIMEboxJob} instance (Default value = None) - @type parent_thread: C{obj} - @param logger: the L{X2GoMIMEboxQueue}'s logging instance (Default value = None) - @type logger: C{obj} + :param mimebox_file: MIME box file name as placed in to the X2Go MIME box spool directory (Default value = None) + :type mimebox_file: C{str} + :param mimebox_action: an instance of either of the possible C{X2GoMIMEboxActionXXX} classes (Default value = None) + :type mimebox_action: C{X2GoMIMEboxActionXXX} nstance + :param mimebox_extensions: filter out files whose file extension is not in this list (Default value = [], means: no filtering) + :type mimebox_extensions: C{list} + :param parent_thread: the L{X2GoMIMEboxQueue} thread that actually created this handler's L{X2GoMIMEboxJob} instance (Default value = None) + :type parent_thread: C{obj} + :param logger: the L{X2GoMIMEboxQueue}'s logging instance (Default value = None) + :type logger: C{obj} """ mimebox_action.profile_name = parent_thread.profile_name @@ -270,7 +271,7 @@ class X2GoMIMEboxJob(threading.Thread): """\ For each X2Go MIME box job we create a sub-thread that let's the MIME box job be processed in the background. - + As a handler for this class the function L{x2go_mimeboxjob_handler()} is used. diff --git a/x2go/mimeboxactions.py b/x2go/mimeboxactions.py index 3d93ae2..fb48441 100644 --- a/x2go/mimeboxactions.py +++ b/x2go/mimeboxactions.py @@ -87,8 +87,10 @@ class X2GoMIMEboxAction(object): """\ Return the X2Go MIME box action's name. - @return: MIME box action name - @rtype: C{str} + + :returns: MIME box action name + + :rtype: C{str} """ return self.__name__ @@ -98,8 +100,10 @@ class X2GoMIMEboxAction(object): """\ Return the X2Go MIME box action's description text. - @return: MIME box action's description - @rtype: C{str} + + :returns: MIME box action's description + + :rtype: C{str} """ return self.__description__ @@ -108,10 +112,10 @@ class X2GoMIMEboxAction(object): """\ Perform the defined MIME box action (doing nothing in L{X2GoMIMEboxAction} parent class). - @param mimebox_file: file name as placed in to the X2Go MIME box directory - @type mimebox_file: C{str} - @param mimebox_dir: location of the X2Go session's MIME box directory - @type mimebox_dir: C{str} + :param mimebox_file: file name as placed in to the X2Go MIME box directory + :type mimebox_file: C{str} + :param mimebox_dir: location of the X2Go session's MIME box directory + :type mimebox_dir: C{str} """ pass @@ -121,10 +125,10 @@ class X2GoMIMEboxAction(object): Wrapper method for the actual processing of MIME box actions. - @param mimebox_file: file name as placed in to the X2Go MIME box directory - @type mimebox_file: C{str} - @param mimebox_dir: location of the X2Go session's MIME box directory - @type mimebox_dir: C{str} + :param mimebox_file: file name as placed in to the X2Go MIME box directory + :type mimebox_file: C{str} + :param mimebox_dir: location of the X2Go session's MIME box directory + :type mimebox_dir: C{str} """ mimebox_file = os.path.normpath(mimebox_file) @@ -161,10 +165,10 @@ class X2GoMIMEboxActionOPEN(X2GoMIMEboxAction): """\ Open an incoming MIME box file in the system's default application. - @param mimebox_file: file name as placed in to the MIME box directory - @type mimebox_file: C{str} - @param mimebox_dir: location of the X2Go session's MIME box directory - @type mimebox_dir: C{str} + :param mimebox_file: file name as placed in to the MIME box directory + :type mimebox_file: C{str} + :param mimebox_dir: location of the X2Go session's MIME box directory + :type mimebox_dir: C{str} """ mimebox_file = os.path.normpath(mimebox_file) @@ -220,10 +224,10 @@ class X2GoMIMEboxActionOPENWITH(X2GoMIMEboxAction): """\ Open an incoming MIME box file in the system's default application. - @param mimebox_file: file name as placed in to the MIME box directory - @type mimebox_file: C{str} - @param mimebox_dir: location of the X2Go session's MIME box directory - @type mimebox_dir: C{str} + :param mimebox_file: file name as placed in to the MIME box directory + :type mimebox_file: C{str} + :param mimebox_dir: location of the X2Go session's MIME box directory + :type mimebox_dir: C{str} """ mimebox_file = os.path.normpath(mimebox_file) @@ -285,11 +289,11 @@ class X2GoMIMEboxActionSAVEAS(X2GoMIMEboxAction): Call an L{X2GoClient} hook method (C{HOOK_open_mimebox_saveas_dialog}) that can handle the MIME box's SAVEAS action. - @param mimebox_file: file name as placed in to the MIME box directory - @type mimebox_file: C{str} - @param mimebox_dir: location of the X2Go session's MIME box directory - @type mimebox_dir: C{str} - @param mimebox_file: PDF file name as placed in to the X2Go spool directory + :param mimebox_file: file name as placed in to the MIME box directory + :type mimebox_file: C{str} + :param mimebox_dir: location of the X2Go session's MIME box directory + :type mimebox_dir: C{str} + :param mimebox_file: PDF file name as placed in to the X2Go spool directory """ mimebox_file = os.path.normpath(mimebox_file) diff --git a/x2go/printactions.py b/x2go/printactions.py index 5426cdf..459dab6 100644 --- a/x2go/printactions.py +++ b/x2go/printactions.py @@ -96,8 +96,10 @@ class X2GoPrintAction(object): """\ Return the X2Go print action's name. - @return: print action name - @rtype: C{str} + + :returns: print action name + + :rtype: C{str} """ return self.__name__ @@ -107,8 +109,10 @@ class X2GoPrintAction(object): """\ Return the X2Go print action's description text. - @return: print action's description - @rtype: C{str} + + :returns: print action's description + + :rtype: C{str} """ return self.__description__ @@ -117,12 +121,12 @@ class X2GoPrintAction(object): """\ Perform the defined print action (doing nothing in L{X2GoPrintAction} parent class). - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param spool_dir: location of the X2Go client's spool directory - @type spool_dir: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param spool_dir: location of the X2Go client's spool directory + :type spool_dir: C{str} """ pass @@ -132,12 +136,12 @@ class X2GoPrintAction(object): Wrap around the actual print action (C{self._do_print}) with gevent.spawn(). - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param spool_dir: location of the X2Go client's spool directory - @type spool_dir: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param spool_dir: location of the X2Go client's spool directory + :type spool_dir: C{str} """ pdf_file = os.path.normpath(pdf_file) @@ -149,14 +153,14 @@ class X2GoPrintAction(object): """\ Extract a human readable filename for the X2Go print job file. - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param target_path: target path for human readable file - @type target_path: C{str} - @return: full readable file name path - @rtype: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param target_path: target path for human readable file + :type target_path: C{str} + :returns: full readable file name path + :rtype: C{str} """ _hr_path = os.path.normpath(os.path.expanduser(os.path.join(os.path.normpath(target_path), '%s.pdf' % utils.slugify(job_title)))) @@ -203,13 +207,13 @@ class X2GoPrintActionPDFVIEW(X2GoPrintAction): """\ Open an incoming X2Go print job (PDF file) in an external PDF viewer application. - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param spool_dir: location of the X2Go client's spool directory - @type spool_dir: C{str} - @raise OSError: pass through all C{OSError}s except no. 2 + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param spool_dir: location of the X2Go client's spool directory + :type spool_dir: C{str} + :raises OSError: pass through all C{OSError}s except no. 2 """ pdf_file = os.path.normpath(pdf_file) @@ -290,12 +294,12 @@ class X2GoPrintActionPDFSAVE(X2GoPrintAction): """\ Save an incoming X2Go print job (PDF file) to a local folder. - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param spool_dir: location of the X2Go client's spool directory - @type spool_dir: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param spool_dir: location of the X2Go client's spool directory + :type spool_dir: C{str} """ pdf_file = os.path.normpath(pdf_file) @@ -335,12 +339,12 @@ class X2GoPrintActionPRINT(X2GoPrintAction): """\ Really print an incoming X2Go print job (PDF file) to a local printer device. - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param spool_dir: location of the X2Go client's spool directory - @type spool_dir: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param spool_dir: location of the X2Go client's spool directory + :type spool_dir: C{str} """ pdf_file = os.path.normpath(pdf_file) @@ -435,7 +439,7 @@ class X2GoPrintActionPRINT(X2GoPrintAction): class X2GoPrintActionPRINTCMD(X2GoPrintAction): """\ Print action that calls an external command for further processing of incoming print jobs. - + The print job's PDF filename will be prepended as last argument to the print command used in L{X2GoPrintActionPRINTCMD} instances. @@ -468,12 +472,12 @@ class X2GoPrintActionPRINTCMD(X2GoPrintAction): Execute an external command that has been defined on construction of this L{X2GoPrintActionPRINTCMD} instance. - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param spool_dir: location of the X2Go client's spool directory - @type spool_dir: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param spool_dir: location of the X2Go client's spool directory + :type spool_dir: C{str} """ pdf_file = os.path.normpath(pdf_file) @@ -530,12 +534,12 @@ class X2GoPrintActionDIALOG(X2GoPrintAction): Execute an external command that has been defined on construction of this L{X2GoPrintActionPRINTCMD} instance. - @param pdf_file: PDF file name as placed in to the X2Go spool directory - @type pdf_file: C{str} - @param job_title: human readable print job title - @type job_title: C{str} - @param spool_dir: location of the X2Go client's spool directory - @type spool_dir: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory + :type pdf_file: C{str} + :param job_title: human readable print job title + :type job_title: C{str} + :param spool_dir: location of the X2Go client's spool directory + :type spool_dir: C{str} """ pdf_file = os.path.normpath(pdf_file) diff --git a/x2go/printqueue.py b/x2go/printqueue.py index be24e13..b204ab6 100644 --- a/x2go/printqueue.py +++ b/x2go/printqueue.py @@ -172,15 +172,16 @@ class X2GoPrintQueue(threading.Thread): """\ Modify the print action of this L{X2GoPrintQueue} thread during runtime. The change of print action will be valid for the next incoming print job. - + As kwargs you can pass arguments for the print action class to be set. Refer to the class descriptions of L{X2GoPrintActionDIALOG}, L{X2GoPrintActionPDFVIEW}, L{X2GoPrintActionPRINT}, etc. - @param print_action: new print action to be valid for incoming print jobs - @type print_action: C{str} or C{class} - @param kwargs: extra options for the specified print action - @type kwargs: C{dict} + :param print_action: new print action to be valid for incoming print jobs + :type print_action: C{str} or C{class} + :param kwargs: extra options for the specified print action + :type kwargs: C{dict} + :param **kwargs: """ if print_action in list(defaults.X2GO_PRINT_ACTIONS.keys()): @@ -228,23 +229,23 @@ def x2go_printjob_handler(job_file=None, pdf_file=None, job_title=None, print_ac """\ This function is called as a handler function for each incoming X2Go print job represented by the class L{X2GoPrintJob}. - + The handler function will (re-)read the »printing« configuration file (if no explicit C{print_action} is passed to this function...). It then will execute the C{<print_action>.do_print()} command. - @param job_file: file name of this print job's Job File (Default value = None) - @type job_file: C{str} - @param pdf_file: PDF file name as placed in to the X2Go spool directory (Default value = None) - @type pdf_file: C{str} - @param job_title: human readable print job title (Default value = None) - @type job_title: C{str} - @param print_action: an instance of either of the possible C{X2GoPrintActionXXX} classes (Default value = None) - @type print_action: C{X2GoPrintActionXXX} nstance - @param parent_thread: the L{X2GoPrintQueue} thread that actually created this handler's L{X2GoPrintJob} instance (Default value = None) - @type parent_thread: C{obj} - @param logger: the L{X2GoPrintQueue}'s logging instance (Default value = None) - @type logger: C{obj} + :param job_file: file name of this print job's Job File (Default value = None) + :type job_file: C{str} + :param pdf_file: PDF file name as placed in to the X2Go spool directory (Default value = None) + :type pdf_file: C{str} + :param job_title: human readable print job title (Default value = None) + :type job_title: C{str} + :param print_action: an instance of either of the possible C{X2GoPrintActionXXX} classes (Default value = None) + :type print_action: C{X2GoPrintActionXXX} nstance + :param parent_thread: the L{X2GoPrintQueue} thread that actually created this handler's L{X2GoPrintJob} instance (Default value = None) + :type parent_thread: C{obj} + :param logger: the L{X2GoPrintQueue}'s logging instance (Default value = None) + :type logger: C{obj} """ if print_action is None: @@ -288,7 +289,7 @@ class X2GoPrintJob(threading.Thread): """\ For each X2Go print job we create a sub-thread that let's the print job be processed in the background. - + As a handler for this class the function L{x2go_printjob_handler()} is used. diff --git a/x2go/pulseaudio.py b/x2go/pulseaudio.py index e7d2d5a..5547258 100644 --- a/x2go/pulseaudio.py +++ b/x2go/pulseaudio.py @@ -49,8 +49,7 @@ from .defaults import LOCAL_HOME as _LOCAL_HOME # Python X2Go modules from . import log -import exceptions -class OSNotSupportedException(exceptions.Exception): pass +class OSNotSupportedException(BaseException): pass """ Exception denoting that this operating system is not supported. """ class X2GoPulseAudio(threading.Thread): diff --git a/x2go/registry.py b/x2go/registry.py index 3d5d7ec..57e2a1d 100644 --- a/x2go/registry.py +++ b/x2go/registry.py @@ -90,9 +90,9 @@ class X2GoSessionRegistry(object): A list of session registry keys. - @return: session registry key list + :returns: session registry key list - @rtype: C{list} + :rtype: C{list} """ return list(self.registry.keys()) @@ -147,8 +147,8 @@ class X2GoSessionRegistry(object): """\ Forget the complete record for session UUID C{session_uuid}. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} """ try: @@ -161,10 +161,10 @@ class X2GoSessionRegistry(object): """\ Retrieve the profile ID of a given session UUID hash. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: profile ID - @rtype: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: profile ID + :rtype: C{str} """ return self(session_uuid).get_profile_id() @@ -173,10 +173,10 @@ class X2GoSessionRegistry(object): """\ Retrieve the profile name of a given session UUID hash. - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @return: profile name - @rtype: C{str} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :returns: profile name + :rtype: C{str} """ return self(session_uuid).get_profile_name() @@ -185,12 +185,12 @@ class X2GoSessionRegistry(object): """\ Compose a session summary (as Python dictionary). - @param session_uuid: the X2Go session's UUID registry hash - @type session_uuid: C{str} - @param status_only: short summary, include session status only (Default value = False) - @type status_only: C{bool} - @return: session summary dictionary - @rtype: C{dict} + :param session_uuid: the X2Go session's UUID registry hash + :type session_uuid: C{str} + :param status_only: short summary, include session status only (Default value = False) + :type status_only: C{bool} + :returns: session summary dictionary + :rtype: C{dict} """ _session_summary = {} @@ -235,24 +235,24 @@ class X2GoSessionRegistry(object): Update the session status for L{X2GoSession} that is represented by a given session UUID hash, profile name or profile ID. - @param session_uuid: the X2Go session's UUID registry hash (Default value = None) - @type session_uuid: C{str} - @param profile_name: alternatively, a profile name can be specified (the stati of all registered sessions for this session + :param session_uuid: the X2Go session's UUID registry hash (Default value = None) + :type session_uuid: C{str} + :param profile_name: alternatively, a profile name can be specified (the stati of all registered sessions for this session profile will be updated) (Default value = None) - @type profile_name: C{str} - @param profile_id: alternatively, a profile ID can be given (the stati of all registered sessions for this session + :type profile_name: C{str} + :param profile_id: alternatively, a profile ID can be given (the stati of all registered sessions for this session profile will be updated) (Default value = None) - @type profile_id: C{str} - @param session_list: an optional C{X2GoServerSessionList*} instance (as returned by the L{X2GoClient.list_sessions()} command can + :type profile_id: C{str} + :param session_list: an optional C{X2GoServerSessionList*} instance (as returned by the L{X2GoClient.list_sessions()} command can be passed to this method. (Default value = None) - @type session_list: C{X2GoServerSessionList*} instance - @param force_update: make sure the session status gets really updated (Default value = False) - @type force_update: C{bool} - @param newly_connected: set this to C{True}, if the control session has just been connected (Default value = False) - @param newly_connected: C{bool} - @return: C{True} if this method has been successful - @rtype: C{bool} - @raise X2GoSessionRegistryException: if the combination of C{session_uuid}, C{profile_name} and C{profile_id} does not match the requirement: + :type session_list: C{X2GoServerSessionList*} instance + :param force_update: make sure the session status gets really updated (Default value = False) + :type force_update: C{bool} + :param newly_connected: set this to C{True}, if the control session has just been connected (Default value = False) + :param newly_connected: C{bool} (Default value = False) + :returns: C{True} if this method has been successful + :rtype: C{bool} + :raises X2GoSessionRegistryException: if the combination of C{session_uuid}, C{profile_name} and C{profile_id} does not match the requirement: only one of them """ @@ -388,17 +388,17 @@ class X2GoSessionRegistry(object): """\ Register server-side available X2Go sessions with this L{X2GoSessionRegistry} instance for a given profile name. - @param profile_name: session profile name to register available X2Go sessions for - @type profile_name: C{str} - @param session_list: an optional C{X2GoServerSessionList*} instance (as returned by the L{X2GoClient.list_sessions()} command can + :param profile_name: session profile name to register available X2Go sessions for + :type profile_name: C{str} + :param session_list: an optional C{X2GoServerSessionList*} instance (as returned by the L{X2GoClient.list_sessions()} command can be passed to this method. (Default value = None) - @type session_list: C{X2GoServerSessionList*} instance - @param newly_connected: give a hint that the session profile got newly connected (Default value = False) - @type newly_connected: C{bool} - @param re_register: re-register available sessions, needs to be done after changes to the session profile (Default value = False) - @type re_register: C{bool} - @param skip_pubapp_sessions: Do not register published applications sessions (Default value = False) - @type skip_pubapp_sessions: C{bool} + :type session_list: C{X2GoServerSessionList*} instance + :param newly_connected: give a hint that the session profile got newly connected (Default value = False) + :type newly_connected: C{bool} + :param re_register: re-register available sessions, needs to be done after changes to the session profile (Default value = False) + :type re_register: C{bool} + :param skip_pubapp_sessions: Do not register published applications sessions (Default value = False) + :type skip_pubapp_sessions: C{bool} """ if self._last_available_session_registration is not None: @@ -482,44 +482,45 @@ class X2GoSessionRegistry(object): """\ Register a new L{X2GoSession} instance with this L{X2GoSessionRegistry}. - @param server: hostname of X2Go server - @type server: C{str} - @param profile_id: profile ID - @type profile_id: C{str} - @param profile_name: profile name - @type profile_name: C{str} - @param session_name: session name (if available) (Default value = None) - @type session_name: C{str} - @param control_backend: X2Go control session backend to use (Default value = _BACKENDS['X2GoControlSession']['default']) - @type control_backend: C{str} - @param terminal_backend: X2Go terminal session backend to use (Default value = _BACKENDS['X2GoTerminalSession']['default']) - @type terminal_backend: C{str} - @param info_backend: X2Go session info backend to use (Default value = _BACKENDS['X2GoServerSessionInfo']['default']) - @type info_backend: C{str} - @param list_backend: X2Go session list backend to use (Default value = _BACKENDS['X2GoServerSessionList']['default']) - @type list_backend: C{str} - @param proxy_backend: X2Go proxy backend to use (Default value = _BACKENDS['X2GoProxy']['default']) - @type proxy_backend: C{str} - @param settings_backend: X2Go client settings backend to use (Default value = _BACKENDS['X2GoClientSettings']['default']) - @type settings_backend: C{str} - @param printing_backend: X2Go client printing backend to use (Default value = _BACKENDS['X2GoClientPrinting']['default']) - @type printing_backend: C{str} - @param client_rootdir: client base dir (default: ~/.x2goclient) - @type client_rootdir: C{str} - @param sessions_rootdir: sessions base dir (default: ~/.x2go) - @type sessions_rootdir: C{str} - @param ssh_rootdir: ssh base dir (default: ~/.ssh) - @type ssh_rootdir: C{str} - @param keep_controlsession_alive: On last L{X2GoSession.disconnect()} keep the associated C{X2GoControlSession} instance alive? + :param server: hostname of X2Go server + :type server: C{str} + :param profile_id: profile ID + :type profile_id: C{str} + :param profile_name: profile name + :type profile_name: C{str} + :param session_name: session name (if available) (Default value = None) + :type session_name: C{str} + :param control_backend: X2Go control session backend to use (Default value = _BACKENDS['X2GoControlSession']['default']) + :type control_backend: C{str} + :param terminal_backend: X2Go terminal session backend to use (Default value = _BACKENDS['X2GoTerminalSession']['default']) + :type terminal_backend: C{str} + :param info_backend: X2Go session info backend to use (Default value = _BACKENDS['X2GoServerSessionInfo']['default']) + :type info_backend: C{str} + :param list_backend: X2Go session list backend to use (Default value = _BACKENDS['X2GoServerSessionList']['default']) + :type list_backend: C{str} + :param proxy_backend: X2Go proxy backend to use (Default value = _BACKENDS['X2GoProxy']['default']) + :type proxy_backend: C{str} + :param settings_backend: X2Go client settings backend to use (Default value = _BACKENDS['X2GoClientSettings']['default']) + :type settings_backend: C{str} + :param printing_backend: X2Go client printing backend to use (Default value = _BACKENDS['X2GoClientPrinting']['default']) + :type printing_backend: C{str} + :param client_rootdir: client base dir (default: ~/.x2goclient) + :type client_rootdir: C{str} + :param sessions_rootdir: sessions base dir (default: ~/.x2go) + :type sessions_rootdir: C{str} + :param ssh_rootdir: ssh base dir (default: ~/.ssh) + :type ssh_rootdir: C{str} + :param keep_controlsession_alive: On last L{X2GoSession.disconnect()} keep the associated C{X2GoControlSession} instance alive? @ŧype keep_controlsession_alive: C{bool} - @param add_to_known_hosts: Auto-accept server host validity? - @type add_to_known_hosts: C{bool} - @param known_hosts: the underlying Paramiko/SSH systems C{known_hosts} file - @type known_hosts: C{str} - @param kwargs: all other options will be passed on to the constructor of the to-be-instantiated L{X2GoSession} instance - @type kwargs: C{dict} - @return: the session UUID of the newly registered (or re-registered) session - @rtype: C{str} + :param add_to_known_hosts: Auto-accept server host validity? + :type add_to_known_hosts: C{bool} + :param known_hosts: the underlying Paramiko/SSH systems C{known_hosts} file + :type known_hosts: C{str} + :param kwargs: all other options will be passed on to the constructor of the to-be-instantiated L{X2GoSession} instance + :type kwargs: C{dict} + :param _X2GO_CLIENT_ROOTDIR: + :returns: the session UUID of the newly registered (or re-registered) session + :rtype: C{str} """ if profile_id not in list(self._profile_locks.keys()): @@ -613,12 +614,12 @@ class X2GoSessionRegistry(object): """\ Detect if we know about an L{X2GoSession} of name C{<session_name>}. - @param session_name: name of session to be searched for - @type session_name: C{str} - @param match_profile_name: a session's profile_name must match this profile name (Default value = None) - @type match_profile_name: C{str} - @return: C{True} if a session of C{<session_name>} has been found - @rtype: C{bool} + :param session_name: name of session to be searched for + :type session_name: C{str} + :param match_profile_name: a session's profile_name must match this profile name (Default value = None) + :type match_profile_name: C{str} + :returns: C{True} if a session of C{<session_name>} has been found + :rtype: C{bool} """ return bool(self.get_session_of_session_name(session_name, match_profile_name=match_profile_name)) @@ -627,15 +628,15 @@ class X2GoSessionRegistry(object): """\ Retrieve the L{X2GoSession} instance with session name C{<session_name>}. - @param session_name: name of session to be retrieved - @type session_name: C{str} - @param return_object: if C{False} the session UUID hash will be returned, if C{True} the L{X2GoSession} instance will be returned (Default value = False) - @type return_object: C{bool} - @param match_profile_name: returned sessions must match this profile name (Default value = None) - @type match_profile_name: C{str} - @return: L{X2GoSession} object or its representing session UUID hash - @rtype: L{X2GoSession} instance or C{str} - @raise X2GoSessionRegistryException: if there is more than one L{X2GoSession} registered for C{<session_name>} within + :param session_name: name of session to be retrieved + :type session_name: C{str} + :param return_object: if C{False} the session UUID hash will be returned, if C{True} the L{X2GoSession} instance will be returned (Default value = False) + :type return_object: C{bool} + :param match_profile_name: returned sessions must match this profile name (Default value = None) + :type match_profile_name: C{str} + :returns: L{X2GoSession} object or its representing session UUID hash + :rtype: L{X2GoSession} instance or C{str} + :raises X2GoSessionRegistryException: if there is more than one L{X2GoSession} registered for C{<session_name>} within the same L{X2GoClient} instance. This should never happen! """ @@ -690,16 +691,16 @@ class X2GoSessionRegistry(object): Retrieve a list of sessions that the underlying L{X2GoClient} instances is currently connected to. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self._sessionsWithState('connected', return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -709,16 +710,16 @@ class X2GoSessionRegistry(object): Retrieve a list of sessions that are currently associated by an C{X2GoTerminalSession*} to the underlying L{X2GoClient} instance. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self._sessionsWithState('associated', return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -728,16 +729,16 @@ class X2GoSessionRegistry(object): Retrieve a list of sessions that are currently still in virgin state (not yet connected, associated etc.). If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self._sessionsWithState('virgin', return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -747,16 +748,16 @@ class X2GoSessionRegistry(object): Retrieve a list of sessions that are currently in running state. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self._sessionsWithState('running', return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -766,16 +767,16 @@ class X2GoSessionRegistry(object): Retrieve a list of sessions that are currently in suspended state. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self._sessionsWithState('suspended', return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -785,16 +786,16 @@ class X2GoSessionRegistry(object): Retrieve a list of sessions that have terminated recently. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self._sessionsWithState('terminated', return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -822,16 +823,16 @@ class X2GoSessionRegistry(object): Retrieve a list of all registered sessions. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return self._sessionsWithState('registered', return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) @@ -841,16 +842,16 @@ class X2GoSessionRegistry(object): Retrieve a list of sessions that are currently _NOT_ in running state. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = False) - @type return_profile_ids: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = False) + :type return_profile_ids: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ return [ s for s in self.registered_sessions(return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) if s not in self.running_sessions(return_objects=return_objects, return_profile_names=return_profile_names, return_profile_ids=return_profile_ids, return_session_names=return_session_names) ] @@ -860,14 +861,14 @@ class X2GoSessionRegistry(object): For a given session profile name retrieve a list of sessions that are currently connected to the profile's X2Go server. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param profile_name: session profile name - @type profile_name: C{str} - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects or session names) - @rtype: C{list} + :param profile_name: session profile name + :type profile_name: C{str} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects or session names) + :rtype: C{list} """ if return_objects: @@ -882,14 +883,14 @@ class X2GoSessionRegistry(object): For a given session profile name retrieve a list of sessions that are currently associated by an C{X2GoTerminalSession*} to this L{X2GoClient} instance. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param profile_name: session profile name - @type profile_name: C{str} - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects or session names) - @rtype: C{list} + :param profile_name: session profile name + :type profile_name: C{str} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects or session names) + :rtype: C{list} """ if return_objects: @@ -904,14 +905,14 @@ class X2GoSessionRegistry(object): For a given session profile name retrieve a list of sessions that can be providers for published application list. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param profile_name: session profile name - @type profile_name: C{str} - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects or session names) - @rtype: C{list} + :param profile_name: session profile name + :type profile_name: C{str} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects or session names) + :rtype: C{list} """ if return_objects: @@ -926,14 +927,14 @@ class X2GoSessionRegistry(object): For a given session profile name retrieve a list of sessions that are currently registered with this L{X2GoClient} instance. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param profile_name: session profile name - @type profile_name: C{str} - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects or session names) - @rtype: C{list} + :param profile_name: session profile name + :type profile_name: C{str} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects or session names) + :rtype: C{list} """ if return_objects: @@ -949,14 +950,14 @@ class X2GoSessionRegistry(object): yet been started (i.e. sessions that are in virgin state). If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param profile_name: session profile name - @type profile_name: C{str} - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects or session names) - @rtype: C{list} + :param profile_name: session profile name + :type profile_name: C{str} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects or session names) + :rtype: C{list} """ if return_objects: @@ -971,14 +972,14 @@ class X2GoSessionRegistry(object): For a given session profile name retrieve a list of sessions that are currently running. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param profile_name: session profile name - @type profile_name: C{str} - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects or session names) - @rtype: C{list} + :param profile_name: session profile name + :type profile_name: C{str} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects or session names) + :rtype: C{list} """ if return_objects: @@ -993,14 +994,14 @@ class X2GoSessionRegistry(object): For a given session profile name retrieve a list of sessions that are currently in suspended state. If none of the C{return_*} options is specified a list of session UUID hashes will be returned. - @param profile_name: session profile name - @type profile_name: C{str} - @param return_objects: return as list of L{X2GoSession} instances (Default value = True) - @type return_objects: C{bool} - @param return_session_names: return as list of X2Go session names (Default value = False) - @type return_session_names: C{bool} - @return: a session list (as UUID hashes, objects or session names) - @rtype: C{list} + :param profile_name: session profile name + :type profile_name: C{str} + :param return_objects: return as list of L{X2GoSession} instances (Default value = True) + :type return_objects: C{bool} + :param return_session_names: return as list of X2Go session names (Default value = False) + :type return_session_names: C{bool} + :returns: a session list (as UUID hashes, objects or session names) + :rtype: C{list} """ if return_objects: @@ -1014,10 +1015,10 @@ class X2GoSessionRegistry(object): """\ For a given session profile name retrieve a the corresponding C{X2GoControlSession*} instance. - @param profile_name: session profile name - @type profile_name: C{str} - @return: contol session instance - @rtype: C{X2GoControlSession*} instance + :param profile_name: session profile name + :type profile_name: C{str} + :returns: contol session instance + :rtype: C{X2GoControlSession*} instance """ _sessions = self.registered_sessions_of_profile_name(profile_name, return_objects=True) @@ -1039,14 +1040,14 @@ class X2GoSessionRegistry(object): """\ Retrieve a list of all currently connected session profiles. - @param use_paramiko: send query directly to the Paramiko/SSH layer (Default value = False) - @type use_paramiko: C{bool} - @param return_profile_names: return as list of profile names (Default value = False) - @type return_profile_names: C{bool} - @param return_profile_ids: return as list of profile IDs (Default value = True) - @type return_profile_ids: C{bool} - @return: list of connected session profiles - @rtype: C{list} + :param use_paramiko: send query directly to the Paramiko/SSH layer (Default value = False) + :type use_paramiko: C{bool} + :param return_profile_names: return as list of profile names (Default value = False) + :type return_profile_names: C{bool} + :param return_profile_ids: return as list of profile IDs (Default value = True) + :type return_profile_ids: C{bool} + :returns: list of connected session profiles + :rtype: C{list} """ if use_paramiko: @@ -1058,14 +1059,14 @@ class X2GoSessionRegistry(object): """\ Retrieve the master session of a specific profile. - @param profile_name: the profile name that we query the master session of - @type profile_name: C{str} - @param return_object: return L{X2GoSession} instance (Default value = True) - @type return_object: C{bool} - @param return_session_name: return X2Go session name (Default value = False) - @type return_session_name: C{bool} - @return: a session list (as UUID hashes, objects, profile names/IDs or session names) - @rtype: C{list} + :param profile_name: the profile name that we query the master session of + :type profile_name: C{str} + :param return_object: return L{X2GoSession} instance (Default value = True) + :type return_object: C{bool} + :param return_session_name: return X2Go session name (Default value = False) + :type return_session_name: C{bool} + :returns: a session list (as UUID hashes, objects, profile names/IDs or session names) + :rtype: C{list} """ if profile_name not in self.connected_profiles(return_profile_names=True): diff --git a/x2go/rforward.py b/x2go/rforward.py index 7631236..50692a0 100644 --- a/x2go/rforward.py +++ b/x2go/rforward.py @@ -43,25 +43,25 @@ from . import log def x2go_transport_tcp_handler(chan, origin, server): """\ An X2Go customized TCP handler for the Paramiko/SSH C{Transport()} class. - + Incoming channels will be put into Paramiko's default accept queue. This corresponds to the default behaviour of Paramiko's C{Transport} class. - + However, additionally this handler function checks the server port of the incoming channel and detects if there are Paramiko/SSH reverse forwarding tunnels waiting for the incoming channels. The Paramiko/SSH reverse forwarding tunnels are initiated by an L{X2GoSession} instance (currently supported: reverse tunneling auf audio data, reverse tunneling of SSH requests). - + If the server port of an incoming Paramiko/SSH channel matches the configured port of an L{X2GoRevFwTunnel} instance, this instance gets notified of the incoming channel and a new L{X2GoRevFwChannelThread} is started. This L{X2GoRevFwChannelThread} then takes care of the new channel's incoming data stream. - @param chan: a Paramiko channel object - @type chan: C{paramiko.Channel} object - @param origin: host/port tuple where a connection originates from - @type origin: C{tuple} - @param server: host/port tuple where to connect to - @type server: C{tuple} + :param chan: a Paramiko channel object + :type chan: C{paramiko.Channel} object + :param origin: host/port tuple where a connection originates from + :type origin: C{tuple} + :param server: host/port tuple where to connect to + :type server: C{tuple} """ (origin_addr, origin_port) = origin @@ -149,10 +149,10 @@ class X2GoRevFwTunnel(threading.Thread): Cancel a port forwarding request. This cancellation request is sent to the server and on the server the port forwarding should be unregistered. - @param address: remote server address - @type address: C{str} - @param port: remote port - @type port: C{int} + :param address: remote server address + :type address: C{str} + :param port: remote port + :type port: C{int} """ timeout = Timeout(10) @@ -192,11 +192,11 @@ class X2GoRevFwTunnel(threading.Thread): def notify(self): """\ Notify an L{X2GoRevFwTunnel} instance of an incoming Paramiko/SSH channel. - + If an incoming reverse tunnel channel appropriate for this instance has been detected, this method gets called from the L{X2GoSession}'s transport TCP handler. - + The sent notification will trigger a C{thread.Condition()} waiting for notification in L{X2GoRevFwTunnel.run()}. @@ -240,16 +240,16 @@ class X2GoRevFwTunnel(threading.Thread): L{start()} method. Use L{X2GoRevFwTunnel}.stop_thread() to stop the reverse forwarding tunnel again. You can also temporarily lock the tunnel down with L{X2GoRevFwTunnel.pause()} and L{X2GoRevFwTunnel.resume()}). - + L{X2GoRevFwTunnel.run()} waits for notifications of an appropriate incoming Paramiko/SSH channel (issued by L{X2GoRevFwTunnel.notify()}). Appropriate in this context means, that its start point on the X2Go server matches the class's property C{server_port}. - + Once a new incoming channel gets announced by the L{notify()} method, a new L{X2GoRevFwChannelThread} instance will be initialized. As a data stream handler, the function L{x2go_rev_forward_channel_handler()} will be used. - + The channel will last till the connection gets dropped on the X2Go server side or until the tunnel gets paused by an L{X2GoRevFwTunnel.pause()} call or stopped via the L{X2GoRevFwTunnel.stop_thread()} method. @@ -292,9 +292,9 @@ def x2go_rev_forward_channel_handler(chan=None, addr='', port=0, parent_thread=N """\ Handle the data stream of a requested channel that got set up by a L{X2GoRevFwTunnel} (Paramiko/SSH reverse forwarding tunnel). - + The channel (and the corresponding connections) close either ... - + - ... if the connecting application closes the connection and thus, drops the channel, or - ... if the L{X2GoRevFwTunnel} parent thread gets paused. The call @@ -302,17 +302,17 @@ def x2go_rev_forward_channel_handler(chan=None, addr='', port=0, parent_thread=N tunneled SSH connections associated to this L{X2GoRevFwTunnel} instance from within a Python X2Go application. - @param chan: channel (Default value = None) - @type chan: C{class} - @param addr: bind address (Default value = '') - @type addr: C{str} - @param port: bind port (Default value = 0) - @type port: C{int} - @param parent_thread: the calling L{X2GoRevFwTunnel} instance (Default value = None) - @type parent_thread: L{X2GoRevFwTunnel} instance - @param logger: you can pass an L{X2GoLogger} object to the + :param chan: channel (Default value = None) + :type chan: C{class} + :param addr: bind address (Default value = '') + :type addr: C{str} + :param port: bind port (Default value = 0) + :type port: C{int} + :param parent_thread: the calling L{X2GoRevFwTunnel} instance (Default value = None) + :type parent_thread: L{X2GoRevFwTunnel} instance + :param logger: you can pass an L{X2GoLogger} object to the L{X2GoRevFwTunnel} constructor (Default value = None) - @type logger: L{X2GoLogger} instance + :type logger: L{X2GoLogger} instance """ fw_socket = socket.socket() diff --git a/x2go/session.py b/x2go/session.py index 9bfb96b..7acd1d4 100644 --- a/x2go/session.py +++ b/x2go/session.py @@ -127,7 +127,7 @@ class X2GoSession(object): Public API class for launching X2Go sessions. Recommended is to manage X2Go sessions from within an L{X2GoClient} instance. However, Python X2Go is designed in a way that it also allows the management of singel L{X2GoSession} instance. - + Thus, you can use the L{X2GoSession} class to manually set up X2Go sessions without L{X2GoClient} context (session registry, session list cache, auto-registration of new sessions etc.). @@ -430,8 +430,10 @@ class X2GoSession(object): """\ Return parent L{X2GoClient} instance if avaiable. - @return: L{X2GoClient} instance this session is associated with - @rtype: C{obj} + + :returns: L{X2GoClient} instance this session is associated with + + :rtype: C{obj} """ return self.client_instance @@ -507,8 +509,8 @@ class X2GoSession(object): """\ HOOK method: called if it is tried to connect to a shared desktop that's not available (anymore). - @param desktop: the could-not-be-shared desktop's name or other identifier (Default value = 'UNKNOWN') - @type desktop: C{str} + :param desktop: the could-not-be-shared desktop's name or other identifier (Default value = 'UNKNOWN') + :type desktop: C{str} """ if self.client_instance: @@ -520,8 +522,8 @@ class X2GoSession(object): """\ HOOK method: called if a reverse port forwarding request has been denied. - @param server_port: remote server port (starting point of reverse forwarding tunnel) (Default value = 0) - @type server_port: C{str} + :param server_port: remote server port (starting point of reverse forwarding tunnel) (Default value = 0) + :type server_port: C{str} """ if self.client_instance: @@ -533,12 +535,12 @@ class X2GoSession(object): """\ HOOK method: called if a port forwarding tunnel setup failed. - @param chain_host: hostname of chain host (forwarding tunnel end point) (Default value = 'UNKNOWN') - @type chain_host: C{str} - @param chain_port: port of chain host (forwarding tunnel end point) (Default value = 0) - @type chain_port: C{str} - @param subsystem: information on the subsystem that provoked this hook call (Default value = None) - @type subsystem: C{str} + :param chain_host: hostname of chain host (forwarding tunnel end point) (Default value = 'UNKNOWN') + :type chain_host: C{str} + :param chain_port: port of chain host (forwarding tunnel end point) (Default value = 0) + :type chain_port: C{str} + :param subsystem: information on the subsystem that provoked this hook call (Default value = None) + :type subsystem: C{str} """ if type(subsystem) in (bytes, str): @@ -602,16 +604,16 @@ class X2GoSession(object): """\ HOOK method: called if a host check is requested. This hook has to either return C{True} (default) or C{False}. - @param host: SSH server name to validate - @type host: C{str} - @param port: SSH server port to validate - @type port: C{int} - @param fingerprint: the server's fingerprint (Default value = 'no fingerprint') - @type fingerprint: C{str} - @param fingerprint_type: finger print type (like RSA, DSA, ...) (Default value = 'UNKNOWN') - @type fingerprint_type: C{str} - @return: if host validity is verified, this hook method should return C{True} - @rtype: C{bool} + :param host: SSH server name to validate + :type host: C{str} + :param port: SSH server port to validate + :type port: C{int} + :param fingerprint: the server's fingerprint (Default value = 'no fingerprint') + :type fingerprint: C{str} + :param fingerprint_type: finger print type (like RSA, DSA, ...) (Default value = 'UNKNOWN') + :type fingerprint_type: C{str} + :returns: if host validity is verified, this hook method should return C{True} + :rtype: C{bool} """ if self.client_instance: @@ -650,16 +652,17 @@ class X2GoSession(object): def is_master_session(self): """\ Is this session a/the master session of sessions. - + The master session is the session has been launched first for a specific connection, it also is _the_ session that controls the client-side shared folders. - + If this L{X2GoSession} instance is a standalone instance (without parent L{X2GoClient}) this method will always return C{True}. - @return: returns C{True} if this session is a master session - @rtype: C{bool} + :returns: returns C{True} if this session is a master session + + :rtype: C{bool} """ if self.master_session is None and self.client_instance is None: @@ -670,15 +673,15 @@ class X2GoSession(object): def set_master_session(self, wait=0, max_wait=20): """\ Declare this as a master session of a connection channel. - + This method gets called by the L{X2GoSessionRegistry} while sessions are starting or resuming and it relies on an already set-up terminal session. - @param wait: wait for <wait> seconds before sharing local folders via the new master session + :param wait: wait for <wait> seconds before sharing local folders via the new master session of the corresponding session profile. (Default value = 0) - @type wait: C{int} - @param max_wait: wait for <max_wait> seconds for the terminal session to appear (Default value = 20) - @type max_wait: C{int} + :type wait: C{int} + :param max_wait: wait for <max_wait> seconds for the terminal session to appear (Default value = 20) + :type max_wait: C{int} """ self.logger('Using session %s as master session for profile %s.' % (self.get_session_name(), self.get_profile_name()), loglevel=log.loglevel_NOTICE) @@ -718,8 +721,8 @@ class X2GoSession(object): """\ Modify server name after L{X2GoSession} has already been initialized. - @param server: new server name - @type server: C{str} + :param server: new server name + :type server: C{str} """ self.server = server @@ -729,8 +732,8 @@ class X2GoSession(object): """\ Modify server port after L{X2GoSession} has already been initialized. - @param port: socket port of server to connect to - @type port: C{int} + :param port: socket port of server to connect to + :type port: C{int} """ self.port = port @@ -740,8 +743,8 @@ class X2GoSession(object): """\ Modify session profile name after L{X2GoSession} has already been initialized. - @param profile_name: new session profile name - @type profile_name: C{str} + :param profile_name: new session profile name + :type profile_name: C{str} """ self.profile_name = profile_name @@ -752,11 +755,11 @@ class X2GoSession(object): """\ Retrieve a specific profile parameter for this session. - @param option: name of a specific profile option to be queried. - @type option: C{str} - @return: value for profile option C{<option>} - @rtype: C{bool,str,int} - @raise X2GoProfileException: if the session profile option is unknown + :param option: name of a specific profile option to be queried. + :type option: C{str} + :returns: value for profile option C{<option>} + :rtype: C{bool,str,int} + :raises X2GoProfileException: if the session profile option is unknown """ if option in _X2GO_SESSION_PARAMS + _X2GO_TERMINAL_PARAMS + _X2GO_SSHPROXY_PARAMS and hasattr(self, option): @@ -770,8 +773,8 @@ class X2GoSession(object): This method can be used to modify L{X2GoSession} parameters after the L{X2GoSession} instance has already been initialized. - @param params: a Python dictionary with L{X2GoSession} parameters - @type params: C{dict} + :param params: a Python dictionary with L{X2GoSession} parameters + :type params: C{dict} """ try: del params['server'] @@ -860,8 +863,9 @@ class X2GoSession(object): Retrieve session UUID hash for this L{X2GoSession}. - @return: the session's UUID hash - @rtype: C{str} + :returns: the session's UUID hash + + :rtype: C{str} """ return str(self.uuid) @@ -873,8 +877,9 @@ class X2GoSession(object): username the session runs as. - @return: the remote username the X2Go session runs as - @rtype: C{str} + :returns: the remote username the X2Go session runs as + + :rtype: C{str} """ # try to retrieve the username from the control session, if already connected @@ -890,8 +895,9 @@ class X2GoSession(object): remote user's home directory path. - @return: the remote home directory path - @rtype: C{str} + :returns: the remote home directory path + + :rtype: C{str} """ # try to retrieve the username from the control session, if already connected @@ -905,10 +911,10 @@ class X2GoSession(object): """\ Check if a given user is valid server-side X2Go user. - @param username: username to check validity for (Default value = None) - @type username: C{str} - @return: C{True} if the username is allowed to launch X2Go sessions - @rtype: C{bool} + :param username: username to check validity for (Default value = None) + :type username: C{str} + :returns: C{True} if the username is allowed to launch X2Go sessions + :rtype: C{bool} """ if username is None: @@ -922,8 +928,9 @@ class X2GoSession(object): username's password from the session. - @return: the username's password - @rtype: C{str} + :returns: the username's password + + :rtype: C{str} """ return base64.base64decode(self.control_session._session_password) @@ -936,9 +943,10 @@ class X2GoSession(object): about to connect to). - @return: the address of the server the X2Go session is + :returns: the address of the server the X2Go session is connected to (as an C{(addr,port)} tuple) - @rtype: C{tuple} + + :rtype: C{tuple} """ return self.control_session.remote_peername() @@ -953,9 +961,10 @@ class X2GoSession(object): about to connect to). - @return: the hostname of the server the X2Go session is + :returns: the hostname of the server the X2Go session is connected to / about to connect to - @rtype: C{str} + + :rtype: C{str} """ self.server = self.control_session.get_hostname() @@ -968,9 +977,10 @@ class X2GoSession(object): IP socket port used for connecting the remote X2Go server. - @return: the server-side IP socket port that is used by the X2Go session to + :returns: the server-side IP socket port that is used by the X2Go session to connect to the server - @rtype: C{str} + + :rtype: C{str} """ return self.control_session.get_port() @@ -981,8 +991,9 @@ class X2GoSession(object): Retrieve the server-side X2Go session name for this session. - @return: X2Go session name - @rtype: C{str} + :returns: X2Go session name + + :rtype: C{str} """ return self.session_name @@ -992,8 +1003,8 @@ class X2GoSession(object): """\ Manipulate the L{X2GoSession}'s session name. - @param session_name: the new session name to be set - @type session_name: C{str} + :param session_name: the new session name to be set + :type session_name: C{str} """ self.session_name = session_name @@ -1004,8 +1015,9 @@ class X2GoSession(object): Retrieve the server-side X2Go session info object for this session. - @return: X2Go session info - @rtype: C{obj} + :returns: X2Go session info + + :rtype: C{obj} """ if self.has_terminal_session(): @@ -1018,8 +1030,9 @@ class X2GoSession(object): on the remote X2Go server. - @return: server-side session command - @rtype: C{str} + :returns: server-side session command + + :rtype: C{str} """ if self.has_terminal_session(): @@ -1032,15 +1045,16 @@ class X2GoSession(object): def get_session_type(self): """\ Retrieve the session type of a session (R, D, S or P). - + - R: rootless session - D: desktop session - S: shadow session - P: session in published applications mode - @return: session type - @rtype: C{str} + :returns: session type + + :rtype: C{str} """ if self.has_terminal_session(): @@ -1055,8 +1069,9 @@ class X2GoSession(object): session. - @return: session window title - @rtype: C{str} + :returns: session window title + + :rtype: C{str} """ if self.has_terminal_session(): @@ -1070,8 +1085,9 @@ class X2GoSession(object): Retrieve the control session (C{X2GoControlSession*} backend) of this L{X2GoSession}. - @return: the L{X2GoSession}'s control session - @rtype: C{X2GoControlSession*} instance + :returns: the L{X2GoSession}'s control session + + :rtype: C{X2GoControlSession*} instance """ return self.control_session @@ -1082,8 +1098,9 @@ class X2GoSession(object): Check if this L{X2GoSession} instance has an associated control session. - @return: returns C{True} if this L{X2GoSession} has a control session associated to itself - @rtype: C{bool} + :returns: returns C{True} if this L{X2GoSession} has a control session associated to itself + + :rtype: C{bool} """ return self.control_session is not None @@ -1094,8 +1111,9 @@ class X2GoSession(object): Retrieve the terminal session (C{X2GoTerminalSession*} backend) of this L{X2GoSession}. - @return: the L{X2GoSession}'s terminal session - @rtype: C{X2GoControlTerminal*} instance + :returns: the L{X2GoSession}'s terminal session + + :rtype: C{X2GoControlTerminal*} instance """ if self.terminal_session == 'PENDING': @@ -1108,8 +1126,9 @@ class X2GoSession(object): Check if this L{X2GoSession} instance has an associated terminal session. - @return: returns C{True} if this L{X2GoSession} has a terminal session associated to itself - @rtype: C{bool} + :returns: returns C{True} if this L{X2GoSession} has a terminal session associated to itself + + :rtype: C{bool} """ return self.terminal_session not in (None, 'PENDING') @@ -1124,8 +1143,9 @@ class X2GoSession(object): override any of these to enable user interaction on X2Go server validity checks. - @return: returns C{True} if an X2Go server host is valid for authentication - @rtype: C{bool} + :returns: returns C{True} if an X2Go server host is valid for authentication + + :rtype: C{bool} """ if self.connected: @@ -1141,8 +1161,9 @@ class X2GoSession(object): Check if a session is configured to use an intermediate SSH proxy server. - @return: returns C{True} if the session is configured to use an SSH proxy, C{False} otherwise. - @rtype: C{bool} + :returns: returns C{True} if the session is configured to use an SSH proxy, C{False} otherwise. + + :rtype: C{bool} """ return self.use_sshproxy @@ -1154,8 +1175,9 @@ class X2GoSession(object): proxy authentication, as well. - @return: returns C{True} if the session is configured to re-use session password / key for proxy authentication - @rtype: C{bool} + :returns: returns C{True} if the session is configured to re-use session password / key for proxy authentication + + :rtype: C{bool} """ return self.sshproxy_reuse_authinfo @@ -1167,9 +1189,10 @@ class X2GoSession(object): to the SSH proxy server (e.g. by public key authentication). - @return: returns C{True} if the session's SSH proxy can auto-connect, C{False} otherwise, C{None} + :returns: returns C{True} if the session's SSH proxy can auto-connect, C{False} otherwise, C{None} if no SSH proxy is used for this session, C{None} is returned. - @rtype: C{bool} + + :rtype: C{bool} """ if self.use_sshproxy: @@ -1197,9 +1220,10 @@ class X2GoSession(object): server (e.g. public key authentication). - @return: returns C{True} if the session can auto-connect, C{False} otherwise, C{None} + :returns: returns C{True} if the session can auto-connect, C{False} otherwise, C{None} if no control session has been set up yet. - @rtype: C{bool} + + :rtype: C{bool} """ if self.control_session is None: @@ -1231,10 +1255,10 @@ class X2GoSession(object): """\ Automatically connect this session. - @param redirect_to_client: Pass this request through to the L{X2GoClient} instance, if given (Default value = True) - @type redirect_to_client: C{True} - @return: Return success (or failure) of connecting this sessions - @rtype: C{bool} + :param redirect_to_client: Pass this request through to the L{X2GoClient} instance, if given (Default value = True) + :type redirect_to_client: C{True} + :returns: Return success (or failure) of connecting this sessions + :rtype: C{bool} """ if not self.is_connected(): @@ -1255,48 +1279,48 @@ class X2GoSession(object): Connects to the L{X2GoSession}'s server host. This method basically wraps around the C{X2GoControlSession*.connect()} method. - @param username: the username for the X2Go server that is going to be + :param username: the username for the X2Go server that is going to be connected to (as a last minute way of changing the session username) (Default value = None) - @type username: C{str} - @param password: the user's password for the X2Go server that is going to be + :type username: C{str} + :param password: the user's password for the X2Go server that is going to be connected to (Default value = None) - @type password: C{str} - @param passphrase: a passphrase to use for unlocking + :type password: C{str} + :param passphrase: a passphrase to use for unlocking a private key in case the password is already needed for two-factor authentication (Default value = None) - @type passphrase: C{str} - @param add_to_known_hosts: non-paramiko option, if C{True} paramiko.AutoAddPolicy() + :type passphrase: C{str} + :param add_to_known_hosts: non-paramiko option, if C{True} paramiko.AutoAddPolicy() is used as missing-host-key-policy. If set to C{False} paramiko.RejectPolicy() is used (Default value = None) - @type add_to_known_hosts: C{bool} - @param force_password_auth: disable SSH pub/priv key authentication mechanisms + :type add_to_known_hosts: C{bool} + :param force_password_auth: disable SSH pub/priv key authentication mechanisms completely (Default value = None) - @type force_password_auth: C{bool} - @param look_for_keys: set to C{True} to enable searching for discoverable + :type force_password_auth: C{bool} + :param look_for_keys: set to C{True} to enable searching for discoverable private key files in C{~/.ssh/} (Default value = None) - @type look_for_keys: C{bool} - @param allow_agent: set to C{True} to enable connecting to a local SSH agent + :type look_for_keys: C{bool} + :param allow_agent: set to C{True} to enable connecting to a local SSH agent for acquiring authentication information (Default value = None) - @type allow_agent: C{bool} - @param use_sshproxy: use an SSH proxy host for connecting the target X2Go server (Default value = None) - @type use_sshproxy: C{bool} - @param sshproxy_reuse_authinfo: for proxy authentication re-use the X2Go session's password / key file (Default value = None) - @type sshproxy_reuse_authinfo: C{bool} - @param sshproxy_user: username for authentication against the SSH proxy host (Default value = None) - @type sshproxy_user: C{str} - @param sshproxy_password: password for authentication against the SSH proxy host (Default value = None) - @type sshproxy_password: C{str} - @param sshproxy_passphrase: a passphrase to use for unlocking + :type allow_agent: C{bool} + :param use_sshproxy: use an SSH proxy host for connecting the target X2Go server (Default value = None) + :type use_sshproxy: C{bool} + :param sshproxy_reuse_authinfo: for proxy authentication re-use the X2Go session's password / key file (Default value = None) + :type sshproxy_reuse_authinfo: C{bool} + :param sshproxy_user: username for authentication against the SSH proxy host (Default value = None) + :type sshproxy_user: C{str} + :param sshproxy_password: password for authentication against the SSH proxy host (Default value = None) + :type sshproxy_password: C{str} + :param sshproxy_passphrase: a passphrase to use for unlocking a private key needed for the SSH proxy host in case the sshproxy_password is already needed for two-factor authentication (Default value = None) - @type sshproxy_passphrase: C{str} - @param sshproxy_force_password_auth: enforce password authentication even is a key(file) is present (Default value = None) - @type sshproxy_force_password_auth: C{bool} - @return: returns C{True} is the connection to the X2Go server has been successful - @rtype: C{bool} - @raise X2GoSessionException: on control session exceptions - @raise X2GoRemoteHomeException: if the remote home directory does not exist - @raise Exception: any other exception during connecting is passed through + :type sshproxy_passphrase: C{str} + :param sshproxy_force_password_auth: enforce password authentication even is a key(file) is present (Default value = None) + :type sshproxy_force_password_auth: C{bool} + :returns: returns C{True} is the connection to the X2Go server has been successful + :rtype: C{bool} + :raises X2GoSessionException: on control session exceptions + :raises X2GoRemoteHomeException: if the remote home directory does not exist + :raises Exception: any other exception during connecting is passed through """ if self.control_session and self.control_session.is_connected(): @@ -1402,8 +1426,9 @@ class X2GoSession(object): Disconnect this L{X2GoSession} instance. - @return: returns C{True} if the disconnect operation has been successful - @rtype: C{bool} + :returns: returns C{True} if the disconnect operation has been successful + + :rtype: C{bool} """ self.connected = False @@ -1438,8 +1463,9 @@ class X2GoSession(object): Return a list of X2Go server-sides features (supported functionalities). - @return: a C{list} of X2Go feature names - @rtype: C{list} + :returns: a C{list} of X2Go feature names + + :rtype: C{list} """ return self.server_features @@ -1449,10 +1475,10 @@ class X2GoSession(object): """\ Check if C{feature} is a present feature of the connected X2Go server. - @param feature: an X2Go server feature as found in C{$SHAREDIR/x2go/feature.d/*} - @type feature: C{str} - @return: returns C{True} if the feature is present - @rtype: C{bool} + :param feature: an X2Go server feature as found in C{$SHAREDIR/x2go/feature.d/*} + :type feature: C{str} + :returns: returns C{True} if the feature is present + :rtype: C{bool} """ return feature in self.get_server_features() @@ -1464,8 +1490,8 @@ class X2GoSession(object): given title, it will be prepended, so that every X2Go session window always contains the X2Go session ID of that window. - @param title: new title for session window (Default value = '') - @type title: C{str} + :param title: new title for session window (Default value = '') + :type title: C{str} """ if self.terminal_session is not None: @@ -1487,16 +1513,17 @@ class X2GoSession(object): """\ If X2Go client-side printing is enable within this X2Go session you can use this method to alter the way how incoming print spool jobs are handled/processed. - + For further information, please refer to the documentation of the L{X2GoClient.set_session_print_action()} method. - @param print_action: one of the named above print actions, either as string or class instance - @type print_action: C{str} or C{instance} - @param kwargs: additional information for the given print action (print + :param print_action: one of the named above print actions, either as string or class instance + :type print_action: C{str} or C{instance} + :param kwargs: additional information for the given print action (print action arguments), for possible print action arguments and their values see each individual print action class - @type kwargs: C{dict} + :type kwargs: C{dict} + :param **kwargs: """ if type(print_action) is not bytes: @@ -1509,8 +1536,9 @@ class X2GoSession(object): Find out if this X2Go session is still alive (that is: connected to the server). - @return: returns C{True} if the server connection is still alive - @rtype: C{bool} + :returns: returns C{True} if the server connection is still alive + + :rtype: C{bool} """ self.connected = self.control_session.is_alive() @@ -1525,10 +1553,10 @@ class X2GoSession(object): """\ Clean all running sessions for the authenticated user on the remote X2Go server. - @param destroy_terminals: destroy associated terminal sessions (Default value = True) - @type destroy_terminals: C{bool} - @param published_applications: clean sessions that are published applications providers, too (Default value = False) - @type published_applications: C{bool} + :param destroy_terminals: destroy associated terminal sessions (Default value = True) + :type destroy_terminals: C{bool} + :param published_applications: clean sessions that are published applications providers, too (Default value = False) + :type published_applications: C{bool} """ if self.is_alive(): @@ -1546,11 +1574,11 @@ class X2GoSession(object): """\ List all sessions on the remote X2Go server that are owned by the authenticated user - @param raw: if C{True} the output of this method equals + :param raw: if C{True} the output of this method equals the output of the server-side C{x2golistsessions} command (Default value = False) - @type raw: C{bool} - @return: a session list (as data object or list of strings when called with C{raw=True} option) - @rtype: C{X2GoServerSessionList*} instance or C{list} + :type raw: C{bool} + :returns: a session list (as data object or list of strings when called with C{raw=True} option) + :rtype: C{X2GoServerSessionList*} instance or C{list} """ try: @@ -1565,11 +1593,11 @@ class X2GoSession(object): """\ List X2Go desktops sessions available for desktop sharing on the remote X2Go server. - @param raw: if C{True} the output of this method equals + :param raw: if C{True} the output of this method equals the output of the server-side C{x2golistdesktops} command (Default value = False) - @type raw: C{bool} - @return: a list of strings representing available desktop sessions - @rtype: C{list} + :type raw: C{bool} + :returns: a list of strings representing available desktop sessions + :rtype: C{list} """ try: @@ -1588,11 +1616,11 @@ class X2GoSession(object): Use the X2Go session registered under C{session_uuid} to retrieve its list of mounted client shares for that session. - @param raw: output the list of mounted client shares in X2Go's + :param raw: output the list of mounted client shares in X2Go's raw C{x2golistmounts} format (Default value = False) - @type raw: C{bool} - @return: a list of strings representing mounted client shares for this session - @rtype: C{list} + :type raw: C{bool} + :returns: a list of strings representing mounted client shares for this session + :rtype: C{list} """ try: @@ -1608,21 +1636,21 @@ class X2GoSession(object): Update the current session status. The L{X2GoSession} instance uses an internal session status cache that allows to query the session status without the need of retrieving data from the remote X2Go server for each query. - + The session status (if initialized properly with the L{X2GoClient} constructor gets updated in regularly intervals. - + In case you use the L{X2GoSession} class in standalone instances (that is: without being embedded into an L{X2GoSession} context) then run this method in regular intervals to make sure the L{X2GoSession}'s internal status cache information is always up-to-date. - @param session_list: provide an C{X2GoServerSessionList*} that refers to X2Go sessions we want to update. + :param session_list: provide an C{X2GoServerSessionList*} that refers to X2Go sessions we want to update. This option is mainly for reducing server/client traffic. (Default value = None) - @type session_list: C{X2GoServerSessionList*} instance - @param force_update: force a session status update, if if the last update is less then 1 second ago (Default value = False) - @type force_update: C{bool} - @raise Exception: any exception is passed through in case the session disconnected surprisingly + :type session_list: C{X2GoServerSessionList*} instance + :param force_update: force a session status update, if if the last update is less then 1 second ago (Default value = False) + :type force_update: C{bool} + :raises Exception: any exception is passed through in case the session disconnected surprisingly or has been marked as faulty """ @@ -1688,8 +1716,9 @@ class X2GoSession(object): Returns true if this session runs in published applications mode. - @return: returns C{True} if this session is a provider session for published applications. - @rtype: C{bool} + :returns: returns C{True} if this session is a provider session for published applications. + + :rtype: C{bool} """ if self.has_terminal_session() and self.is_running() : @@ -1702,21 +1731,21 @@ class X2GoSession(object): Return a list of published menu items from the X2Go server for session type published applications. - @param lang: locale/language identifier (Default value = None) - @type lang: C{str} - @param refresh: force reload of the menu tree from X2Go server (Default value = False) - @type refresh: C{bool} - @param raw: retrieve a raw output of the server list of published applications (Default value = False) - @type raw: C{bool} - @param very_raw: retrieve a very raw output of the server list of published applications (as-is output of x2gogetapps script) (Default value = False) - @type very_raw: C{bool} - @param max_no_submenus: Number of applications before applications are put into XDG category submenus + :param lang: locale/language identifier (Default value = None) + :type lang: C{str} + :param refresh: force reload of the menu tree from X2Go server (Default value = False) + :type refresh: C{bool} + :param raw: retrieve a raw output of the server list of published applications (Default value = False) + :type raw: C{bool} + :param very_raw: retrieve a very raw output of the server list of published applications (as-is output of x2gogetapps script) (Default value = False) + :type very_raw: C{bool} + :param max_no_submenus: Number of applications before applications are put into XDG category submenus (Default value = defaults.PUBAPP_MAX_NO_SUBMENUS) - @type max_no_submenus: C{int} - @return: A C{list} of C{dict} elements. Each C{dict} elements has a + :type max_no_submenus: C{int} + :returns: A C{list} of C{dict} elements. Each C{dict} elements has a C{desktop} key containing the text output of a .desktop file and an C{icon} key which contains the desktop icon data base64 encoded - @rtype: C{list} + :rtype: C{list} """ if self.client_instance and hasattr(self.client_instance, 'lang'): @@ -1728,10 +1757,10 @@ class X2GoSession(object): """\ Execute an application while in published application mode. - @param exec_name: command to execute on server - @type exec_name: C{str} - @param timeout: time in secs to wait for server query to reply (Default value = 20) - @type timeout: C{int} + :param exec_name: command to execute on server + :type exec_name: C{str} + :param timeout: time in secs to wait for server query to reply (Default value = 20) + :type timeout: C{int} """ if self.terminal_session is not None: @@ -1744,21 +1773,21 @@ class X2GoSession(object): Automatically start or resume this session, if already associated with a server session. Otherwise resume a server-side available/suspended session (see options to declare which session to resume). If no session is available for resuming a new session will be launched. - + Sessions in published applications mode are not resumed/started by this method. - @param newest: if resuming, only resume newest/youngest session (Default value = True) - @type newest: C{bool} - @param oldest: if resuming, only resume oldest session (Default value = False) - @type oldest: C{bool} - @param all_suspended: if resuming, resume all suspended sessions (Default value = False) - @type all_suspended: C{bool} - @param start: is no session is to be resumed, start a new session (Default value = True) - @type start: C{bool} - @param redirect_to_client: redirect this call to the L{X2GoClient} instance (if available) to allow frontend interaction (Default value = True) - @type redirect_to_client: C{bool} - @return: returns success (or failure) of starting/resuming this sessions - @rtype: C{bool} + :param newest: if resuming, only resume newest/youngest session (Default value = True) + :type newest: C{bool} + :param oldest: if resuming, only resume oldest session (Default value = False) + :type oldest: C{bool} + :param all_suspended: if resuming, resume all suspended sessions (Default value = False) + :type all_suspended: C{bool} + :param start: is no session is to be resumed, start a new session (Default value = True) + :type start: C{bool} + :param redirect_to_client: redirect this call to the L{X2GoClient} instance (if available) to allow frontend interaction (Default value = True) + :type redirect_to_client: C{bool} + :returns: returns success (or failure) of starting/resuming this sessions + :rtype: C{bool} """ if self.client_instance and redirect_to_client: @@ -1803,8 +1832,9 @@ class X2GoSession(object): Retrieve session startup/resumption progress status. - @return: returns an C{int} value between 0 and 100 reflecting the session startup/resumption status - @rtype: C{int} + :returns: returns an C{int} value between 0 and 100 reflecting the session startup/resumption status + + :rtype: C{int} """ return self._progress_status @@ -1814,19 +1844,19 @@ class X2GoSession(object): Resume or continue a suspended / running X2Go session on the remote X2Go server. - @param session_name: the server-side name of an X2Go session (Default value = None) - @type session_name: C{str} - @param session_list: a session list to avoid a server-side session list query (Default value = None) - @type session_list: C{dict} - @param cmd: if starting a new session, manually hand over the command to be launched in + :param session_name: the server-side name of an X2Go session (Default value = None) + :type session_name: C{str} + :param session_list: a session list to avoid a server-side session list query (Default value = None) + :type session_list: C{dict} + :param cmd: if starting a new session, manually hand over the command to be launched in the new session (Default value = None) - @type cmd: C{str} - @param progress_event: a C{thread.Event} object that notifies a status object like the one in + :type cmd: C{str} + :param progress_event: a C{thread.Event} object that notifies a status object like the one in L{utils.ProgressStatus}. (Default value = None) - @type progress_event: C{obj} - @return: returns C{True} if resuming the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise Exception: any exception that occurs during published application menu retrieval is passed through + :type progress_event: C{obj} + :returns: returns C{True} if resuming the session has been successful, C{False} otherwise + :rtype: C{bool} + :raises Exception: any exception that occurs during published application menu retrieval is passed through """ self._lock.acquire() @@ -1846,19 +1876,19 @@ class X2GoSession(object): Resume or continue a suspended / running X2Go session on the remote X2Go server. - @param session_name: the server-side name of an X2Go session (Default value = None) - @type session_name: C{str} - @param session_list: a session list to avoid a server-side session list query (Default value = None) - @type session_list: C{dict} - @param cmd: if starting a new session, manually hand over the command to be launched in + :param session_name: the server-side name of an X2Go session (Default value = None) + :type session_name: C{str} + :param session_list: a session list to avoid a server-side session list query (Default value = None) + :type session_list: C{dict} + :param cmd: if starting a new session, manually hand over the command to be launched in the new session (Default value = None) - @type cmd: C{str} - @param progress_event: a C{thread.Event} object that notifies a status object like the one in + :type cmd: C{str} + :param progress_event: a C{thread.Event} object that notifies a status object like the one in L{utils.ProgressStatus}. (Default value = None) - @type progress_event: C{obj} - @return: returns C{True} if resuming the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise Exception: any exception that occurs during published application menu retrieval is passed through + :type progress_event: C{obj} + :returns: returns C{True} if resuming the session has been successful, C{False} otherwise + :rtype: C{bool} + :raises Exception: any exception that occurs during published application menu retrieval is passed through """ if self.terminal_session is None: @@ -2095,13 +2125,13 @@ class X2GoSession(object): """\ Start a new X2Go session on the remote X2Go server. - @param cmd: manually hand over the command that is to be launched in the new session (Default value = None) - @type cmd: C{str} - @param progress_event: a C{thread.Event} object that notifies a status object like the one in + :param cmd: manually hand over the command that is to be launched in the new session (Default value = None) + :type cmd: C{str} + :param progress_event: a C{thread.Event} object that notifies a status object like the one in L{utils.ProgressStatus}. (Default value = None) - @type progress_event: C{obj} - @return: returns C{True} if starting the session has been successful, C{False} otherwise - @rtype: C{bool} + :type progress_event: C{obj} + :returns: returns C{True} if starting the session has been successful, C{False} otherwise + :rtype: C{bool} """ self.session_name = None @@ -2113,26 +2143,26 @@ class X2GoSession(object): Share an already running X2Go session on the remote X2Go server locally. The shared session may be either owned by the same user or by a user that grants access to his/her desktop session by the local user. - @param desktop: desktop ID of a sharable desktop in format <user>@<display> (Default value = None) - @type desktop: C{str} - @param user: user name and display number can be given separately, here give the + :param desktop: desktop ID of a sharable desktop in format <user>@<display> (Default value = None) + :type desktop: C{str} + :param user: user name and display number can be given separately, here give the name of the user who wants to share a session with you. (Default value = None) - @type user: C{str} - @param display: user name and display number can be given separately, here give the + :type user: C{str} + :param display: user name and display number can be given separately, here give the number of the display that a user allows you to be shared with. (Default value = None) - @type display: C{str} - @param share_mode: desktop sharing mode, 0 is VIEW-ONLY, 1 is FULL-ACCESS. (Default value = 0) - @type share_mode: C{int} - @param check_desktop_list: check if the given desktop is available on the X2Go server; handle with care as + :type display: C{str} + :param share_mode: desktop sharing mode, 0 is VIEW-ONLY, 1 is FULL-ACCESS. (Default value = 0) + :type share_mode: C{int} + :param check_desktop_list: check if the given desktop is available on the X2Go server; handle with care as the server-side C{x2golistdesktops} command might block client I/O. (Default value = True) - @type check_desktop_list: C{bool} - @param progress_event: a C{thread.Event} object that notifies a status object like the one in + :type check_desktop_list: C{bool} + :param progress_event: a C{thread.Event} object that notifies a status object like the one in L{utils.ProgressStatus}. (Default value = None) - @type progress_event: C{obj} - @return: returns C{True} if starting the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise X2GoDesktopSharingException: if a given desktop ID does not specify an available desktop session - @raise X2GoSessionException: if the available desktop session appears to be dead, in fact + :type progress_event: C{obj} + :returns: returns C{True} if starting the session has been successful, C{False} otherwise + :rtype: C{bool} + :raises X2GoDesktopSharingException: if a given desktop ID does not specify an available desktop session + :raises X2GoSessionException: if the available desktop session appears to be dead, in fact """ self._lock.acquire() @@ -2152,26 +2182,26 @@ class X2GoSession(object): Share an already running X2Go session on the remote X2Go server locally. The shared session may be either owned by the same user or by a user that grants access to his/her desktop session by the local user. - @param desktop: desktop ID of a sharable desktop in format <user>@<display> (Default value = None) - @type desktop: C{str} - @param user: user name and display number can be given separately, here give the + :param desktop: desktop ID of a sharable desktop in format <user>@<display> (Default value = None) + :type desktop: C{str} + :param user: user name and display number can be given separately, here give the name of the user who wants to share a session with you. (Default value = None) - @type user: C{str} - @param display: user name and display number can be given separately, here give the + :type user: C{str} + :param display: user name and display number can be given separately, here give the number of the display that a user allows you to be shared with. (Default value = None) - @type display: C{str} - @param share_mode: desktop sharing mode, 0 is VIEW-ONLY, 1 is FULL-ACCESS. (Default value = 0) - @type share_mode: C{int} - @param check_desktop_list: check if the given desktop is available on the X2Go server; handle with care as + :type display: C{str} + :param share_mode: desktop sharing mode, 0 is VIEW-ONLY, 1 is FULL-ACCESS. (Default value = 0) + :type share_mode: C{int} + :param check_desktop_list: check if the given desktop is available on the X2Go server; handle with care as the server-side C{x2golistdesktops} command might block client I/O. (Default value = True) - @type check_desktop_list: C{bool} - @param progress_event: a C{thread.Event} object that notifies a status object like the one in + :type check_desktop_list: C{bool} + :param progress_event: a C{thread.Event} object that notifies a status object like the one in L{utils.ProgressStatus}. (Default value = None) - @type progress_event: C{obj} - @return: returns C{True} if starting the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise X2GoDesktopSharingException: if a given desktop ID does not specify an available desktop session - @raise X2GoSessionException: if the available desktop session appears to be dead, in fact + :type progress_event: C{obj} + :returns: returns C{True} if starting the session has been successful, C{False} otherwise + :rtype: C{bool} + :raises X2GoDesktopSharingException: if a given desktop ID does not specify an available desktop session + :raises X2GoSessionException: if the available desktop session appears to be dead, in fact """ self.terminal_session = 'PENDING' @@ -2282,8 +2312,9 @@ class X2GoSession(object): Test if this X2Go session is a desktop session. - @return: C{True} if this session is of session type desktop ('D'). - @rtype: C{bool} + :returns: C{True} if this session is of session type desktop ('D'). + + :rtype: C{bool} """ if self.has_terminal_session(): @@ -2295,8 +2326,9 @@ class X2GoSession(object): Test if this X2Go session is a rootless session. - @return: C{True} if this session is of session type rootless ('R'). - @rtype: C{bool} + :returns: C{True} if this session is of session type rootless ('R'). + + :rtype: C{bool} """ if self.has_terminal_session(): @@ -2308,8 +2340,9 @@ class X2GoSession(object): Test if this X2Go session is a desktop sharing (aka shadow) session. - @return: C{True} if this session is of session type shadow ('S'). - @rtype: C{bool} + :returns: C{True} if this session is of session type shadow ('S'). + + :rtype: C{bool} """ if self.has_terminal_session(): @@ -2321,8 +2354,9 @@ class X2GoSession(object): Test if this X2Go session is a published applications session. - @return: C{True} if this session is of session type published applications ('P'). - @rtype: C{bool} + :returns: C{True} if this session is of session type published applications ('P'). + + :rtype: C{bool} """ if self.has_terminal_session(): @@ -2334,9 +2368,10 @@ class X2GoSession(object): Suspend this X2Go session. - @return: returns C{True} if suspending the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise X2GoSessionException: if the session could not be suspended + :returns: returns C{True} if suspending the session has been successful, C{False} otherwise + + :rtype: C{bool} + :raises X2GoSessionException: if the session could not be suspended """ self._lock.acquire() @@ -2356,9 +2391,10 @@ class X2GoSession(object): Suspend this X2Go session. - @return: returns C{True} if suspending the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise X2GoSessionException: if the session could not be suspended + :returns: returns C{True} if suspending the session has been successful, C{False} otherwise + + :rtype: C{bool} + :raises X2GoSessionException: if the session could not be suspended """ if self.is_alive(): @@ -2407,9 +2443,10 @@ class X2GoSession(object): Terminate this X2Go session. - @return: returns C{True} if terminating the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise X2GoSessionException: if the session could not be terminated + :returns: returns C{True} if terminating the session has been successful, C{False} otherwise + + :rtype: C{bool} + :raises X2GoSessionException: if the session could not be terminated """ self._lock.acquire() @@ -2429,9 +2466,10 @@ class X2GoSession(object): Terminate this X2Go session. - @return: returns C{True} if terminating the session has been successful, C{False} otherwise - @rtype: C{bool} - @raise X2GoSessionException: if the session could not be terminated + :returns: returns C{True} if terminating the session has been successful, C{False} otherwise + + :rtype: C{bool} + :raises X2GoSessionException: if the session could not be terminated """ if self.is_alive(): @@ -2479,8 +2517,9 @@ class X2GoSession(object): Retrieve the profile name of this L{X2GoSession} instance. - @return: X2Go client profile name of the session - @rtype: C{str} + :returns: X2Go client profile name of the session + + :rtype: C{str} """ return self.profile_name @@ -2491,8 +2530,9 @@ class X2GoSession(object): Retrieve the profile ID of this L{X2GoSession} instance. - @return: the session profile's id - @rtype: C{str} + :returns: the session profile's id + + :rtype: C{str} """ return self.profile_id @@ -2508,8 +2548,9 @@ class X2GoSession(object): in a healthy state. - @return: C{True} if session is ok, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if session is ok, C{False} otherwise + + :rtype: C{bool} """ if self.has_terminal_session(): @@ -2522,8 +2563,9 @@ class X2GoSession(object): Extract color depth from session name. - @return: the session's color depth (as found in the session name) - @rtype: C{str} + :returns: the session's color depth (as found in the session name) + + :rtype: C{str} """ try: @@ -2537,9 +2579,10 @@ class X2GoSession(object): Check if this session will display properly with the local screen's color depth. - @return: C{True} if the session will display on this client screen, + :returns: C{True} if the session will display on this client screen, C{False} otherwise. If no terminal session is yet registered with this session, C{None} is returned. - @rtype: C{bool} + + :rtype: C{bool} """ _depth_local = utils.local_color_depth() @@ -2558,8 +2601,9 @@ class X2GoSession(object): remote X2Go server. - @return: C{True} if session is connected, C{False} otherwise - @rtype: C{bool} + :returns: C{True} if session is connected, C{False} otherwise + + :rtype: C{bool} """ self.connected = bool(self.control_session and self.control_session.is_connected()) @@ -2575,10 +2619,10 @@ class X2GoSession(object): """\ Test if the L{X2GoSession}'s terminal session is up and running. - @param update_status: if C{True}, the status is updated by a server call (Default value = False) - @type update_status: C{bool} - @return: C{True} if session is running, C{False} otherwise - @rtype: C{bool} + :param update_status: if C{True}, the status is updated by a server call (Default value = False) + :type update_status: C{bool} + :returns: C{True} if session is running, C{False} otherwise + :rtype: C{bool} """ if not update_status: @@ -2599,10 +2643,10 @@ class X2GoSession(object): """\ Test if the L{X2GoSession}'s terminal session is in suspended state. - @param update_status: if C{True}, the status is updated by a server call (Default value = False) - @type update_status: C{bool} - @return: C{True} if session is suspended, C{False} otherwise - @rtype: C{bool} + :param update_status: if C{True}, the status is updated by a server call (Default value = False) + :type update_status: C{bool} + :returns: C{True} if session is suspended, C{False} otherwise + :rtype: C{bool} """ if not update_status: @@ -2623,10 +2667,10 @@ class X2GoSession(object): """\ Test if the L{X2GoSession}'s terminal session has terminated. - @param update_status: if C{True}, the status is updated by a server call (Default value = False) - @type update_status: C{bool} - @return: C{True} if session has terminated, C{False} otherwise - @rtype: C{bool} + :param update_status: if C{True}, the status is updated by a server call (Default value = False) + :type update_status: C{bool} + :returns: C{True} if session has terminated, C{False} otherwise + :rtype: C{bool} """ if not update_status: @@ -2647,8 +2691,10 @@ class X2GoSession(object): """\ Test if the remote session allows sharing of local folders with the session. - @return: returns C{True} if local folder sharing is available in the remote session - @rtype: C{bool} + + :returns: returns C{True} if local folder sharing is available in the remote session + + :rtype: C{bool} """ if self._SUPPORTED_FOLDERSHARING and self.allow_share_local_folders: @@ -2677,17 +2723,17 @@ class X2GoSession(object): """\ Share a local folder with this registered X2Go session. - @param local_path: the full path to an existing folder on the local + :param local_path: the full path to an existing folder on the local file system (Default value = None) - @type local_path: C{str} - @param folder_name: synonymous to C{local_path} (Default value = None) - @type folder_name: C{str} - @param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) - @type update_exported_folders: C{bool} - @return: returns C{True} if the local folder has been successfully mounted within + :type local_path: C{str} + :param folder_name: synonymous to C{local_path} (Default value = None) + :type folder_name: C{str} + :param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) + :type update_exported_folders: C{bool} + :returns: returns C{True} if the local folder has been successfully mounted within this X2Go session - @rtype: C{bool} - @raise X2GoSessionException: if this L{X2GoSession} does not have an associated terminal session + :rtype: C{bool} + :raises X2GoSessionException: if this L{X2GoSession} does not have an associated terminal session """ # compat for Python-X2Go (<=0.1.1.6) @@ -2741,11 +2787,11 @@ class X2GoSession(object): """\ Share all local folders configured to be mounted within this X2Go session. - @param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) - @type update_exported_folders: C{bool} - @return: returns C{True} if all local folders could be successfully mounted + :param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) + :type update_exported_folders: C{bool} + :returns: returns C{True} if all local folders could be successfully mounted inside this X2Go session - @rtype: C{bool} + :rtype: C{bool} """ retval = False @@ -2778,16 +2824,16 @@ class X2GoSession(object): """\ Unshare a local folder that is mounted within this X2Go session. - @param local_path: the full path to an existing folder on the local + :param local_path: the full path to an existing folder on the local file system that is mounted in this X2Go session and shall be unmounted (Default value = None) - @type local_path: C{str} - @param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) - @type update_exported_folders: C{bool} - @return: returns C{True} if all local folders could be successfully unmounted + :type local_path: C{str} + :param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) + :type update_exported_folders: C{bool} + :returns: returns C{True} if all local folders could be successfully unmounted inside this X2Go session - @rtype: C{bool} - @raise X2GoSessionException: if this L{X2GoSession} does not have an associated terminal session + :rtype: C{bool} + :raises X2GoSessionException: if this L{X2GoSession} does not have an associated terminal session """ retval = False @@ -2820,15 +2866,15 @@ class X2GoSession(object): """\ Unshare all local folders mounted within this X2Go session. - @param force_all: Really unmount _all_ shared folders, including the print spool folder and + :param force_all: Really unmount _all_ shared folders, including the print spool folder and the MIME box spool dir (not recommended). (Default value = False) - @type force_all: C{bool} - @param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) - @type update_exported_folders: C{bool} - @return: returns C{True} if all local folders could be successfully unmounted + :type force_all: C{bool} + :param update_exported_folders: do an update of the session profile option ,,export'' after the operation (Default value = True) + :type update_exported_folders: C{bool} + :returns: returns C{True} if all local folders could be successfully unmounted inside this X2Go session - @rtype: C{bool} - @raise X2GoSessionException: if this L{X2GoSession} does not have an associated terminal session + :rtype: C{bool} + :raises X2GoSessionException: if this L{X2GoSession} does not have an associated terminal session """ if self.has_terminal_session(): @@ -2857,13 +2903,13 @@ class X2GoSession(object): """\ Get a list of local folders mounted within this X2Go session from this client. - @param check_list_mounts: if set to C{True} the list of shared folders is referenced against + :param check_list_mounts: if set to C{True} the list of shared folders is referenced against the latest status of the server-side mount list. (Default value = False) - @type check_list_mounts: C{bool} - @param mounts: a server-side dictionary of session name keys and lists of mounted shares (server-side mount points) (Default value = None) - @type mounts: C{dict} - @return: returns a C{list} of those local folder names that are mounted with this X2Go session. - @rtype: C{list} + :type check_list_mounts: C{bool} + :param mounts: a server-side dictionary of session name keys and lists of mounted shares (server-side mount points) (Default value = None) + :type mounts: C{dict} + :returns: returns a C{list} of those local folder names that are mounted with this X2Go session. + :rtype: C{list} """ if self.is_folder_sharing_available and self.is_master_session() and self.shared_folders and check_list_mounts: @@ -2940,8 +2986,9 @@ class X2GoSession(object): change. - @return: returns C{True} if the session is locked - @rtype: C{bool} + :returns: returns C{True} if the session is locked + + :rtype: C{bool} """ self._lock.locked() diff --git a/x2go/sftpserver.py b/x2go/sftpserver.py index 4ec4488..f87c7b2 100644 --- a/x2go/sftpserver.py +++ b/x2go/sftpserver.py @@ -85,12 +85,12 @@ class _SSHServer(paramiko.ServerInterface): """\ Only allow session requests. - @param kind: request type - @type kind: C{str} - @param chanid: channel id (unused) - @type chanid: C{any} - @return: returns a Paramiko/SSH return code - @rtype: C{int} + :param kind: request type + :type kind: C{str} + :param chanid: channel id (unused) + :type chanid: C{any} + :returns: returns a Paramiko/SSH return code + :rtype: C{int} """ self.logger('detected a channel request for sFTP', loglevel=log.loglevel_DEBUG_SFTPXFER) @@ -102,12 +102,12 @@ class _SSHServer(paramiko.ServerInterface): """\ Ensure proper authentication. - @param username: username of incoming authentication request - @type username: C{str} - @param key: incoming SSH key to be used for authentication - @type key: C{paramiko.RSAKey} instance - @return: returns a Paramiko/SSH return code - @rtype: C{int} + :param username: username of incoming authentication request + :type username: C{str} + :param key: incoming SSH key to be used for authentication + :type key: C{paramiko.RSAKey} instance + :returns: returns a Paramiko/SSH return code + :rtype: C{int} """ self.logger('sFTP server %s: username is %s' % (self, self.current_local_user), loglevel=log.loglevel_DEBUG) @@ -122,10 +122,10 @@ class _SSHServer(paramiko.ServerInterface): """\ Only allow public key authentication. - @param username: username of incoming authentication request - @type username: C{str} - @return: statically returns C{publickey} as auth mechanism - @rtype: C{str} + :param username: username of incoming authentication request + :type username: C{str} + :returns: statically returns C{publickey} as auth mechanism + :rtype: C{str} """ self.logger('sFTP client asked for support auth methods, answering: publickey', loglevel=log.loglevel_DEBUG_SFTPXFER) @@ -142,8 +142,10 @@ class _SFTPHandle(paramiko.SFTPHandle): """\ Create an SFTPAttributes object from an existing stat object (an object returned by os.stat). - @return: new C{SFTPAttributes} object with the same attribute fields. - @rtype: C{obj} + + :returns: new C{SFTPAttributes} object with the same attribute fields. + + :rtype: C{obj} """ try: @@ -190,10 +192,10 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): Enforce the chroot jail. On Windows systems the drive letter is incorporated in the chroot path name (/windrive/<drive_letter>/path/to/file/or/folder). - @param path: path name within chroot - @type path: C{str} - @return: real path name (including drive letter on Windows systems) - @rtype: C{str} + :param path: path name within chroot + :type path: C{str} + :returns: real path name (including drive letter on Windows systems) + :rtype: C{str} """ if defaults.X2GOCLIENT_OS == 'Windows' and path.startswith('/windrive'): @@ -211,10 +213,10 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ List the contents of a folder. - @param path: path to folder - @type path: C{str} - @return: returns the folder contents, on failure returns a Paramiko/SSH return code - @rtype: C{dict} or C{int} + :param path: path to folder + :type path: C{str} + :returns: returns the folder contents, on failure returns a Paramiko/SSH return code + :rtype: C{dict} or C{int} """ path = self._realpath(path) @@ -243,10 +245,10 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Stat on a file. - @param path: path to file/folder - @type path: C{str} - @return: returns the file's stat output, on failure: returns a Paramiko/SSH return code - @rtype: C{class} or C{int} + :param path: path to file/folder + :type path: C{str} + :returns: returns the file's stat output, on failure: returns a Paramiko/SSH return code + :rtype: C{class} or C{int} """ path = self._realpath(path) @@ -261,10 +263,10 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ LStat on a file. - @param path: path to folder - @type path: C{str} - @return: returns the file's lstat output, on failure: returns a Paramiko/SSH return code - @rtype: C{class} or C{int} + :param path: path to folder + :type path: C{str} + :returns: returns the file's lstat output, on failure: returns a Paramiko/SSH return code + :rtype: C{class} or C{int} """ path = self._realpath(path) @@ -279,14 +281,14 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Open a file for reading, writing, appending etc. - @param path: path to file - @type path: C{str} - @param flags: file flags - @type flags: C{str} - @param attr: file attributes - @type attr: C{class} - @return: file handle/object for remote file, on failure: returns a Paramiko/SSH return code - @rtype: L{_SFTPHandle} instance or C{int} + :param path: path to file + :type path: C{str} + :param flags: file flags + :type flags: C{str} + :param attr: file attributes + :type attr: C{class} + :returns: file handle/object for remote file, on failure: returns a Paramiko/SSH return code + :rtype: L{_SFTPHandle} instance or C{int} """ path = self._realpath(path) @@ -335,10 +337,10 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Remove a file. - @param path: path to file - @type path: C{str} - @return: returns Paramiko/SSH return code - @rtype: C{int} + :param path: path to file + :type path: C{str} + :returns: returns Paramiko/SSH return code + :rtype: C{int} """ path = self._realpath(path) @@ -350,12 +352,12 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Rename/move a file. - @param oldpath: old path/location/file name - @type oldpath: C{str} - @param newpath: new path/location/file name - @type newpath: C{str} - @return: returns Paramiko/SSH return code - @rtype: C{int} + :param oldpath: old path/location/file name + :type oldpath: C{str} + :param newpath: new path/location/file name + :type newpath: C{str} + :returns: returns Paramiko/SSH return code + :rtype: C{int} """ self.logger('sFTP server %s: renaming path from %s to %s' % (self, oldpath, newpath), loglevel=log.loglevel_DEBUG_SFTPXFER) @@ -372,12 +374,12 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Make a directory. - @param path: path to new folder - @type path: C{str} - @param attr: file attributes - @type attr: C{class} - @return: returns Paramiko/SSH return code - @rtype: C{int} + :param path: path to new folder + :type path: C{str} + :param attr: file attributes + :type attr: C{class} + :returns: returns Paramiko/SSH return code + :rtype: C{int} """ self.logger('sFTP server: creating new dir (perms: %s): %s' % (attr.st_mode, path), loglevel=log.loglevel_DEBUG_SFTPXFER) @@ -393,10 +395,10 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Remove a directory (if needed recursively). - @param path: folder to be removed - @type path: C{str} - @return: returns Paramiko/SSH return code - @rtype: C{int} + :param path: folder to be removed + :type path: C{str} + :returns: returns Paramiko/SSH return code + :rtype: C{int} """ self.logger('sFTP server %s: removing dir: %s' % (self, path), loglevel=log.loglevel_DEBUG_SFTPXFER) @@ -412,12 +414,12 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Change file attributes. - @param path: path of file/folder - @type path: C{str} - @param attr: new file attributes - @type attr: C{class} - @return: returns Paramiko/SSH return code - @rtype: C{int} + :param path: path of file/folder + :type path: C{str} + :param attr: new file attributes + :type attr: C{class} + :returns: returns Paramiko/SSH return code + :rtype: C{int} """ self.logger('sFTP server %s: modifying attributes of path: %s' % (self, path), loglevel=log.loglevel_DEBUG_SFTPXFER) @@ -436,12 +438,12 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Create a symbolic link. - @param target_path: link shall point to this path - @type target_path: C{str} - @param path: link location - @type path: C{str} - @return: returns Paramiko/SSH return code - @rtype: C{int} + :param target_path: link shall point to this path + :type target_path: C{str} + :param path: link location + :type path: C{str} + :returns: returns Paramiko/SSH return code + :rtype: C{int} """ self.logger('sFTP server %s: creating symlink from: %s to target: %s' % (self, path, target_path), loglevel=log.loglevel_DEBUG_SFTPXFER) @@ -459,10 +461,10 @@ class _SFTPServerInterface(paramiko.SFTPServerInterface): """\ Read the target of a symbolic link. - @param path: path of symbolic link - @type path: C{str} - @return: target location of the symbolic link, on failure: returns a Paramiko/SSH return code - @rtype: C{str} or C{int} + :param path: path of symbolic link + :type path: C{str} + :returns: target location of the symbolic link, on failure: returns a Paramiko/SSH return code + :rtype: C{str} or C{int} """ path = self._realpath(path) @@ -538,16 +540,16 @@ class X2GoRevFwTunnelToSFTP(rforward.X2GoRevFwTunnel): This method gets run once an L{X2GoRevFwTunnelToSFTP} has been started with its L{start()} method. Use L{X2GoRevFwTunnelToSFTP}.stop_thread() to stop the reverse forwarding tunnel again (refer also to its pause() and resume() method). - + L{X2GoRevFwTunnelToSFTP.run()} waits for notifications of an appropriate incoming Paramiko/SSH channel (issued by L{X2GoRevFwTunnelToSFTP.notify()}). Appropriate in this context means, that its starting point on the X2Go server matches the class's property C{server_port}. - + Once a new incoming channel gets announced by the L{notify()} method, a new L{X2GoRevFwSFTPChannelThread} instance will be initialized. As a data stream handler, the function L{x2go_rev_forward_sftpchannel_handler()} will be used. - + The channel will last till the connection gets dropped on the X2Go server side or until the tunnel gets paused by an L{X2GoRevFwTunnelToSFTP.pause()} call or stopped via the C{X2GoRevFwTunnelToSFTP.stop_thread()} method. @@ -588,9 +590,9 @@ class X2GoRevFwTunnelToSFTP(rforward.X2GoRevFwTunnel): def x2go_rev_forward_sftpchannel_handler(chan=None, auth_key=None, logger=None): """\ Handle incoming sFTP channels that got setup by an L{X2GoRevFwTunnelToSFTP} instance. - + The channel (and the corresponding connections) close either ... - + - ... if the connecting application closes the connection and thus, drops the sFTP channel, or - ... if the L{X2GoRevFwTunnelToSFTP} parent thread gets paused. The call @@ -598,13 +600,13 @@ def x2go_rev_forward_sftpchannel_handler(chan=None, auth_key=None, logger=None): tunneled SSH connections associated to this L{X2GoRevFwTunnelToSFTP} instance from within a Python X2Go application. - @param chan: an incoming sFTP channel (Default value = None) - @type chan: paramiko.Channel instance - @param auth_key: Paramiko/SSH RSAkey object that has to be authenticated against by + :param chan: an incoming sFTP channel (Default value = None) + :type chan: paramiko.Channel instance + :param auth_key: Paramiko/SSH RSAkey object that has to be authenticated against by the remote sFTP client (Default value = None) - @type auth_key: C{paramiko.RSAKey} instance - @param logger: you must pass an L{X2GoLogger} object to this handler method (Default value = None) - @type logger: C{X2GoLogger} instance + :type auth_key: C{paramiko.RSAKey} instance + :param logger: you must pass an L{X2GoLogger} object to this handler method (Default value = None) + :type logger: C{X2GoLogger} instance """ if logger is None: diff --git a/x2go/sshproxy.py b/x2go/sshproxy.py index 421e0f3..23162ed 100644 --- a/x2go/sshproxy.py +++ b/x2go/sshproxy.py @@ -412,7 +412,7 @@ class X2GoSSHProxy(paramiko.SSHClient, threading.Thread): Start the SSH proxying tunnel... - @raise X2GoSSHProxyException: if the SSH proxy could not retrieve an SSH transport for proxying a X2Go server-client connection + :raises X2GoSSHProxyException: if the SSH proxy could not retrieve an SSH transport for proxying a X2Go server-client connection """ if self.get_transport() is not None and self.get_transport().is_authenticated(): @@ -437,9 +437,9 @@ class X2GoSSHProxy(paramiko.SSHClient, threading.Thread): Retrieve the local IP socket address this SSH proxying tunnel is (about to) bind/bound to. - @return: local IP socket address + :returns: local IP socket address - @rtype: C{str} + :rtype: C{str} """ return self.local_host @@ -449,9 +449,9 @@ class X2GoSSHProxy(paramiko.SSHClient, threading.Thread): Retrieve the local IP socket port this SSH proxying tunnel is (about to) bind/bound to. - @return: local IP socket port + :returns: local IP socket port - @rtype: C{int} + :rtype: C{int} """ return self.local_port @@ -461,9 +461,9 @@ class X2GoSSHProxy(paramiko.SSHClient, threading.Thread): Retrieve the remote IP socket address at the remote end of the SSH proxying tunnel. - @return: remote IP socket address + :returns: remote IP socket address - @rtype: C{str} + :rtype: C{str} """ return self.remote_host @@ -473,9 +473,9 @@ class X2GoSSHProxy(paramiko.SSHClient, threading.Thread): Retrieve the remote IP socket port of the target system's SSH daemon. - @return: remote SSH port + :returns: remote SSH port - @rtype: C{int} + :rtype: C{int} """ return self.remote_port diff --git a/x2go/telekinesis.py b/x2go/telekinesis.py index cc0c326..268a67e 100644 --- a/x2go/telekinesis.py +++ b/x2go/telekinesis.py @@ -54,7 +54,7 @@ from x2go.defaults import CURRENT_LOCAL_USER as _CURRENT_LOCAL_USER class X2GoTelekinesisClient(threading.Thread): """\ Telekinesis is a communication framework used by X2Go. - + This class implements the startup of the telekinesis client used by Python X2Go. @@ -143,9 +143,9 @@ class X2GoTelekinesisClient(threading.Thread): Test if the Telekinesis client command is installed on this machine. - @return: C{True} if the Telekinesis client command is available + :returns: C{True} if the Telekinesis client command is available - @rtype: C{bool} + :rtype: C{bool} """ ### @@ -301,9 +301,9 @@ class X2GoTelekinesisClient(threading.Thread): Start the thread runner and wait for the Telekinesis client to come up. - @return: a subprocess instance that knows about the externally started Telekinesis client command. + :returns: a subprocess instance that knows about the externally started Telekinesis client command. - @rtype: C{obj} + :rtype: C{obj} """ self.logger('starting local Telekinesis client...', loglevel=log.loglevel_INFO) @@ -414,9 +414,9 @@ class X2GoTelekinesisClient(threading.Thread): Check if a proxy instance is up and running. - @return: Proxy state, C{True} for proxy being up-and-running, C{False} otherwise + :returns: Proxy state, C{True} for proxy being up-and-running, C{False} otherwise - @rtype: C{bool} + :rtype: C{bool} """ return bool(self.tekiclient and self.tekiclient.poll() is None) and self.fw_ctrl_tunnel.is_active and self.fw_data_tunnel.is_active diff --git a/x2go/tests/test_printing.py b/x2go/tests/test_printing.py index a46646d..9b0b124 100644 --- a/x2go/tests/test_printing.py +++ b/x2go/tests/test_printing.py @@ -29,18 +29,19 @@ import x2go class TestX2GoClientPrinting(unittest.TestCase): def test_client_printing_dialog(self): - """_printing = """\ - [General] - pdfview=true - showdialog=true - [print] - startcmd=false - command=lpr - [view] - open=true - command=xpdf - [CUPS] - defaultprinter=PDF + _printing = """\ +[General] +pdfview=true +showdialog=true +[print] +startcmd=false +command=lpr +[view] +open=true +command=xpdf +[CUPS] +defaultprinter=PDF +""" tf = tempfile.NamedTemporaryFile() print(_printing, file=tf) tf.seek(0) @@ -49,17 +50,18 @@ class TestX2GoClientPrinting(unittest.TestCase): tf.close() def test_client_printing_pdfview(self): - """_printing = """\ - [General] - pdfview=true - [print] - startcmd=false - command=lpr - [view] - open=true - command=xpdf - [CUPS] - defaultprinter=PDF + _printing = """\ +[General] +pdfview=true +[print] +startcmd=false +command=lpr +[view] +open=true +command=xpdf +[CUPS] +defaultprinter=PDF +""" tf = tempfile.NamedTemporaryFile() print(_printing, file=tf) tf.seek(0) @@ -68,17 +70,18 @@ class TestX2GoClientPrinting(unittest.TestCase): tf.close() def test_client_printing_pdfsave(self): - """_printing = """\ - [General] - pdfview=true - [print] - startcmd=false - command=lpr - [view] - open=false - command=xpdf - [CUPS] - defaultprinter=PDF + _printing = """\ +[General] +pdfview=true +[print] +startcmd=false +command=lpr +[view] +open=false +command=xpdf +[CUPS] +defaultprinter=PDF +""" tf = tempfile.NamedTemporaryFile() print(_printing, file=tf) tf.seek(0) @@ -87,17 +90,18 @@ class TestX2GoClientPrinting(unittest.TestCase): tf.close() def test_client_printing_print(self): - """_printing = """\ - [General] - pdfview=false - [print] - startcmd=false - command=lpr - [view] - open=false - command=xpdf - [CUPS] - defaultprinter=PDF + _printing = """\ +[General] +pdfview=false +[print] +startcmd=false +command=lpr +[view] +open=false +command=xpdf +[CUPS] +defaultprinter=PDF +""" tf = tempfile.NamedTemporaryFile() print(_printing, file=tf) tf.seek(0) @@ -106,17 +110,18 @@ class TestX2GoClientPrinting(unittest.TestCase): tf.close() def test_client_printing_printcmd(self): - """_printing = """\ - [General] - pdfview=false - [print] - startcmd=true - command=lpr - [view] - open=false - command=xpdf - [CUPS] - defaultprinter=PDF + _printing = """\ +[General] +pdfview=false +[print] +startcmd=true +command=lpr +[view] +open=false +command=xpdf +[CUPS] +defaultprinter=PDF +""" tf = tempfile.NamedTemporaryFile() print(_printing, file=tf) tf.seek(0) diff --git a/x2go/utils.py b/x2go/utils.py index 79005bb..5d17f43 100644 --- a/x2go/utils.py +++ b/x2go/utils.py @@ -66,10 +66,10 @@ def is_in_nx3packmethods(method): """\ Test if a given compression method is valid for NX3 Proxy. - @param method: name of an NXv3 pack method - @type method: C{str} - @return: C{True} if C{method} is in the hard-coded list of NX3 compression methods. - @rtype: C{bool} + :param method: name of an NXv3 pack method + :type method: C{str} + :returns: C{True} if C{method} is in the hard-coded list of NX3 compression methods. + :rtype: C{bool} """ return method in pack_methods_nx3 @@ -80,12 +80,12 @@ def find_session_line_in_x2golistsessions(session_name, stdout): Return the X2Go session meta information as returned by the C{x2golistsessions} server command for session C{session_name}. - @param session_name: name of a session - @type session_name: C{str} - @param stdout: raw output from the ,,x2golistsessions'' command, as list of strings - @type stdout: C{list} - @return: the output line that contains C{<session_name>} - @rtype: C{str} or C{None} + :param session_name: name of a session + :type session_name: C{str} + :param stdout: raw output from the ,,x2golistsessions'' command, as list of strings + :type stdout: C{list} + :returns: the output line that contains C{<session_name>} + :rtype: C{str} or C{None} """ sessions = stdout.read().split("\n") @@ -103,10 +103,10 @@ def slugify(value): Normalizes string, converts to lowercase, removes non-alpha characters, converts spaces to hyphens and replaces round brackets by pointed brackets. - @param value: a string that shall be sluggified - @type value: C{str} - @return: the sluggified string - @rtype: C{str} + :param value: a string that shall be sluggified + :type value: C{str} + :returns: the sluggified string + :rtype: C{str} """ import unicodedata @@ -121,9 +121,9 @@ def _genSessionProfileId(): Generate a session profile ID as used in x2goclient's sessions config file. - @return: profile ID + :returns: profile ID - @rtype: C{str} + :rtype: C{str} """ import datetime @@ -134,10 +134,10 @@ def _checkIniFileDefaults(data_structure): """\ Check an ini file data structure passed on by a user app or class. - @param data_structure: an ini file date structure - @type data_structure: C{dict} of C{dict}s - @return: C{True} if C{data_structure} matches that of an ini file data structure - @rtype: C{bool} + :param data_structure: an ini file date structure + :type data_structure: C{dict} of C{dict}s + :returns: C{True} if C{data_structure} matches that of an ini file data structure + :rtype: C{bool} """ if data_structure is None: @@ -154,10 +154,10 @@ def _checkSessionProfileDefaults(data_structure): """\ Check the data structure of a default session profile passed by a user app. - @param data_structure: an ini file date structure - @type data_structure: C{dict} of C{dict}s - @return: C{True} if C{data_structure} matches that of an ini file data structure - @rtype: C{bool} + :param data_structure: an ini file date structure + :type data_structure: C{dict} of C{dict}s + :returns: C{True} if C{data_structure} matches that of an ini file data structure + :rtype: C{bool} """ if data_structure is None: @@ -172,10 +172,10 @@ def _convert_SessionProfileOptions_2_SessionParams(options): Convert session profile options as used in x2goclient's sessions file to Python X2Go session parameters. - @param options: a dictionary of options, parameter names as in the X2Go ,,sessions'' file - @type options: C{dict} - @return: session options as used in C{X2GoSession} instances - @rtype: C{dict} + :param options: a dictionary of options, parameter names as in the X2Go ,,sessions'' file + :type options: C{dict} + :returns: session options as used in C{X2GoSession} instances + :rtype: C{dict} """ _params = copy.deepcopy(options) @@ -385,10 +385,10 @@ def session_names_by_timestamp(session_infos): """\ Sorts session profile names by their timestamp (as used in the file format's section name). - @param session_infos: a dictionary of session infos as reported by L{X2GoClient.list_sessions()} - @type session_infos: C{dict} - @return: a timestamp-sorted list of session names found in C{session_infos} - @rtype: C{list} + :param session_infos: a dictionary of session infos as reported by L{X2GoClient.list_sessions()} + :type session_infos: C{dict} + :returns: a timestamp-sorted list of session names found in C{session_infos} + :rtype: C{list} """ session_names = list(session_infos.keys()) @@ -401,10 +401,10 @@ def touch_file(filename, mode='a'): """\ Imitates the behaviour of the GNU/touch command. - @param filename: name of the file to touch - @type filename: C{str} - @param mode: the file mode (as used for Python file objects) (Default value = 'a') - @type mode: C{str} + :param filename: name of the file to touch + :type filename: C{str} + :param mode: the file mode (as used for Python file objects) (Default value = 'a') + :type mode: C{str} """ if not os.path.isdir(os.path.dirname(filename)): @@ -417,10 +417,10 @@ def unique(seq): """\ Imitates the behaviour of the GNU/uniq command. - @param seq: a list/sequence containing consecutive duplicates. - @type seq: C{list} - @return: list that has been clean up from the consecutive duplicates - @rtype: C{list} + :param seq: a list/sequence containing consecutive duplicates. + :type seq: C{list} + :returns: list that has been clean up from the consecutive duplicates + :rtype: C{list} """ # order preserving @@ -455,10 +455,10 @@ def patiently_remove_file(dirname, filename): """\ Try to remove a file, wait for unlocking, remove it once removing is possible... - @param dirname: directory name the file is in - @type dirname: C{str} - @param filename: name of the file to be removed - @type filename: C{str} + :param dirname: directory name the file is in + :type dirname: C{str} + :param filename: name of the file to be removed + :type filename: C{str} """ _not_removed = True @@ -475,12 +475,12 @@ def detect_unused_port(bind_address='127.0.0.1', preferred_port=None): """\ Detect an unused IP socket. - @param bind_address: IP address to bind to (Default value = '127.0.0.1') - @type bind_address: C{str} - @param preferred_port: IP socket port that shall be tried first for availability (Default value = None) - @type preferred_port: C{str} - @return: free local IP socket port that can be used for binding - @rtype: C{str} + :param bind_address: IP address to bind to (Default value = '127.0.0.1') + :type bind_address: C{str} + :param preferred_port: IP socket port that shall be tried first for availability (Default value = None) + :type preferred_port: C{str} + :returns: free local IP socket port that can be used for binding + :rtype: C{str} """ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) @@ -501,9 +501,9 @@ def get_encoding(): Detect systems default character encoding. - @return: The system's local character encoding. + :returns: The system's local character encoding. - @rtype: C{str} + :rtype: C{str} """ try: @@ -522,10 +522,10 @@ def is_abs_path(path): """\ Test if a given path is an absolute path name. - @param path: test this path for absolutism... - @type path: C{str} - @return: Returns C{True} if path is an absolute path name - @rtype: C{bool} + :param path: test this path for absolutism... + :type path: C{str} + :returns: Returns C{True} if path is an absolute path name + :rtype: C{bool} """ return bool((path.startswith('/') or re.match('^[%s]\:\\\\' % string.ascii_letters, path))) @@ -536,9 +536,9 @@ def xkb_rules_names(): Wrapper for: xprop -root _XKB_RULES_NAMES - @return: A Python dictionary that contains the current X11 keyboard rules. + :returns: A Python dictionary that contains the current X11 keyboard rules. - @rtype: C{dict} + :rtype: C{dict} """ p = subprocess.Popen(['xprop', '-root', '_XKB_RULES_NAMES',], stdout=subprocess.PIPE, ) @@ -557,9 +557,9 @@ def local_color_depth(): Detect the current local screen's color depth. - @return: the local color depth in bits + :returns: the local color depth in bits - @rtype: C{int} + :rtype: C{int} """ if _X2GOCLIENT_OS != 'Windows': @@ -587,12 +587,12 @@ def is_color_depth_ok(depth_session, depth_local): Test if color depth of this session is compatible with the local screen's color depth. - @param depth_session: color depth of the session - @type depth_session: C{int} - @param depth_local: color depth of local screen - @type depth_local: C{int} - @return: Does the session color depth work with the local display? - @rtype: C{bool} + :param depth_session: color depth of the session + :type depth_session: C{int} + :param depth_local: color depth of local screen + :type depth_local: C{int} + :returns: Does the session color depth work with the local display? + :rtype: C{bool} """ if depth_session == 0: @@ -610,10 +610,10 @@ def find_session_window(session_name): """\ Find a session window by its X2GO session ID. - @param session_name: session name/ID of an X2Go session window - @type session_name: C{str} - @return: the window object (or ID) of the searched for session window - @rtype: C{obj} on Unix, C{int} on Windows + :param session_name: session name/ID of an X2Go session window + :type session_name: C{str} + :returns: the window object (or ID) of the searched for session window + :rtype: C{obj} on Unix, C{int} on Windows """ if _X2GOCLIENT_OS != 'Windows': @@ -665,9 +665,9 @@ def get_desktop_geometry(): Get the geometry of the current screen's desktop. - @return: a (<width>, <height>) tuple will be returned + :returns: a (<width>, <height>) tuple will be returned - @rtype: C{tuple} + :rtype: C{tuple} """ if _X2GOCLIENT_OS != 'Windows': @@ -682,13 +682,13 @@ def get_workarea_geometry(): """\ Get the geometry of the current screen's work area by wrapping around:: - + xprop -root '_NET_WORKAREA' - @return: a (<width>, <height>) tuple will be returned + :returns: a (<width>, <height>) tuple will be returned - @rtype: C{tuple} + :rtype: C{tuple} """ if _X2GOCLIENT_OS != 'Windows': @@ -707,10 +707,10 @@ def set_session_window_title(session_window, session_title): """\ Set title of session window. - @param session_window: session window instance - @type session_window: C{obj} - @param session_title: session title to be set for C{session_window} - @type session_title: C{str} + :param session_window: session window instance + :type session_window: C{obj} + :param session_title: session title to be set for C{session_window} + :type session_title: C{str} """ if _X2GOCLIENT_OS != 'Windows': @@ -729,8 +729,8 @@ def raise_session_window(session_window): """\ Raise session window. Not functional for Unix-like operating systems. - @param session_window: session window instance - @type session_window: C{obj} + :param session_window: session window instance + :type session_window: C{obj} """ if _X2GOCLIENT_OS != 'Windows': @@ -744,12 +744,12 @@ def merge_ordered_lists(l1, l2): """\ Merge sort two sorted lists - @param l1: first sorted list - @type l1: C{list} - @param l2: second sorted list - @type l2: C{list} - @return: the merge result of both sorted lists - @rtype: C{list} + :param l1: first sorted list + :type l1: C{list} + :param l2: second sorted list + :type l2: C{list} + :returns: the merge result of both sorted lists + :rtype: C{list} """ ordered_list = [] @@ -781,12 +781,12 @@ def compare_versions(version_a, op, version_b): In the background C{distutils.version.LooseVersion} is used for the comparison operation. - @param version_a: a version string - @type version_a: C{str} - @param op: an operator provide as string (e.g. '<', '>', '==', '>=' etc.) - @type op: C{str} - @param version_b: another version string that is to be compared with <version_a> - @type version_b: C{str} + :param version_a: a version string + :type version_a: C{str} + :param op: an operator provide as string (e.g. '<', '>', '==', '>=' etc.) + :type op: C{str} + :param version_b: another version string that is to be compared with <version_a> + :type version_b: C{str} """ @@ -859,12 +859,12 @@ def genkeypair(local_username, client_address, key_type='RSA'): """\ Generate an SSH pub/priv key pair without writing the private key to file. - @param local_username: the key is for this user - @type local_username: C{unicode} - @param client_address: the key is only valid for this client - @type client_address: C{unicode} - @param key_type: either of: RSA, DSA (Default value = 'RSA') - @type key_type: C{unicode} + :param local_username: the key is for this user + :type local_username: C{unicode} + :param client_address: the key is only valid for this client + :type client_address: C{unicode} + :param key_type: either of: RSA, DSA (Default value = 'RSA') + :type key_type: C{unicode} """ key = None @@ -895,10 +895,10 @@ def which(basename): """\ Python equivalent to the shell command "which". - @param basename: the basename of an application to be search for in $PATH - @type basename: C{str} - @return: full path to the application - @rtype: C{str} + :param basename: the basename of an application to be search for in $PATH + :type basename: C{str} + :returns: full path to the application + :rtype: C{str} """ if _X2GOCLIENT_OS == 'Windows': diff --git a/x2go/xserver.py b/x2go/xserver.py index 1ecf022..33e3970 100644 --- a/x2go/xserver.py +++ b/x2go/xserver.py @@ -50,7 +50,7 @@ from . import utils class X2GoClientXConfig(inifiles.X2GoIniFile): """\ Configuration file based XServer startup settings for X2GoClient instances. - + This class is needed for Windows systems and (maybe soon) for Unix desktops using Wayland. @@ -99,13 +99,14 @@ class X2GoClientXConfig(inifiles.X2GoIniFile): def write(self): """\ Store the Xserver configuration to the storage backend (i.e. on disk). - + For writing the first of the C{config_files} specified on instance construction that is writable will be used. - @return: C{True} if the user config file has been successfully written, C{False} otherwise. - @rtype: C{bool} + :returns: C{True} if the user config file has been successfully written, C{False} otherwise. + + :rtype: C{bool} """ self._write_user_config = self.write_user_config @@ -115,10 +116,10 @@ class X2GoClientXConfig(inifiles.X2GoIniFile): """\ Retrieve the XServer configuration (from the xconfig file) for the given XServer application. - @param xserver_name: name of the XServer application - @type xserver_name: C{str} - @return: A Python dictionary containing the XServer's configuration settings - @rtype: C{list} + :param xserver_name: name of the XServer application + :type xserver_name: C{str} + :returns: A Python dictionary containing the XServer's configuration settings + :rtype: C{list} """ _xserver_config = {} @@ -198,8 +199,10 @@ class X2GoClientXConfig(inifiles.X2GoIniFile): """\ Returns a tuple of (<xserver_name>, <xserver_config>). - @return: (<xserver_name>, <xserver_config>) - @rtype: C{tuple} + + :returns: xserver_name>, <xserver_config>) + + :rtype: C{tuple} """ if self.xserver_launch_possible: @@ -221,8 +224,8 @@ class X2GoClientXConfig(inifiles.X2GoIniFile): Get an unused TCP/IP port for the to-be-launched X server and write it to the user's X configuration file. - @param xserver_name: name of the XServer application - @type xserver_name: C{str} + :param xserver_name: name of the XServer application + :type xserver_name: C{str} """ _default_display = self.get_xserver_config(xserver_name)['display'] @@ -271,7 +274,7 @@ class X2GoClientXConfig(inifiles.X2GoIniFile): class X2GoXServer(threading.Thread): """\ This class is responsible for starting/stopping an external XServer application. - + X2Go applications require a running XServer on the client system. This class will manage/handle the XServer while your X2Go application is running. -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/python-x2go.git