python_graphs.program_graph.ProgramGraph

class documentation

class ProgramGraph(object): (source)

A ProgramGraph represents a Python program or function.

Method	`__init__`	Constructs an empty ProgramGraph with no root.
Method	`add_edge`	Adds an edge between two nodes in the graph.
Method	`add_new_edge`	Adds a new edge between two nodes in the graph.
Method	`add_node`	Adds a ProgramGraphNode to this graph.
Method	`add_node_from_instruction`	Adds a node to the program graph.
Method	`all_nodes`	Undocumented
Method	`children`	Yields the (direct) AST children of an AST program graph node.
Method	`contains_ast_node`	Undocumented
Method	`copy_subgraph`	Returns a new program graph containing only the subtree rooted at NODE.
Method	`copy_with_placeholder`	Returns a new program graph in which the subtree of NODE is removed.
Method	`dump_tree`	Returns a string representation for debugging.
Method	`get_ast_nodes_of_type`	Undocumented
Method	`get_node`	Returns the node in the program graph corresponding to an object.
Method	`get_node_by_access`	Gets a ProgramGraph node for the given read or write.
Method	`get_node_by_ast_node`	Undocumented
Method	`get_node_by_function_name`	Undocumented
Method	`get_node_by_id`	Gets a ProgramGraph node for the given integer id.
Method	`get_node_by_source`	Undocumented
Method	`get_node_by_source_and_identifier`	Undocumented
Method	`get_nodes_by_function_name`	Undocumented
Method	`get_nodes_by_source`	Generates the nodes in the program graph containing the query source.
Method	`get_nodes_by_source_and_identifier`	Undocumented
Method	`incoming_neighbors`	Returns the incoming neighbors of a program graph node.
Method	`neighbors`	Returns the incoming and outgoing neighbors of a program graph node.
Method	`outgoing_neighbors`	Returns the outgoing neighbors of a program graph node.
Method	`parent`	Returns the AST parent of an AST program graph node.
Method	`reconstruct_ast`	Reconstruct all internal ProgramGraphNode.ast_node references.
Method	`remove_edge`	Removes an edge from the graph.
Method	`to_ast`	Convert the program graph to a Python AST.
Method	`walk_ast_descendants`	Yields the nodes that correspond to the descendants of node in the AST.
Instance Variable	`ast_id_to_program_graph_node`	Maps from an AST node's object id to the corresponding AST program graph node, if it exists.
Instance Variable	`child_map`	Maps from node id to a list of that node's AST children node ids.
Instance Variable	`edges`	A list of the edges (from_node.id, to_node.id, edge type) in the graph.
Instance Variable	`neighbors_map`	Maps from node id to a list of that node's neighboring edges.
Instance Variable	`nodes`	Maps from node id to the ProgramGraphNode with that id.
Instance Variable	`parent_map`	Maps from node id to that node's AST parent node id.
Instance Variable	`root_id`	The id of the root ProgramGraphNode.
Property	`root`	Undocumented
Method	`_build_ast`	Helper method: builds an AST and optionally sets ast_node references.

def __init__(self): (source) ¶

Constructs an empty ProgramGraph with no root.

def add_edge(self, edge): (source) ¶

Adds an edge between two nodes in the graph.

Parameters
edge	The edge, a pb.Edge proto.

def add_new_edge(self, n1, n2, edge_type=None, field_name=None): (source) ¶

Adds a new edge between two nodes in the graph.

Both nodes must already be part of the graph.

Parameters
n1	Specifies the from node of the edge. Can be any object type accepted by get_node.
n2	Specifies the to node of the edge. Can be any object type accepted by get_node.
edge_type	The type of edge. Can be any integer in the pb.Edge enum.
field_name	For AST edges, a string describing the Python AST field
Returns
The new edge.

def add_node(self, node): (source) ¶

Adds a ProgramGraphNode to this graph.

Parameters
node	The ProgramGraphNode that should be added.
Returns
The node that was added.
Raises
`ValueError`	the node has already been added to this graph.

def add_node_from_instruction(self, instruction): (source) ¶

Adds a node to the program graph.

def all_nodes(self): (source) ¶

Undocumented

def children(self, node): (source) ¶

Yields the (direct) AST children of an AST program graph node.

Parameters
node	A ProgramGraphNode.
Yields
The AST children of node, which are ProgramGraphNode objects.

def contains_ast_node(self, ast_node): (source) ¶

Undocumented

def copy_subgraph(self, node): (source) ¶

Returns a new program graph containing only the subtree rooted at NODE.

All edges that connect nodes in the subtree are included, both AST edges and other types of edges.

Parameters
node	A node in this program graph
Returns
A new ProgramGraph object whose root is NODE

def copy_with_placeholder(self, node): (source) ¶

Returns a new program graph in which the subtree of NODE is removed.

In the new graph, the subtree headed by NODE is replaced by a single node of type PLACEHOLDER, which is connected to the AST parent of NODE by the same edge type as in the original graph.

The new program graph will share structure (i.e. the ProgramGraphNode objects) with the original graph.

Parameters
node	A node in this program graph
Returns
A new ProgramGraph object with NODE replaced

def dump_tree(self, start_node=None): (source) ¶

Returns a string representation for debugging.

def get_ast_nodes_of_type(self, ast_type): (source) ¶

Undocumented

def get_node(self, obj): (source) ¶

Returns the node in the program graph corresponding to an object.

Parameters
obj	Can be an integer, AST node, ProgramGraphNode, or program graph node protobuf.
Raises
`ValueError`	no node exists in the program graph matching obj.

def get_node_by_access(self, access): (source) ¶

Gets a ProgramGraph node for the given read or write.

def get_node_by_ast_node(self, ast_node): (source) ¶

Undocumented

def get_node_by_function_name(self, name): (source) ¶

Undocumented

def get_node_by_id(self, obj): (source) ¶

Gets a ProgramGraph node for the given integer id.

def get_node_by_source(self, node): (source) ¶

Undocumented

def get_node_by_source_and_identifier(self, source, name): (source) ¶

Undocumented

def get_nodes_by_function_name(self, name): (source) ¶

Undocumented

def get_nodes_by_source(self, source): (source) ¶

Generates the nodes in the program graph containing the query source.

Parameters
source	The query source.
Returns
A generator of all nodes in the program graph with an Instruction with source that includes the query source.

def get_nodes_by_source_and_identifier(self, source, name): (source) ¶

Undocumented

def incoming_neighbors(self, node, edge_type=None): (source) ¶

Returns the incoming neighbors of a program graph node.

Parameters
node	A ProgramGraphNode.
edge_type	If provided, only edges of this type are considered.
Returns
The incoming neighbors of node, which are ProgramGraphNode objects but not necessarily AST nodes.

def neighbors(self, node, edge_type=None): (source) ¶

Returns the incoming and outgoing neighbors of a program graph node.

Parameters
node	A ProgramGraphNode.
edge_type	If provided, only edges of this type are considered.
Returns
The incoming and outgoing neighbors of node, which are ProgramGraphNode objects but not necessarily AST nodes.

def outgoing_neighbors(self, node, edge_type=None): (source) ¶

Returns the outgoing neighbors of a program graph node.

Parameters
node	A ProgramGraphNode.
edge_type	If provided, only edges of this type are considered.
Returns
The outgoing neighbors of node, which are ProgramGraphNode objects but not necessarily AST nodes.

def parent(self, node): (source) ¶

Returns the AST parent of an AST program graph node.

Parameters
node	A ProgramGraphNode.
Returns
The node's AST parent, which is also a ProgramGraphNode.

def reconstruct_ast(self): (source) ¶

Reconstruct all internal ProgramGraphNode.ast_node references.

After calling this method, all nodes of type AST_NODE will have their ast_node property refer to subtrees of a reconstructed AST object, and self.ast_id_to_program_graph_node will contain only entries from this new AST.

Note that only AST nodes reachable by fields from the root node will be converted; this should be all of them but this is not checked.

def remove_edge(self, edge): (source) ¶

Removes an edge from the graph.

If there are multiple copies of the same edge, only one copy is removed.

Parameters
edge	The edge, a pb.Edge proto.

def to_ast(self, node=None): (source) ¶

Convert the program graph to a Python AST.

def walk_ast_descendants(self, node=None): (source) ¶

Yields the nodes that correspond to the descendants of node in the AST.

Parameters
node	the node in the program graph corresponding to the root of the AST subtree that should be walked. If None, defaults to the root of the program graph.
Yields
All nodes corresponding to descendants of node in the AST.

ast_id_to_program_graph_node: dict = (source) ¶

Maps from an AST node's object id to the corresponding AST program graph node, if it exists.

child_map = (source) ¶

Maps from node id to a list of that node's AST children node ids.

edges: list = (source) ¶

A list of the edges (from_node.id, to_node.id, edge type) in the graph.

neighbors_map = (source) ¶

Maps from node id to a list of that node's neighboring edges.

nodes: dict = (source) ¶

Maps from node id to the ProgramGraphNode with that id.

parent_map = (source) ¶

Maps from node id to that node's AST parent node id.

root_id = (source) ¶

The id of the root ProgramGraphNode.

@property
root = (source) ¶

Undocumented

def _build_ast(self, node, update_references): (source) ¶

Helper method: builds an AST and optionally sets ast_node references.

Parameters
node	Program graph node to build an AST for.
update_references	Whether to modify this node and all of its children so that they point to the reconstructed AST node.
Returns
AST node corresponding to the program graph node.