deephaven_enterprise.client.session_manager¶

class CatalogTicket[source]¶

Bases: Ticket

A CatalogTicket is ticket that the catalog table

property bytes¶: Returns the ticket as raw bytes.

classmethod catalog_ticket()[source]¶

Creates a ticket that references the database catalog table

Returns:: a CatalogTicket

property pb_ticket¶: Returns the ticket as a gRPC protobuf ticket.

class DatabaseTicket(ticket_bytes)[source]¶

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

property bytes¶: Returns the ticket as raw bytes.

classmethod historical_ticket(namespace, table_name)[source]¶

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)[source]¶

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

property pb_ticket¶: Returns the ticket as a gRPC protobuf ticket.

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)[source]¶

Bases: Session

Wrapper around a basic Community 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 (str) – the host name or IP address of the remote machine, default is ‘localhost’
port (int) – the port number that Deephaven server is listening on, default is 10000
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 (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 (bytes) – PEM encoded client certificate if using mutual TLS. Defaults to None, which implies not using mutual TLS.
client_private_key (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 (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 (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()[source]¶

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

Return type:: barrage.BarrageSession
Returns:: the Barrage session connected to the same Persistent Query as this DndSession

barrage_snapshot(table_ref)[source]¶

Creates a local table snapshot of the specified table reference.

Parameters:: table_ref (Table) – table reference to create local table of
Return type:: deephaven.table.Table
Returns:: local table snapshot

barrage_subscribe(table_ref)[source]¶

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

Parameters:: table_ref (Table) – table reference to create local table of
Return type:: deephaven.table.Table
Returns:: local table subscribed to updates

bind_table(name, table)¶

Binds a table to the given name on the server so that it can be referenced by that name.

Parameters:

name (str) – name for the table
table (Table) – a Table object

Raises:

DHError –

Return type:

None

catalog_table()[source]¶

Fetches the catalog table from the database on the server.

Returns:: a Table object
Raise:: DHError

close()[source]¶

Closes the Session object if it hasn’t timed out already.

Raises:: DHError –

empty_table(size)¶

Creates an empty table on the server.

Parameters:: size (int) – the size of the empty table in number of rows
Return type:: Table
Returns:: a Table object
Raises:: DHError –

fetch(ticket)¶

Fetches a server object by ticket.

This is low-level method that can be used to fetch non-Table server objects. The ticket represents a fetchable server object, e.g PluginClient, Fetchable. This method is used together with the publish() method to share server objects between sessions.

Parameters:: ticket (Ticket) – a ticket
Return type:: ExportTicket
Returns:: an ExportTicket object
Raises:: DHError –

fetch_table(ticket)¶

Fetches a table by ticket.

Parameters:: ticket (SharedTicket) – a ticket
Return type:: Table
Returns:: a Table object
Raises:: DHError –

historical_table(namespace, table_name)[source]¶

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

Returns:

a Table object

Raise:

DHError

import_table(data)¶

Imports the pyarrow table as a new Deephaven table on the server.

Deephaven supports most of the Arrow data types. However, if the pyarrow table contains any field with a data type not supported by Deephaven, the import operation will fail.

Parameters:: data (pa.Table) – a pyarrow Table object
Return type:: Table
Returns:: a Table object
Raises:: DHError –

input_table(schema=None, init_table=None, key_cols=None, blink_table=False)¶

Creates an InputTable from either Arrow schema or initial table. When blink_table is True, the InputTable will be a blink table. When blink_table is False (default), the InputTable will be keyed if key columns are provided, otherwise it will be append-only.

Parameters:

schema (pa.Schema) – the schema for the InputTable
init_table (Table) – the initial table
key_cols (Union[str, Sequence[str]) – the name(s) of the key column(s)
blink_table (bool) – whether the InputTable should be a blink table, default is False

Return type:

InputTable

Returns:

an InputTable

Raises:

DHError, ValueError –

property is_alive¶: Whether the session is alive.

live_table(namespace, table_name)[source]¶

Fetches a live table from the database on the server.

Parameters:

namespace (str) – the namespace of the table
table_name (str) – the name of the table

Returns:

a Table object

Raise:

DHError

merge_tables(tables, order_by=None)¶

Merges several tables into one table on the server.

Parameters:

tables (list[Table]) – the list of Table objects to merge
order_by (str, optional) – if specified the resultant table will be sorted on this column

Return type:

Table

Returns:

a Table object

Raises:

DHError –

open_table(name)¶

Opens a table in the global scope with the given name on the server.

Parameters:: name (str) – the name of the table
Return type:: Table
Returns:: a Table object
Raises:: DHError –

plugin_client(server_obj)¶

Wraps a ticket as a PluginClient. Capabilities here vary based on the server implementation of the ObjectType, but most will at least send a response payload to the client, possibly including references to other objects. In some cases, depending on the server implementation, the client will also be able to send the same sort of messages back to the server.

Part of the experimental plugin API.

Return type:: PluginClient

pqinfo()[source]¶

Retrieve the persistent query information for this query.

Return type:: PersistentQueryInfoMessage
Returns:

publish(source_ticket, result_ticket)¶

Publishes a source ticket to the result ticket.

This is low-level method that can be used to publish non-Table server objects that are previously fetched from the server. The source ticket represents the previously fetched server object to be published, and the result ticket, which should normally be a SharedTicket, is the ticket to publish to. The result ticket can then be fetched by other sessions to access the object as long as the object is not released. This method is used together with the fetch() method to share server objects between sessions.

Parameters:

source_ticket (Ticket) – The source ticket to publish from.
result_ticket (Ticket) – The result ticket to publish to.

Raises:

DHError – If the operation fails.

Return type:

None

publish_table(ticket, table)¶

Publishes a table to the given shared ticket. The ticket can then be used by another session to fetch the table.

Note that, the shared ticket can be fetched by other sessions to access the table as long as the table is not released. When the table is released either through an explicit call of the close method on it, or implicitly through garbage collection, or through the closing of the publishing session, the shared ticket will no longer be valid.

Parameters:

ticket (SharedTicket) – a SharedTicket object
table (Table) – a Table object

Raises:

DHError –

Return type:

None

query(table)¶

Creates a Query object to define a sequence of operations on a Deephaven table.

Parameters:: table (Table) – a Table object
Return type:: Query
Returns:: a Query object
Raises:: DHError –

release(ticket)¶

Releases an export ticket.

Parameters:: ticket (Ticket) – the ticket to release
Return type:: None

run_script(script, systemic=None)¶

Runs the supplied Python script on the server.

Parameters:

script (str) – the Python script code
systemic (bool) – Whether to treat the code as systemically important. Defaults to None which uses the default system behavior

Raises:

DHError –

Return type:

None

time_table(period, start_time=None, blink_table=False)¶

Creates a time table on the server.

Parameters:

period (Union[int, str]) – the interval at which the time table ticks (adds a row); units are nanoseconds or a time interval string, e.g. “PT00:00:.001” or “PT1S”
start_time (Union[int, str]) – the start time for the time table in nanoseconds or as a date time formatted string; default is None (meaning now)
blink_table (bool, optional) – if the time table should be a blink table, defaults to False

Return type:

Table

Returns:

a Table object

Raises:

DHError –

class SessionManager(url=None, json=None)[source]¶

Bases: object

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

Create 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 (Optional[str]) – a URL to get the JSON connection information from
json (Optional[str]) – a JSON document containing connection information

close()[source]¶: Terminate this session managers connection to the authentication server and controller.

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)[source]¶

Create a new worker (as a temporary PersistentQuery) and establish a session to it.

Parameters:

name – the name of the persistent query. Defaults to None, which 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 query be automatically deleted after inactivity. Defaults to ten minutes. If none, auto-delete is disabled. If zero, the query is deleted immediately after a client connection is lost
admin_groups (List[str]) – list of groups that may administer the query. Defaults to None, which means only the current user may administer the query.
viewer_groups (List[str]) – list of groups that may view the query. Defaults to None, which means only the current user may view the query.
timeout_seconds (float) – how long to wait for the query to start. Defaults to 60 seconds.
configuration_transformer (Callable[[PersistentQueryConfigMessage], PersistentQueryConfigMessage]) – 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

Return type:

DndSession

Returns:

a session connected to a new Interactive Console PQ worker

connect_to_persistent_query(name=None, serial=None, session_arguments=None)[source]¶

Connect to an existing persistent query by name or serial number. The query must be running.

Parameters:

name (Optional[str]) – the name of the persistent query to connect to
serial (Optional[int]) – the serial number of the persistent query to connect to
session_arguments (Optional[Dict[str, any]]) – a dictionary of additional arguments to pass to the pydeephaven.Session created and wrapped by a DndSession

Return type:

DndSession

Returns:

a session connected to the persistent query

create_auth_client(auth_host=None)[source]¶

Create the authentication client for this session manager.

Parameters:: auth_host (Optional[str]) – the host to connect to, defaults to the first host in the JSON config’s auth_host list
Return type:: AuthClient
Returns:: the authentication client

create_controller_client()[source]¶

Create the controller client for this session manager.

Return type:: ControllerClient
Returns:: the controller client

delete_key(pubtext)[source]¶: Delete the specified public key from the Deephaven server.

password(user, password, effective_user=None)[source]¶

Authenticates to the server using a username and password.

Parameters:

user (str) – the user to authenticate
password (str) – the user’s password
effective_user (Optional[str]) – the user to operate as, defaults to the user to authenticate

ping()[source]¶: Send a ping to the authentication server and controller. :return: False if either ping was not sent, True if both pings were sent.

private_key(file)[source]¶

Authenticate 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 generate-iris-keys, or alternatively an

io.StringIO instance (which may be closed after it is read)

saml()[source]¶: Authenticate using SAML, which must be configured on the server.

upload_key(pubtext)[source]¶: Upload the provided public key to the Deephaven server.