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
7The :py:mod:`~altgraph.Dot` module provides a simple interface to the
8file format used in the `graphviz`_ program. The module is intended to
9offload the most tedious part of the process (the **dot** file generation)
10while transparently exposing most of its features.
11
12.. _`graphviz`: <http://www.research.att.com/sw/tools/graphviz/>`_
13
14To display the graphs or to generate image files the `graphviz`_
15package needs to be installed on the system, moreover the :command:`dot` and :command:`dotty` programs must
16be accesible in the program path so that they can be ran from processes spawned
17within the module.
18
19Example usage
20-------------
21
22Here 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
43Directed graph and non-directed graph
44-------------------------------------
45
46Dot class can use for both directed graph and non-directed graph
47by passing *graphtype* parameter.
48
49Example::
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
58Customizing the output
59----------------------
60
61The graph drawing process may be customized by passing
62valid :command:`dot` parameters for the nodes and edges. For a list of all
63parameters see the `graphviz`_ documentation.
64
65Example::
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
86Valid 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
111Class 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
140Updating 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
173Emitting 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