# Python X2Go (Client) API Documentation (v0.6.1.4)

## Welcome to Python X2Go’s documentation!

Python X2Go is a Python module that implements X2Go client support for the free X2Go Server project (http://wiki.x2go.org) in Python.

## Introduction

> With Python X2Go you can write your own X2Go clients or embed X2Go client features into already existing application environments.

> NOTE: Beginning with v0.4.0.0 of Python X2Go all class names start with X2Go***. Earlier versions used X2go***. As X2Go is the official name of the project (i.e. with a capital X and a capital G) we have adapted the class names to this circumstance.

## API Concept

> Python X2Go consists of quite a few classes. Furthermore, Python X2Go is quite heavily taking advantage of Python's 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.

> Python X2Go only offers five public API classes. With the release of version 0.1.0.0, we will try to keep these five public API classes of future releases as compatible as possible with versions of Python X2Go greater/equal than v0.1.0.0.

> The seven public API classes are:

> > - `x2go.client.X2GoClient` — a whole X2Go client API

> > - `x2go.session.X2GoSession` — management of an individual X2Go session–either started standalone or from within an `x2go.client.X2GoClient` instance

> > - `x2go.backends.settings.file.X2GoClientSettings` — provide access to X2Go (global and user) configuration node »settings«

> > - `x2go.backends.printing.file.X2GoClientPrinting` — provide access to X2Go (global and user) configuration node »printing«

> > - `x2go.backends.profiles.file.X2GoSessionProfiles` — provide access to X2Go (global and user) configuration node »sessions«

> > - `x2go.backends.profiles.httpbroker.X2GoSessionProfiles` — provide API for obtaining session profiles from a http(s) based X2Go Session Broker

> > - `x2go.backends.profiles.sshbroker.X2GoSessionProfiles` — provide API for obtaining session profiles from an SSH based X2Go Session Broker

> Plus two extra classes on MS Windows platforms:

> > - `x2go.xserver.X2GoClientXConfig` and `x2go.xserver.X2GoXServer` — these classes will be initialized during `x2go.client.X2GoClient` instantiation on MS Windows platforms and start an installed XServer

> 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 different versions of Python X2Go. If you directly use other than the five public API classes in your own applications, so please be warned.

## API Structure

> When using Python X2Go in your applications, the basic idea is that you create your own class and inherit the X2GoClient class in that:

>     import x2go
>     class MyX2GoClient(x2go.X2GoClient):

>         ...

> Python X2Go is capable of handling multiple running/suspended sessions within the same client instance, so for your application, there should not be any need of instantiating more than one `x2go.client.X2GoClient` object in parallel.

> NOTE: Doing so is–herewith–fully disrecommended.

> The `x2go.client.X2GoClient` class flattens the complex structure of Python X2Go into many `x2go.client.X2GoClient` methods that you can use in your own `MyX2GoClient` instance.

> However, it might be handy to retrieve a whole X2Go session instance from the `x2go.client.X2GoClient` instance. This can be achieved by the `X2GoClient.register_session()` method:

>     import x2go
>     my_x2gocli = MyX2GoClient()
>     reg_session_instance = my_x2gocli.register_session(<options>, return_object=True)

> Whereas <options> can be as simple as:

>     »profile_name=<PROFILE_NAME_IN_SESSIONS_FILE>«

> or contain a whole set of `x2go.session.X2GoSession` parameters that can be used to start a session manually (i.e. a session that is based on a pre-configured session profile in either of the »sessions« config files).

> The `X2GoClient.register_session()` method—in object-retrieval-mode—returns an `x2go.session.X2GoSession` instance. With this instance you can then manage your X2Go session:

>     import gevent, getpass
>     pw=getpass.getpass()
>     # authenticate
>     reg_session_instance.connect(password=pw, <further_options>)
>     # then launch the session window with either a new session
>     if start:
>         reg_session_instance.start()
>     # or resume a session
>     if resume:
>         reg_session_instance.resume(session_name=<X2Go-session-name>)
>     # leave it runnint for 60 seconds
>     gevent.sleep(60)
>     # and then suspend
>     if suspend:
>         reg_session_instance.suspend()
>     # or alternatively terminate it
>     elif terminate:
>         reg_session_instance.terminate()

> How to access—especially how to modify—the X2Go client configuration files »settings«, »printing«, »sessions« and »xconfig« (Windows only) is explained in detail with each class declaration in this API documentation. Please refer to the class docs of `x2go.backends.settings.file.X2GoClientSettings`, `x2go.backends.printing.file.X2GoClientPrinting`, `x2go.backends.profiles.file.X2GoSessionProfiles` and `x2go.xserver.X2GoXServer`.

## Configuration and Session Management

> Python X2Go strictly separates configuration management from session management. The classes needed for session management / administration are supposed to only gain »read access« to the classes handling the X2Go client configuration nodes.

> A configuration node in Python X2Go can be a file, a gconf database section, a section in the Windows registry, etc.

> NOTE: Each configuration node will be re-read whenever it is needed by an X2Go sesion or the X2GoClient class itself.

> Conclusively, any change to either of the configuration nodes will be reflected as a change in your X2Go client behaviour:

> > - `x2go.backends.profiles.file.X2GoSessionProfiles`: changes to a session profile in the »sessions« node will be available for the next registered `x2go.session.X2GoSession` instance

> > - `x2go.backends.printing.file.X2GoClientPrinting`: on each incoming X2Go print job the »printing« configuration node will be re-read, thus you can change your X2Go client’s print setup during a running session

> > - `x2go.backends.settings.file.X2GoClientSettings`: also the configuration node »settings« is re-read whenever needed in the course of X2Go session management

> > - `x2go.xserver.X2GoClientXConfig` and `x2go.xserver.X2GoXServer` (Windows only): these classes will only be initialized once (starting the XServer on Windows platforms) on construction of an `x2go.client.X2GoClient` instance

## Dependencies

> Python X2Go takes advantage of the libevent/greenlet implementation gevent (http://www.gevent.org). The least needed version of Python gevent is 0.13.0. On MS Windows Python gevent 1.0 is highly recommended.

> Python X2Go (because of gevent) requires at least Python 2.6 or Python 3.4. Further recent information on Python X2Go is available at: https://wiki.x2go.org/doku.php/wiki:libs:python-x2go

## Contact

> If you have any questions concerning Python X2Go, please sign up for the x2go-dev list (https://lists.x2go.org/listinfo/x2go-dev) and post your questions, requests and feedbacks there.

## Contents

- x2go package
  - Subpackages
    - x2go.backends package
      - Subpackages
      - Module contents
  - Submodules
    - x2go.cache module
      - `X2GoListSessionsCache`
    - x2go.checkhosts module
      - `X2GoAutoAddPolicy`
      - `X2GoInteractiveAddPolicy`
      - `X2GoMissingHostKeyPolicy`
      - `check_ssh_host_key()`
    - x2go.cleanup module
      - `x2go_cleanup()`
    - x2go.client module
      - Supported Features
      - Non-Profile Sessions
      - Profiled Sessions
      - Session Suspending / Terminating
      - `X2GoClient`
    - x2go.defaults module
      - `DEFAULT_PDFSAVE_LOCATION`
      - `DEFAULT_PDFVIEW_CMD`
      - `DEFAULT_PRINTCMD_CMD`
      - `PUBAPP_MAX_NO_SUBMENUS`
      - `RSAHostKey`
      - `X2GO_DESKTOPSESSIONS`
      - `X2GO_DESKTOPSESSIONS_KDRIVE_PREFERRED`
      - `X2GO_DESKTOPSESSIONS_NX3_PREFERRED`
      - `X2GO_GENERIC_APPLICATIONS`
      - `X2GO_MIMEBOX_ACTIONS`
      - `X2GO_MIMEBOX_EXTENSIONS_BLACKLIST`
      - `X2GO_PRINT_ACTIONS`
      - `X2GO_SESSIONPROFILE_DEFAULTS`
      - `X2GO_SHARE_FULLACCESS`
      - `X2GO_SHARE_VIEWONLY`
      - `pack_methods_nx3_noqual`
    - x2go.forward module
      - `X2GoFwServer`
      - `start_forward_tunnel()`
      - `stop_forward_tunnel()`
    - x2go.gevent_subprocess module
      - `Popen`
    - x2go.guardian module
      - `X2GoSessionGuardian`
    - x2go.inifiles module
      - `X2GoIniFile`
    - x2go.log module
      - `X2GoLogger`
      - `X2goLogger`
      - `loglevel_DEFAULT`
    - x2go.mimebox module
      - `X2GoMIMEboxJob`
      - `X2GoMIMEboxQueue`
      - `x2go_mimeboxjob_handler()`
    - x2go.mimeboxactions module
      - `X2GoMIMEboxAction`
      - `X2GoMIMEboxActionOPEN`
      - `X2GoMIMEboxActionOPENWITH`
      - `X2GoMIMEboxActionSAVEAS`
    - x2go.printactions module
      - `X2GoPrintAction`
      - `X2GoPrintActionDIALOG`
      - `X2GoPrintActionPDFSAVE`
      - `X2GoPrintActionPDFVIEW`
      - `X2GoPrintActionPRINT`
      - `X2GoPrintActionPRINTCMD`
    - x2go.printqueue module
      - `X2GoPrintJob`
      - `X2GoPrintQueue`
      - `x2go_printjob_handler()`
    - x2go.pulseaudio module
      - `OSNotSupportedException`
      - `X2GoPulseAudio`
    - x2go.registry module
      - `X2GoSessionRegistry`
    - x2go.rforward module
      - `X2GoRevFwChannelThread`
      - `X2GoRevFwTunnel`
      - `x2go_rev_forward_channel_handler()`
      - `x2go_transport_tcp_handler()`
    - x2go.session module
      - `X2GoSession`
    - x2go.sftpserver module
      - `X2GoRevFwSFTPChannelThread`
      - `X2GoRevFwTunnelToSFTP`
      - `x2go_rev_forward_sftpchannel_handler()`
    - x2go.sshproxy module
      - `X2GoSSHProxy`
    - x2go.telekinesis module
      - `X2GoTelekinesisClient`
    - x2go.utils module
      - `ProgressStatus`
      - `compare_versions()`
      - `detect_unused_port()`
      - `find_session_line_in_x2golistsessions()`
      - `find_session_window()`
      - `genkeypair()`
      - `get_desktop_geometry()`
      - `get_encoding()`
      - `get_workarea_geometry()`
      - `is_abs_path()`
      - `is_color_depth_ok()`
      - `is_in_nx3packmethods()`
      - `known_encodings()`
      - `local_color_depth()`
      - `merge_ordered_lists()`
      - `patiently_remove_file()`
      - `raise_session_window()`
      - `session_names_by_timestamp()`
      - `set_session_window_title()`
      - `slugify()`
      - `touch_file()`
      - `unique()`
      - `which()`
      - `xkb_rules_names()`
    - x2go.x2go_exceptions module
      - `AuthenticationException`
      - `BadHostKeyException`
      - `PasswordRequiredException`
      - `SSHException`
      - `WindowsError`
      - `X2GoBackendException`
      - `X2GoBrokerConnectionException`
      - `X2GoClientException`
      - `X2GoClientPrintingException`
      - `X2GoClientSettingsException`
      - `X2GoControlSessionException`
      - `X2GoDesktopSharingDenied`
      - `X2GoFwTunnelException`
      - `X2GoHostKeyException`
      - `X2GoMIMEboxActionException`
      - `X2GoMIMEboxQueueException`
      - `X2GoNotImplementedYetException`
      - `X2GoPrintActionException`
      - `X2GoPrintException`
      - `X2GoPrintQueueException`
      - `X2GoProfileException`
      - `X2GoProxyException`
      - `X2GoRemoteHomeException`
      - `X2GoRevFwTunnelException`
      - `X2GoSFTPClientException`
      - `X2GoSSHProxyAuthenticationException`
      - `X2GoSSHProxyException`
      - `X2GoSSHProxyHostKeyException`
      - `X2GoSSHProxyPasswordRequiredException`
      - `X2GoSessionCacheException`
      - `X2GoSessionException`
      - `X2GoSessionRegistryException`
      - `X2GoTelekinesisClientException`
      - `X2GoTerminalSessionException`
      - `X2GoTimeOutException`
      - `X2GoUserException`
      - `X2goClientException`
      - `X2goClientPrintingException`
      - `X2goClientSettingsException`
      - `X2goControlSessionException`
      - `X2goDesktopSharingException`
      - `X2goFwTunnelException`
      - `X2goHostKeyException`
      - `X2goMIMEboxActionException`
      - `X2goMIMEboxQueueException`
      - `X2goNotImplementedYetException`
      - `X2goPrintActionException`
      - `X2goPrintException`
      - `X2goPrintQueueException`
      - `X2goProfileException`
      - `X2goProxyException`
      - `X2goRemoteHomeException`
      - `X2goRevFwTunnelException`
      - `X2goSSHProxyAuthenticationException`
      - `X2goSSHProxyException`
      - `X2goSSHProxyHostKeyException`
      - `X2goSessionCacheException`
      - `X2goSessionException`
      - `X2goSessionRegistryException`
      - `X2goTerminalSessionException`
      - `X2goTimeOutException`
      - `X2goUserException`
    - x2go.xserver module
      - `X2GoClientXConfig`
      - `X2GoXServer`
  - Module contents

# Indices and tables

- Index

- Module Index

- Search Page