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

## x2go.backends.terminal.plain module

X2GoTerminalSession class - core functions for handling your individual X2Go sessions.

This backend handles X2Go server implementations that respond with session infos via server-side PLAIN text output.

class x2go.backends.terminal.plain.X2GoSessionParams

  Bases: `object`

  The `x2go.backends.terminal.plain.X2GoSessionParams` class is used to store all parameters that `X2GoTerminalSession` backend objects are constructed with.

  rewrite_session_type()

    Rewrite the X2Go session type, so that the X2Go server can understand it (`desktop` -> `D` or `K`, depending on the proxy backend, etc.).

    Also if the object’s `command` property is a known window manager, the session type will be set to ‘D’ (i.e. desktop with NX3 backend).

    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

    Return type:

      `str`

  update(**properties_to_be_updated)

    Update all properties in the object `x2go.backends.terminal.plain.X2GoSessionParams` object from the passed on dictionary.

    Parameters:

      properties_to_be_updated (`dict`) – a dictionary with `x2go.backends.terminal.plain.X2GoSessionParams` property names as keys und their values to be update in `x2go.backends.terminal.plain.X2GoSessionParams` object.

class x2go.backends.terminal.plain.X2GoTerminalSession(control_session, session_info=None, geometry='800x600', depth=24, link='adsl', pack='16m-jpeg-9', dpi='', cache_type='unix-kde', kbtype='null/null', kblayout='null', kbvariant='null', clipboard='both', xinerama=False, kdrive=False, session_type='application', snd_system='pulse', snd_port=4713, cmd=None, published_applications=False, set_session_title=False, session_title='', applications=[], rdp_server=None, rdp_options=None, xdmcp_server=None, convert_encoding=False, server_encoding='UTF-8', client_encoding='UTF-8', rootdir=None, profile_name='UNKNOWN', profile_id='20240215120239349529', print_action=None, print_action_args={}, info_backend='PLAIN', list_backend='PLAIN', proxy_backend='NX3', proxy_options={}, printing_backend='FILE', client_rootdir='/sbuild-nonexistent/.x2goclient', sessions_rootdir='/sbuild-nonexistent/.x2go', session_instance=None, logger=None, loglevel=56)

  Bases: `object`

  Class for managing X2Go terminal sessions on a remote X2Go server via Paramiko/SSH.

  With the `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 `x2go.backends.terminal.plain.X2GoTerminalSession` object uses two main data structure classes:

  > - `x2go.backends.terminal.plain.X2GoSessionParams`: stores all parameters that have been passed to the constructor method.

  > - `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. `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 `x2go.session.X2GoSession` instances.

  auto_session_window_title(dont_set=False)

    Automatically generate an appropriate human-readable session window title.

    The session window title will be provider in the `session_title` property of this method.

    Parameters:

      dont_set (`bool`) – generate the session window title, but do not actually set it (Default value = False)

  color_depth()

    Retrieve the session’s color depth.

    Returns:

      the session’s color depth

    Return type:

      `int`

  exec_published_application(exec_name, timeout=20, env={})

    Executed a published application.

    Parameters:

      - exec_name (`str`) – application to be executed

      - timeout (`int`) – execution timeout (Default value = 20)

      - env (`dict`) – session environment dictionary (Default value = {})

  find_session_window(timeout=60)

    Try for <timeout> seconds to find the X2Go session window of this terminal session.

    A background thread will get spawned for this operation.

    Parameters:

      timeout (`int`) – try for <timeout> seconds to find the session window (Default value = 60)

  get_mimebox_spooldir()

    Return the server-side MIME box spooldir path.

    Returns:

      the directory where remote MIME box jobs are placed

    Return type:

      `str`

  get_printing_spooldir()

    Return the server-side printing spooldir path.

    Returns:

      the directory for remote print job spooling

    Return type:

      `str`

  get_session_cmd()

    Retrieve the X2Go session’s command as stored in the session parameter object.

    Returns:

      the session command

    Return type:

      `str`

  get_session_info()

    Retrieve the X2Go session’s session info object.

    Returns:

      the session info object

    Return type:

      `X2GoServerSessionInfo*`

  get_session_name()

    Retrieve the X2Go session’s name from the session info object.

    Returns:

      the session name

    Return type:

      `str`

  get_session_type()

    Retrieve the X2Go session’s session type as stored either in the parameter object (for sessions not yet launched) or in the `session_info` object (for already launched / to-be-resumed sessions).

    Returns:

      the session type

    Return type:

      `str`

  has_command(cmd)

    ,,Guess’’ if the command `<cmd>` exists on the X2Go server and is executable. The expected result is not 100% safe, however, it comes with a high probability to be correct.

    Parameters:

      cmd (`str`) – session command

    Returns:

      `True` if this method reckons that the command is executable on the remote X2Go server

    Return type:

      `bool`

  is_connected()

    X2Go session connected?

    Returns:

      Returns `True` if this X2Go session’s Paramiko/SSH transport is connected/authenticated, `False` else.

    Return type:

      `bool`

  is_desktop_session()

    Is this (terminal) session a desktop session?

    Returns:

      Returns `True` is this session is a desktop session.

    Return type:

      `bool`

  is_kdrive_session()

    Test if this terminal session is a KDrive based desktop session.

    Returns:

      `True` if this session is of session type KDrive (‘K’).

    Return type:

      `bool`

  is_pubapp_session()

    Test if this terminal session is a published applications session.

    Returns:

      `True` if this session is of session type published applications (‘P’).

    Return type:

      `bool`

  is_published_applications_provider()

    Is this (terminal) session a published applications provider?

    Returns:

      Returns `True` is this session is a provider session for published applications.

    Return type:

      `bool`

  is_rootless_session()

    Test if this terminal session is a rootless session.

    Returns:

      `True` if this session is of session type rootless (‘R’).

    Return type:

      `bool`

  is_running()

    X2Go session running?

    Returns:

      Returns `True` if this X2Go (terminal) session is in running state, `False` otherwise.

    Return type:

      `bool`

  is_session_info_protected()

    Test if this terminal’s session info object is write-protected.

    Returns:

      `True`, if session info object is read-only, `False` for read-write.

    Return type:

      `bool`

  is_shadow_session()

    Test if this terminal session is a desktop sharing (aka shadow) session.

    Returns:

      `True` if this session is of session type shadow (‘S’).

    Return type:

      `bool`

  is_suspended()

    X2Go session suspended?

    Returns:

      Returns `True` if this X2Go (terminal) session is in suspended state, `False` otherwise.

    Return type:

      `bool`

  ok()

    X2Go session OK?

    Returns:

      Returns `True` if this X2Go (terminal) session is up and running, `False` otherwise.

    Return type:

      `bool`

  post_terminate_cleanup()

    Do some cleanup after this session has terminated.

  raise_session_window(timeout=60)

    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.

    Parameters:

      timeout (`int`) – try for <timeout> seconds to raise the session window (Default value = 60)

  release_proxy()

    Let the X2Go proxy command cleanly die away… (by calling its destructor).

  release_telekinesis()

    Let the attached Telekinesis client cleanly die away… (by calling its destructor).

  resume()

    Resume a running/suspended X2Go session.

    Returns:

      `True` if the session could successfully be resumed

    Return type:

      `bool`

    Raises:

      X2GoTerminalSessionException – if the terminal session failed to update server-side reported port changes

  run_command(cmd=None, env={})

    Run a command in this session.

    After `x2go.backends.terminal.plain.X2GoTerminalSession.start()` has been called one or more commands can be executed with `x2go.backends.terminal.plain.X2GoTerminalSession.run_command()` within the current X2Go session.

    Parameters:

      - cmd (`str`) – Command to be run (Default value = None)

      - env (`dict`) – add server-side environment variables (Default value = {})

    Returns:

      stdout.read() and stderr.read() as returned by the run command on the X2Go server

    Return type:

      `tuple` of `str`

  session_info_protect()

    Protect this terminal session’s info object against updates.

  session_info_unprotect()

    Allow session info updates from within the list_sessions method of the control session.

  set_keyboard(layout='null', variant='null')

    Set the keyboard layout and variant for this (running) session.

    Parameters:

      - layout (`str`) – keyboard layout to be set (Default value = ‘null’)

      - variant (`str`) – keyboard variant to be set (Default value = ‘null’)

    Returns:

      returns `True` if the {setxkbmap} command could be executed successfully.

    Return type:

      `bool`

  set_mimebox_action(mimebox_action, **kwargs)

    Set a MIME box action for the next incoming MIME jobs.

    This method is a wrapper for `x2go.mimebox.X2GoMIMEboxQueue```set_mimebox_action()``.

    Parameters:

      - mimebox_action (`str` or `X2GoMIMEboxAction*`) – MIME box action name or object (i.e. an instance of `X2GoMIMEboxAction*` classes)

      - kwargs (`dict`) – MIME box action specific parameters

  set_print_action(print_action, **kwargs)

    Set a print action for the next incoming print jobs.

    This method is a wrapper for `x2go.printing.X2GoPrintQueue`.set_print_action()``.

    Parameters:

      - print_action (`str` or `X2GoPrintAction*`) – print action name or object (i.e. an instance of `X2GoPrintAction*` classes)

      - kwargs (`dict`) – print action specific parameters

  set_session_window_title(title, timeout=60)

    Modify the session window title.

    A background thread will get spawned for this operation.

    Parameters:

      - title (`str`) – new title for the terminal session’s session window

      - timeout (`int`) – try for <timeout> seconds to find the session window (Default value = 60)

  share_local_folder(local_path=None, folder_type='disk')

    Share a local folder with the X2Go session.

    Parameters:

      - local_path (`str`) – the full path to an existing folder on the local file system (Default value = None)

      - folder_type (`str`) – 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’)

    Returns:

      returns `True` if the local folder has been successfully mounted within the X2Go server session

    Return type:

      `bool`

    Raises:

      - X2GoUserException – if local folder sharing is not available to this user

      - Exception – any other exception occuring on the way is passed through by this method

  start()

    Start a new X2Go session.

    Returns:

      `True` if session startup has been successful and the X2Go proxy is up-and-running

    Return type:

      `bool`

    Raises:

      - X2GoTerminalSessionException – if the session startup failed

      - X2GoDesktopSharingDenied – if desktop sharing fails because of denial by the user running the desktop to be shared

  start_mimebox(mimebox_extensions=[], mimebox_action=None)

    Initialize the X2Go MIME box. Open/process incoming files from the server-side locally.

    Parameters:

      - mimebox_extensions (`list`) – file name extensions that are allowed for local opening/processing (Default value = [])

      - mimebox_action (`str` or `obj`) – MIME box action given as name or object (i.e. an instance of `X2GoMIMEboxAction*` classes). (Default value = None)

    Raises:

      X2GoUserException – if the X2Go MIME box feature is not available to this user

  start_printing()

    Initialize X2Go print spooling.

    Raises:

      X2GoUserException – if the X2Go printing feature is not available to this user

  start_sound()

    Initialize Paramiko/SSH reverse forwarding tunnel for X2Go sound.

    Currently supported audio protocols:

    > - PulseAudio

    > - Esound (not tested very much)

    Raises:

      X2GoControlSessionException – if the control session of this terminal session is not connected

  start_sshfs()

    Initialize Paramiko/SSH reverse forwarding tunnel for X2Go folder sharing.

  start_telekinesis()

    Initialize Telekinesis client for X2Go.

  stop_mimebox()

    Shutdown (pause) the X2Go MIME box Queue thread.

  stop_printing()

    Shutdown (pause) the X2Go Print Queue thread.

  stop_sound()

    Shutdown (pause) Paramiko/SSH reverse forwarding tunnel for X2Go sound.

  stop_sshfs()

    Shutdown (pause) Paramiko/SSH reverse forwarding tunnel for X2Go folder sharing.

  suspend()

    Suspend this X2Go (terminal) session.

    Returns:

      `True` if the session terminal could be successfully suspended

    Return type:

      `bool`

  terminate()

    Terminate this X2Go (terminal) session.

    Returns:

      `True` if the session could be successfully terminated

    Return type:

      `bool`

  unshare_all_local_folders()

    Unshare all local folders mount in the X2Go session.

    Returns:

      returns `True` if all local folders could be successfully unmounted from the X2Go server session

    Return type:

      `bool`

  unshare_local_folder(local_path)

    Unshare local folder given as <local_path> from X2Go session.

    Parameters:

      local_path – the full path to an existing folder on the local file system (Default value = None)

    Returns:

      returns `True` if the local folder <local_path> could be successfully unmounted from the X2Go server session

    Return type:

      `bool`

  update_session_window_file()

    Create a file that contains information on the session window. . If the file already exists, its content gets update.