Metadata-Version: 2.4
Name: cs-gvutils
Version: 20260531
Summary: Graphviz utility functions.
Keywords: python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: cs.lex>=20260526
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/gvutils.py

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 = <factory>).
* `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:
- <a name="DOTNodeMixin"></a>`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``.
- <a name="Graph"></a>`class Graph`: A representation of a graphviz graph suitable for transcribing as DOT.

*`Graph.add(self, *items)`*:
Add a `Node` id or a `Node`s or `Graph`s 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 `Node`s, `Node` ids or `Graph`s in an edge.

*`Graph.mapping_as_dot(kv: Mapping[str, Any])`*:
Transcribe a mapping as DOT i.e. an `a_list`.
- <a name="gvdata"></a>`gvdata(dot_s, **kw)`: Convenience wrapper for `gvprint` which returns the binary image data.
- <a name="gvdataurl"></a>`gvdataurl(dot_s, **kw)`: Convenience wrapper for `gvprint` which returns the binary image data
  as a `data:` URL.
- <a name="gvprint"></a>`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/](libsixel).

  Example:

      data_url = gvprint('digraph FOO {A->B}', file=GVDATAURL, fmt='svg')
- <a name="gvsvg"></a>`gvsvg(dot_s, **gvdata_kw)`: Convenience wrapper for `gvprint` which returns an SVG string.
- <a name="Node"></a>`class Node(DOTNodeMixin)`: Node(id: str, rankdir: str = 'LR', shape: str = 'rect', attrs: dict = <factory>)
- <a name="quote"></a>`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.
