[X2Go-Commits] python-x2go.git - build-baikal (branch) updated: 0.0.44.2-41-g23b3853
X2Go dev team
git-admin at x2go.org
Wed Jan 8 15:30:27 CET 2014
The branch, build-baikal has been updated
via 23b38533e89e80dc69d2ba5a100fc1b5f91944dc (commit)
from 8f96ae78ee15292f4984e384b0f9e9d21b63501e (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
-----------------------------------------------------------------------
Summary of changes:
x2go/session.py | 316 +++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 259 insertions(+), 57 deletions(-)
The diff of changes is:
diff --git a/x2go/session.py b/x2go/session.py
index 47dffca..b00a17b 100644
--- a/x2go/session.py
+++ b/x2go/session.py
@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
# Copyright (C) 2010-2011 by Mike Gabriel <mike.gabriel at das-netzwerkteam.de>
#
@@ -17,7 +18,13 @@
# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
"""\
-X2goSession class - the X2goClient's session backend
+X2goSession class - a public API of Python X2go, handling standalone X2go
+sessions.
+
+This class is normally embedded into the context of an L{X2goClient}
+instance, but it is also possible to address L{X2goSession}s directly via this
+class.
+
"""
__NAME__ = 'x2gosession-pylib'
@@ -64,13 +71,24 @@ _X2GO_SESSION_PARAMS = ('geometry', 'depth', 'link', 'pack',
'control_backend', 'terminal_backend', 'proxy_backend',
'profiles_backend', 'settings_backend', 'printing_backend',
)
+"""A list of allowed X2go session parameters."""
_X2GO_SSHPROXY_PARAMS = ('sshproxy_host', 'sshproxy_user', 'sshproxy_password',
'sshproxy_key_filename', 'sshproxy_tunnel',
)
+"""A list of allowed X2go SSH proxy parameters."""
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.).
+ """
def __init__(self, server=None, control_session=None,
use_sshproxy=False,
profile_id=None, profile_name='UNKNOWN',
@@ -91,14 +109,78 @@ class X2goSession(object):
client_rootdir=os.path.join(_LOCAL_HOME, _X2GO_CLIENT_ROOTDIR),
sessions_rootdir=os.path.join(_LOCAL_HOME, _X2GO_SESSIONS_ROOTDIR),
ssh_rootdir=os.path.join(_LOCAL_HOME, _X2GO_SSH_ROOTDIR),
+ keep_controlsession_alive=False,
add_to_known_hosts=False,
known_hosts=None,
- keep_controlsession_alive=False,
logger=None, loglevel=log.loglevel_DEFAULT,
virgin=True, running=None, suspended=None, terminated=None,
client_instance=None,
**params):
+ """\
+ @param server: hostname of X2go server
+ @type server: C{str}
+ @param control_session: an already initialized C{X2goControlSession*} instance
+ @type control_session: C{X2goControlSession*} instance
+ @param use_sshproxy: for communication with X2go server use an SSH proxy host
+ @type use_sshproxy: C{bool}
+ @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)
+ @type session_name: C{str}
+ @param printing: enable X2go printing
+ @type printing: C{bool}
+ @param allow_mimebox: enable X2go MIME box support
+ @type allow_mimebox: C{bool}
+ @param mimebox_extensions: whitelist of allowed X2go MIME box extensions
+ @type mimebox_extensions: C{list}
+ @param mimebox_action: action for incoming X2go MIME box files
+ @type mimebox_action: C{X2goMimeBoxAction*} or C{str}
+ @param allow_share_local_folders: enable local folder sharing support
+ @type allow_share_local_folders: C{bool}
+ @param share_local_folders: list of local folders to share with the remote X2go session
+ @type share_local_folders: C{list}
+ @param control_backend: X2go control session backend to use
+ @type control_backend: C{class}
+ @param terminal_backend: X2go terminal session backend to use
+ @type terminal_backend: C{class}
+ @param info_backend: X2go session info backend to use
+ @type info_backend: C{class}
+ @param list_backend: X2go session list backend to use
+ @type list_backend: C{class}
+ @param proxy_backend: X2go proxy backend to use
+ @type proxy_backend: C{class}
+ @param settings_backend: X2go client settings backend to use
+ @type settings_backend: C{class}
+ @param printing_backend: X2go client printing backend to use
+ @type printing_backend: C{class}
+ @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 virgin: manipulate session state »virgin« by giving a pre-set value
+ @type virgin: C{bool}
+ @param running: manipulate session state »running« by giving a pre-set value
+ @type running: C{bool}
+ @param suspended: manipulate session state »suspended« by giving a pre-set value
+ @type suspended: C{bool}
+ @param terminated: manipulate session state »terminated« by giving a pre-set value
+ @type terminated: C{bool}
+ @param client_instance: if available, the underlying L{X2goClient} instance
+ @type client_instance: C{X2goClient} instance
+ @param params: further control session, terminal session and SSH proxy class options
+ @type params: C{dict}
+ """
if logger is None:
self.logger = log.X2goLogger(loglevel=loglevel)
else:
@@ -182,7 +264,10 @@ class X2goSession(object):
def HOOK_rforward_request_denied(self, server_port=0):
"""\
- STILL UNDOCUMENTED
+ HOOK method: called if a reverse port forwarding request has been denied.
+
+ @param server_port: remote server port (starting point of reverse forwarding tunnel)
+ @type server_port: C{str}
"""
if self.client_instance:
@@ -192,7 +277,12 @@ class X2goSession(object):
def HOOK_forwarding_tunnel_setup_failed(self, chain_host='UNKNOWN', chain_port=0):
"""\
- STILL UNDOCUMENTED
+ HOOK method: called if a port forwarding tunnel setup failed.
+
+ @param chain_host: hostname of chain host (forwarding tunnel end point)
+ @type chain_host: C{str}
+ @param chain_port: port of chain host (forwarding tunnel end point)
+ @type chain_port: C{str}
"""
if self.client_instance:
@@ -202,7 +292,18 @@ class X2goSession(object):
def HOOK_check_host_dialog(self, host, port, fingerprint='no fingerprint', fingerprint_type='RSA'):
"""\
- STILL UNDOCUMENTED
+ 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
+ @type fingerprint: C{str}
+ @param fingerprint_type: finger print type (like RSA, DSA, ...)
+ @type fingerprint_type: C{str}
+ @return: if host validity is verified, this hook method should return C{True}
+ @rtype: C{bool}
"""
if self.client_instance:
@@ -213,7 +314,7 @@ class X2goSession(object):
def init_control_session(self):
"""\
- STILL UNDOCUMENTED
+ Initialize a new control session (C{X2goControlSession*}).
"""
if self.control_session is None:
@@ -231,9 +332,23 @@ class X2goSession(object):
logger=self.logger)
def set_server(self, server):
+ """\
+ Modify server name after L{X2goSession} has already been initialized.
+
+ @param server: new server name
+ @type server: C{str}
+
+ """
self.server = server
def set_profile_name(self, profile_name):
+ """\
+ Modify session profile name after L{X2goSession} has already been initialized.
+
+ @param profile_name: new session profile name
+ @type profile_name: C{str}
+
+ """
self.profile_name = profile_name
self.control_session.set_profile_name(profile_name)
@@ -251,7 +366,10 @@ class X2goSession(object):
return self.__get_uuid()
def __del__(self):
+ """\
+ Class destructor.
+ """
if self.has_control_session() and self.has_terminal_session():
self.get_control_session().dissociate(self.get_terminal_session())
@@ -286,10 +404,13 @@ class X2goSession(object):
def update_params(self, params):
"""\
- STILL UNDOCUMENTED
+ This method can be used to modify L{X2goSession} parameters after the
+ L{X2goSession} instance has already been initialized.
- """
+ @params: a Python dictionary with L{X2goSession} parameters
+ @type: C{dict}
+ """
try: del params['server']
except KeyError: pass
try: del params['profile_name']
@@ -345,7 +466,7 @@ class X2goSession(object):
def get_uuid(self):
"""\
- STILL UNDOCUMENTED
+ Retrieve session UUID hash for this L{X2goSession}.
"""
return str(self.uuid)
@@ -353,7 +474,7 @@ class X2goSession(object):
def get_username(self):
"""\
- After a session has been setup up you can query the
+ After a session has been set up you can query the
username the sessions runs as.
@return: the remote username the X2go session runs as
@@ -369,6 +490,15 @@ class X2goSession(object):
def user_is_x2gouser(self, username=None):
+ """\
+ Check if a given user is valid server-side X2go user.
+
+ @param username: username to check validity for
+ @type username: C{str}
+ @return: return C{True} if the username is allowed to launch X2go sessions
+ @rtype: C{bool}
+
+ """
if username is None:
username = self.__get_username()
return self.control_session.is_x2gouser(username)
@@ -389,7 +519,7 @@ class X2goSession(object):
def get_server_peername(self):
"""\
After a session has been setup up you can query the
- hostname of the host the sessions is connected to (or
+ peername of the host this session is connected to (or
about to connect to).
@return: the address of the server the X2go session is
@@ -402,8 +532,12 @@ class X2goSession(object):
def get_server_hostname(self):
"""\
+ After a session has been setup up you can query the
+ hostname of the host this session is connected to (or
+ about to connect to).
+
@return: the hostname of the server the X2go session is
- connected to
+ connected to / about to connect to
@rtype: C{str}
"""
@@ -413,8 +547,11 @@ class X2goSession(object):
def get_server_port(self):
"""\
- @return: the server-side TCP port that is used by the X2go session to
- connect the session
+ After a session has been setup up you can query the
+ 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
+ connect to the server
@rtype: C{str}
"""
@@ -423,8 +560,7 @@ class X2goSession(object):
def get_session_name(self):
"""\
- Retrieve the server-side X2go session name for the session that has
- been registered under C{profile_id}.
+ Retrieve the server-side X2go session name for this session.
@return: X2go session name
@rtype: C{str}
@@ -435,7 +571,11 @@ class X2goSession(object):
def get_session_cmd(self):
"""\
- STILL UNDOCUMENTED
+ Retrieve the server-side command that is used to start a session
+ on the remote X2go server.
+
+ @return: server-side session command
+ @rtype: C{str}
"""
if self.terminal_params.has_key('cmd'):
@@ -445,15 +585,20 @@ class X2goSession(object):
def get_control_session(self):
"""\
- STILL UNDOCUMENTED
+ Retrieve the control session (C{X2goControlSession*} backend) of this L{X2goSession}.
+ @return: the L{X2goSession}'s control session
+ @rtype: C{X2goControlSession*} instance
"""
return self.control_session
__get_control_session = get_control_session
def has_control_session(self):
"""\
- STILL UNDOCUMENTED
+ 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}
"""
return self.control_session is not None
@@ -461,7 +606,10 @@ class X2goSession(object):
def get_terminal_session(self):
"""\
- STILL UNDOCUMENTED
+ Retrieve the terminal session (C{X2goTerminalSession*} backend) of this L{X2goSession}.
+
+ @return: the L{X2goSession}'s terminal session
+ @rtype: C{X2goControlTerminal*} instance
"""
return self.terminal_session
@@ -469,7 +617,11 @@ class X2goSession(object):
def has_terminal_session(self):
"""\
- STILL UNDOCUMENTED
+ 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}
+
"""
return self.terminal_session is not None
@@ -477,7 +629,12 @@ class X2goSession(object):
def check_host(self):
"""\
- Provide a host check mechanism.
+ Provide a host check mechanism. This method basically calls the L{HOOK_check_host_dialog()} method
+ which by itself calls the L{X2goClient.HOOK_check_host_dialog()} method. Make sure you
+ 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}
"""
if self.connected:
@@ -491,9 +648,8 @@ class X2goSession(object):
def connect(self, username='', password='', add_to_known_hosts=False, force_password_auth=False,
use_sshproxy=False, sshproxy_user='', sshproxy_password=''):
"""\
- Connect to a registered X2go session with registry hash C{<session_uuid>}.
- This method basically wraps around paramiko.SSHClient.connect() for the
- corresponding session.
+ 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
connected to (as a last minute way of changing the session username)
@@ -508,6 +664,15 @@ class X2goSession(object):
@param force_password_auth: disable SSH pub/priv key authentication mechanisms
completely
@type force_password_auth: C{bool}
+ @param use_sshproxy: use an SSH proxy host for connecting the target X2go server
+ @type use_sshproxy: C{bool}
+ @param sshproxy_user: username for authentication against the SSH proxy host
+ @type sshproxy_user: C{str}
+ @param sshproxy_password: password for authentication against the SSH proxy host
+ @type sshproxy_password: C{str}
+
+ @return: returns C{True} is the connection to the X2go server has been successful
+ @rtype C{bool}
"""
if self.control_session and self.control_session.is_connected():
@@ -553,7 +718,10 @@ class X2goSession(object):
def disconnect(self):
"""\
- STILL UNDOCUMENTED
+ Disconnect this L{X2goSession} instance.
+
+ @return: returns C{True} if the disconnect operation has been successful
+ @rtype: C{bool}
"""
self.connected = False
@@ -570,7 +738,18 @@ class X2goSession(object):
def set_print_action(self, print_action, **kwargs):
"""\
- STILL UNDOCUMENTED
+ 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
+ action arguments), for possible print action arguments and their values see each individual
+ print action class
+ @type kwargs: C{dict}
"""
if type(print_action) is not types.StringType:
@@ -580,7 +759,10 @@ class X2goSession(object):
def is_alive(self):
"""\
- STILL UNDOCUMENTED
+ 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}
"""
self.connected = self.control_session.is_alive()
@@ -591,7 +773,7 @@ class X2goSession(object):
def clean_sessions(self):
"""\
- STILL UNDOCUMENTED
+ Clean all running sessions for the authenticated user on the remote X2go server.
"""
if self.is_alive():
@@ -602,7 +784,14 @@ class X2goSession(object):
def list_sessions(self, raw=False):
"""\
- STILL UNDOCUMENTED
+ 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
+ the output of the server-side C{x2golistsessions} command
+ @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}
"""
try:
@@ -614,7 +803,21 @@ class X2goSession(object):
def update_status(self, session_list=None):
"""\
- STILL UNDOCUMENTED
+ 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.
+ This option is mainly for reducing server/client traffic.
+ @type session_list: C{X2goServerSessionList*} instance
"""
if self._last_status is not None:
@@ -676,6 +879,9 @@ class X2goSession(object):
@param session_name: the server-side name of an X2go session
@type session_name: C{str}
+ @return: returns C{True} if resuming the session has been successful, C{False} otherwise
+ @rtype: C{bool}
+
"""
_new_session = False
if self.session_name is None:
@@ -732,27 +938,27 @@ class X2goSession(object):
return self.running
else:
self._X2goSession__disconnect()
+ return False
__resume = resume
def start(self):
"""\
Start a new X2go session on the remote X2go server.
+ @return: returns C{True} if starting the session has been successful, C{False} otherwise
+ @rtype: C{bool}
+
"""
self.session_name = None
- self.resume()
+ return self.resume()
__start = start
def suspend(self):
"""\
- Suspend an X2go session.
-
- You can either suspend a session that you have formerly
- started/resumed the current X2goClient instance.
+ Suspend this X2go session.
- Or you can suspend a non-attached session by simply
- registering an X2go server session and then passing the
- server-side X2go session name to this method.
+ @return: returns C{True} if suspending the session has been successful, C{False} otherwise
+ @rtype: C{bool}
"""
if self.is_alive():
@@ -785,14 +991,10 @@ class X2goSession(object):
def terminate(self):
"""\
- Terminate an X2go session.
-
- You can either terminate a session that you have formerly
- started/resumed within the current X2goClient instance.
+ Terminate this X2go session.
- Or you can terminate a non-attached session by simply
- registering an X2go server session and then passing the
- server-side X2go session name to this method.
+ @return: returns C{True} if terminating the session has been successful, C{False} otherwise
+ @rtype: C{bool}
"""
if self.is_alive():
@@ -824,7 +1026,7 @@ class X2goSession(object):
def get_profile_name(self):
"""\
- Retrieve the profile name of this registered session.
+ Retrieve the profile name of this L{X2goSession} instance.
@return: X2go client profile name of the session
@rtype: C{str}
@@ -835,7 +1037,7 @@ class X2goSession(object):
def get_profile_id(self):
"""\
- Retrieve this registered session's profile id.
+ Retrieve the profile ID of this L{X2goSession} instance.
@return: the session profile's id
@rtype: C{str}
@@ -850,7 +1052,7 @@ class X2goSession(object):
def session_ok(self):
"""\
- Test if this registered X2go session is
+ Test if this C{X2goSession} is
in a healthy state.
@return: C{True} if session is ok, C{False} otherwise
@@ -864,8 +1066,8 @@ class X2goSession(object):
def is_connected(self):
"""\
- Test if this registered X2go session is connected to the
- remote server.
+ Test if the L{X2goSession}'s control session is connected to the
+ remote X2go server.
@return: C{True} if session is connected, C{False} otherwise
@rtype: C{bool}
@@ -881,7 +1083,7 @@ class X2goSession(object):
def is_running(self):
"""\
- Test if this registered X2go session is up and running.
+ Test if the L{X2goSession}'s terminal session is up and running.
@return: C{True} if session is running, C{False} otherwise
@rtype: C{bool}
@@ -899,7 +1101,7 @@ class X2goSession(object):
def is_suspended(self):
"""\
- Test if this registered X2go session is in suspended state.
+ Test if the L{X2goSession}'s terminal session is in suspended state.
@return: C{True} if session is suspended, C{False} otherwise
@rtype: C{bool}
@@ -917,7 +1119,7 @@ class X2goSession(object):
def has_terminated(self):
"""\
- Test if this registered X2go session has terminated.
+ Test if the L{X2goSession}'s terminal session has terminated.
@return: C{True} if session has terminated, C{False} otherwise
@rtype: C{bool}
@@ -941,8 +1143,8 @@ class X2goSession(object):
file system
@type folder_name: C{str}
- @return: returns C{True} if the local folder has been successfully mounted within
- this registered X2go server session
+ @return: returns C{True} if the local folder has been successfully mounted within
+ this X2go session
@rtype: C{bool}
"""
@@ -954,7 +1156,7 @@ class X2goSession(object):
def session_cleanup(self):
"""\
- STILL UNDOCUMENTED
+ Clean up X2go session.
"""
if self.has_terminal_session():
hooks/post-receive
--
python-x2go.git (Python X2Go Client API)
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "python-x2go.git" (Python X2Go Client API).
More information about the x2go-commits
mailing list