#
# Copyright (c) 2016-2026 Deephaven Data Labs and Patent Pending
#
"""This module implements the Session class which provides methods to connect to and interact with the Deephaven
server."""
from __future__ import annotations
import base64
import logging
import os
import queue
import sys
import threading
import time
import weakref
from abc import ABC, abstractmethod
from collections.abc import Iterable
from random import random
from typing import Any, NewType, TypeAlias, cast
import grpc
import pyarrow as pa
import pyarrow.flight as paflight
from pyarrow._flight import ClientMiddleware, ClientMiddlewareFactory
from pydeephaven._app_service import AppService
from pydeephaven._arrow_flight_service import ArrowFlightService
from pydeephaven._config_service import ConfigService
from pydeephaven._console_service import ConsoleService
from pydeephaven._input_table_service import InputTableService
from pydeephaven._plugin_obj_service import PluginObjService
from pydeephaven._session_service import SessionService
from pydeephaven._table_ops import (
CreateInputTableOp,
EmptyTableOp,
FetchTableOp,
MergeTablesOp,
TimeTableOp,
)
from pydeephaven._table_service import TableService
from pydeephaven._utils import to_list
from pydeephaven.dherror import DHError
from pydeephaven.experimental.plugin_client import PluginClient
from pydeephaven.query import Query
from pydeephaven.table import InputTable, Table
from pydeephaven.ticket import (
ExportTicket,
ScopeTicket,
ServerObject,
SharedTicket,
Ticket,
_server_object_from_proto,
)
logger = logging.getLogger(__name__)
class _SessionJob(ABC):
"""Work for a session's release thread."""
@abstractmethod
def run(self, session: Session) -> None:
pass
class _ReleaseTicket(_SessionJob):
"""Releases the ticket of a garbage-collected Table."""
def __init__(self, ticket: Ticket):
self.ticket = ticket
def run(self, session: Session) -> None:
session.release(self.ticket)
class _Stop(_SessionJob):
"""Ends the release thread, which exits before running it."""
def run(self, session: Session) -> None:
pass
_STOP = _Stop()
def _run_release_worker(
session_ref: weakref.ReferenceType[Session],
jobs: queue.SimpleQueue[_SessionJob],
) -> None:
"""Runs a session's queued jobs. It ends when the session is closed or when the session is gone.
While it waits for a job it holds the session only weakly, so a dropped session can be collected. A failing job is
logged and does not end the thread."""
while True:
job = jobs.get()
if job is _STOP:
return
session = session_ref()
if session is None or not session.is_connected:
return
try:
job.run(session)
except Exception:
logger.exception(
f"{session._logpfx}: background job {type(job).__name__} failed"
)
del session # hold the session only weakly while waiting
def _run_token_refresher(session_ref: weakref.ReferenceType[Session]) -> None:
"""Refreshes a session's auth token whenever a refresh is due. It sleeps until then and is never woken early, so
after the session is closed or gone, it ends when it next wakes. It also ends when refreshes keep failing and give
up. While it sleeps it holds the session only weakly, so a dropped session can be collected."""
refresh_due = False # the first refresh is scheduled, not due
while True:
session = session_ref()
if session is None or not session.is_connected:
return
if refresh_due:
try:
session._keep_alive()
except Exception:
logger.exception(f"{session._logpfx}: token refresh failed")
timeout = session._seconds_until_refresh()
del session # hold the session only weakly while waiting
if timeout is None:
return
time.sleep(timeout)
refresh_due = True
class _DhClientAuthMiddlewareFactory(ClientMiddlewareFactory):
def __init__(self, session: Session):
super().__init__()
self._middleware = _DhClientAuthMiddleware(session)
def start_call(self, info: Any) -> _DhClientAuthMiddleware:
return self._middleware
class _DhClientAuthMiddleware(ClientMiddleware):
def __init__(self, session: Session):
super().__init__()
# Weak: the Flight client holds this in C++, out of the garbage collector's sight, so a strong reference
# would keep a dropped session alive.
self._session_ref = weakref.ref(session)
def call_completed(self, exception: Exception | None) -> None:
super().call_completed(exception)
def received_headers(self, headers: dict) -> None:
super().received_headers(headers)
header_key = "authorization"
try:
if headers and header_key in headers:
header_value = headers[header_key]
auth_header_value = bytes(header_value[0], encoding="ascii")
session = self._session_ref()
if auth_header_value and session is not None:
session._auth_header_value = auth_header_value
except Exception:
logger.exception(
f"_DhClientAuthMiddleware.received_headers got headers={headers}"
)
return
def sending_headers(self) -> None:
return None
def _trace(who: str) -> None:
logger.debug(f"TRACE: {who}")
_BidiRpc = NewType("_BidiRpc", grpc.StreamStreamMultiCallable)
_NotBidiRpc: TypeAlias = grpc.UnaryUnaryMultiCallable | grpc.StreamUnaryMultiCallable
[docs]
class Session:
"""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. A closed or disconnected session cannot be used again.
Create a new Session instead.
Attributes:
tables (list[str]): names of the global tables available in the server after running scripts
is_alive (bool): check if the session is still alive (may refresh the session)
"""
def __init__(
self,
host: str | None = None,
port: int | None = None,
auth_type: str = "Anonymous",
auth_token: str = "",
never_timeout: bool = True,
session_type: str = "python",
use_tls: bool = False,
tls_root_certs: bytes | None = None,
client_cert_chain: bytes | None = None,
client_private_key: bytes | None = None,
client_opts: list[tuple[str, int | str]] | None = None,
extra_headers: dict[bytes, bytes] | None = None,
):
"""Initializes a Session object that connects to the Deephaven server
Args:
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
"""
_trace("Session.__init__")
self._r_lock = (
threading.RLock()
) # for thread-safety when accessing/changing session global state
self._services_lock = threading.Lock() # for lazy initialization of services
# Before anything that can raise: close() and __del__ use it, and __del__ runs on a partly built session too.
self._release_queue: queue.SimpleQueue[_SessionJob] = queue.SimpleQueue()
self._release_thread: threading.Thread | None = None
self._last_export_ticket_number: int = 0
if not host:
self._host = os.environ.get("DH_HOST", "localhost")
else:
self._host = host
if not port:
self._port = int(os.environ.get("DH_PORT", 10000))
else:
self._port = port
self._logpfx = f"pydh.Session {id(self)} {self._host}:{self._port}"
self._use_tls = use_tls
self._tls_root_certs = tls_root_certs
self._client_cert_chain = client_cert_chain
self._client_private_key = client_private_key
self._client_opts = client_opts
self._extra_headers = extra_headers if extra_headers else {}
self.is_connected = False
# We set here the initial value for the authorization header,
# which will bootstrap our authentication to the server on the first
# RPC going out. The server will give us back a bearer token to use
# in subsequent RPCs in the same authorization header. From then
# on, the value of _auth_header_value will be similar to b'Bearer X'
# where X is the bearer token provided by the server.
if auth_type == "Anonymous":
auth_header_value: str = auth_type
elif auth_type == "Basic":
auth_token_base64 = base64.b64encode(auth_token.encode("ascii")).decode(
"ascii"
)
auth_header_value = "Basic " + auth_token_base64
else:
auth_header_value = str(auth_type) + " " + auth_token
self._auth_header_value: bytes = bytes(auth_header_value, "ascii")
# Counter for consecutive failures to refresh auth token, used to calculate retry backoff
self._refresh_failures = 0
self.grpc_channel: grpc.Channel | None = None
self._session_service: SessionService | None = None
self._table_service: TableService | None = None
self._grpc_barrage_stub = None
self._console_service: ConsoleService | None = None
self._flight_service: ArrowFlightService | None = None
self._app_service: AppService | None = None
self._input_table_service: InputTableService | None = None
self._plugin_obj_service: PluginObjService | None = None
self._never_timeout = never_timeout
# The time.monotonic() time of the next token refresh, or None for no refresh.
self._next_refresh: float | None = None
self._refresh_thread: threading.Thread | None = None
self._session_type = session_type
self._flight_client: paflight.FlightClient | None = None
self._auth_handler = None
self._config_service: ConfigService | None = None
self._connect()
def __enter__(self) -> Session:
# A session does not reconnect. Its services and auth token are bound to its first connection.
if not self.is_connected:
raise DHError("the session is not connected. Create a new Session.")
return self
def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
self.close()
def __del__(self) -> None:
# Stop the release thread, but make no RPC. The garbage collector can run this on any thread, including the
# gRPC thread that delivers this session's RPC results. An RPC there waits forever for a result that only the
# blocked thread can deliver. The server expires the abandoned session on its own.
# During interpreter shutdown the release thread is a daemon that dies anyway, and module globals such as
# _STOP may already be cleared.
if sys.is_finalizing():
return
self._release_queue.put(_STOP)
def update_metadata(self, metadata: Iterable[tuple[str, str | bytes]]) -> None:
for header_tuple in metadata:
if header_tuple[0] == "authorization":
v = header_tuple[1]
self._auth_header_value = (
v if isinstance(v, bytes) else v.encode("ascii")
)
break
def wrap_rpc(self, stub_call: _NotBidiRpc, *args, **kwargs) -> Any:
if "metadata" in kwargs:
raise DHError(
'Internal error: "metadata" in kwargs not supported in wrap_rpc.'
)
kwargs["metadata"] = self.grpc_metadata
# We use a future to get a chance to process initial metadata before the call
# is completed
future = stub_call.future(*args, **kwargs)
self.update_metadata(future.initial_metadata())
# Now block until we get the result (or an exception)
return future.result()
def wrap_bidi_rpc(self, stub_call: _BidiRpc, *args, **kwargs) -> Any:
if "metadata" in kwargs:
raise DHError(
'Internal error: "metadata" in kwargs not supported in wrap_bidi_rpc.'
)
kwargs["metadata"] = self.grpc_metadata
response = stub_call(*args, **kwargs)
self.update_metadata(response.initial_metadata())
return response
@property
def host(self) -> str:
"""The host name of the server."""
return self._host
@property
def port(self) -> int:
"""The port number of the server."""
return self._port
@property
def tables(self) -> list[str]:
with self._r_lock:
fields = self._fetch_fields()
return [
field.field_name
for field in fields
if field.application_id == "scope"
and field.typed_ticket.type == "Table"
]
@property
def exportable_objects(self) -> dict[str, ServerObject]:
"""The objects the server can export to this session, keyed by field name. Each value is a ServerObject
holding the object's type and a ticket to it."""
with self._r_lock:
fields = self._fetch_fields()
return {
field.field_name: _server_object_from_proto(field.typed_ticket)
for field in fields
}
@property
def grpc_metadata(self) -> list[tuple[bytes, bytes]]:
header_value_snap = (
self._auth_header_value
) # ensure it doesn't change while doing multiple reads
if not header_value_snap or not isinstance(header_value_snap, bytes):
logger.warning(
f"{self._logpfx}: internal invariant violated, _auth_header_value={header_value_snap}"
)
tuple_l = []
else:
tuple_l = [(b"authorization", header_value_snap)]
if self._extra_headers:
tuple_l.extend(list(self._extra_headers.items()))
return tuple_l
@property
def table_service(self) -> TableService:
if not self._table_service:
with self._services_lock:
if not self._table_service:
self._table_service = TableService(self)
return self._table_service
@property
def session_service(self) -> SessionService:
if not self._session_service:
with self._services_lock:
if not self._session_service:
self._session_service = SessionService(self)
return self._session_service
@property
def console_service(self) -> ConsoleService:
if not self._console_service:
with self._services_lock:
if not self._console_service:
self._console_service = ConsoleService(self)
return self._console_service
@property
def flight_service(self) -> ArrowFlightService:
if not self._flight_service:
with self._services_lock:
if not self._flight_service:
self._flight_service = ArrowFlightService(self, self._flight_client)
return self._flight_service
@property
def app_service(self) -> AppService:
if not self._app_service:
with self._services_lock:
if not self._app_service:
self._app_service = AppService(self)
return self._app_service
@property
def config_service(self) -> ConfigService:
if not self._config_service:
with self._services_lock:
if not self._config_service:
self._config_service = ConfigService(self)
return self._config_service
@property
def input_table_service(self) -> InputTableService:
if not self._input_table_service:
with self._services_lock:
if not self._input_table_service:
self._input_table_service = InputTableService(self)
return self._input_table_service
@property
def plugin_object_service(self) -> PluginObjService:
if not self._plugin_obj_service:
with self._services_lock:
if not self._plugin_obj_service:
self._plugin_obj_service = PluginObjService(self)
return self._plugin_obj_service
def make_export_ticket(self, ticket_no: int | None = None) -> ExportTicket:
if not ticket_no:
ticket_no = self.next_export_ticket_number()
return ExportTicket.export_ticket(ticket_no)
def next_export_ticket_number(self) -> int:
with self._r_lock:
self._last_export_ticket_number += 1
if self._last_export_ticket_number == 2**31 - 1:
raise DHError("fatal error: out of free internal ticket")
return self._last_export_ticket_number
def _fetch_fields(self) -> list[Any]:
"""Returns a list of available fields on the server.
Raises:
DHError
"""
with self._r_lock:
list_fields = self.app_service.list_fields()
resp = next(list_fields)
if not list_fields.cancel():
raise DHError("could not cancel ListFields subscription")
return resp.created if resp.created else []
def _connect(self) -> None:
_trace(f"_connect id={id(self)}")
with self._r_lock:
_trace(f"_connect id={id(self)} connecting.")
try:
scheme = "grpc+tls" if self._use_tls else "grpc"
self._flight_client = paflight.FlightClient(
location=f"{scheme}://{self._host}:{self._port}",
middleware=[_DhClientAuthMiddlewareFactory(self)],
tls_root_certs=self._tls_root_certs,
cert_chain=self._client_cert_chain,
private_key=self._client_private_key,
generic_options=self._client_opts,
)
except Exception as e:
raise DHError("failed to connect to the server.") from e
self.grpc_channel = self.session_service.connect()
# This RPC will get is the configuration and will also bootstrap
# our authentication to the server by virtue of sending the right
# header: "authorization" header key and our selected header value.
# The implementation will process the initial headers coming back
# from the server which will contain the bearer token we will
# use in subsequent RPCs; the token will be included in the updated
# value for self._auth_header_value that will happen through a call
# to update_metadata.
config_dict = self.config_service.get_configuration_constants()
session_duration = config_dict.get("http.session.durationMs")
if not session_duration:
raise DHError("server configuration is missing http.session.durationMs")
self._timeout_seconds = int(session_duration.string_value) / 1000.0
# Random skew to ensure multiple processes that may have
# started together don't align retries.
skew = random()
# Backoff schedule for retries after consecutive failures to refresh auth token
self._refresh_backoff = [skew + 0.1, skew + 1, skew + 10]
if self._refresh_backoff[0] > self._timeout_seconds:
raise DHError(
f"server configuration http.session.durationMs={session_duration} is too small."
)
if 0.25 * self._timeout_seconds < self._refresh_backoff[-1]:
self._refresh_backoff.extend(
[
skew + 0.25 * self._timeout_seconds,
skew + 0.35 * self._timeout_seconds,
skew + 0.45 * self._timeout_seconds,
]
)
for i in range(1, len(self._refresh_backoff)):
if self._refresh_backoff[i] > self._timeout_seconds:
self._refresh_backoff = self._refresh_backoff[0:i]
break
self.is_connected = True
if self._never_timeout:
self._next_refresh = time.monotonic() + 0.5 * self._timeout_seconds
self._release_thread = threading.Thread(
target=_run_release_worker,
args=(weakref.ref(self), self._release_queue),
name=f"pydh.Session {id(self)} release",
daemon=True,
)
self._release_thread.start()
self._refresh_thread = None
if self._never_timeout:
self._refresh_thread = threading.Thread(
target=_run_token_refresher,
args=(weakref.ref(self),),
name=f"pydh.Session {id(self)} token refresh",
daemon=True,
)
self._refresh_thread.start()
def _seconds_until_refresh(self) -> float | None:
"""The seconds until the next token refresh, or None for no refresh."""
if self._next_refresh is None:
return None
return max(0.0, self._next_refresh - time.monotonic())
def _keep_alive(self) -> None:
"""Refreshes the auth token and schedules the next refresh. Runs on the session's token refresh thread."""
_trace("_keep_alive")
if not self.is_connected:
return
if self._refresh_token():
self._refresh_failures = 0
wakeup = 0.5 * self._timeout_seconds
else:
self._refresh_failures += 1
if self._refresh_failures >= len(self._refresh_backoff):
logger.critical(
f"Failed to refresh token {self._refresh_failures} times, will stop retrying."
)
self._next_refresh = None
return
wakeup = self._refresh_backoff[self._refresh_failures]
logger.warning(
f"{self._logpfx}: failed to refresh auth token (retry #{self._refresh_failures - 1})."
+ f" Will retry in {wakeup} seconds."
)
_trace(f"_keep_alive wakeup={wakeup}")
self._next_refresh = time.monotonic() + wakeup
def _refresh_token(self) -> bool:
_trace("_refresh_token")
try:
self.config_service.get_configuration_constants()
return True
except Exception as ex:
logger.warning(
f"{self._logpfx}: caught exception while refreshing auth token: {ex}."
)
return False
@property
def is_alive(self) -> bool:
"""Whether the session is alive."""
with self._r_lock:
if not self.is_connected:
return False
if self._never_timeout:
return True
try:
self.config_service.get_configuration_constants()
return True
except DHError:
self.is_connected = False
return False
[docs]
def close(self) -> None:
"""Closes the Session object if it hasn't timed out already.
Raises:
DHError
"""
with self._r_lock:
# Stop the release thread even if already disconnected. The server releases any tickets still queued.
self._release_queue.put(_STOP)
if not self.is_connected:
return
try:
self.session_service.close()
finally:
# Disconnect locally even if CloseSession fails.
if self.grpc_channel:
self.grpc_channel.close()
self.is_connected = False
self._last_export_ticket_number = 0
if self._flight_client:
self._flight_client.close()
[docs]
def release(self, ticket: Ticket) -> None:
"""Releases a ticket.
Args:
ticket (Ticket): the ticket to release
"""
self.session_service.release(ticket)
def _queue_release(self, ticket: Ticket) -> None:
"""Queues a ticket for the release thread to release. Unlike release, it makes no RPC, so a finalizer can call
it: queue.SimpleQueue.put is reentrant."""
self._release_queue.put(_ReleaseTicket(ticket))
# convenience/factory methods
[docs]
def run_script(self, script: str, systemic: bool | None = None) -> None:
"""Runs the supplied Python script on the server.
Args:
script (str): the Python script code
systemic (Optional[bool]): Whether to treat the code as systemically important. Defaults to None which uses the
default system behavior
Raises:
DHError
"""
response = self.console_service.run_script(script, systemic)
if response.error_message != "":
raise DHError("could not run script: " + response.error_message)
[docs]
def open_table(self, name: str) -> Table:
"""Opens a table in the global scope with the given name on the server.
Args:
name (str): the name of the table
Returns:
a Table object
Raises:
DHError
"""
ticket = ScopeTicket.scope_ticket(name)
fake_table = Table(session=self, ticket=ticket)
try:
table_op = FetchTableOp()
return self.table_service.grpc_table_op(fake_table, table_op)
except Exception as e:
if isinstance(e.__cause__, grpc.RpcError):
if e.__cause__.code() == grpc.StatusCode.INVALID_ARGUMENT:
raise DHError(f"no table by the name {name}") from None
raise
finally:
# Explicitly close the table without releasing it (because it isn't ours)
fake_table._closed = True
fake_table.schema = None
[docs]
def bind_table(self, name: str, table: Table) -> None:
"""Binds a table to the given name on the server so that it can be referenced by that name.
Args:
name (str): name for the table
table (Table): a Table object
Raises:
DHError
"""
self.console_service.bind_table(table=table, variable_name=name)
[docs]
def publish(self, source_ticket: Ticket, result_ticket: Ticket) -> None:
"""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 :meth:`.fetch` method to share server objects between sessions.
Args:
source_ticket (Ticket): The source ticket to publish from.
result_ticket (Ticket): The result ticket to publish to.
Raises:
DHError: If the operation fails.
"""
if not self._session_service:
raise DHError("session service is not available")
self._session_service.publish(source_ticket, result_ticket)
[docs]
def fetch(self, ticket: Ticket) -> ExportTicket:
"""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 :class:`~.plugin_client.PluginClient`, :class:`~.plugin_client.Fetchable`.
This method is used together with the :meth:`.publish` method to share server objects between sessions.
Args:
ticket (Ticket): a ticket
Returns:
an ExportTicket object
Raises:
DHError
"""
if not self._session_service:
raise DHError("session service is not available")
return self._session_service.fetch(ticket)
[docs]
def publish_table(self, ticket: SharedTicket, table: Table) -> None:
"""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.
Args:
ticket (SharedTicket): a SharedTicket object
table (Table): a Table object
Raises:
DHError
"""
self.publish(table.ticket, ticket)
[docs]
def fetch_table(self, ticket: SharedTicket) -> Table:
"""Fetches a table by ticket.
Args:
ticket (SharedTicket): a ticket
Returns:
a Table object
Raises:
DHError
"""
try:
return self.table_service.fetch_etcr(ticket.pb_ticket)
except Exception as e:
raise DHError("could not fetch table by ticket") from e
[docs]
def time_table(
self,
period: int | str,
start_time: int | str | None = None,
blink_table: bool = False,
) -> Table:
"""Creates a time table on the server.
Args:
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 (Optional[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): if the time table should be a blink table, defaults to False
Returns:
a Table object
Raises:
DHError
"""
table_op = TimeTableOp(
start_time=start_time, period=period, blink_table=blink_table
)
return self.table_service.grpc_table_op(None, table_op)
[docs]
def empty_table(self, size: int) -> Table:
"""Creates an empty table on the server.
Args:
size (int): the size of the empty table in number of rows
Returns:
a Table object
Raises:
DHError
"""
table_op = EmptyTableOp(size=size)
return self.table_service.grpc_table_op(None, table_op)
[docs]
def import_table(self, data: pa.Table) -> Table:
"""Imports the pyarrow table as a new Deephaven table on the server.
Deephaven supports most of the Arrow data types. Before sending any data, the client checks each field's data
type and rejects the import if it does not map the type. A dictionary-encoded or run-end encoded field is
checked by the type of its values.
Args:
data (pa.Table): a pyarrow Table object
Returns:
a Table object
Raises:
DHError
"""
return self.flight_service.import_table(data=data)
[docs]
def merge_tables(self, tables: list[Table], order_by: str = "") -> Table:
"""Merges several tables into one table on the server.
Args:
tables (list[Table]): the list of Table objects to merge
order_by (str): the order by column name, if specified, the input tables must already be sorted on this
column, and the result table will be sorted on it as well, default is ""
Returns:
a Table object
Raises:
DHError
"""
table_op = MergeTablesOp(tables=tables, key_column=order_by)
return self.table_service.grpc_table_op(None, table_op)
[docs]
def query(self, table: Table) -> Query:
"""Creates a Query object to define a sequence of operations on a Deephaven table.
Args:
table (Table): a Table object
Returns:
a Query object
Raises:
DHError
"""
return Query(self, table)
[docs]
def plugin_client(self, server_obj: ServerObject) -> PluginClient:
"""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 PluginClient(self, server_obj)