deephaven.table_listener

This module provides utilities for listening to table changes.

class MergedListener[source]

Bases: ABC

An abstract multi-table listener class that should be subclassed by any user multi-table listener class. It provides a default implementation for the on_error method that simply prints out the error.

on_error(e)[source]

The callback method on a listener object that handles the received error. The default implementation simply prints the error.

Parameters:

e (Exception) – the exception that occurred during the listener’s execution.

Return type:

None

abstract on_update(updates, is_replay)[source]

The required method on a listener object that receives table updates from the tables that are listened to.

Return type:

None

class MergedListenerHandle(tables, listener, description=None, dependencies=None, on_error=None)[source]

Bases: JObjectWrapper

A handle to manage a merged listener’s lifecycle.

Creates a new MergedListenerHandle with the provided listener recorders and dependencies.

Table change events are processed by ‘listener’, which can be either (1) a callable (e.g. function) or (2) an instance of a MergedListener subclass that must override the abstract “on_update” method, and optionally override the default “on_error” method.

The callable or the on_update method must have the following signature. *(updates: Dict[Table, TableUpdate], is_replay: bool): support replaying the initial table snapshots and normal table updates The ‘updates’ parameter is a dictionary of Table to TableUpdate; The ‘is_replay’ parameter is used only by replay listeners, it is set to ‘True’ when replaying the initial snapshots and ‘False’ during normal updates.

Note: Don’t do table operations in the listener. Do them beforehand, and add the results as dependencies.

Parameters:

  • tables (Sequence[Table]) – tables to listen to

  • listener (Union[Callable[[Dict[Table, TableUpdate], bool], None], MergedListener]) – listener to process table updates from the tables.

  • description (str, optional) – description for the UpdatePerformanceTracker to append to the listener’s entry

  • dependencies (Union[Table, Sequence[Table]]) –

    tables that must be satisfied before the listener’s execution. A refreshing table is considered to be satisfied if all possible updates to the table have been processed in the current update graph cycle. A static table is always considered to be satisfied. If a specified table is refreshing, it must belong to the same update graph as the table being listened to. Default is None.

    Dependencies ensure that the listener can safely access the dependent tables during its execution. This mainly includes reading the data from the tables. While performing operations on the dependent tables in the listener is safe, it is not recommended because reading or operating on the result tables of those operations may not be safe. It is best to perform the operations on the dependent tables beforehand, and then add the result tables as dependencies to the listener so that they can be safely read in it.

  • on_error (Callable[[Exception], None]) – a callback function to be invoked when an error occurs during the listener’s execution. It should only be set when the listener is a function, not when it is an instance of MergedListener. When the listener is a MergedListener, MergedListener.on_error will be used. Defaults to None. When None, a default callback function will be provided that simply prints out the received exception. If the callback function itself raises an exception, the new exception will be logged in the Deephaven server log and will not be further processed by the server.

Raises:

DHError –

j_object_type

alias of PythonMergedListenerAdapter

start(do_replay=False)[source]

Start the listener by registering it with the tables and listening for updates.

Parameters:

do_replay (bool) – whether to replay the initial snapshots of the tables, default is False

Raises:

DHError –

Return type:

None

stop()[source]

Stop the listener.

Return type:

None

class TableListener[source]

Bases: ABC

An abstract table listener class that should be subclassed by any user table listener class. It provides a default implementation for the on_error method that simply prints out the error.

on_error(e)[source]

The callback method on a listener object that handles the received error. The default implementation simply prints the error.

Parameters:

e (Exception) – the exception that occurred during the listener’s execution.

Return type:

None

abstract on_update(update, is_replay)[source]

The required method on a listener object that receives table updates.

Return type:

None

class TableListenerHandle(t, listener, description=None, dependencies=None, on_error=None)[source]

Bases: JObjectWrapper

A handle to manage a table listener’s lifecycle.

Creates a new table listener handle with dependencies.

Table change events are processed by ‘listener’, which can be either (1) a callable (e.g. function) or (2) an instance of a TableListener subclass that must override the abstract “on_update” method, and optionally override the default “on_error” method.

The callable or the on_update method must have the following signatures. * (update: TableUpdate, is_replay: bool): support replaying the initial table snapshot and normal table updates The ‘update’ parameter is an object that describes the table update; The ‘is_replay’ parameter is used only by replay listeners, it is set to ‘True’ when replaying the initial snapshot and ‘False’ during normal updates.

Note: Don’t do table operations in the listener. Do them beforehand, and add the results as dependencies.

Parameters:

  • t (Table) – table to listen to

  • listener (Union[Callable[[TableUpdate, bool], None], TableListener]) – listener for table changes

  • description (str, optional) – description for the UpdatePerformanceTracker to append to the listener’s entry description, default is None

  • dependencies (Union[Table, Sequence[Table]]) –

    tables that must be satisfied before the listener’s execution. A refreshing table is considered to be satisfied if all possible updates to the table have been processed in the current update graph cycle. A static table is always considered to be satisfied. If a specified table is refreshing, it must belong to the same update graph as the table being listened to. Default is None.

    Dependencies ensure that the listener can safely access the dependent tables during its execution. This mainly includes reading the data from the tables. While performing operations on the dependent tables in the listener is safe, it is not recommended because reading or operating on the result tables of those operations may not be safe. It is best to perform the operations on the dependent tables beforehand, and then add the result tables as dependencies to the listener so that they can be safely read in it.

  • on_error (Callable[[Exception], None]) – a callback function to be invoked when an error occurs during the listener’s execution. It should only be set when the listener is a function, not when it is an instance of TableListener. When the listener is a TableListener, TableListener.on_error will be used. Defaults to None. When None, a default callback function will be provided that simply prints out the received exception. If the callback function itself raises an exception, the new exception will be logged in the Deephaven server log and will not be further processed by the server.

Raises:

DHError –

j_object_type

alias of PythonReplayListenerAdapter

start(do_replay=False)[source]

Start the listener by registering it with the table and listening for updates.

Parameters:

do_replay (bool) – whether to replay the initial snapshot of the table, default is False

Raises:

DHError –

Return type:

None

stop()[source]

Stop the listener by de-registering it from the table and stop listening for updates.

Return type:

None

class TableUpdate(table, j_table_update)[source]

Bases: JObjectWrapper

A TableUpdate object represents a table update event. It contains the added, removed, and modified rows in the table.

added(cols=None)[source]

Returns a dict with each key being a column name and each value being a NumPy array of all the added rows in the columns.

Parameters:

cols (Union[str, List[str]) – the column(s) for which to return the added rows

Return type:

Dict[str, ndarray]

Returns:

a dict

added_chunks(chunk_size, cols=None)[source]

Returns a generator that on each iteration, only returns a chunk of added rows in the form of a dict with each key being a column name and each value being a NumPy array of the rows in the chunk.

Parameters:

  • chunk_size (int) – the size of the chunk

  • cols (Union[str, List[str]]) – the columns(s) for which to return the added rows

Return type:

Generator[Dict[str, ndarray], None, None]

Returns:

a generator

j_object_type

alias of TableUpdate

modified(cols=None)[source]

Returns a dict with each key being a column name and each value being a NumPy array of the current values of all the modified rows in the columns.

Parameters:

cols (Union[str, List[str]) – the column(s) for which to return the added rows

Return type:

Dict[str, ndarray]

Returns:

a dict

modified_chunks(chunk_size, cols=None)[source]

Returns a generator that on each iteration, only returns a chunk of modified rows in the form of a dict with each key being a column name and each value being a NumPy array of the current values of the rows in the chunk.

Parameters:

  • chunk_size (int) – the size of the chunk

  • cols (Union[str, List[str]]) – the columns(s) for which to return the added rows

Return type:

Generator[Dict[str, ndarray], None, None]

Returns:

a generator

property modified_columns

The list of modified columns in this update.

modified_prev(cols=None)[source]

Returns a dict with each key being a column name and each value being a NumPy array of the previous values of all the modified rows in the columns.

Parameters:

cols (Union[str, List[str]) – the column(s) for which to return the added rows

Return type:

Dict[str, ndarray]

Returns:

a dict

modified_prev_chunks(chunk_size, cols=None)[source]

Returns a generator that on each iteration, only returns a chunk of modified rows in the form of a dict with each key being a column name and each value being a NumPy array of the previous values of the rows in the chunk.

Parameters:

  • chunk_size (int) – the size of the chunk

  • cols (Union[str, List[str]]) – the columns(s) for which to return the added rows

Return type:

Generator[Dict[str, ndarray], None, None]

Returns:

a generator

removed(cols=None)[source]

Returns a dict with each key being a column name and each value being a NumPy array of all the removed rows in the columns.

Parameters:

cols (Union[str, List[str]) – the column(s) for which to return the added rows

Return type:

Dict[str, ndarray]

Returns:

a dict

removed_chunks(chunk_size, cols=None)[source]

Returns a generator that on each iteration, only returns a chunk of removed rows in the form of a dict with each key being a column name and each value being a NumPy array of the rows in the chunk.

Parameters:

  • chunk_size (int) – the size of the chunk

  • cols (Union[str, List[str]]) – the columns(s) for which to return the added rows

Return type:

Generator[Dict[str, ndarray], None, None]

Returns:

a generator

listen(t, listener, description=None, do_replay=False, dependencies=None, on_error=None)[source]

This is a convenience function that creates a TableListenerHandle object and immediately starts it to listen for table updates.

The function returns the created TableListenerHandle object whose ‘stop’ method can be called to stop listening. If it goes out of scope and is garbage collected, the listener will stop receiving any table updates.

Note: Don’t do table operations in the listener. Do them beforehand, and add the results as dependencies.

Parameters:

  • t (Table) – table to listen to

  • listener (Union[Callable[[TableUpdate, bool], None], TableListener]) – listener for table changes

  • description (str, optional) – description for the UpdatePerformanceTracker to append to the listener’s entry description, default is None

  • do_replay (bool) – whether to replay the initial snapshot of the table, default is False

  • dependencies (Union[Table, Sequence[Table]]) –

    tables that must be satisfied before the listener’s execution. A refreshing table is considered to be satisfied if all possible updates to the table have been processed in the current update graph cycle. A static table is always considered to be satisfied. If a specified table is refreshing, it must belong to the same update graph as the table being listened to. Default is None.

    Dependencies ensure that the listener can safely access the dependent tables during its execution. This mainly includes reading the data from the tables. While performing operations on the dependent tables in the listener is safe, it is not recommended because reading or operating on the result tables of those operations may not be safe. It is best to perform the operations on the dependent tables beforehand, and then add the result tables as dependencies to the listener so that they can be safely read in it.

  • on_error (Callable[[Exception], None]) – a callback function to be invoked when an error occurs during the listener’s execution. It should only be set when the listener is a function, not when it is an instance of TableListener. When the listener is a TableListener, TableListener.on_error will be used. Defaults to None. When None, a default callback function will be provided that simply prints out the received exception. If the callback function itself raises an exception, the new exception will be logged in the Deephaven server log and will not be further processed by the server.

Return type:

TableListenerHandle

Returns:

a TableListenerHandle

Raises:

DHError –

merged_listen(tables, listener, do_replay=False, description=None, dependencies=None, on_error=None)[source]

This is a convenience function that creates a MergedListenerHandle object and immediately starts it to listen for table updates.

The function returns the created MergedListenerHandle object whose ‘stop’ method can be called to stop listening. If it goes out of scope and is garbage collected, the listener will stop receiving any table updates.

Note: Don’t do table operations in the listener. Do them beforehand, and add the results as dependencies.

Parameters:

  • tables (Sequence[Table]) – tables to listen to.

  • listener (Union[Callable[[Dict[Table, TableUpdate]], None], MergedListener]) – listener to process table updates from the tables.

  • description (str, optional) – description for the UpdatePerformanceTracker to append to the listener’s entry description, default is None

  • do_replay (bool) – whether to replay the initial snapshots of the tables, default is False

  • dependencies (Union[Table, Sequence[Table]]) –

    tables that must be satisfied before the listener’s execution. A refreshing table is considered to be satisfied if all possible updates to the table have been processed in the current update graph cycle. A static table is always considered to be satisfied. If a specified table is refreshing, it must belong to the same update graph as the table being listened to. Default is None.

    Dependencies ensure that the listener can safely access the dependent tables during its execution. This mainly includes reading the data from the tables. While performing operations on the dependent tables in the listener is safe, it is not recommended because reading or operating on the result tables of those operations may not be safe. It is best to perform the operations on the dependent tables beforehand, and then add the result tables as dependencies to the listener so that they can be safely read in it.

  • on_error (Callable[[Exception], None]) – a callback function to be invoked when an error occurs during the listener’s execution. It should only be set when the listener is a function, not when it is an instance of MergedListener. When the listener is a MergedListener, MergedListener.on_error will be used. Defaults to None. When None, a default callback function will be provided that simply prints out the received exception. If the callback function itself raises an exception, the new exception will be logged in the Deephaven server log and will not be further processed by the server.

Return type:

MergedListenerHandle