Selections¶

ElementSelection¶

class api.ElementSelection(context: api.utils.ElementContext)[source]¶

attrs(attrs: Union[Callable[[Any], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]], Callable[[Any, int], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]] = {}, **kwargs: Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]) → S[source]¶

Applies a dictionary of attributes to all selected elements.

All attributes correspond to the available methods. Most attribute endpoints can be provided either as a single value, or as partial dictionary in the form: * value: The attribute value. * duration: The duration of the animation, see duration(). * ease: The animation ease, see ease(). * highlight: Whether the change is temporary, see highlight(). * linger: How long a highlight should last, see highlight(). * Some attributes may also contain additional properties.

The whole dictionary, or any of its direct entries, can be provided as an [[ElementFn]].

nodes.size((20, 30))                 .pos(lambda _, i: (i * 10, 0))                 .svgattr('stroke', 'blue')                 .duration(2.5).color('red')

# is equivalent to
nodes.attrs(
   size=[20, 30],
   pos=lambda _, i: (i * 10, 0),
   svgattrs: { stroke: "blue" },
   color={
       "value": "red",
       "duration": 2.5,
   },
)

The whole dictionary, or any of its direct entries, can be provided as an ElementFn. Entries can also be provided using keyword arguments.

Parameters: attrs (dict) – An attribute dictionary.

add(attrs: Union[Callable[[Any], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]], Callable[[Any, int], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]] = {}, **kwargs: Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]) → S[source]¶

Adds all selected elements to the canvas with the given initial attributes.

Parameters: attrs (ElementArg[Mapping]) – An attribute dictionary, see ElementAttrs.
Returns: A new instance of the current selection with animations disabled, to allow for further attribute initialisation.

remove() → S[source]¶: Removes all selected elements, resetting their attributes and layout state.

visible(visible: Union[Callable[[Any], bool], Callable[[Any, int], bool], bool]) → S[source]¶

Sets whether or not the elements in the current selection should be visible. This can be animated in the same way as additions and removals. However, in contrast to removing, disabling visibility will not clear attributes or affect layout.

Parameters: visible (ElementArg[bool]) – Whether or not the elements should be visible.

svgattr(key: str, value: Union[Callable[[Any], Union[str, int, float]], Callable[[Any, int], Union[str, int, float]], str, int, float])[source]¶

Sets a custom SVG attribute on the element. The root SVG tag is <shape> for nodes, <path> for edges, <text> for labels, and <svg> for the canvas.

Note that when using attrs(), SVG attributes should be provided as a dictionary under the key svgattrs.

Parameters

key (str) – The name of the SVG attribute.
value (ElementArg[Union[str, int, float]]) – The value of the SVG attribute.

withQ(queue: Optional[Any] = 0) → S[source]¶

Sets the event queue to use for all events triggered by the selection. Each queue handles events independently, and all queues execute in parallel, which enables multiple animations to run simultaneously.

The None queue is special; all events added to it will execute immediately. The default queue ID is 0.

Parameters: queue (Union[str, int, None]) – The name of the queue. This can be any string or number, or None for the immediate queue. Defaults to 0.
Returns: A new instance of the current selection using the specified event queue.

duration(seconds: Union[Callable[[Any], Union[int, float]], Callable[[Any, int], Union[int, float]], int, float]) → S[source]¶

Configures the duration of all animations triggered by the selection. A duration of 0 will ensure that changes occur immediately. The default duration is usually 0.5.

Parameters: seconds (Union[int, float]) – The animation duration, in seconds.
Returns: A new instance of the current selection using the given animation duration.

ease(ease: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Configures the ease function used in all animations triggered by the selection. This will affect the way attributes transition from one value to another. More information is available here: https://github.com/d3/d3-ease.

Parameters

ease (str) –

The name of the ease function, based on the functions found in D3. The full list is below:

”linear”, “poly”, “poly-in”, “poly-out”, “poly-in-out”, “quad”, “quad-in”, “quad-out”, “quad-in-out”, “cubic”, “cubic-in”, “cubic-out”, “cubic-in-out”, “sin”, “sin-in”, “sin-out”, “sin-in-out”, “exp”, “exp-in”, “exp-out”, “exp-in-out”, “circle”, “circle-in”, “circle-out”, “circle-in-out”, “elastic”, “elastic-in”, “elastic-out”, “elastic-in-out”, “back”, “back-in”, “back-out”, “back-in-out”, “bounce”, “bounce-in”, “bounce-out”, “bounce-in-out”.

Returns

A new instance of the current selection using the given animation ease.

highlight(seconds: Optional[Union[Callable[[Any], Union[int, float]], Callable[[Any, int], Union[int, float]], int, float]] = None) → S[source]¶

Returns a new selection through which all attribute changes are temporary. This is typically used to draw attention to a certain element without permanently changing its attributes.

Parameters: seconds (Optional[ElementArg[Union[int, float]]]) – The amount of time attributes should remain ‘highlighted’, in seconds, before changing back to their original values. Defaults to 0.5.
Returns: A new instance of the current selection, where all attribute changes are temporary.

pause(seconds: Union[int, float]) → S[source]¶

Adds a pause to the current event queue. The pause will only start once all previous pauses have finished. This is a shortcut for pause().

Parameters: seconds (Union[int, float]) – The duration of the pause, in seconds.

data(data: Union[Iterable[Any], Callable[[Any], Any], Callable[[Any, int], Any]]) → S[source]¶

Binds the selection to a list of data values. This will determine the data argument to provide whenever an ElementFn is used.

You can also provide a function to map the current data list to a new one.

Parameters: data (Union[Iterable[Any], ElementFn[Any]]) – Either a list of data values (which must have the same length as the number of elements in the selection), or a function which maps the current data list.
Raises: Exception – If the length of the data does not equal the number of elements in the selection.
Returns: A new instance of the current selection bound to the given data.

Canvas¶

class api.Canvas(context: api.utils.ElementContext)[source]¶

node(id: Any) → api.NodeSelection.NodeSelection[source]¶

Selects a node by its ID. Use “*” to select all existing nodes.

Parameters: id (api.types.ElementId) – A node ID. Avoid using the “-” character.
Returns: A new selection corresponding to the given node.

nodes(ids: Iterable[Any] = ['*']) → api.NodeSelection.NodeSelection[source]¶

Selects multiple nodes using an list of ID values. If no list is provided, all existing nodes will be selected.

Parameters: ids (Iterable[api.types.ElementId]) – A list of node IDs. Avoid using the “-” character.
Returns: A new selection corresponding to the given nodes.

edge(edge: Union[Tuple[Any, Any], Tuple[Any, Any, Any]]) → api.EdgeSelection.EdgeSelection[source]¶

Selects a single edge using a (source, target, optional ID) tuple.

The optional ID is used to distinguish multi-edges. The full string ID of the edge will take the form “source-target(-ID)”. If the edge has directed set to false, ‘source’ and ‘target’ can be provided in any order, as long as they do not contain the “-” character.

When accessing edges using string IDs, e.g. through attrs(), the following rules apply: * New edges with IDs in the form “source-target(-ID)” will automatically initialize their source/target attributes. * For edges with directed set to false, “target-source(-ID)” will fall back to “source-target(-ID)”.

Parameters: edge (EdgeId) – A (source, target) or (source, target, ID) tuple.
Returns: A new selection corresponding to the given edge.

edges(ids: Iterable[Union[Tuple[Any, Any], Tuple[Any, Any, Any]]] = None) → api.EdgeSelection.EdgeSelection[source]¶

Selects multiple edges using a list of (source, target, optional ID) tuples, see edge().

If no list is provided, all existing edges will be selected.

Parameters: ids (Iterable[EdgeId]) – A list of (source, target) or (source, target, ID) tuples. All values will be converted to strings.
Returns: A new selection corresponding to the given edges.

label(id: Any) → api.LabelSelection.LabelSelection[source]¶

Selects a single canvas label by its ID. Use “*” to select all existing labels.

Parameters: id (Union[str, int]) – A label ID.
Returns: A new selection corresponding to the given label.

labels(ids: Iterable[Any] = ['*']) → api.LabelSelection.LabelSelection[source]¶

Selects multiple canvas labels using a list of ID values. If no list is provided, all existing labels will be selected.

Parameters: ids (Iterable[api.types.ElementId]) – A list of label IDs.
Returns: A new selection corresponding to the given labels.

size(size: Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]) → S[source]¶

Sets the width and height of the canvas.

This will determine the coordinate system, and will update the width and height attributes of the main SVG element, unless otherwise specified with svgattr(). Size is not animated by default.

Parameters: size (Tuple[NumAttr, NumAttr]]) – A (width, height) tuple.

edgelayout(edgelayout: str) → S[source]¶

Sets strategy used to calculate edge lengths. Edges can either specify individual length values (see length(), or have their lengths dynamically calculated with the given strategy, and with an average of edgelength().

More information is available at https://github.com/tgdwyer/WebCola/wiki/link-lengths.

Parameters: edgelayout (str) – The edge length calculation strategy: * “individual”: Uses each edge’s length attribute individually. * “jaccard” (default): Dynamic calculation based on edgelength(). * “symmetric”: Dynamic calculation based on edgelength().

edgelength(edgelength: float) → S[source]¶

Sets the average length of all edges. This only applies if edgelayout() is not “individual”.

The default average edge length is 70.

Parameters: edgelength (float) – The average edge length.

pan(pan: Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]) → S[source]¶

Sets the location of the canvas camera. The canvas uses a Cartesian coordinate system with (0,0) at the center.

Parameters: pan (Tuple[NumAttr, NumAttr]) – An (x, y) tuple describing the new pan location.

zoom(zoom: Union[int, float, str, Mapping]) → S[source]¶

Sets the zoom level of the canvas camera. A zoom level of 2.0 will make objects appear twice as large, 0.5 will make them half as large, etc.

Parameters: zoom (NumAttr) – The new zoom level.

panlimit(panlimit: Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]) → S[source]¶

Restricts the movement of the canvas camera to the given bounding box, centered at (0,0).

The default pan limit is: (-Infinity, Infinity).

Parameters: panlimit (Tuple[NumAttr, NumAttr]) – A (width/2, height/2) tuple describing the bounding box.

zoomlimit(zoomlimit: Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]) → S[source]¶

Restricts the zoom level of the canvas camera to the given range. The lower bound describes how far out the camera can zoom, while the upper bound describes the maximum enlarging zoom.

The default zoom limit is (0.1, 10).

Parameters: limit (Tuple[NumAttr, NumAttr]) – A (min, max) tuple describing the zoom limit.

zoomtoggle(zoomtoggle: bool) → S[source]¶

Sets whether or not zooming requires the ctrl/cmd key to be held down. Disabled by default.

Parameters: zoomtoggle (bool.) – True if the ctrl/cmd key is required, false otherwise.

queue(id: Any = 0) → api.QueueSelection.QueueSelection[source]¶

Selects a single event queue by its ID. The default queue has ID 0. Use “*” to select all existing queues.

By default, any changes made to the queue (e.g. start/stop) will take place immediately. However, if withQ() was previously called, the changes themselves will be added as events onto the current queue.

Parameters: id – A queue ID. Defaults to 0.
Returns: A new selection corresponding to the given queue.

queues(ids: Iterable[Any] = ['*']) → api.QueueSelection.QueueSelection[source]¶

Selects multiple event queues using an list of ID values, see queue().

If no list is provided, all existing queues will be selected.

Parameters: ids – A list of queue IDs.
Returns: A new selection corresponding to the given queues.

message(message: str) → S[source]¶

Adds a message to the current event queue. Together with onmessage(), this can be used to detect when a queue reaches a certain point in execution.

Parameters: message – A message string.

onmessage(message: str, fn: Union[Callable[], Any], Callable[[str], Any]]) → S[source]¶

Registers a callback function for messages sent by message(). Use “*” to listen for all messages.

Parameters

message – The message to listen for, or “*” to listen for all messages.
fn – A callback function. When using “*”, the exact message will be provided as an argument.

dispatch(event: Mapping) → S[source]¶

Sends an event to the client, in the form: * attrs: An attribute dictionary, see attrs(). * animation: A partial animation dictionary will apply to all provided attributes, see attrs(). * message: A message, as sent by message(). * withQ: The event queue to which the event will be added, see withQ(). * queues:

[id]:

stop: True if the queue should be stopped, see stop().

start: True if the queue should be started, see start().

clear: True if all events should be cleared from the queue, see clear().

pause: The number of seconds the queue should be paused for, see pause().

Parameters: event (DispatchEvent) – A partial event object.

ondispatch(fn: Callable[[Mapping], Any]) → S[source]¶

Registers a callback function to listen for all dispatched events, see dispatch().

This will override the default event handler.

Parameters: fn (Callable[[DispatchEvent], Any]) – A callback function which receives a partial event object.

receive(event: Mapping) → S[source]¶

Simulates an event being received from the client, see onreceive().

Parameters: event (ReceiveEvent) – A partial event object.

onreceive(fn: Callable[[Mapping], Any]) → S[source]¶

Registers a callback function for all events sent back by the client, in the form: * error:

type: “attribute” (invalid attributes), “unknown”.

message: The error message.

message: A message, as sent by message().
nodes:
- [id]:
  click: True if the node was clicked.
  
  hoverin: True if the mouse hovered over the node.
  
  hoverout: True if the mouse exited the node.

Parameters: fn (Callable[[ReceiveEvent], Any]) – A callback function which receives a partial event object.

NodeSelection¶

class api.NodeSelection(context: api.utils.ElementContext)[source]¶

remove() → S[source]¶: Removes all selected nodes nodes, and any edges connected to the nodes.

label(id: Any = 0) → api.LabelSelection.LabelSelection[source]¶

Selects a single node label by its ID. The node’s default ‘value label’ has ID 0. Use “*” to select all existing labels.

Parameters: id (ElementId) – A label ID. Defaults to 0.
Returns: A new selection corresponding to the given labels, with the same data as the current selection.

labels(ids: Iterable[Any]) → api.LabelSelection.LabelSelection[source]¶

Selects multiple node labels using a list of ID values. If no list is provided, all existing labels will be selected.

Parameters: ids (Iterable[api.types.ElementId]) – An list of label IDs.
Returns: A new selection corresponding to the given labels, with the same data as the current selection.

shape(shape: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets the shape of the node.

Parameters

shape (ElementArg[str]) –

One of the following strings:

”circle” (default): Circular node with a single radius dimension.
”rect”: Rectangular node with separate width and height dimensions, and corner rounding.
”ellipse”: Elliptical node with separate width and height dimensions.

color(color: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets the color of the node. The default color is “dark-gray”.

Parameters: color (ElementArg[str]) – A CSS color string.

size(size: Union[Callable[[Any], Union[int, float, str, Mapping, Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]], Callable[[Any, int], Union[int, float, str, Mapping, Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]], int, float, str, Mapping, Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]) → S[source]¶

Sets the size of the node using a (width/2, height/2) tuple.

If a single value is provided, it will be used for both dimensions. If the node is a circle, width/2 is the radius and height is ignored.

Note that size can be set relative to the node’s current size using string expressions, e.g. “1.5x” for circles or (“1.5x”, “1.5y”) for rectangles.

The default size is (12, 12).

Parameters: size (ElementArg[Union[NumAttr, Tuple[NumAttr, NumAttr]]]) – A single radius, or a (width/2, height/2) tuple.

pos(pos: Union[Callable[[Any], Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]], Callable[[Any, int], Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]], Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]) → S[source]¶

Sets the position of the node. The canvas uses a Cartesian coordinate system with (0, 0) at the center.

Parameters: pos (ElementArg[Tuple[NumAttr, NumAttr]]) – An (x, y) tuple describing the new position of the node.

fixed(fixed: Union[Callable[[Any], bool], Callable[[Any, int], bool], bool]) → S[source]¶

When set to true, this prevents the node from being automatically moved during the layout process. This does not affect manual dragging.

Parameters: fixed (ElementArg[bool]) – True if the position of the node should be fixed, false otherwise.

draggable(draggable: Union[Callable[[Any], bool], Callable[[Any, int], bool], bool]) → S[source]¶

Sets whether the node can be manually dragged around.

Parameters: draggable (ElementArg[bool]) – True if the node should be draggable, false otherwise.

onclick(fn: Union[Callable[[Any], T], Callable[[Any, int], T]]) → S[source]¶

Registers a callback function to listen for node click events.

This will override any previous callback.

Parameters: fn (ElementFn) – A callback function taking the node’s data and, optionally, index.

onhoverin(fn: Union[Callable[[Any], T], Callable[[Any, int], T]]) → S[source]¶

Registers a callback function to listen for node mouse-over events, triggered when the mouse enters the node.

This will override any previous callback.

Parameters: fn (ElementFn) – A callback function taking the node’s data and, optionally, index.

onhoverout(fn: Union[Callable[[Any], T], Callable[[Any, int], T]]) → S[source]¶

Registers a callback function to listen for node mouse-over events, triggered when the mouse leaves the node.

This will override any previous callback.

Parameters: fn (ElementFn) – A callback function taking the node’s data and, optionally, index.

EdgeSelection¶

class api.EdgeSelection(context: api.EdgeSelection.EdgeContext)[source]¶

add(attrs: Union[Callable[[Any], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]], Callable[[Any, int], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]], Mapping[str, Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]]] = {}, **kwargs: Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]) → S[source]¶

Adds all selected elements to the canvas with the given initial attributes.

Parameters: attrs (ElementArg[Mapping]) – An attribute dictionary, see ElementAttrs.
Returns: A new instance of the current selection with animations disabled, to allow for further attribute initialisation.

label(id: Any = 0) → api.LabelSelection.LabelSelection[source]¶

Selects a single edge label by its ID. Use “*” to select all existing labels.

Parameters: id (api.types.ElementId) – A label ID. Defaults to 0.
Returns: A new selection corresponding to the given label, with the same data as the current selection.

labels(ids: Iterable[Any]) → api.LabelSelection.LabelSelection[source]¶

Selects multiple edge labels using a list of ID values. If no list is provided, all existing labels will be selected.

Parameters: ids (Iterable[api.types.ElementId]) – An list of label IDs.
Returns: A new selection corresponding to the given labels, with the same data as the current selection.

directed(directed: Union[Callable[[Any], bool], Callable[[Any, int], bool], bool]) → S[source]¶

Sets whether or not the edge should include an arrow pointing towards its target node.

Parameters: directed (ElementArg[bool]) – True if the edge should be directed, false otherwise.

length(length: Union[Callable[[Any], Union[int, float, str, Mapping]], Callable[[Any, int], Union[int, float, str, Mapping]], int, float, str, Mapping]) → S[source]¶

Sets the length of the edge. This will only take effect when edgelayout() is set to “individual”.

Parameters: length (ElementArg[NumAttr]) – The length of the edge.

thickness(thickness: Union[Callable[[Any], Union[int, float, str, Mapping]], Callable[[Any, int], Union[int, float, str, Mapping]], int, float, str, Mapping]) → S[source]¶

Sets the thickness of the edge.

Parameters: thickness (ElementArg[NumAttr]) – The thickness of the edge, in pixels.

color(color: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets the color of the edge. The default color is “light-gray”.

Parameters: color (ElementArg[str]) – A CSS color string.

traverse(color: Union[Callable[[Any], str], Callable[[Any, int], str], str], source: Optional[Union[Callable[[Any], Any], Callable[[Any, int], Any], Any]] = None) → S[source]¶

Sets the color of the edge using a traversal animation.

If no source is provided, the first element in each edge tuple will be used.

Parameters

value (Optional[ElementArg[str]) – A CSS color string.
source (Optional[ElementArg[ElementId]) – The ID of the node from which the traversal animation should originate.

flip(flip: Union[Callable[[Any], bool], Callable[[Any, int], bool], bool]) → S[source]¶

Sets whether or not the edge should be ‘flipped’ after exceeding a certain angle, such that it is never rendered upside-down. This does not apply to looping edges.

Parameters: flip (ElementArg[bool]) – True if the edge should flip automatically, false otherwise.

curve(curve: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets the curve function used to interpolate the edge’s path.

The default setting is “cardinal”. More information is available here: https://github.com/d3/d3-shape#curves.

Parameters

curve (ElementArg[str]) –

The name of the curve function, based on the functions found in D3. The full list is below:

”basis”, “bundle”, “cardinal”, “catmull-rom”, “linear”, “monotone-x”, “monotone-y”, “natural”, “step”, “step-before”, “step-after”

path(path: Union[Callable[[Any], List[Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]], Callable[[Any, int], List[Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]], List[Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]]) → S[source]¶

Sets a custom path for the edge. The path is a list of (x, y) tuples, which will automatically connect to the boundaries of the source and target nodes.

If the edge connects two nodes, (0,0) will be the midpoint between the two nodes. If edge is a loop, (0,0) will be a point on the node’s boundary.

Parameters: path (ElementArg[List[Tuple[NumAttr, NumAttr]]]) – An list of (x, y) tuples.

LabelSelection¶

class api.LabelSelection(context: api.utils.ElementContext)[source]¶

text(text: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets the text displayed by the label.

The newline character (“\n”) can be used to break the text into multiple lines.

Parameters: text (ElementArg[str]) – The text displayed by the label.

align(align: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets alignment of the label’s text.

This will affect the direction in which text is appended, as well as its positioning relative to the label’s base position. For example, an alignment of “top-left” will ensure that the top left corner of the label is located at the base position.

A special “radial” alignment can be used to dynamically calculate the label’s alignment based on its angle() and rotate() attributes, such that text is optimally positioned around an element.

Parameters

align (ElementArg[str]) –

A string describing the alignment, typically in the form “vertical-horizontal”. The full list is below:

”top-left”, “top-middle”, “top-right”, “middle-left”, “middle”, “middle-right”, “bottom-left”, “bottom-middle”, “bottom-right”, “radial”

pos(pos: Union[Callable[[Any], Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]], Callable[[Any, int], Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]], Tuple[Union[int, float, str, Mapping], Union[int, float, str, Mapping]]]) → S[source]¶

Sets the position of the label relative to its parent element.

If the parent is a node, (0,0) will be the node’s center. If the parent is an edge connecting two nodes, (0,0) will be the midpoint between the two nodes. If the parent is a looping edge connecting one node, (0,0) will be a point on the node’s boundary.

Parameters: pos (ElementArg[Tuple[NumAttr, NumAttr]]) – An (x, y) tuple describing the position of the label.

radius(radius: Union[Callable[[Any], Union[int, float, str, Mapping]], Callable[[Any, int], Union[int, float, str, Mapping]], int, float, str, Mapping]) → S[source]¶

Positions the label using polar coordinates, together with angle(). This will specify the distance from the label’s base position (see pos()).

Parameters: radius (ElementArg[NumAttr]) – The polar radius, defined as the distance from the label’s base position.

angle(angle: Union[Callable[[Any], Union[int, float, str, Mapping]], Callable[[Any, int], Union[int, float, str, Mapping]], int, float, str, Mapping]) → S[source]¶

Allows the label to be positioned using polar coordinates, together with the radius() attribute. This will specify the angle, in degrees, along a standard unit circle centered at the label’s base position (see pos()).

This will also affect the rotation of the label if rotate() is enabled.

Parameters: angle (ElementArg[NumAttr]) – The polar angle, in degrees, increasing counter-clockwise from the x-axis.

rotate(rotate: Union[Callable[[Any], bool], Callable[[Any, int], bool], bool]) → S[source]¶

Sets whether the label should be rotated by angle() degrees.

The exact rotation will also depend on the label’s alignment. For example, an alignment of “top-center” together with an angle of 90 degrees will result in the text being upside-down.

Parameters: rotate (ElementArg[bool]) – True if the label should be rotated.

color(color: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets the color of the label’s text.

The default color is “gray” in most cases.

Parameters: color (ElementArg[str]) – A CSS color string.

font(font: Union[Callable[[Any], str], Callable[[Any, int], str], str]) → S[source]¶

Sets the font of the label’s text.

Parameters: font (ElementArg[str]) – A CSS font-family string.

size(size: Union[Callable[[Any], Union[int, float, str, Mapping]], Callable[[Any, int], Union[int, float, str, Mapping]], int, float, str, Mapping]) → S[source]¶

Sets the size of the label’s text.

Parameters: size (ElementArg[NumAttr]) – The size of the label’s text, in pixels.