pydeephaven.session

This module implements the Session class which provides methods to connect to and interact with the Deephaven server.

class Session(host=None, port=None, auth_type='Anonymous', auth_token='', never_timeout=True, session_type='python', use_tls=False, tls_root_certs=None, client_cert_chain=None, client_private_key=None, client_opts=None, extra_headers=None)[source]

Bases: object

A Session represents a connection to the Deephaven data server. It contains a number of convenience methods for asking the server to create tables, import Arrow data into tables, merge tables, run Python scripts, and execute queries.

Session objects can be used in Python with statement so that whatever happens in the with statement block, they are guaranteed to be closed upon exit.

tables

names of the global tables available in the server after running scripts

Type:

list[str]

is_alive

check if the session is still alive (may refresh the session)

Type:

bool

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 –

bind_table(name, table)[source]

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

close()[source]

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

Raises:

DHError –

Return type:

None

empty_table(size)[source]

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

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

Fetches a table by ticket.

Parameters:

ticket (SharedTicket) – a ticket

Return type:

Table

Returns:

a Table object

Raises:

DHError –

import_table(data)[source]

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

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.

merge_tables(tables, order_by=None)[source]

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

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

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

publish(source_ticket, result_ticket)[source]

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

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:
Raises:

DHError –

Return type:

None

query(table)[source]

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

Releases an export ticket.

Parameters:

ticket (Ticket) – the ticket to release

Return type:

None

run_script(script, systemic=None)[source]

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

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 –

random() → x in the interval [0, 1).