gv(3python)

okay bestie, welcome to the gv(3python) manual — aka the group chat for gv_python, graph manipulation in python. grab a strawberry 🍓 and let's get into it.

✨ NAME ✨

gv_python — graph manipulation in python. that's the name, periodt.

🌸 SYNOPSIS 🌸

#!/usr/bin/python
import sys
import gv

🫶 USAGE 🫶

nothing is listed under this heading in the source, bestie — it's giving placeholder energy — so we slide straight into the intro.

🦋 INTRODUCTION 🦋

gv_python is a dynamically loaded extension for python, and it gives you access to the graph facilities of graphviz. iconic behavior, honestly. 👑

💖 COMMANDS 💖

🌱 New graphs 🌱

New empty graph

fresh little baby graphs, no cap:

graph_handle gv.graph (name);
graph_handle gv.digraph (name);
graph_handle gv.strictgraph (name);
graph_handle gv.strictdigraph (name);

New graph from a dot-syntax string or file

pull a graph straight out of a dot-syntax string or a file — readstring and read are right there:

graph_handle gv.readstring (string);
graph_handle gv.read (string filename);
graph_handle gv.read (channel);

Add new subgraph to existing graph

add a new subgraph to a graph that already exists:

graph_handle gv.graph (graph_handle, name);

🎀 New nodes 🎀

Add new node to existing graph

one new node, added to an existing graph:

node_handle gv.node (graph_handle, name);

🌈 New edges 🌈

Add new edge between existing nodes

new edge between two nodes that already exist:

edge_handle gv.edge (tail_node_handle, head_node_handle);

Add a new edge between an existing tail node, and a named head node which will be induced in the graph if it doesn't already exist

tail node is already there, head node is named and gets induced if it's missing:

edge_handle gv.edge (tail_node_handle, head_name);

Add a new edge between an existing head node, and a named tail node which will be induced in the graph if it doesn't already exist

head node is already there, tail node is named and gets induced if it's missing:

edge_handle gv.edge (tail_name, head_node_handle);

Add a new edge between named tail and head nodes which will be induced in the graph if they don't already exist

both ends are named, and both get induced if they don't already exist:

edge_handle gv.edge (graph_handle, tail_name, head_name);

💅 Setting attribute values 💅

Set value of named attribute of graph/node/edge — creating attribute if necessary

set a named attribute on a graph, node or edge, and create the attribute if it isn't there yet:

string gv.setv (graph_handle, attr_name, attr_value);
string gv.setv (node_handle, attr_name, attr_value);
string gv.setv (edge_handle, attr_name, attr_value);

Set value of existing attribute of graph/node/edge (using attribute handle)

set an existing attribute by its handle:

string gv.setv (graph_handle, attr_handle, attr_value);
string gv.setv (node_handle, attr_handle, attr_value);
string gv.setv (edge_handle, attr_handle, attr_value);

🔥 Getting attribute values 🔥

Get value of named attribute of graph/node/edge

grab the value of a named attribute on a graph, node or edge:

string gv.getv (graph_handle, attr_name);
string gv.getv (node_handle, attr_name);
string gv.getv (edge_handle, attr_name);

Get value of attribute of graph/node/edge (using attribute handle)

grab the value using the attribute handle instead:

string gv.getv (graph_handle, attr_handle);
string gv.getv (node_handle, attr_handle);
string gv.getv (edge_handle, attr_handle);

🌟 Obtain names from handles 🌟

handles in, names out:

string gv.nameof (graph_handle);
string gv.nameof (node_handle);
string gv.nameof (attr_handle);

🧚 Find handles from names 🧚

names in, handles out — very main character energy:

graph_handle gv.findsubg (graph_handle, name);
node_handle gv.findnode (graph_handle, name);
edge_handle gv.findedge (tail_node_handle, head_node_handle);
attribute_handle gv.findattr (graph_handle, name);
attribute_handle gv.findattr (node_handle, name);
attribute_handle gv.findattr (edge_handle, name);

🌀 Misc graph navigators returning handles 🌀

little navigator functions that hand you back handles:

node_handle gv.headof (edge_handle);
node_handle gv.tailof (edge_handle);
graph_handle gv.graphof (graph_handle);
graph_handle gv.graphof (edge_handle);
graph_handle gv.graphof (node_handle);
graph_handle gv.rootof (graph_handle);

🎁 Obtain handles of proto node/edge for setting default attribute values 🎁

proto node and proto edge handles, for setting default attribute values:

node_handle gv.protonode (graph_handle);
edge_handle gv.protoedge (graph_handle);

🦋 Iterators 🦋

Iteration termination tests

these are the iteration termination tests:

bool gv.ok (graph_handle);
bool gv.ok (node_handle);
bool gv.ok (edge_handle);
bool gv.ok (attr_handle);

Iterate over subgraphs of a graph

walk the subgraphs:

graph_handle gv.firstsubg (graph_handle);
graph_handle gv.nextsubg (graph_handle, subgraph_handle);

Iterate over supergraphs of a graph (obscure and rarely useful)

walk the supergraphs — the original literally calls this obscure and rarely useful, so bestie, that's the vibe:

graph_handle gv.firstsupg (graph_handle);
graph_handle gv.nextsupg (graph_handle, subgraph_handle);

Iterate over edges of a graph

walk the edges of a graph:

edge_handle gv.firstedge (graph_handle);
edge_handle gv.nextedge (graph_handle, edge_handle);

Iterate over outedges of a graph

walk the outedges of a graph:

edge_handle gv.firstout (graph_handle);
edge_handle gv.nextout (graph_handle, edge_handle);

Iterate over edges of a node

walk the edges of a node:

edge_handle gv.firstedge (node_handle);
edge_handle gv.nextedge (node_handle, edge_handle);

Iterate over out-edges of a node

walk the out-edges of a node:

edge_handle gv.firstout (node_handle);
edge_handle gv.nextout (node_handle, edge_handle);

Iterate over head nodes reachable from out-edges of a node

walk the head nodes reachable from a node's out-edges:

node_handle gv.firsthead (node_handle);
node_handle gv.nexthead (node_handle, head_node_handle);

Iterate over in-edges of a graph

walk the in-edges of a graph:

edge_handle gv.firstin (graph_handle);
edge_handle gv.nextin (node_handle, edge_handle);

Iterate over in-edges of a node

walk the in-edges of a node:

edge_handle gv.firstin (node_handle);
edge_handle gv.nextin (graph_handle, edge_handle);

Iterate over tail nodes reachable from in-edges of a node

walk the tail nodes reachable from a node's in-edges:

node_handle gv.firsttail (node_handle);
node_handle gv.nexttail (node_handle, tail_node_handle);

Iterate over nodes of a graph

walk the nodes of a graph:

node_handle gv.firstnode (graph_handle);
node_handle gv.nextnode (graph_handle, node_handle);

Iterate over nodes of an edge

walk the nodes of an edge:

node_handle gv.firstnode (edge_handle);
node_handle gv.nextnode (edge_handle, node_handle);

Iterate over attributes of a graph

walk the attributes of a graph:

attribute_handle gv.firstattr (graph_handle);
attribute_handle gv.nextattr (graph_handle, attr_handle);

Iterate over attributes of an edge

walk the attributes of an edge:

attribute_handle gv.firstattr (edge_handle);
attribute_handle gv.nextattr (edge_handle, attr_handle);

Iterate over attributes of a node

walk the attributes of a node:

attribute_handle gv.firstattr (node_handle);
attribute_handle gv.nextattr (node_handle, attr_handle);

💀 Remove graph objects 💀

remove a graph, node or edge:

bool gv.rm (graph_handle);
bool gv.rm (node_handle);
bool gv.rm (edge_handle);

👑 Layout 👑

Annotate a graph with layout attributes and values using a specific layout engine

annotate the graph with layout attributes and values using a specific layout engine:

bool gv.layout (graph_handle, string engine);

🎀 Render 🎀

Render a layout into attributes of the graph

render a layout into the graph's attributes:

bool gv.render (graph_handle);

Render a layout to stdout

render a layout straight to stdout:

bool gv.render (graph_handle, string format);

Render to an open file

render to an already-open file:

bool gv.render (graph_handle, string format, channel fout);

Render a layout to an unopened file by name

render a layout to an unopened file, by filename:

bool gv.render (graph_handle, string format, string filename);

Render to a string result

render to a string result — and yes, the code below is exactly as the page gives it, typo energy and all:

string gv.renderresult (graph_handle ing, string format);
gv.renderresult (graph_handle, string format, string outdata);

Render to an open channel

render to an open channel:

bool gv.renderchannel (graph_handle, string format, string channelname);

Render a layout to a malloc'ed string, to be free'd by the caller

deprecated - too easy to leak memory 😭 still needed for "eval [gv::renderdata $G tk]"

string gv.renderdata (graph_handle, string format);

🍓 Writing graph back to file 🍓

write the graph back to a file or a channel:

bool gv.write (graph_handle, string filename);
bool gv.write (graph_handle, channel);

⭐ Graph transformation tools ⭐

graph transformation tools, right here:

bool gv.tred (graph_handle);

🌈 KEYWORDS 🌈

graph, dot, neato, fdp, circo, twopi, python.

---

💅 okay that's the whole page, bestie — the footer's source/version + date stamp energy is 1787242656 and gv(3python), so consider this group chat signed off. periodt. 🫶