• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
126Debug 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