cs-gvutils 20260531

Graphviz utility functions.

Graphviz utility functions.

Latest release 20260531:

• New DOT_KEYWORDS, update quote() to quote keywords.
• New Node and Graph classes for constructing a graphviz style node graph.
• gvprint: print a final newline after the sixel output.

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.

Module contents:

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

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.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.

• 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.

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

• 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.

Release Log

Release 20260531:

• New DOT_KEYWORDS, update quote() to quote keywords.
• New Node and Graph classes for constructing a graphviz style node graph.
• gvprint: print a final newline after the sixel output.

Release 20230816: DOTNodeMixin: new dot_node_attrs_str for transcribing a node attributes list.

Release 20221207: New gvsvg() convenience function to return SVG.

Release 20221118:

• quote: provide escape sequence for newline.
• DOTNodeMixin: provide .dot_node_id property, default str(id(self)).
• DOTNodeMixin.dot_node: omit [attrs] if they are empty.
• DOTNodeMixin: new .dot_node_palette_key property, new getattr for .dot_node_*color attributes, new empty default DOT_NODE_COLOR_PALETTE and DOT_NODE_FILLCOLOR_PALETTE class attributes.
• DOTNodeMixin.dot_node: include the node label in the attributes.
• Add colours to DOTNodeMixin.dot_node_attrs and fix "fontcolor".

Release 20220827.1: gvprint: new optional parameter dataurl_encoding to specify the data URL encoding.

Release 20220827:

• Remove dependency on cs.lex - now we need only the stdlib.
• New GVCAPTURE value for gvprint(file=) to return the binary image data as a bytes object; associated gvdata() convenience function.
• New GVDATAURL value for gvprint(file=) to return the binary image data as a data URL; associated gvdataurl() convenience function.

Release 20220805.1: New DOTNodeMixin, a mixin for classes which can be rendered as a DOT node.

Release 20220805: Initial PyPI release.