deephaven_enterprise.client.session_manager

This module provides the SessionManager class which is used to authenticate to the Deephaven Enterprise server and create sessions for Deephaven Core+ workers. It also provides the DndSession class which wraps around pydeephaven.Session and adds the ability to create a Barrage session and subscribe to tables.

class CatalogTicket

Bases: Ticket

A CatalogTicket is ticket that the catalog table

classmethod catalog_ticket()

Creates a ticket that references the database catalog table

Return type:

CatalogTicket

Returns:

a CatalogTicket

class DatabaseTicket(ticket_bytes)

Bases: Ticket

A DatabaseTicket is ticket that references a table by namespace and table name

Initializes a DatabaseTicket.

Parameters:

ticket_bytes (bytes) – the raw bytes for the ticket

Raises:

DHError –

classmethod historical_ticket(namespace, table_name)

Creates a ticket that references a database historical table

Parameters:

• namespace (str) – the namespace

• table_name (str) – the table name

Return type:

DatabaseTicket

Returns:

a DatabaseTicket

classmethod live_ticket(namespace, table_name)

Creates a ticket that references a database intraday table

Parameters:

• namespace (str) – the namespace

• table_name (str) – the table name

Return type:

DatabaseTicket

Returns:

a DatabaseTicket

class DndSession(session_manager, pqinfo, host=None, port=None, auth_type='io.deephaven.proto.auth.Token', auth_token=None, extra_headers=None, delete_on_close=None, session_type='python', session_arguments=None)

Bases: Session

A DndSession wraps around pydeephaven.Session. For queries that are ephemeral, they are explicitly deleted on session close.

Initializes a Session object that connects to the Deephaven server

Parameters:

• host (Optional[str]) – the host name or IP address of the remote machine, if None, ‘localhost’ is used.

• port (Optional[int]) – the port number that Deephaven server is listening on, if None, 10000 is used.

• auth_type (str) – the authentication type string, can be “Anonymous’, ‘Basic”, or any custom-built authenticator in the server, such as “io.deephaven.authentication.psk.PskAuthenticationHandler”, default is ‘Anonymous’.

• auth_token (str) – the authentication token string. When auth_type is ‘Basic’, it must be “user:password”; when auth_type is “Anonymous’, it will be ignored; when auth_type is a custom-built authenticator, it must conform to the specific requirement of the authenticator

• never_timeout (bool) – never allow the session to timeout, default is True

• session_type (str) – the Deephaven session type. Defaults to ‘python’

• use_tls (bool) – if True, use a TLS connection. Defaults to False

• tls_root_certs (Optional[bytes]) – PEM encoded root certificates to use for TLS connection, or None to use system defaults. If not None implies use a TLS connection and the use_tls argument should have been passed as True. Defaults to None

• client_cert_chain (Optional[bytes]) – PEM encoded client certificate if using mutual TLS. Defaults to None, which implies not using mutual TLS.

• client_private_key (Optional[bytes]) – PEM encoded client private key for client_cert_chain if using mutual TLS. Defaults to None, which implies not using mutual TLS.

• client_opts (Optional[list[Tuple[str,Union[int,str]]]) –

  list of tuples for name and value of options to the underlying grpc channel creation. Defaults to None, which implies not using any channel options. See https://grpc.github.io/grpc/cpp/group__grpc__arg__keys.html for a list of valid options. Example options:

  [ (‘grpc.target_name_override’, ‘idonthaveadnsforthishost’),

  (‘grpc.min_reconnect_backoff_ms’, 2000) ]

• extra_headers (Optional[dict[bytes, bytes]]) – additional headers (and values) to add to server requests. Defaults to None, which implies not using any extra headers.

Raises:

DHError –

barrage_session()

Returns a Barrage session connected to the same Persistent Query as this DndSession.

This method is only supported when running the Deephaven Enterprise Python Client in workers. This is a convenience method to get a Barrage session to the same remote worker that this DndSession connects to.

Return type:

BarrageSession

Returns:

a BarrageSession object in the worker

barrage_snapshot(table_ref)

Creates a local table snapshot of the specified table reference.

This method is only supported when running the Deephaven Enterprise Python Client in workers. It allows you to snapshot a remote live table that is visible to the client. Note that the returned table is a worker-side table which can be used in the same way as a local table in the worker.

Parameters:

table_ref (Table) – the table reference to create a local table of

Return type:

Table

Returns:

a Table object in the worker

barrage_subscribe(table_ref)

Creates a local table of the specified table reference that subscribes to updates.

This method is only supported when running the Deephaven Enterprise Python Client in workers. It allows you to subscribe to a remote live table that is visible to the client and receive updates as they occur. Note that the returned table is a worker-side table which can be used in the same way as a local table in the worker.

Parameters:

table_ref (Table) – the table reference to create a local table of

Return type:

Table

Returns:

a Table object in the worker

catalog_table()

Fetches the catalog table from the server.

Return type:

Table

Returns:

a Table object

Raises:

DHError –

close()

Closes the session, releasing the Persistent Query if it was created by this session.

historical_table(namespace, table_name)

Fetches a historical table from the database on the server.

Parameters:

• namespace (str) – the namespace of the table

• table_name (str) – the name of the table

Return type:

Table

Returns:

a Table object

Raises:

DHError –

live_table(namespace, table_name)

Fetches a live table from the server.

Parameters:

• namespace (str) – the namespace of the table

• table_name (str) – the name of the table

Return type:

Table

Returns:

a Table object

Raises:

DHError –

pqinfo()

Retrieve the Persistent Query information for the Persistent Query on this session.

Returns:

the Persistent Query information

Return type:

persistent_query_pb2.PersistentQueryInfoMessage

class SessionManager(url=None, truststore_bytes=None, json=None, client_name=None, rpc_timeout_seconds=120)

Bases: object

The SessionManager authenticates to the Deephaven Enterprise server and allows you to create sessions for Deephaven Core+ workers by either creating a new temporary Persistent Query or connecting to an existing Persistent Query.

Creates a SessionManager for the specified JSON, which may either be a string or a URL to download. The Deephaven server typically provides the JSON as “https://host:port/iris/connection.json”. Exactly one of url or json must be provided.

The JSON must have the following parameters: auth_host, auth_port, controller_host, controller_port. If the truststore_url is set, then a trust store PEM file is downloaded from the given URL. If the override_authorities parameter is set then the authority used for the TLS connection to the authentication server is the value of the auth_authority parameter (or “authserver” if unspecified) and the TLS connection to the controller uses the value of the controller_authority parameter (or for backwards compatibility “authserver” if unspecified).

Parameters:

• url (str) – a URL to get the JSON connection information from, defaults to None

• truststore_bytes (Optional[bytes]) – Optional PEM-formatted certificate trust store; only necessary if the envoy/web server is using non-publicly trusted / self-generated certificates, defaults to None

• json (str) – a JSON document containing connection information, defaults to None

• client_name (str) – a descriptive string identifying this client that will be used in the server for logging

• rpc_timeout_seconds (int) – the timeout period in seconds for RPCs. Defaults to 120 if not provided.

Raises:

RuntimeError –

close()

Terminates this session managers connection to the authentication server and controller.

Return type:

None

connect_to_new_worker(name, heap_size_gb, server=None, extra_jvm_args=None, extra_environment_vars=None, engine='DeephavenCommunity', auto_delete_timeout=600, admin_groups=None, viewer_groups=None, timeout_seconds=60, configuration_transformer=None, session_arguments=None)

Creates a new worker (as a temporary Persistent Query) and establish a session to it.

Parameters:

• name (str) – the name of the Persistent Query, if None, means a name based on the current time is used.

• heap_size_gb (float) – the heap size of the worker.

• server (str) – the server to connect to. Defaults to None, which means the first available server

• extra_jvm_args (list[str]) – extra JVM arguments for starting the worker. Defaults to None.

• extra_environment_vars (list[str]) – extra Environment variables for the worker. Defaults to None.

• engine (str) – which engine (worker kind) to use for the backend worker. Defaults to None, which means “DeephavenCommunity”.

• auto_delete_timeout (Optional[int]) – after how many seconds should the Persistent Query be automatically deleted after inactivity. Defaults to ten minutes. If none, auto-delete is disabled. If zero, the Persistent Query is deleted immediately after a client connection is lost.

• admin_groups (list[str]) – list of groups that may administer the Persistent Query. Defaults to None, which means only the current user may administer the Persistent Query.

• viewer_groups (list[str]) – list of groups that may view the Persistent Query. Defaults to None, which means only the current user may view the Persistent Query.

• timeout_seconds (float) – how long to wait for the Persistent Query to start. Defaults to 60 seconds.

• configuration_transformer (Callable) – a function that can replace (or edit) the automatically generated Persistent Query configuration, enabling you to set more advanced options than the other function parameters provide. Defaults to None.

• session_arguments (dict[str, Any]) – a dictionary of additional arguments to pass to the pydeephaven.Session created and wrapped by a DndSession. Defaults to None.

Returns:

a session connected to a new Interactive Console PQ worker

Return type:

DndSession

Raises:

RuntimeError –

connect_to_persistent_query(name=None, serial=None, session_arguments=None)

Connects to an existing Persistent Query by name or serial number. The Persistent Query must be running.

Parameters:

• name (str) – the name of the Persistent Query to connect to, defaults to None

• serial (int) – the serial number of the Persistent Query to connect to, defaults to None

• session_arguments (dict[str, Any]) – a dictionary of additional arguments to pass to the pydeephaven.Session created and wrapped by a DndSession, defaults to None

Returns:

a session connected to the Persistent Query

Return type:

DndSession

Raises:

RuntimeError –

create_auth_client(auth_host=None, rpc_timeout_seconds=120)

Creates the authentication client for this session manager.

Parameters:

• auth_host (str) – the host to connect to, defaults to None, meaning to use the first host in the JSON config’s auth_host list

• rpc_timeout_seconds (int) – the timeout period in seconds for RPCs. Defaults to 120 if not provided.

Returns:

the authentication client

Return type:

AuthClient

create_controller_client(rpc_timeout_seconds=120)

Creates the controller client for this session manager.

Parameters:

rpc_timeout_seconds (int) – the timeout period in seconds for RPCs. Defaults to 120 if not provided.

Returns:

the controller client

Return type:

ControllerClient

delete_key(pubtext)

Deletes the specified public key from the Deephaven server.

Parameters:

pubtext (str) – the public key to delete

Return type:

None

external_login(auth_key)

Authenticates to the server using an external authentication method, such as SAML or a custom, non-standard external authentication module.

This requires that the server be configured with the external authentication module and that the external authentication module should be configured to accept the provided auth_key.

Parameters:

auth_key (Union[str, bytes]) – the key to authenticate with, which may be a string or bytes. If it is a string, it should be the key that the external authentication module expects. If it is bytes, it will be decoded to a string using UTF-8 before sending.

Raises:

AuthenticationFailedException – if the server responds with a failure

Return type:

None

password(user, password, effective_user=None)

Authenticates to the server using a username and password.

Parameters:

• user (str) – the user to authenticate

• password (str) – the user’s password

• effective_user (str) – the user to operate as, defaults to the user to authenticate

Return type:

None

ping()

Sends a ping to the authentication server and controller.

Returns:

False if either ping was not sent, True if both pings were sent.

Return type:

bool

private_key(file)

Authenticates to the server using a Deephaven format private key file.

https://deephaven.io/enterprise/docs/resources/how-to/connect-from-java/#instructions-for-setting-up-private-keys

Parameters:

file (Union[str, io.StringIO]) – a string file name containing the private key produced by auth.AuthClient.generate_keypair(), or alternatively an io.StringIO instance (which may be closed after it is read)

Return type:

None

saml()

Authenticates to the server using SAML, which must be configured on the server.

Return type:

None

upload_key(pubtext)

Uploads the provided public key to the Deephaven server.

Parameters:

pubtext (str) – the public key to upload

Return type:

None