1 :mod:`altgraph.Dot` --- Interface to the dot language 2 ===================================================== 3 4 .. module:: altgraph.Dot 5 :synopsis: Interface to the dot language as used by Graphviz.. 6 7 The :py:mod:`~altgraph.Dot` module provides a simple interface to the 8 file format used in the `graphviz`_ program. The module is intended to 9 offload the most tedious part of the process (the **dot** file generation) 10 while transparently exposing most of its features. 11 12 .. _`graphviz`: <http://www.research.att.com/sw/tools/graphviz/>`_ 13 14 To display the graphs or to generate image files the `graphviz`_ 15 package needs to be installed on the system, moreover the :command:`dot` and :command:`dotty` programs must 16 be accesible in the program path so that they can be ran from processes spawned 17 within the module. 18 19 Example usage 20 ------------- 21 22 Here is a typical usage:: 23 24 from altgraph import Graph, Dot 25 26 # create a graph 27 edges = [ (1,2), (1,3), (3,4), (3,5), (4,5), (5,4) ] 28 graph = Graph.Graph(edges) 29 30 # create a dot representation of the graph 31 dot = Dot.Dot(graph) 32 33 # display the graph 34 dot.display() 35 36 # save the dot representation into the mydot.dot file 37 dot.save_dot(file_name='mydot.dot') 38 39 # save dot file as gif image into the graph.gif file 40 dot.save_img(file_name='graph', file_type='gif') 41 42 43 Directed graph and non-directed graph 44 ------------------------------------- 45 46 Dot class can use for both directed graph and non-directed graph 47 by passing *graphtype* parameter. 48 49 Example:: 50 51 # create directed graph(default) 52 dot = Dot.Dot(graph, graphtype="digraph") 53 54 # create non-directed graph 55 dot = Dot.Dot(graph, graphtype="graph") 56 57 58 Customizing the output 59 ---------------------- 60 61 The graph drawing process may be customized by passing 62 valid :command:`dot` parameters for the nodes and edges. For a list of all 63 parameters see the `graphviz`_ documentation. 64 65 Example:: 66 67 # customizing the way the overall graph is drawn 68 dot.style(size='10,10', rankdir='RL', page='5, 5' , ranksep=0.75) 69 70 # customizing node drawing 71 dot.node_style(1, label='BASE_NODE',shape='box', color='blue' ) 72 dot.node_style(2, style='filled', fillcolor='red') 73 74 # customizing edge drawing 75 dot.edge_style(1, 2, style='dotted') 76 dot.edge_style(3, 5, arrowhead='dot', label='binds', labelangle='90') 77 dot.edge_style(4, 5, arrowsize=2, style='bold') 78 79 80 .. note:: 81 82 dotty (invoked via :py:func:`~altgraph.Dot.display`) may not be able to 83 display all graphics styles. To verify the output save it to an image 84 file and look at it that way. 85 86 Valid attributes 87 ---------------- 88 89 - dot styles, passed via the :py:meth:`Dot.style` method:: 90 91 rankdir = 'LR' (draws the graph horizontally, left to right) 92 ranksep = number (rank separation in inches) 93 94 - node attributes, passed via the :py:meth:`Dot.node_style` method:: 95 96 style = 'filled' | 'invisible' | 'diagonals' | 'rounded' 97 shape = 'box' | 'ellipse' | 'circle' | 'point' | 'triangle' 98 99 - edge attributes, passed via the :py:meth:`Dot.edge_style` method:: 100 101 style = 'dashed' | 'dotted' | 'solid' | 'invis' | 'bold' 102 arrowhead = 'box' | 'crow' | 'diamond' | 'dot' | 'inv' | 'none' | 'tee' | 'vee' 103 weight = number (the larger the number the closer the nodes will be) 104 105 - valid `graphviz colors <http://www.research.att.com/~erg/graphviz/info/colors.html>`_ 106 107 - for more details on how to control the graph drawing process see the 108 `graphviz reference <http://www.research.att.com/sw/tools/graphviz/refs.html>`_. 109 110 111 Class interface 112 --------------- 113 114 .. class:: Dot(graph[, nodes[, edgefn[, nodevisitor[, edgevisitor[, name[, dot[, dotty[, neato[, graphtype]]]]]]]]]) 115 116 Creates a new Dot generator based on the specified 117 :class:`Graph <altgraph.Graph.Graph>`. The Dot generator won't reference 118 the *graph* once it is constructed. 119 120 If the *nodes* argument is present it is the list of nodes to include 121 in the graph, otherwise all nodes in *graph* are included. 122 123 If the *edgefn* argument is present it is a function that yields the 124 nodes connected to another node, this defaults to 125 :meth:`graph.out_nbr <altgraph.Graph.Graph.out_nbr>`. The constructor won't 126 add edges to the dot file unless both the head and tail of the edge 127 are in *nodes*. 128 129 If the *name* is present it specifies the name of the graph in the resulting 130 dot file. The default is ``"G"``. 131 132 The functions *nodevisitor* and *edgevisitor* return the default style 133 for a given edge or node (both default to functions that return an empty 134 style). 135 136 The arguments *dot*, *dotty* and *neato* are used to pass the path to 137 the corresponding `graphviz`_ command. 138 139 140 Updating graph attributes 141 ......................... 142 143 .. method:: Dot.style(\**attr) 144 145 Sets the overall style (graph attributes) to the given attributes. 146 147 See `Valid Attributes`_ for more information about the attributes. 148 149 .. method:: Dot.node_style(node, \**attr) 150 151 Sets the style for *node* to the given attributes. 152 153 This method will add *node* to the graph when it isn't already 154 present. 155 156 See `Valid Attributes`_ for more information about the attributes. 157 158 .. method:: Dot.all_node_style(\**attr) 159 160 Replaces the current style for all nodes 161 162 163 .. method:: edge_style(head, tail, \**attr) 164 165 Sets the style of an edge to the given attributes. The edge will 166 be added to the graph when it isn't already present, but *head* 167 and *tail* must both be valid nodes. 168 169 See `Valid Attributes`_ for more information about the attributes. 170 171 172 173 Emitting output 174 ............... 175 176 .. method:: Dot.display([mode]) 177 178 Displays the current graph via dotty. 179 180 If the *mode* is ``"neato"`` the dot file is processed with 181 the neato command before displaying. 182 183 This method won't return until the dotty command exits. 184 185 .. method:: save_dot(filename) 186 187 Saves the current graph representation into the given file. 188 189 .. note:: 190 191 For backward compatibility reasons this method can also 192 be called without an argument, it will then write the graph 193 into a fixed filename (present in the attribute :data:`Graph.temp_dot`). 194 195 This feature is deprecated and should not be used. 196 197 198 .. method:: save_image(file_name[, file_type[, mode]]) 199 200 Saves the current graph representation as an image file. The output 201 is written into a file whose basename is *file_name* and whose suffix 202 is *file_type*. 203 204 The *file_type* specifies the type of file to write, the default 205 is ``"gif"``. 206 207 If the *mode* is ``"neato"`` the dot file is processed with 208 the neato command before displaying. 209 210 .. note:: 211 212 For backward compatibility reasons this method can also 213 be called without an argument, it will then write the graph 214 with a fixed basename (``"out"``). 215 216 This feature is deprecated and should not be used. 217 218 .. method:: iterdot() 219 220 Yields all lines of a `graphviz`_ input file (including line endings). 221 222 .. method:: __iter__() 223 224 Alias for the :meth:`iterdot` method. 225
