Graphviz utility functions.

See also the [https://www.graphviz.org/documentation/](graphviz documentation) and particularly the [https://graphviz.org/doc/info/lang.html](DOT language specification) and the [https://www.graphviz.org/doc/info/command.html](dot command line tool).

Short summary:

• DOTNodeMixin: A mixin providing methods for things which can be drawn as nodes in a DOT graph description.

• Graph: A representation of a graphviz graph suitable for transcribing as DOT.

• gvdata: Convenience wrapper for gvprint which returns the binary image data.

• gvdataurl: Convenience wrapper for gvprint which returns the binary image data as a data: URL.

• gvprint: Print the graph specified by dot_s, a graph in graphViz DOT syntax, to file (default sys.stdout) in format fmt using the engine specified by layout (default 'dot').

• gvsvg: Convenience wrapper for gvprint which returns an SVG string.

• Node: Node(id: str, rankdir: str = 'LR', shape: str = 'rect', attrs: dict = ).

• quote: Quote a string for use in DOT syntax. This implementation passes non-keyword identifiers and sequences of decimal numerals through unchanged and double quotes other strings.

Functions

gvdata(dot_s, **kw)

Convenience wrapper for gvprint which returns the binary image data.

gvdataurl(dot_s, **kw)

Convenience wrapper for gvprint which returns the binary image data as a data: URL.

gvprint(dot_s, file=None, fmt=None, layout=None, dataurl_encoding=None, **dot_kw)

Print the graph specified by dot_s, a graph in graphViz DOT syntax, to file (default sys.stdout) in format fmt using the engine specified by layout (default 'dot').

If fmt is unspecified it defaults to 'png' unless file is a terminal in which case it defaults to 'sixel'.

In addition to being a file or file descriptor, file may also take the following special values:

• GVCAPTURE: causes gvprint to return the image data as bytes
• GVDATAURL: causes gvprint to return the image data as a data: URL

For GVDATAURL, the parameter dataurl_encoding may be used to override the default encoding, which is 'utf8' for fmt values 'dot' and 'svg', otherwise 'base64'.

This uses the graphviz utility dot to draw graphs. If printing in SIXEL format the img2sixel utility is required, see https://saitoha.github.io/libsixel/.

Example:

data_url = gvprint('digraph FOO {A->B}', file=GVDATAURL, fmt='svg')

gvsvg(dot_s, **gvdata_kw)

Convenience wrapper for gvprint which returns an SVG string.

quote(s)

Quote a string for use in DOT syntax. This implementation passes non-keyword identifiers and sequences of decimal numerals through unchanged and double quotes other strings.

Classes

class DOTNodeMixin(cs.obj.NoAttrs)

A mixin providing methods for things which can be drawn as nodes in a DOT graph description.

DOTNodeMixin.DOT_NODE_FILLCOLOR_PALETTE

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

DOTNodeMixin.DOT_NODE_FONTCOLOR_PALETTE

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

DOTNodeMixin.__getattr__(self, attr: str)

Recognise various dot_node_* attributes.

dot_node_*color is an attribute derives from self.DOT_NODE_COLOR_*PALETTE.

DOTNodeMixin.dot_node(self, label=None, **node_attrs) -> str

A DOT syntax node definition for self.

DOTNodeMixin.dot_node_attrs(self) -> Mapping[str, str]

The default DOT node attributes.

DOTNodeMixin.dot_node_attrs_str(attrs)

An attributes mapping transcribed for DOT, ready for insertion between [] in a node definition.

DOTNodeMixin.dot_node_id

An id for this DOT node, also the default index into the palettes.

DOTNodeMixin.dot_node_label(self) -> str

The default node label. This implementation returns str(self) and a common implementation might return self.name or similar.

DOTNodeMixin.dot_node_palette_key

The default palette index is `self.dot_node_id``.

class Graph

A representation of a graphviz graph suitable for transcribing as DOT.

Graph.add(self, *items)

Add a Node id or a Nodes or Graphs to self.nodes.

Graph.as_dot(self, *, fold=False, indent='', subindent=' ', graphtype=None) -> str

Return a DOT representation of this Graph.

Parameters:

• fold: default False; if true then produce indented multiline text
• indent: the prevailing indent if fold, default ""
• subindent: incremental indent of nested items if fold, default " "

Graph.digraph

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

Graph.id

The type of the None singleton.

Graph.join(self, *items, **attrs)

Join the specified Nodes, Node ids or Graphs in an edge.

Graph.mapping_as_dot(kv: Mapping[str, Any])

Transcribe a mapping as DOT i.e. an a_list.

Graph.strict

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

class Node(DOTNodeMixin)

Node(id: str, rankdir: str = 'LR', shape: str = 'rect', attrs: dict = )

Node.rankdir

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

Node.shape

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.