python_graphs.instruction

module documentation

(source)

An Instruction represents an executable unit of a Python program.

Almost all simple statements correspond to Instructions, except for statements likes pass, continue, and break, whose effects are already represented in the structure of the control-flow graph.

In addition to simple statements, assignments that take place outside of simple statements such as implicitly in a function or class definition also correspond to Instructions.

The complete set of places where Instructions occur in source are listed here:

<Instruction> (Any node in INSTRUCTION_AST_NODES used as a statement.)

2. if <Instruction>: ... (elif is the same.) 3+4. for <Instruction> in <Instruction>: ... 5. while <Instruction>: ... 6. try: ... except <Instruction>: ... 7. TODO(dbieber): Test for "with <Instruction>:"...

In the code:

@decorator def fn(args=defaults):

body

Outside of the function definition, we get the following instructions: 8. Each decorator is an Instruction. 9. Each default is an Instruction. 10. The assignment of the function def to the function name is an Instruction. Inside the function definition, we get the following instructions: 11. An Instruction for the assignment of values to the arguments. (1, again) And then the body can consist of multiple Instructions too.

Likewise in the code:

@decorator class C(object):

body

The following are Instructions: (8, again) Each decorator is an Instruction 12. The assignment of the class to the variable C is an Instruction. (1, again) And then the body can consist of multiple Instructions too. 13. TODO(dbieber): The base class (object) is an Instruction too.

Class	`AccessVisitor`	Visitor that computes an ordered list of accesses.
Class	`Instruction`	Represents an executable unit of a Python program.
Function	`access_identifier`	Undocumented
Function	`access_is_read`	Undocumented
Function	`access_is_write`	Undocumented
Function	`access_kind`	Undocumented
Function	`access_kind_and_name`	Undocumented
Function	`access_name`	Undocumented
Function	`create_writes`	Undocumented
Function	`get_accesses_from_ast_node`	Get all accesses for an AST node, in depth-first AST field order.
Function	`get_reads_from_ast_node`	Get all reads for an AST node, in depth-first AST field order.
Function	`get_writes_from_ast_node`	Get all writes for an AST node, in depth-first AST field order.
Function	`represent_same_program`	Whether AST nodes node1 and node2 represent the same program syntactically.
Constant	`ARGS`	Undocumented
Constant	`CLASS`	Undocumented
Constant	`EXCEPTION`	Undocumented
Constant	`FUNCTION`	Undocumented
Constant	`INSTRUCTION_AST_NODES`	Undocumented
Constant	`ITERATOR`	Undocumented
Constant	`KWARG`	Undocumented
Constant	`KWONLYARGS`	Undocumented
Constant	`READ`	Undocumented
Constant	`READ_CONTEXTS`	Undocumented
Constant	`SIMPLE_STATEMENT_AST_NODES`	Undocumented
Constant	`VARARG`	Undocumented
Constant	`WRITE`	Undocumented
Constant	`WRITE_CONTEXTS`	Undocumented
Function	`_canonicalize`	Undocumented

def access_identifier(name, kind): (source) ¶

Undocumented

def access_is_read(access): (source) ¶

Undocumented

def access_is_write(access): (source) ¶

Undocumented

def access_kind(access): (source) ¶

Undocumented

def access_kind_and_name(access): (source) ¶

Undocumented

def access_name(access): (source) ¶

Undocumented

def create_writes(node, parent=None): (source) ¶

Undocumented

def get_accesses_from_ast_node(node): (source) ¶

Get all accesses for an AST node, in depth-first AST field order.

def get_reads_from_ast_node(ast_node): (source) ¶

Get all reads for an AST node, in depth-first AST field order.

Parameters
ast_node	The AST node of interest.
Returns
A list of writes performed by that AST node.

def get_writes_from_ast_node(ast_node): (source) ¶

Get all writes for an AST node, in depth-first AST field order.

Parameters
ast_node	The AST node of interest.
Returns
A list of writes performed by that AST node.

def represent_same_program(node1, node2): (source) ¶

Whether AST nodes node1 and node2 represent the same program syntactically.

Two programs are the same syntactically is they have equivalent ASTs, up to some small changes. The context field of Name nodes can change without the syntax represented by the AST changing. This allows for example for the short program 'x' (a read) to match with a subprogram 'x' of 'x = 3' (in which x is a write), since these two programs are the same syntactically ('x' and 'x').

Except for the context field of Name nodes, the two nodes are recursively checked for exact equality.

Parameters
node1	An AST node. This can be an ast.AST object, a primitive, or a list of AST nodes (primitives or ast.AST objects).
node2	An AST node. This can be an ast.AST object, a primitive, or a list of AST nodes (primitives or ast.AST objects).
Returns
Whether the two nodes represent equivalent programs.

ARGS: str = (source) ¶

Undocumented

Value

'args'

CLASS: str = (source) ¶

Undocumented

Value

'class'

EXCEPTION: str = (source) ¶

Undocumented

Value

'exception'

FUNCTION: str = (source) ¶

Undocumented

Value

'function'

INSTRUCTION_AST_NODES = (source) ¶

Undocumented

Value

(ast.Expr,
 ast.Assert,
 ast.Assign,
 ast.AugAssign,
 ast.Delete,
 ast.Print,
 ast.Return,
...

ITERATOR: str = (source) ¶

Undocumented

Value

'iter'

KWARG: str = (source) ¶

Undocumented

Value

'kwarg'

KWONLYARGS: str = (source) ¶

Undocumented

Value

'kwonlyargs'

READ: str = (source) ¶

Undocumented

Value

'read'

READ_CONTEXTS = (source) ¶

Undocumented

Value

(ast.Load, ast.AugLoad)

SIMPLE_STATEMENT_AST_NODES = (source) ¶

Undocumented

Value

INSTRUCTION_AST_NODES+(ast.Pass, ast.Break, ast.Continue)

VARARG: str = (source) ¶

Undocumented

Value

'vararg'

WRITE: str = (source) ¶

Undocumented

Value

'write'

WRITE_CONTEXTS = (source) ¶

Undocumented

Value

(ast.Store, ast.Del, ast.Param, ast.AugStore)

def _canonicalize(node): (source) ¶

Undocumented