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

## x2go.registry module

X2GoSessionRegistry class - the X2GoClient’s session registry backend

class x2go.registry.X2GoSessionRegistry(client_instance, logger=None, loglevel=56)

  Bases: `object`

  This class is utilized by `x2go.client.X2GoClient` instances to maintain a good overview on session status of all associated `x2go.session.X2GoSession` instances.

  associated_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of sessions that are currently associated by an `X2GoTerminalSession*` to the underlying `x2go.client.X2GoClient` instance. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  associated_sessions_of_profile_name(profile_name, return_objects=True, return_session_names=False)

    For a given session profile name retrieve a list of sessions that are currently associated by an `X2GoTerminalSession*` to this `x2go.client.X2GoClient` instance. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - profile_name (`str`) – session profile name

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects or session names)

    Return type:

      `list`

  property connected_control_sessions

    Equals a list of all currently connected control sessions.

  connected_profiles(use_paramiko=False, return_profile_ids=True, return_profile_names=False)

    Retrieve a list of all currently connected session profiles.

    Parameters:

      - use_paramiko (`bool`) – send query directly to the Paramiko/SSH layer (Default value = False)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = True)

    Returns:

      list of connected session profiles

    Return type:

      `list`

  connected_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of sessions that the underlying `x2go.client.X2GoClient` instances is currently connected to. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  connected_sessions_of_profile_name(profile_name, return_objects=True, return_session_names=False)

    For a given session profile name retrieve a list of sessions that are currently connected to the profile’s X2Go server. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - profile_name (`str`) – session profile name

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects or session names)

    Return type:

      `list`

  control_session_of_profile_name(profile_name)

    For a given session profile name retrieve a the corresponding `X2GoControlSession*` instance.

    Parameters:

      profile_name (`str`) – session profile name

    Returns:

      contol session instance

    Return type:

      `X2GoControlSession*` instance

  disable_session_auto_registration()

    This method is used to temporarily skip auto-registration of newly appearing X2Go session on the server side. This is necessary during session startups to assure that the session registry does not get filled with session UUID duplicates.

  enable_session_auto_registration()

    This method is used to temporarily (re-)enable auto-registration of newly appearing X2Go session on the server side.

  forget(session_uuid)

    Forget the complete record for session UUID `session_uuid`.

    Parameters:

      session_uuid (`str`) – the X2Go session’s UUID registry hash

  get_master_session(profile_name, return_object=True, return_session_name=False)

    Retrieve the master session of a specific profile.

    Parameters:

      - profile_name (`str`) – the profile name that we query the master session of

      - return_object (`bool`) – return `x2go.session.X2GoSession` instance (Default value = True)

      - return_session_name (`bool`) – return X2Go session name (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  get_profile_id(session_uuid)

    Retrieve the profile ID of a given session UUID hash.

    Parameters:

      session_uuid (`str`) – the X2Go session’s UUID registry hash

    Returns:

      profile ID

    Return type:

      `str`

  get_profile_name(session_uuid)

    Retrieve the profile name of a given session UUID hash.

    Parameters:

      session_uuid (`str`) – the X2Go session’s UUID registry hash

    Returns:

      profile name

    Return type:

      `str`

  get_session_of_session_name(session_name, return_object=False, match_profile_name=None)

    Retrieve the `x2go.session.X2GoSession` instance with session name `<session_name>`.

    Parameters:

      - session_name (`str`) – name of session to be retrieved

      - return_object (`bool`) – if `False` the session UUID hash will be returned, if `True` the `x2go.session.X2GoSession` instance will be returned (Default value = False)

      - match_profile_name (`str`) – returned sessions must match this profile name (Default value = None)

    Returns:

      `x2go.session.X2GoSession` object or its representing session UUID hash

    Return type:

      `x2go.session.X2GoSession` instance or `str`

    Raises:

      X2GoSessionRegistryException – if there is more than one `x2go.session.X2GoSession` registered for `<session_name>` within the same `x2go.client.X2GoClient` instance. This should never happen!

  property has_running_sessions

    Equals `True` if the underlying `x2go.client.X2GoClient` instance has any running sessions at hand.

  has_session_of_session_name(session_name, match_profile_name=None)

    Detect if we know about an `x2go.session.X2GoSession` of name `<session_name>`.

    Parameters:

      - session_name (`str`) – name of session to be searched for

      - match_profile_name (`str`) – a session’s profile_name must match this profile name (Default value = None)

    Returns:

      `True` if a session of `<session_name>` has been found

    Return type:

      `bool`

  property has_suspended_sessions

    Equals `True` if the underlying `x2go.client.X2GoClient` instance has any suspended sessions at hand.

  keys()

    A list of session registry keys.

    Returns:

      session registry key list

    Return type:

      `list`

  non_running_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of sessions that are currently _NOT_ in running state. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  pubapp_sessions_of_profile_name(profile_name, return_objects=True, return_session_names=False)

    For a given session profile name retrieve a list of sessions that can be providers for published application list. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - profile_name (`str`) – session profile name

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects or session names)

    Return type:

      `list`

  register(server, profile_id, profile_name, session_name=None, control_backend='PLAIN', terminal_backend='PLAIN', info_backend='PLAIN', list_backend='PLAIN', proxy_backend='NX3', settings_backend='FILE', printing_backend='FILE', client_rootdir='/sbuild-nonexistent/.x2goclient', sessions_rootdir='/sbuild-nonexistent/.x2go', ssh_rootdir='/sbuild-nonexistent/.ssh', keep_controlsession_alive=True, add_to_known_hosts=False, known_hosts=None, **kwargs)

    Register a new `x2go.session.X2GoSession` instance with this `x2go.registry.X2GoSessionRegistry`.

    Parameters:

      - server (`str`) – hostname of X2Go server

      - profile_id (`str`) – profile ID

      - profile_name (`str`) – profile name

      - session_name (`str`) – session name (if available) (Default value = None)

      - control_backend (`str`) – X2Go control session backend to use (Default value = _BACKENDS[‘X2GoControlSession’][‘default’])

      - terminal_backend (`str`) – X2Go terminal session backend to use (Default value = _BACKENDS[‘X2GoTerminalSession’][‘default’])

      - info_backend (`str`) – X2Go session info backend to use (Default value = _BACKENDS[‘X2GoServerSessionInfo’][‘default’])

      - list_backend (`str`) – X2Go session list backend to use (Default value = _BACKENDS[‘X2GoServerSessionList’][‘default’])

      - proxy_backend (`str`) – X2Go proxy backend to use (Default value = _BACKENDS[‘X2GoProxy’][‘default’])

      - settings_backend (`str`) – X2Go client settings backend to use (Default value = _BACKENDS[‘X2GoClientSettings’][‘default’])

      - printing_backend (`str`) – X2Go client printing backend to use (Default value = _BACKENDS[‘X2GoClientPrinting’][‘default’])

      - client_rootdir (`str`) – client base dir (default: ~/.x2goclient)

      - sessions_rootdir (`str`) – sessions base dir (default: ~/.x2go)

      - ssh_rootdir (`str`) – ssh base dir (default: ~/.ssh)

      - keep_controlsession_alive (`bool`) – On last `X2GoSession.disconnect()` keep the associated `X2GoControlSession` instance alive?

      - add_to_known_hosts (`bool`) – Auto-accept server host validity?

      - known_hosts (`str`) – the underlying Paramiko/SSH systems `known_hosts` file

      - kwargs (`dict`) – all other options will be passed on to the constructor of the to-be-instantiated `x2go.session.X2GoSession` instance

      - _X2GO_CLIENT_ROOTDIR

    Returns:

      the session UUID of the newly registered (or re-registered) session

    Return type:

      `str`

  register_available_server_sessions(profile_name, session_list=None, newly_connected=False, re_register=False, skip_pubapp_sessions=False)

    Register server-side available X2Go sessions with this `x2go.registry.X2GoSessionRegistry` instance for a given profile name.

    Parameters:

      - profile_name (`str`) – session profile name to register available X2Go sessions for

      - session_list (`X2GoServerSessionList*` instance) – an optional `X2GoServerSessionList*` instance (as returned by the `X2GoClient.list_sessions()` command can be passed to this method. (Default value = None)

      - newly_connected (`bool`) – give a hint that the session profile got newly connected (Default value = False)

      - re_register (`bool`) – re-register available sessions, needs to be done after changes to the session profile (Default value = False)

      - skip_pubapp_sessions (`bool`) – Do not register published applications sessions (Default value = False)

  registered_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of all registered sessions. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  registered_sessions_of_profile_name(profile_name, return_objects=True, return_session_names=False)

    For a given session profile name retrieve a list of sessions that are currently registered with this `x2go.client.X2GoClient` instance. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - profile_name (`str`) – session profile name

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects or session names)

    Return type:

      `list`

  running_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of sessions that are currently in running state. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  running_sessions_of_profile_name(profile_name, return_objects=True, return_session_names=False)

    For a given session profile name retrieve a list of sessions that are currently running. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - profile_name (`str`) – session profile name

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects or session names)

    Return type:

      `list`

  session_summary(session_uuid, status_only=False)

    Compose a session summary (as Python dictionary).

    Parameters:

      - session_uuid (`str`) – the X2Go session’s UUID registry hash

      - status_only (`bool`) – short summary, include session status only (Default value = False)

    Returns:

      session summary dictionary

    Return type:

      `dict`

  suspended_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of sessions that are currently in suspended state. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  suspended_sessions_of_profile_name(profile_name, return_objects=True, return_session_names=False)

    For a given session profile name retrieve a list of sessions that are currently in suspended state. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - profile_name (`str`) – session profile name

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects or session names)

    Return type:

      `list`

  terminated_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of sessions that have terminated recently. If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  update_status(session_uuid=None, profile_name=None, profile_id=None, session_list=None, force_update=False, newly_connected=False)

    Update the session status for `x2go.session.X2GoSession` that is represented by a given session UUID hash, profile name or profile ID.

    Parameters:

      - session_uuid (`str`) – the X2Go session’s UUID registry hash (Default value = None)

      - profile_name (`str`) – alternatively, a profile name can be specified (the stati of all registered sessions for this session profile will be updated) (Default value = None)

      - profile_id (`str`) – alternatively, a profile ID can be given (the stati of all registered sessions for this session profile will be updated) (Default value = None)

      - session_list (`X2GoServerSessionList*` instance) – an optional `X2GoServerSessionList*` instance (as returned by the `X2GoClient.list_sessions()` command can be passed to this method. (Default value = None)

      - force_update (`bool`) – make sure the session status gets really updated (Default value = False)

      - newly_connected – set this to `True`, if the control session has just been connected (Default value = False)

      - newly_connected – `bool` (Default value = False)

    Returns:

      `True` if this method has been successful

    Return type:

      `bool`

    Raises:

      X2GoSessionRegistryException – if the combination of `session_uuid`, `profile_name` and `profile_id` does not match the requirement: only one of them

  virgin_sessions(return_objects=True, return_profile_names=False, return_profile_ids=False, return_session_names=False)

    Retrieve a list of sessions that are currently still in virgin state (not yet connected, associated etc.). If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_profile_names (`bool`) – return as list of profile names (Default value = False)

      - return_profile_ids (`bool`) – return as list of profile IDs (Default value = False)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects, profile names/IDs or session names)

    Return type:

      `list`

  virgin_sessions_of_profile_name(profile_name, return_objects=True, return_session_names=False)

    For a given session profile name retrieve a list of sessions that are registered with this `x2go.client.X2GoClient` instance but have not yet been started (i.e. sessions that are in virgin state). If none of the `return_*` options is specified a list of session UUID hashes will be returned.

    Parameters:

      - profile_name (`str`) – session profile name

      - return_objects (`bool`) – return as list of `x2go.session.X2GoSession` instances (Default value = True)

      - return_session_names (`bool`) – return as list of X2Go session names (Default value = False)

    Returns:

      a session list (as UUID hashes, objects or session names)

    Return type:

      `list`