Metadata-Version: 2.4
Name: cs-gvutils
Version: 20260914
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>=20260912
Requires-Dist: cs.obj>=20260912
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.

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.

# 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/](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 `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.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 `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`.

### `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 = <factory>)

### `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'.
