[X2Go-Commits] python-x2go.git - build-baikal (branch) updated: fcb891c13b7e1d434c9f40ad522e6a52215f2f21

X2Go dev team git-admin at x2go.org
Wed Jan 8 15:27:18 CET 2014


The branch, build-baikal has been updated
       via  fcb891c13b7e1d434c9f40ad522e6a52215f2f21 (commit)
      from  df35eae6552bb6f03757ece2da849efa90ad536b (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/__init__.py |   12 ++--
 x2go/cleanup.py  |    9 +++
 x2go/client.py   |  209 +++++++++++++++++++++++++++---------------------------
 x2go/forward.py  |   28 ++++----
 x2go/guardian.py |    6 +-
 x2go/inifiles.py |   32 ++++-----
 x2go/log.py      |   14 ++--
 x2go/printing.py |  196 +++++++++++++++++++++++++++++++++++++-------------
 x2go/registry.py |   33 +++------
 9 files changed, 315 insertions(+), 224 deletions(-)

The diff of changes is:
diff --git a/x2go/__init__.py b/x2go/__init__.py
index d93b0ce..3f30976 100644
--- a/x2go/__init__.py
+++ b/x2go/__init__.py
@@ -31,7 +31,7 @@ API Concept
 
     Python X2go consists of quite a few classes. Furthermore, 
     Python X2go is quite heavily taking advantage of Python\'s 
-    threading features. As, when providing a library like Python
+    threading features. When providing a library like Python
     X2go, it is always quite a task to keep the library code 
     compatible with former versions of the same library. This is 
     intended for Python X2go, but with some restraints.
@@ -54,7 +54,7 @@ API Concept
 
     Any other of the Python X2go classes may be subject to internal changes 
     and the way of addressing these classes in code may vary between versions. 
-    If you use them, so please be warned.
+    If you directly use them in your own applications, so please be warned.
 
 
 API Structure
@@ -68,11 +68,11 @@ API Structure
 
             ...
 
-    The X2goClient class flattens the complex structure behind it into many
-    X2goClient methods that you can use in your own C{MyX2goClient} instances.
+    The L{X2goClient} class flattens the complex structure of Python X2go into
+    many L{X2goClient} methods that you can use in your own C{MyX2goClient} instances.
 
-    However, it might be handy, to retrieve a whole X2go session instance 
-    from the X2goClient instance. This can be achieved by the 
+    However, it might be handy to retrieve a whole X2go session instance 
+    from the L{X2goClient} instance. This can be achieved by the 
     L{X2goClient.register_session()} method::
 
         import x2go
diff --git a/x2go/cleanup.py b/x2go/cleanup.py
index 1c38ccd..72aa038 100644
--- a/x2go/cleanup.py
+++ b/x2go/cleanup.py
@@ -45,6 +45,15 @@ def x2go_cleanup(e=None, session=None, threads=[]):
             sys.exit(0)
         except (KeyboardInterrupt, SystemExit):
             x2go.x2go_cleanup()
+
+    @param e: if L{x2go_cleanup} got called as we caught an exception this can be the C{Exception} that
+        we might process at the end of the clean-up (or if clean-up failed or was not appropriate)
+    @type e: C{exception}
+    @param session: an L{X2goSession} object
+    @type session: C{instance}
+    @param threads: a list of threads to clean up
+    @type threads: C{list}
+
     """
     if session is None:
         active_threads = threading.enumerate()
diff --git a/x2go/client.py b/x2go/client.py
index 75ed361..9bb7dc8 100644
--- a/x2go/client.py
+++ b/x2go/client.py
@@ -19,15 +19,9 @@
 # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
 
 """\
-L{X2goClient} class - use this class as parent class in your Python-based 
-X2go applications.
-
 L{X2goClient} is a public API class. Use this class in your Python X2go based 
-applications.
-
-The L{X2goClient} class supports registry based multiple sessions, with it you 
-can gain access to you X2go client's configuration files.
-
+applications.  Use it as a parent class for your own object oriented L{X2goClient}'ish
+class implementation.
 
 Supported Features
 ==================
@@ -35,19 +29,20 @@ Supported Features
 
         - X2go multi-session management
         - keep track of initiated sessions
-        - grant access to X2go client config files: settings, printing, sessions
-          as normally found in C{~/.x2goclient}
+        - grant access to X2go client config files: C{settings}, C{printing}, C{sessions}
+          and C{xconfig} (Windows only) as normally found in C{~/.x2goclient}
         - instantiate an X2go session by a set of Python parameters
-        - load a session profile from x2goclient's »sessions« configuration file
-          and start the in this way pre-configured session
+        - load a session profile from x2goclient's C{sessions} configuration file
+          and start the---profile-based pre-configured---session
         - sharing of local folders with remote X2go sessions
         - enabling and mangaging X2go printing (real printing, viewing as PDF, saving
           to a local folder or executing a custom »print« command
+        - transparent tunneling of audio (Pulseaudio, ESD)
         - LDAP support for X2go server clusters (NOT IMPLEMENTED YET)
 
 Non-Profile Sessions
 ====================
-    A new non-profile based X2go session within an X2goClient instance is setup in the 
+    A new non-profile based X2go session within an L{X2goClient} instance is setup in the 
     following way:
 
         - import the Python X2go module and call the session constructor::
@@ -80,8 +75,8 @@ Non-Profile Sessions
 
 Profiled Sessions
 =================
-    A new profile based (i.e. using pre-defined session profiles) X2go session within an 
-    X2goClient instance is setup in a much easier way:
+    A new profile based X2go session (i.e. using pre-defined session profiles) within an 
+    L{X2goClient} instance is setup in a much easier way:
 
         - import the Python X2go module and call the session constructor::
 
@@ -112,11 +107,11 @@ Session Suspending/Terminating
 
     You can suspend or terminate your sessions by calling the follwing commands::
 
-        x2go_client.suspend_session(x2go_profile_id)
+        x2go_client.suspend_session(x2go_sess_uuid)
 
     resp.::
 
-        x2go_client.terminate_session(x2go_profile_id)
+        x2go_client.terminate_session(x2go_sess_uuid)
 
 """
 __NAME__ = 'x2goclient-pylib'
@@ -142,13 +137,13 @@ from defaults import X2GO_CLIENT_ROOTDIR as _X2GO_CLIENT_ROOTDIR
 
 class X2goClient(object):
     """\
-    The X2goClient implements is THE public Python X2go API. With it you can
+    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
-    use the methods L{X2goClient.register_session()} and L{X2goClient.connect_session()}.
+    use these methods: L{X2goClient.register_session()} and L{X2goClient.connect_session()}.
     """
     session_profiles = None
     session_registry = None
@@ -162,7 +157,7 @@ class X2goClient(object):
         @type logger: L{X2goLogger} instance
         @param loglevel: if no X2goLogger object has been supplied a new one will be
             constructed with the given loglevel
-        @type loglevel: int
+        @type loglevel: C{int}
 
         """
         if logger is None:
@@ -183,7 +178,7 @@ class X2goClient(object):
         Query the local user's username (i.e. the user running the X2go client).
 
         @return: the local username this X2goClient instance runs as
-        @rtype: str
+        @rtype: C{str}
 
         """
         return _CURRENT_LOCAL_USER
@@ -201,42 +196,46 @@ class X2goClient(object):
 
         A profile is 
         a pre-defined set of session options stored in a sessions
-        profile file (i.e. a configuration file). Normally such a session profiles are
-        is stored in C{~/.x2goclient/sessions} or globally (for all users on the
-        client) in /etc/x2goclient/sessions. If needed, you can also create multiple 
-        X2go sessions from one session profile.
+        profile file (i.e. a configuration file). Normally such session profiles are
+        stored in C{~/.x2goclient/sessions} or globally (for all users on the
+        client) in C{/etc/x2goclient/sessions}. 
+
+        Of coures, Python X2go supports starting multiple X2go sessions from the same
+        session profile simultaneously.
 
-        L{X2goClient.register_session()} accepts the same set of parameters
-        as the L{X2goSession} constructor.
+        This method (L{X2goClient.register_session()}) accepts a similar set of parameters
+        as the L{X2goSession} constructor itself.
 
         Alternatively, you can also pass a profile name or a profile id 
-        to this method. When this is done, all session parameters are first derived
-        from the session's profile. Additional X2goSession parameters passed to
-        this method will override the option value in the session profile.
+        to this method. When this is done, Python X2go tries to find the specified session
+        in the C{sessions} configuration and then derives the necessary session parameters
+        from the session's profile configuration. Additional L{X2goSession} parameters can 
+        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
-        @type server: str
+        @type server: C{str}
         @param profile_id: id (config section name) of a session profile to load 
             from your session config
-        @type profile_id: str
+        @type profile_id: C{str}
         @param profile_name: name of a session profile to load from your session
             config
-        @type profile_name: str
+        @type profile_name: C{str}
         @param printing: enable X2go printing support for the to-be-registered X2go session
-        @type printing: bool
+        @type printing: C{bool}
         @param share_local_folders: a list of local folders (as strings) to be shared directly
             after session start up
         @type share_local_folders: list
         @param return_object: normally this method returns a unique session UUID. If 
             C{return_object} is set to C{True} an X2goRegisteredSession object will be returned 
             instead
-        @type return_object: bool
+        @type return_object: C{bool}
         @param kwargs: any option that is also valid for L{X2goSession.__init__()}
-        @type kwargs: dict
+        @type kwargs: C{dict}
 
         @return: a unique identifier (UUID) for the newly registered X2go session (or an
             X2goRegisteredSession object if C{return_object} is set to True
-        @rtype: str
+        @rtype: C{str}
 
         """
         if profile_id and self.session_profiles.has_profile_id(profile_id):
@@ -285,14 +284,14 @@ class X2goClient(object):
 
     def get_session_username(self, session_uuid):
         """\
-        After an X2go session has been setup up you can query the 
+        After an X2go session has been set up you can query the 
         username the remote sessions runs as.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: the remote username the X2go session runs as
-        @rtype: str
+        @rtype: C{str}
 
         """
         return self.session_registry(session_uuid).get_username()
@@ -300,12 +299,12 @@ class X2goClient(object):
 
     def get_session_server(self, session_uuid):
         """\
-        After a session has been setup up you can query the 
+        After a session has been set up you can query the 
         hostname of the host the session is connected to (or 
         about to connect to).
 
         @param session_uuid: the X2go sessions UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: the host an X2go session is connected to 
             (as an C{(addr,port)} tuple) 
@@ -317,19 +316,19 @@ class X2goClient(object):
 
     def get_session(self, session_uuid):
         """\
-        Retrieve the complete X2goSession object that has been 
+        Retrieve the complete L{X2goSession} object that has been 
         registered under the given session registry hash.
 
-        This method exist mainly for debugging. The returned 
-        X2goSession class is not a Python X2go public API class.
-        If you use it in your applications, note that method names 
+        NOTE: This method exist mainly for debugging and internal use. The returned 
+        L{X2goSession} class is not a Python X2go public API class.
+        If you use it in your applications, note that method names and
         options or syntax might change in the future.
 
         To retrieve a public API based session object, use the 
         L{get_registered_session()}.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: the L{X2goSession} instance
         @rtype: obj
@@ -338,17 +337,19 @@ class X2goClient(object):
         return self.session_registry(session_uuid).session_object
     __get_session = get_session
     with_session = __get_session
+    """Alias for L{get_session()}."""
 
     def get_registered_session(self, session_uuid):
         """\
-        Retrieve the complete X2goRegisteredSession object that has been 
+        Retrieve the complete L{X2goRegisteredSession} object that has been 
         registered under the given session registry hash.
 
-        X2goRegisteredSession is one of Python X2go's public API classes 
-        and may safely be used in user applications.
+        L{X2goRegisteredSession} is one of Python X2go's public API classes 
+        and may safely be used in user applications to operate on individual 
+        sessions.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: the L{X2goRegisteredSession} instance
         @rtype: obj
@@ -357,6 +358,7 @@ class X2goClient(object):
         return self.session_registry(session_uuid)
     __get_registered_session = get_registered_session
     with_registered_session = __get_registered_session
+    """Alias for L{get_registered_session()}."""
 
     def get_session_name(self, session_uuid):
         """\
@@ -364,10 +366,10 @@ class X2goClient(object):
         been registered under C{session_uuid}.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: X2go session name
-        @rtype: str
+        @rtype: C{str}
 
         """
         return self.session_registry(session_uuid).get_session_name()
@@ -380,20 +382,20 @@ class X2goClient(object):
         corresponding session.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
         @param password: the user's password for the X2go server that is going to be 
             connected to
-        @type password: str
+        @type password: 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
-        @type add_to_known_hosts: bool
+        @type add_to_known_hosts: C{bool}
         @param force_password_auth: disable SSH pub/priv key authentication mechanisms
             completely
-        @type force_password_auth: bool
+        @type force_password_auth: C{bool}
 
         @return: returns True if this method has been successful
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).connect(password=password, 
@@ -407,29 +409,30 @@ 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 four different print actions available, define as individual
-        print action classes:
+        Currently, there are four different print actions available, each defined as an individual
+        print action class:
 
-            - B{PDFVIEW} (L{X2goPrintActionPDFVIEW}): view incoming spool jobs (a PDF file) 
+            - B{PDFVIEW} (L{X2goPrintActionPDFVIEW}): view an incoming spool job (a PDF file) 
               locally in a PDF viewer
-            - B{PDFSAVE} (L{X2goPrintActionPDFSAVE}): save incoming spool jobs (a PDF file) 
+            - B{PDFSAVE} (L{X2goPrintActionPDFSAVE}): save an incoming spool job (a PDF file) 
               under a nice name in a designated folder
-            - B{PRINT} (L{X2goPrintActionPRINT}): really print the incoming spool job
+            - B{PRINT} (L{X2goPrintActionPRINT}): really print the incoming spool job on a real printing device
             - B{PRINTCMD} L{X2goPrintActionPRINTCMD}: on each incoming spool job execute an 
               external command that lets the client user handle the further processing of the 
-              print job file (PDF file)
+              print job (PDF) file
 
         Each of the print action classes accepts different print action arguments. For detail
-        information on this please refer to the constructor methods of each class individually.
+        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: str
+        @type session_uuid: C{str}
         @param print_action: one of the named above print actions, either as string or class instance
-        @type print_action: str or 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: dict
+        @type kwargs: C{dict}
 
         """
         self.session_registry(session_uuid).set_print_action(print_action=print_action, **kwargs)
@@ -438,7 +441,7 @@ class X2goClient(object):
     def start_session(self, session_uuid):
         """\
         Start a new X2go session on the remote X2go server. This method
-        will open---if everything has been successful till here--the X2go 
+        will open---if everything has been successful till here---the X2go 
         session window.
 
         Before calling this method you have to register your desired session
@@ -446,10 +449,10 @@ class X2goClient(object):
         connect to it with L{connect_session} (authentication).
 
         @param session_uuid: the X2go sessions UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: returns True if this method has been successful
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).start()
@@ -462,12 +465,12 @@ class X2goClient(object):
         called).
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
         @param session_name: the server-side name of an X2go session
-        @type session_name: str
+        @type session_name: C{str}
 
         @return: returns True if this method has been successful
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).resume(session_name)
@@ -491,13 +494,13 @@ class X2goClient(object):
         name (as shown e.g. in x2golistsessions output).
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
         @param session_name: the server-side name of an X2go session (for 
             non-associated session suspend)
-        @type session_name: str
+        @type session_name: C{str}
 
         @return: returns True if this method has been successful
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         if session_name:
@@ -531,12 +534,12 @@ class X2goClient(object):
         server-side X2go session name to this method.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
         @param session_name: the server-side name of an X2go session
-        @type session_name: str
+        @type session_name: C{str}
 
         @return: returns True if this method has been successful
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         if session_name:
@@ -561,10 +564,10 @@ class X2goClient(object):
         instantiated this X2goClient object.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: X2go session profile name
-        @rtype: str
+        @rtype: C{str}
 
         """
         return self.session_registry(session_uuid).get_profile_name()
@@ -584,10 +587,10 @@ class X2goClient(object):
         X2go session registration by C{register_session}.
 
         @param session_uuid: the session profile name
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: the X2go session profile's id
-        @rtype: str
+        @rtype: C{str}
 
         """
         return self.session_registry(session_uuid).profile_id
@@ -599,10 +602,10 @@ class X2goClient(object):
         in a healthy state.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: C{True} if session is ok, C{False} otherwise
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).session_ok()
@@ -614,10 +617,10 @@ class X2goClient(object):
         and running.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: C{True} if session is running, C{False} otherwise
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).is_running()
@@ -629,10 +632,10 @@ class X2goClient(object):
         is in suspended state.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: C{True} if session is suspended, C{False} otherwise
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).is_suspended()
@@ -644,10 +647,10 @@ class X2goClient(object):
         has terminated.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         @return: C{True} if session has terminated, C{False} otherwise
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).has_terminated()
@@ -662,13 +665,13 @@ class X2goClient(object):
         desktop icon on your remote session's desktop.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
         @param folder_name: the full path to an existing folder on the local (client-side)
             file system
-        @type folder_name: str
+        @type folder_name: C{str}
 
         @return: returns C{True} if the local folder has been successfully mounted
-        @rtype: bool
+        @rtype: C{bool}
 
         """
         return self.session_registry(session_uuid).share_local_folder(folder_name=folder_name)
@@ -689,7 +692,7 @@ class X2goClient(object):
         L{X2goClient.connect_session()}.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         """
         session = self.session_registry(session_uuid).session_object
@@ -710,7 +713,7 @@ class X2goClient(object):
         L{X2goClient.connect_session()}.
 
         @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
+        @type session_uuid: C{str}
 
         """
         session = self.session_registry(session_uuid).session_object
@@ -768,10 +771,10 @@ class X2goClient(object):
 
         @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: str
+        @type profile_id_or_name: C{str}
 
         @return: a Python dictionary with session profile options
-        @rtype: dict
+        @rtype: C{dict}
 
         """
         return self.session_profiles.get_profile_config(profile_id_or_name)
@@ -784,10 +787,10 @@ class X2goClient(object):
         is C{profile_name}
 
         @param profile_name: the session profile name
-        @type profile_name: str
+        @type profile_name: C{str}
 
         @return: the session profile's id
-        @rtype: str
+        @rtype: C{str}
 
         """
         return self.session_profiles.get_profile_id(profile_name)
@@ -799,10 +802,10 @@ class X2goClient(object):
         is C{profile_id}
 
         @param profile_id: the session profile id
-        @type profile_id: str
+        @type profile_id: C{str}
 
         @return: the session profile's name
-        @rtype: str
+        @rtype: C{str}
 
         """
         return self.session_profiles.get_profile_name(profile_id)
diff --git a/x2go/forward.py b/x2go/forward.py
index 7e0d476..e8f9d2c 100644
--- a/x2go/forward.py
+++ b/x2go/forward.py
@@ -42,19 +42,19 @@ class X2goFwServer(StreamServer):
     through an external proxy command launched by L{X2goProxy}.
 
     @param listener: listen on TCP/IP socket C{(<IP>, <Port>)}
-    @type listener: tuple
+    @type listener: C{tuple}
     @param remote_host: hostname or IP of remote host (in case of X2go mostly localhost)
-    @type remote_host: str
+    @type remote_host: C{str}
     @param remote_port: port of remote host
-    @type remote_port: int
+    @type remote_port: C{int}
     @param ssh_transport: a valid Paramiko/SSH transport object
-    @type ssh_transport: class
+    @type ssh_transport: C{instance}
     @param logger: you can pass an L{X2goLogger} object to the
         L{X2goFwServer} constructor
-    @type logger: L{X2goLogger} instance
+    @type logger: C{instance}
     @param loglevel: if no L{X2goLogger} object has been supplied a new one will be
         constructed with the given loglevel
-    @type loglevel: int
+    @type loglevel: C{int}
 
     """
     def __init__ (self, listener, remote_host, remote_port, ssh_transport, logger=None, loglevel=log.loglevel_DEFAULT,):
@@ -75,9 +75,9 @@ class X2goFwServer(StreamServer):
         Handle for SSH/Paramiko forwarding tunnel.
 
         @param fw_socket: local end of the forwarding tunnel
-        @type fw_socket: class
+        @type fw_socket: C{instance}
         @param address: unused/ignored
-        @type address: tuple
+        @type address: C{tuple}
 
         """
         try:
@@ -127,17 +127,17 @@ def start_forward_tunnel(local_port, remote_host, remote_port, ssh_transport, lo
     The tunnel is used to transport X2go graphics data through a proxy application like nxproxy.
 
     @param local_port: local starting point of the forwarding tunnel
-    @type local_port: int
+    @type local_port: C{int}
     @param remote_host: from the endpoint of the tunnel, connect to host C{<remote_host>}...
-    @type remote_host: str
+    @type remote_host: C{str}
     @param remote_port: ... on port C{<remote_port>}
-    @type remote_port: int
+    @type remote_port: C{int}
     @param ssh_transport: the Paramiko/SSH transport (i.e. the X2go sessions Paramiko/SSH transport object)
     @param logger: an X2goLogger object
-    @type logger: class
+    @type logger: C{instance}
 
     @return: returns an L{X2goFwServer} instance
-    @rtype: instance
+    @rtype: C{instance}
 
     """
     fw_server = X2goFwServer(('localhost', local_port), remote_host, remote_port, ssh_transport, logger=logger)
@@ -153,7 +153,7 @@ 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: instance
+    @type fw_server: C{instance}
 
     """
     fw_server.stop()
diff --git a/x2go/guardian.py b/x2go/guardian.py
index 748d019..4c2fa8d 100644
--- a/x2go/guardian.py
+++ b/x2go/guardian.py
@@ -59,12 +59,12 @@ class X2goSessionGuardian(threading.Thread):
     def __init__(self, session, logger=None, loglevel=log.loglevel_DEFAULT):
         """\
         @param session: the L{X2goSession} that is controlled by this L{X2goSessionGuardian}
-        @type session: L{X2goSession} instance
+        @type session: C{instance}
         @param logger: you can pass an L{X2goLogger} object to the L{X2goSessionGuardian} constructor
-        @type logger: L{X2goLogger} instance
+        @type logger: C{instance}
         @param loglevel: if no L{X2goLogger} object has been supplied a new one will be
             constructed with the given loglevel
-        @type loglevel: int
+        @type loglevel: C{int}
 
         """
         if logger is None:
diff --git a/x2go/inifiles.py b/x2go/inifiles.py
index 5ddd441..24282b5 100644
--- a/x2go/inifiles.py
+++ b/x2go/inifiles.py
@@ -64,9 +64,9 @@ class X2goIniFile(object):
         """\
         @param config_files: a list of configuration files names (e.g. a global filename and a user's home 
             directory filename)
-        @type config_files: list
+        @type config_files: C{list}
         @param defaults: a cascaded Python dicitionary structure with ini file defaults (to override 
-            Python X2go's hard coded defaults in L{default}
+            Python X2go's hard coded defaults in L{defaults}
         @type defaults: dict
         @param logger: you can pass an L{X2goLogger} object to the
             L{X2goFwServer} constructor
@@ -122,11 +122,11 @@ class X2goIniFile(object):
         method.
 
         @param section: the ini file section
-        @type section: str
+        @type section: C{str}
         @param key: the ini file key in the given section
-        @type key: str
+        @type key: C{str}
         @param value: the value for the given section and key
-        @type value: str, list, bool, ...
+        @type value: C{str}, C{list}, C{bool}, ...
 
         """
         if type(value) is types.StringType:
@@ -158,11 +158,11 @@ class X2goIniFile(object):
         does not have any effect on configuration files.
 
         @param section: the ini file section
-        @type section: str
+        @type section: C{str}
         @param key: the ini file key in the given section
-        @type key: str
+        @type key: C{str}
         @param value: the value for the given section and key
-        @type value: str, list, bool, ...
+        @type value: C{str}, C{list}, C{bool}, ...
 
         """
         if not self.iniConfig.has_section(section):
@@ -187,13 +187,13 @@ class X2goIniFile(object):
 
     def get_type(self, section, key):
         """\
-        Retrieve a value type for a given section section and key. The returned
+        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: str
+        @type section: C{str}
         @param key: the ini file key in the given section
-        @type key: str
+        @type key: C{str}
 
         @return: a Python variable type 
         @rtype: class
@@ -206,9 +206,9 @@ class X2goIniFile(object):
         Retrieve a value for a given section and key.
 
         @param section: the ini file section
-        @type section: str
+        @type section: C{str}
         @param key: the ini file key in the given section
-        @type key: str
+        @type key: C{str}
 
         @return: the value for the given section and key
         @rtype: class
@@ -254,11 +254,7 @@ class X2goIniFile(object):
     @property
     def printable_config_file(self):
         """\
-        Returns a printable configuration file.
-
-        @return: multi-line string that looks like an ini configuration file
-            when printed
-        @rtype: str
+        Returns a printable configuration file as a multi-line string.
 
         """
         stdout = cStringIO.StringIO()
diff --git a/x2go/log.py b/x2go/log.py
index bff885c..638296e 100644
--- a/x2go/log.py
+++ b/x2go/log.py
@@ -60,11 +60,11 @@ class X2goLogger(object):
     def __init__(self, name=sys.argv[0], loglevel=loglevel_DEFAULT, tag=None):
         """\
         @param name: name of the programme that uses Python X2go
-        @type name: str
+        @type name: C{str}
         @param loglevel: log level for Python X2go
-        @type loglevel: int
+        @type loglevel: C{int}
         @param tag: additional tag for all log entries
-        @type tag: str
+        @type tag: C{str}
 
         """
         self.name = os.path.basename(name)
@@ -77,11 +77,11 @@ class X2goLogger(object):
         Log a message.
 
         @param msg: log message text
-        @type msg: str
+        @type msg: C{str}
         @param loglevel: log level of this message
-        @type loglevel: int
+        @type loglevel: C{int}
         @param tag: additional tag for this log entry
-        @type tag: str
+        @type tag: C{str}
 
         """
         if tag is None:
@@ -98,7 +98,7 @@ class X2goLogger(object):
         Set log level by name.
 
         @param loglevel_name: name of loglevel to be set
-        @type loglevel_name: str
+        @type loglevel_name: C{str}
 
         """
         if type(loglevel_name) is types.IntegerType:
diff --git a/x2go/printing.py b/x2go/printing.py
index 29add2e..1d360de 100644
--- a/x2go/printing.py
+++ b/x2go/printing.py
@@ -87,16 +87,16 @@ class X2goClientPrinting(inifiles.X2goIniFile):
         """\
         @param config_files: a list of configuration files names (e.g. a global filename and a user's home 
             directory filename)
-        @type config_files: list
+        @type config_files: C{list}
         @param defaults: a cascaded Python dicitionary structure with ini file defaults (to override 
-            Python X2go's hard coded defaults in L{default}
-        @type defaults: dict
+            Python X2go's hard coded defaults in L{defaults}
+        @type defaults: C{dict}
         @param logger: you can pass an L{X2goLogger} object to the
             L{X2goPrintAction} constructor
-        @type logger: L{X2goLogger} instance
+        @type logger: C{instance}
         @param loglevel: if no L{X2goLogger} object has been supplied a new one will be
             constructed with the given loglevel
-        @type loglevel: int
+        @type loglevel: C{int}
 
         """
         inifiles.X2goIniFile.__init__(self, config_files, defaults=defaults, logger=logger, loglevel=loglevel)
@@ -150,10 +150,10 @@ class X2goPrintAction(object):
 
         @param logger: you can pass an L{X2goLogger} object to the
             L{X2goPrintAction} constructor
-        @type logger: L{X2goLogger} instance
+        @type logger: C{instance}
         @param loglevel: if no L{X2goLogger} object has been supplied a new one will be
             constructed with the given loglevel
-        @type loglevel: int
+        @type loglevel: C{int}
 
         """
         if logger is None:
@@ -167,9 +167,6 @@ class X2goPrintAction(object):
         """\
         Return the X2go print action's name.
 
-        @return: the print action's name
-        @rtype: string
-
         """
         return self.__name__
 
@@ -178,16 +175,20 @@ class X2goPrintAction(object):
         """\
         Return the X2go print action's description text.
 
-        @return: the print action\'s description
-        @rtype: string
-
         """
         return self.__description__
 
-    def do_print(self, pdf_file, job_title):
+    def do_print(self, pdf_file, job_title, spool_dir, ):
         """\
         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}
+
         """
         pass
 
@@ -216,26 +217,34 @@ class X2goPrintActionPDFVIEW(X2goPrintAction):
 
     pdfview_cmd = None
 
-    def __init__(self, pdfview_cmd=None, **kwargs):
+    def __init__(self, pdfview_cmd=None, logger=None, loglevel=log.loglevel_DEFAULT):
         """\
         @param pdfview_cmd: command that starts the external PDF viewer application
-        @type pdfview_cmd: string
+        @type pdfview_cmd: C{str}
         @param logger: you can pass an L{X2goLogger} object to the
-            L{X2goPrintAction} constructor
-        @type logger: L{X2goLogger} instance
+            L{X2goPrintActionPDFVIEW} constructor
+        @type logger: C{instance}
         @param loglevel: if no L{X2goLogger} object has been supplied a new one will be
             constructed with the given loglevel
-        @type loglevel: int
+        @type loglevel: C{int}
 
         """
         if pdfview_cmd is None:
             pdfview_cmd = defaults.DEFAULT_PDFVIEW_CMD
         self.pdfview_cmd = pdfview_cmd
-        X2goPrintAction.__init__(self, **kwargs)
+        X2goPrintAction.__init__(self, logger=logger, loglevel=loglevel)
 
     def do_print(self, pdf_file, job_title, spool_dir, ):
         """\
-        STILL UNDOCUMENTED
+        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}
+
         """
         _hr_filename = self._humanreadable_filename(pdf_file, job_title, spool_dir, )
         shutil.copy2(pdf_file, _hr_filename)
@@ -254,7 +263,7 @@ class X2goPrintActionPDFVIEW(X2goPrintAction):
 
 class X2goPrintActionPDFSAVE(X2goPrintAction):
     """\
-    STILL UNDOCUMENTED
+    Print action that saves incoming print jobs to a local folder.
 
     """
     __name__ = 'PDFSAVE'
@@ -262,19 +271,33 @@ class X2goPrintActionPDFSAVE(X2goPrintAction):
 
     save_to_folder = None
 
-    def __init__(self, save_to_folder=None, *args, **kwargs):
+    def __init__(self, save_to_folder=None, logger=None, loglevel=log.loglevel_DEFAULT):
         """\
-        STILL UNDOCUMENTED
+        @param save_to_folder: saving location for incoming print jobs (PDF files)
+        @type save_to_folder: C{str}
+        @param logger: you can pass an L{X2goLogger} object to the
+            L{X2goPrintActionPDFSAVE} constructor
+        @type logger: C{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}
 
         """
         if save_to_folder is None:
             save_to_folder = os.path.expanduser(defaults.DEFAULT_PDFSAVE_LOCATION)
         self.save_to_folder = save_to_folder
-        X2goPrintAction.__init__(self, *args, **kwargs)
+        X2goPrintAction.__init__(self, logger=None, loglevel=loglevel)
 
-    def do_print(self, pdf_file, job_title, spool_dir, ):
+    def do_print(self, pdf_file, job_title, spool_dir):
         """\
-        STILL UNDOCUMENTED
+        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}
 
         """
         dest_file = self._humanreadable_filename(pdf_file, job_title, target_path=self.save_to_folder)
@@ -287,23 +310,37 @@ class X2goPrintActionPDFSAVE(X2goPrintAction):
 
 class X2goPrintActionPRINT(X2goPrintAction):
     """\
-    STILL UNDOCUMENTED
+    Print action that actually prints an incoming print job file.
 
     """
     __name__ = 'PRINT'
     __decription__= 'UNIX/Win32GDI printing'
 
-    def __init__(self, printer=None, *args, **kwargs):
+    def __init__(self, printer=None, logger=None, loglevel=log.loglevel_DEFAULT):
         """\
-        STILL UNDOCUMENTED
+        @param printer: name of the preferred printer, if C{None} the system's/user's default printer will be used
+        @type printer: C{str}
+        @param logger: you can pass an L{X2goLogger} object to the
+            L{X2goPrintAction} constructor
+        @type logger: C{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}
 
         """
         self.printer = printer
-        X2goPrintAction.__init__(self, *args, **kwargs)
+        X2goPrintAction.__init__(self, logger=logger, loglevel=loglevel)
 
     def do_print(self, pdf_file, job_title, spool_dir, ):
         """\
-        STILL UNDOCUMENTED
+        Actually 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}
 
         """
         _hr_filename = self._humanreadable_filename(pdf_file, job_title, spool_dir)
@@ -343,26 +380,61 @@ class X2goPrintActionPRINT(X2goPrintAction):
 
 class X2goPrintActionPRINTCMD(X2goPrintAction):
     """\
-    STILL UNDOCUMENTED
+    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.
 
     """
     __name__      = 'PRINTCMD'
     __decription__= 'Print via a command (like LPR)'
 
-    def __init__(self, print_cmd=None, *args, **kwargs):
+    def __init__(self, print_cmd=None, logger=None, loglevel=log.loglevel_DEFAULT):
         """\
-        STILL UNDOCUMENTED
+        @param print_cmd: external command to be called on incoming print jobs
+        @type print_cmd: C{str}
+        @param logger: you can pass an L{X2goLogger} object to the
+            L{X2goPrintAction} constructor
+        @type logger: C{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}
 
         """
         if print_cmd is None:
             print_cmd = defaults.DEFAULT_PRINTCMD_CMD
         self.print_cmd = print_cmd
-        X2goPrintAction.__init__(self, *args, **kwargs)
+        X2goPrintAction.__init__(self, logger=logger, loglevel=loglevel)
+
+    def do_print(self, pdf_file, job_title, spool_dir):
+        """\
+        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}
+
+        """
+        _hr_filename = self._humanreadable_filename(pdf_file, job_title, spool_dir)
+        shutil.copy2(pdf_file, _hr_filename)
+        self.logger('executing external command »%s« on PDF file %s' % (self.print_cmd, _hr_filename), loglevel=log.loglevel_NOTICE)
+        cmd_line = self.print_cmd.split()
+        cmd_line.append(_hr_filename)
+        self.logger('executing external command: %s' % " ".join(cmd_line), loglevel=log.loglevel_DEBUG)
+        p = subprocess.Popen(cmd_line, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, env=_PRINT_ENV)
+
+        # this is nasty!!!!
+        gevent.sleep(20)
 
 
 class X2goPrintQueue(threading.Thread):
     """\
-    STILL UNDOCUMENTED
+    If X2go printing is supported in a particaluar L{X2goSession} instance
+    this class provides a sub-thread for handling incoming X2go print jobs.
 
     """
     print_action = None
@@ -371,16 +443,19 @@ class X2goPrintQueue(threading.Thread):
     active_jobs = {}
     job_history = []
 
-    def __init__(self, spool_dir=None, print_action=None, print_action_args={}, logger=None, loglevel=log.loglevel_DEFAULT):
+    def __init__(self, print_action=None, print_action_args={}, logger=None, loglevel=log.loglevel_DEFAULT):
         """\
-        STILL UNDOCUMENTED
-
+        @param print_action: name or instance of either of the possible X2go print action classes
+        @type print_action: C{str} or instance
+        @param print_action_args: depending of the chosen C{print_action} this dictionary may contain different
+            values; the C{print_action_args} will be passed on to the X2go print action instance constructor, so 
+            refer to either of these: L{X2goPrintActionPDFVIEW.__init__()}, L{X2goPrintActionPRINT.__init__()} et al.
         @param logger: you can pass an L{X2goLogger} object to the
             L{X2goProxy} constructor
-        @type logger: L{X2goLogger} instance
+        @type logger: C{instance}
         @param loglevel: if no L{X2goLogger} object has been supplied a new one will be
             constructed with the given loglevel
-        @type loglevel: int
+        @type loglevel: C{int}
 
         """
         if logger is None:
@@ -389,7 +464,6 @@ class X2goPrintQueue(threading.Thread):
             self.logger = copy.deepcopy(logger)
         self.logger.tag = __NAME__
 
-        self.spool_dir = spool_dir
         if print_action is not None:
             self.set_print_action(print_action, logger=logger, **print_action_args)
         threading.Thread.__init__(self)
@@ -421,7 +495,7 @@ class X2goPrintQueue(threading.Thread):
 
     def stop_thread(self):
         """\
-        Stops this L{X2goRevFwTunnel} thread completely.
+        Stops this L{X2goPrintQueue} thread completely.
 
         """
         self.pause()
@@ -444,7 +518,8 @@ class X2goPrintQueue(threading.Thread):
 
     def set_print_action(self, print_action, **kwargs):
         """\
-        STILL UNDOCUMENTED
+        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.
 
         """
         if print_action in defaults.X2GO_PRINT_ACTIONS.keys():
@@ -455,7 +530,7 @@ class X2goPrintQueue(threading.Thread):
 
     def run(self):
         """\
-        STILL UNDOCUMENTED
+        Start this L{X2goPrintQueue} thread...
 
         """
         self.logger('starting print queue thread: %s' % repr(self), loglevel=log.loglevel_DEBUG)
@@ -489,7 +564,23 @@ class X2goPrintQueue(threading.Thread):
 
 def x2go_printjob_handler(job_file=None, pdf_file=None, job_title=None, print_action=None, parent_thread=None, logger=None, ):
     """\
-    STILL UNDOCUMENTED
+    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 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 print_action: an instance of either of the possible C{X2goPrintActionXXX} classes
+    @type print_action: C{X2goPrintActionXXX} nstance
+    @param parent_thread: the L{X2goPrintQueue} thread that actually created this handler's L{X2goPrintJob} instance
+    @type parent_thread: C{instance}
+    @param logger: the L{X2goPrintQueue}'s logging instance
+    @type logger: C{instance}
 
     """
     if print_action is None:
@@ -512,12 +603,19 @@ def x2go_printjob_handler(job_file=None, pdf_file=None, job_title=None, print_ac
 
 class X2goPrintJob(threading.Thread):
     """\
-    STILL UNDOCUMENTED
+    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.
 
     """
     def __init__(self, **kwargs):
         """\
-        STILL UNDOCUMENTED
+        Construct the X2go print job thread...
+
+        All parameters (**kwargs) are passed through to the constructor
+        of C{threading.Thread()}.
 
         """
         threading.Thread.__init__(self, **kwargs)
diff --git a/x2go/registry.py b/x2go/registry.py
index 74bf195..afdf5a9 100644
--- a/x2go/registry.py
+++ b/x2go/registry.py
@@ -231,12 +231,7 @@ class X2goRegisteredSession(object):
 
     def get_profile_name(self):
         """\
-        Retrieve the profile name of the session that has been registered
-        under C{session_hash}
-
-
-        @param session_hash: the X2go session's UUID registry hash
-        @type session_hash: str
+        Retrieve the profile name of this registered session.
 
         @return: X2go client profile name of the session
         @rtype: str
@@ -247,11 +242,7 @@ class X2goRegisteredSession(object):
 
     def get_profile_id(self):
         """\
-        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: str
+        Retrieve this registered session's profile id.
 
         @return: the session profile's id
         @rtype: str
@@ -266,12 +257,9 @@ class X2goRegisteredSession(object):
 
     def session_ok(self):
         """\
-        Test if the X2go session registered as C{session_uuid} is
+        Test if this registered X2go session is
         in a healthy state.
 
-        @param session_uuid: the X2go session's UUID registry hash
-        @type session_uuid: str
-
         @return: C{True} if session is ok, C{False} otherwise
         @rtype: bool
 
@@ -281,8 +269,7 @@ class X2goRegisteredSession(object):
 
     def is_running(self):
         """\
-        Test if the X2go session registered as C{session_uuid} is up
-        and running.
+        Test if this registered X2go session is up and running.
 
         @return: C{True} if session is running, C{False} otherwise
         @rtype: bool
@@ -293,8 +280,7 @@ class X2goRegisteredSession(object):
 
     def is_suspended(self):
         """\
-        Test if the X2go session registered as C{session_uuid}
-        is in suspended state.
+        Test if this registered X2go session is in suspended state.
 
         @return: C{True} if session is suspended, C{False} otherwise
         @rtype: bool
@@ -305,8 +291,7 @@ class X2goRegisteredSession(object):
 
     def has_terminated(self):
         """\
-        Test if the X2go session registered as C{session_uuid}
-        has terminated.
+        Test if this registered X2go session has terminated.
 
         @return: C{True} if session has terminated, C{False} otherwise
         @rtype: bool
@@ -317,14 +302,14 @@ class X2goRegisteredSession(object):
 
     def share_local_folder(self, folder_name):
         """\
-        Share a local folder with the X2go session registered as C{session_uuid}.
+        Share a local folder with this registered X2go session.
 
         @param folder_name: the full path to an existing folder on the local
             file system
         @type folder_name: str
 
-        @return: returns C{True} if the local folder has been successfully mounted within the
-            X2go server session registerd as UUID C{session_uuid}
+        @return: returns C{True} if the local folder has been successfully mounted within 
+            this registered X2go server session
         @rtype: bool
 
         """


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