pyopticon.socket_client module

class pyopticon.socket_client.PyOpticonSocketClient(**kwargs)

Bases: object

Class representing a client-side socket connection to a PyOpticon dashboard. Can be used to send various commands and queries to the dashboard from a separate Python script.

Parameters:

• socket_number (int, optional) – The port on which to open the socket connection. Defaults to 12345.

• handle_errors (str, optional) – How to handle errors reported by the dashboard when attempting to execute a socket command. ‘none’ does nothing, ‘print’ prints a warning to console but continues executing, ‘exception’ raises an exception. Defaults to ‘none’.

_check_errors(source, result)

Checks a string returned by the dashboard for whether it’s an error message (beginning with ‘Error: ‘) and, if so, processes it.

Parameters:

• source (str) – The command, e.g. ‘get’, that the dashboard was trying to execute.

• result (str) – The string that the dashboard sent through the socket as its reply, which may or may not be an error message.

_query_socket(to_send)

Converts a dict to a JSON string and sends it through the socket.

Parameters:

to_send (dict) – The dict to send to the dashboard.

get_field(widget_nickname, field_name, printout=True)

Gets the current value of a field from the dashboard via the socket.

Parameters:

• widget_nickname (str) – The nickname of the widget to query

• field_name (str) – The field to query

• printout (bool, optional) – Whether the dashboard should print to its own console a record that the socket command was received. Defaults to True.

Returns:

The current value of the specified field.

Return type:

str

set_field(widget_nickname, field_name, new_value, printout=True)

Sets the value of a field to a specified value via the socket.

Parameters:

• widget_nickname (str) – The nickname of the widget whose field to set

• field_name (str) – The field to set

• printout (bool, optional) – Whether the dashboard should print to its own console a record that the socket command was received. Defaults to True.

do_confirm(widget_nickname, printout=True)

Executes a widget’s ‘confirm’ method via the socket.

Parameters:

• widget_nickname (str) – The nickname of the widget to confirm

• printout (bool, optional) – Whether the dashboard should print to its own console a record that the socket command was received. Defaults to True.

do_eval(expression, printout=True)

Tells the dashboard to evaluate an expression and return the result. Eval is run in a namespace containing the methods get_dashboard(), which returns a dashboard object, and do_threadsafe(f), which executes a function f in the main GUI thread.

Parameters:

• expression – The expression to evaluate

• printout (bool, optional) – Whether the dashboard should print to its own console a record that the socket command was received. Defaults to True.

do_exec(fn, printout=True)

Tells the dashboard to execute a given function. Exec is run in a namespace containing the methods get_dashboard(), which returns a dashboard object, and do_threadsafe(f), which executes a function f in the main GUI thread.

The code to execute should be supplied as a function. The object uses the ‘inspect’ module to get the function’s source as a string and pass it through the socket. This lets you benefit from normal syntax highlighting in writing your function, rather than having to define it as a string with a bunch of escaped newline and tab characters in it. Due to the ‘inspect’ module’s limitations, the function must be defined separately and then passed to do_exec, rather than being defined inline with the do_exec call using a lambda function. E.g., s.do_exec(lambda: print(“Hi”)) is invalid. See the tutorial.

Parameters:

• expression – The code to run

• printout (bool, optional) – Whether the dashboard should print to its own console a record that the socket command was received. Defaults to True.

close()

Send a message via the socket telling the Dashboard to close the socket on its end. Close the socket connection on the client end.