Home | History | Annotate | Download | only in doc 
      1 :mod:`altgraph.ObjectGraph` --- Graphs of objecs with an identifier
      2 ===================================================================
      3 
      4 .. module:: altgraph.ObjectGraph
      5    :synopsis: A graph of objects that have a "graphident" attribute.
      6 
      7 .. class:: ObjectGraph([graph[, debug]])
      8 
      9    A graph of objects that have a "graphident" attribute. The
     10    value of this attribute is the key for the object in the
     11    graph.
     12 
     13    The optional *graph* is a previously constructed
     14    :class:`Graph <altgraph.Graph.Graph>`.
     15 
     16    The optional *debug* level controls the amount of debug output
     17    (see :meth:`msg`, :meth:`msgin` and :meth:`msgout`).
     18 
     19    .. note:: the altgraph library does not generate output, the
     20       debug attribute and message methods are present for use
     21       by subclasses.
     22 
     23 .. data:: ObjectGraph.graph
     24 
     25    An :class:`Graph <altgraph.Graph.Graph>` object that contains
     26    the graph data.
     27 
     28 
     29 .. method:: ObjectGraph.addNode(node)
     30 
     31    Adds a *node* to the graph.
     32 
     33    .. note:: re-adding a node that was previously removed
     34       using :meth:`removeNode` will reinstate the previously
     35       removed node.
     36 
     37 .. method:: ObjectGraph.createNode(self, cls, name, \*args, \**kwds)
     38 
     39    Creates a new node using ``cls(*args, **kwds)`` and adds that
     40    node using :meth:`addNode`.
     41 
     42    Returns the newly created node.
     43 
     44 .. method:: ObjectGraph.removeNode(node)
     45 
     46    Removes a *node* from the graph when it exists. The *node* argument
     47    is either a node object, or the graphident of a node.
     48 
     49 .. method:: ObjectGraph.createReferences(fromnode, tonode[, edge_data])
     50 
     51    Creates a reference from *fromnode* to *tonode*. The optional
     52    *edge_data* is associated with the edge.
     53 
     54    *Fromnode* and *tonode* can either be node objects or the graphident
     55    values for nodes.
     56 
     57 .. method:: removeReference(fromnode, tonode)
     58 
     59    Removes the reference from *fromnode* to *tonode* if it exists.
     60 
     61 .. method:: ObjectGraph.getRawIdent(node)
     62 
     63    Returns the *graphident* attribute of *node*, or the graph itself
     64    when *node* is :data:`None`.
     65 
     66 .. method:: getIdent(node)
     67 
     68    Same as :meth:`getRawIdent`, but only if the node is part
     69    of the graph.
     70 
     71    *Node* can either be an actual node object or the graphident of
     72    a node.
     73 
     74 .. method:: ObjectGraph.findNode(node)
     75 
     76    Returns a given node in the graph, or :data:`Node` when it cannot
     77    be found.
     78 
     79    *Node* is either an object with a *graphident* attribute or
     80    the *graphident* attribute itself.
     81 
     82 .. method:: ObjectGraph.__contains__(node)
     83 
     84    Returns True if *node* is a member of the graph. *Node* is either an
     85    object with a *graphident* attribute or the *graphident* attribute itself.
     86 
     87 .. method:: ObjectGraph.flatten([condition[, start]])
     88 
     89    Yield all nodes that are entirely reachable by *condition*
     90    starting fromt he given *start* node or the graph root.
     91 
     92    .. note:: objects are only reachable from the graph root
     93       when there is a reference from the root to the node
     94       (either directly or through another node)
     95 
     96 .. method:: ObjectGraph.nodes()
     97 
     98    Yield all nodes in the graph.
     99 
    100 .. method:: ObjectGraph.get_edges(node)
    101 
    102    Returns two iterators that yield the nodes reaching by
    103    outgoing and incoming edges.
    104 
    105 .. method:: ObjectGraph.filterStack(filters)
    106 
    107    Filter the ObjectGraph in-place by removing all edges to nodes that
    108    do not match every filter in the given filter list
    109 
    110    Returns a tuple containing the number of:
    111    (*nodes_visited*, *nodes_removed*, *nodes_orphaned*)
    112 
    113 .. method:: ObjectGraph.edgeData(fromNode, toNode):
    114    Return the edge data associated with the edge from *fromNode*
    115    to *toNode*.  Raises :exc:`KeyError` when no such edge exists.
    116 
    117    .. versionadded: 0.12
    118 
    119 .. method:: ObjectGraph.updateEdgeData(fromNode, toNode, edgeData)
    120 
    121    Replace the data associated with the edge from *fromNode* to
    122    *toNode* by *edgeData*.
    123 
    124    Raises :exc:`KeyError` when the edge does not exist.
    125 
    126 Debug output
    127 ------------
    128 
    129 .. data:: ObjectGraph.debug
    130 
    131    The current debug level.
    132 
    133 .. method:: ObjectGraph.msg(level, text, \*args)
    134 
    135    Print a debug message at the current indentation level when the current
    136    debug level is *level* or less.
    137 
    138 .. method:: ObjectGraph.msgin(level, text, \*args)
    139 
    140    Print a debug message when the current debug level is *level* or less,
    141    and increase the indentation level.
    142 
    143 .. method:: ObjectGraph.msgout(level, text, \*args)
    144 
    145    Decrease the indentation level and print a debug message when the
    146    current debug level is *level* or less.
    147