Selection¶

Note

All methods, from detroit.selection.Selection, remain the same for LiveSelection (except it returns a LiveSelection and not a Selection).

detroit_live.create(name: str) → LiveSelection¶

Given the specified element name, returns a single-element selection containing a detached element of the given name in the current document. This method assumes the HTML namespace, so you must specify a namespace explicitly when creating SVG or other non-HTML elements.

Parameters:: name (str) – Tag name
Returns:: XML tree
Return type:: Selection

detroit_live.select(node: Element) → LiveSelection¶

Returns a selection object given a node

Parameters:

node (etree.Element) – Node
ref_selection (LiveSelection | None) – Reference selection for sharing data, tree and events attributes

Returns:

Selection object

Return type:

LiveSelection

class detroit_live.selection.selection.LiveSelection(groups: list[list[Element]], parents: list[Element], enter: list[EnterNode[T]] | None = None, exit: list[Element] = None)¶

A selection is a set of elements from the DOM. Typically these elements are identified by selectors such as .fancy for elements with the class fancy, or div to select DIV elements.

Selection methods come in two forms, select and select_all: the former selects only the first matching element, while the latter selects all matching elements in document order. The top-level selection methods, d3.select and d3.select_all, query the entire document; the subselection methods, selection.select and selection.select_all, restrict selection to descendants of the selected elements.

By convention, selection methods that return the current selection such as selection.attr use four spaces of indent, while methods that return a new selection use only two. This helps reveal changes of context by making them stick out of the chain:

Parameters:

groups (list[list[etree.Element]]) – List of groups of selected nodes given its parent.
parents (list[etree.Element]) – List of parents related to groups.
enter (list[EnterNode[T]] | None = None) – List of placeholder nodes for each datum that had no corresponding DOM element in the selection.
exit (list[etree.Element] = None) – List of existing DOM elements in the selection for which no new datum was found.

Examples

>>> body = d3.create("body")
>>> (
...     body
...     .append("svg")
...     .attr("width", 960)
...     .attr("height", 500)
...     .append("g")
...     .attr("transform", "translate(20, 20)")
...     .append("rect")
...     .attr("width", 920)
...     .attr("height", 460)
... )
>>> print(body.to_string())
<body>
  <svg xmlns="http://www.w3.org/2000/svg" weight="960" height="500">
    <g transform="translate(20, 20)">
      <rect width="920" height="460"/>
    </g>
  </svg>
</body>
>>> str(body)
'<body><svg xmlns="http://www.w3.org/2000/svg" weight="960" height="500"><g transform="translate(20, 20)"><rect width="920" height="460"/></g></svg></body>'

Adds a listener to each selected element for the specified event typename if the specified listener is not None. Else, it removes the listener given the specified event typename.

Parameters:

typename (str) – Event typename
listener (Callable[[Event, T | None, Optional[etree.Element]], None] | None) – Listener function
extra_nodes (list[etree.Element] | None) – Extra nodes to update when the listener is called
active (bool) – False if you want to create the event listener but not active when the application is launched. It is useful when you want to activate this event listener only when another event listener was activated.
target (str | None) – Javascript target on which the event listener is added.

Returns:

Itself

Return type:

LiveSelection

set_event(typename: str, active: bool) → LiveSelection¶

Updates selected event listeners for being active or not given the specified active value.

Parameters:

typename (str) – Event typename
active (bool) – True for activating event listeners else False

Returns:

Itself

Return type:

LiveSelection

create_app(name: str | None = None, html: Callable[[LiveSelection, str], str] | None = None, host: str | None = None, port: int | None = None) → App¶

Creates an application for allowing interactivity. Use App.run to start the application.

This is best used for development only, see Hypercorn for production servers.

Parameters:

name (str | None) – Name of the application
html (Callable[[LiveSelection, str], str] | None) – Function to transform the selection and a script content into a HTML content. Event listeners are parsed and joined as a string variable script which should be placed into a <script> tag in order to communicate events via websocket.
host (str | None) – Hostname to listen on. By default this is loopback only, use 0.0.0.0 to have the server listen externally.
port (int | None) – Port number to listen on.

Returns:

Application for allowing interactivity.

Return type:

App

Quart Application¶

The following class inherits from quart.app.Quart class and has almost the same behavior. The only thing changed is its signal_handler function :

def _signal_handler(*_: Any) -> None:
    # Patch from https://github.com/tf198/quart/commit/a6a9ec1e5bdaa4d5e410b4150fa95b5d870af262
    # See discussions in https://github.com/python/cpython/issues/123720
    # and the issue https://github.com/pallets/quart/issues/333
    for task in asyncio.all_tasks():
        if task.get_coro().__name__ in ["handle_websocket", "handle_request"]:
            task.cancel()
    shutdown_event.set()

This modification helps to have a better graceful exit.

class detroit_live.selection.app.App(import_name: str, static_url_path: str | None = None, static_folder: str | None = 'static', static_host: str | None = None, host_matching: bool = False, subdomain_matching: bool = False, template_folder: str | None = 'templates', instance_path: str | None = None, instance_relative_config: bool = False, root_path: str | None = None)¶

Run this application.

This is best used for development only, see Hypercorn for production servers.

Parameters:

debug (bool | None) – If set enable (or disable) debug mode and debug output.
use_reloader (bool) – Automatically reload on code changes.
loop (asyncio.AbstractEventLoop | None) – Asyncio loop to create the server in, if None, take default one. If specified it is the caller’s responsibility to close and cleanup the loop.
ca_certs (str | None) – Path to the SSL CA certificate file.
certfile (str | None) – Path to the SSL certificate file.
keyfile (str | None) – Path to the SSL key file.

Note

The parameters host and port from the original signature are passed through attributes to avoid copied arguments in LiveSelection.create_app and App.run.