sdk/platform-tools/systrace/catapult/telemetry/third_party/altgraph/doc/dot.rst

   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.