stormvogel.communication_server¶

Communication from Javascript/HTML to IPython/Jupyter lab using a local server and requests. Initialization by user is not recommended. It should happen automatically when creating a network.Network.

Remember that you need AT LEAST ONE AVAILABLE (and sometimes also forwarded) PORT BETWEEN min_port AND max_port IN ORDER FOR IT TO WORK.

Attributes¶

`enable_server`	Disable if you don't want to use an internal communication server. Some features might break.
`localhost_address`
`min_port`
`max_port`
`port_range`	The range of ports that stromvogel uses. They should all be forwarded if you're on an http tunnel.
`server_port`	Global variable storing the port that is being used by this process. Changes when initialize_server is called.
`events`	Dictionary that stores currently active events, along with their function, hashed by randomly generated ids.
`server_running`	Global variable that is set to true when the server is running.
`server`	Global variable holding the server used for this notebook. None if not initialized.

Classes¶

CommunicationServer

Run a web server in the background to receive Javascript communications.

Functions¶

`random_word`(→ str)	Generate a random word of length k.
`__warn_request`()
`__warn_server`()
`__warn_no_free_port`()
`is_port_free`(→ bool)	Return `True` if the specified port is free on `localhost_address`.
`find_free_port`(→ int)	Find a free port in the configured port range.
`initialize_server`(→ CommunicationServer \| None)	If server is None, then create a new server and store it in global variable server.

Module Contents¶

stormvogel.communication_server.random_word(k: int) → str¶

Generate a random word of length k.

Parameters:: k – Length of the random word.
Returns:: A random string of ASCII letters.

stormvogel.communication_server.enable_server: bool = True¶: Disable if you don’t want to use an internal communication server. Some features might break.

stormvogel.communication_server.localhost_address: str = '127.0.0.1'¶

stormvogel.communication_server.min_port = 8889¶

stormvogel.communication_server.max_port = 8905¶

stormvogel.communication_server.port_range¶: The range of ports that stromvogel uses. They should all be forwarded if you’re on an http tunnel.

stormvogel.communication_server.server_port: int = 8888¶: Global variable storing the port that is being used by this process. Changes when initialize_server is called.

stormvogel.communication_server.events: dict[str, Callable[[str], Any]]¶: Dictionary that stores currently active events, along with their function, hashed by randomly generated ids.

stormvogel.communication_server.server_running: bool = False¶: Global variable that is set to true when the server is running.

stormvogel.communication_server.server: CommunicationServer | None = None¶: Global variable holding the server used for this notebook. None if not initialized.

class stormvogel.communication_server.CommunicationServer(server_port: int = 8080)¶

Run a web server in the background to receive Javascript communications.

The server maintains a list of events, each with a unique id. The Javascript code sends a POST request to the server with the id and the data. The server then looks up the event with that id and calls the function associated with it.

server_port: int = 8080¶

web_server: http.server.HTTPServer¶

__run_server()¶

Run the server on a background thread.

Set the global variable server_running to True once started. This prevents making requests too early.

add_event(js: str, function: Callable[[str], Any]) → str¶

Add an event using some JavaScript code.

Within the js code, use the special function FUNCTION(...) to call the Python function.

Example:

js = "FUNCTION(37 + 42);"
function = lambda data: print(data)

The arithmetic is performed in Javascript, and the result is printed in Python. Note that the function is called with the result of the arithmetic as a string.

Parameters:

js – JavaScript code containing a FUNCTION(...) call.
function – Python callable invoked with the JavaScript result as a string.

Returns:

Event id which can be used to remove the event later.

remove_event(event_id: str) → Callable[[str], Any]¶

Remove the event associated with the given event id.

Parameters:: event_id – The id of the event to remove.
Returns:: The callable that was associated with the event.

result(js: str, timeout_seconds: float = 2.0) → str¶

Execute some JavaScript and return the result.

Use the special function RETURN(...) in js to send the result back.

Example:

js = "RETURN(37 + 42);"

The arithmetic is executed in Javascript, and "79" is returned as a string.

Parameters:

js – JavaScript code containing a RETURN(...) call.
timeout_seconds – Seconds to wait for a result before raising.

Returns:

The result from JavaScript as a string.

Raises:

TimeoutError – If no result is received within timeout_seconds.

stormvogel.communication_server.__warn_request()¶

stormvogel.communication_server.__warn_server()¶

stormvogel.communication_server.__warn_no_free_port()¶

stormvogel.communication_server.is_port_free(port: int) → bool¶

Return True if the specified port is free on localhost_address.

Parameters:: port – Port number to check.
Returns:: True if the port is free, False otherwise.

stormvogel.communication_server.find_free_port() → int¶

Find a free port in the configured port range.

Returns:: A free port number, or -1 if none are available.

stormvogel.communication_server.initialize_server(silent=True) → CommunicationServer | None¶

If server is None, then create a new server and store it in global variable server. Use the port stored in global variable server_port. If the server is already initialized, just return it.

If the server has not been created yet, create one on the first free port in the configured range and store it in the global server variable. If already initialized, return the existing server.

Returns:: The server instance, or None if initialization failed or is disabled.