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

## 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`

  `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!

  `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`

  `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`