Represents an executable unit of a Python program.
An Instruction is a part of an AST corresponding to a simple statement or assignment, not corresponding to control flow. The part of the AST is not necessarily an AST node. It may be an AST node, or it may instead be a string (such as a variable name).
Instructions play an important part in control flow graphs. An Instruction is the smallest unit of a control flow graph (wrapped in a ControlFlowNode). A control flow graph consists of basic blocks which represent a sequence of Instructions that are executed in a straight-line manner, or not at all.
Conceptually an Instruction is immutable. This means that while Python does permit the mutation of an Instruction, in practice an Instruction object should not be modified once it is created.
Note that an Instruction may be interrupted by an exception mid-execution. This is captured in control flow graphs via interrupting exits from basic blocks to either exception handlers or special 'raises' blocks.
In addition to pure simple statements, an Instruction can represent a number of different parts of code. These are all listed explicitly in the module docstring.
In the common case, the accesses made by an Instruction are given by the Name AST nodes contained in the Instruction's AST node. In some cases, when the instruction.source field is not None, the accesses made by an Instruction are not simply the Name AST nodes of the Instruction's node. For example, in a function definition, the only access is the assignment of the function def to the variable with the function's name; the Name nodes contained in the function definition are not part of the function definition Instruction, and instead are part of other Instructions that make up the function. The set of accesses made by an Instruction is computed when the Instruction is created and available via the accesses attribute of the Instruction.
| Method | __init__ |
Undocumented |
| Method | contains |
Whether this Instruction contains the given AST as a subprogram. |
| Method | get |
Undocumented |
| Method | get |
Undocumented |
| Method | get |
Undocumented |
| Method | get |
Undocumented |
| Instance Variable | accesses |
(optional) An ordered list of all reads and writes made by this instruction. Each item in accesses is one of either: |
| Instance Variable | node |
The AST node corresponding to the instruction. |
| Instance Variable | source |
(optional) The source of the writes. For example in the for loop for x in items: pass there is a instruction for the Name node "x". Its |
Whether this Instruction contains the given AST as a subprogram.
Computes whether node is a subtree of this Instruction's AST.
If the Instruction represents an implied write, then the node must match
against the Instruction's writes.
| Parameters | |
| node | The node to check the instruction against for a match. |
| Returns | |
| (bool) Whether or not this Instruction contains the node, syntactically. | |
(optional) An ordered list of all reads and writes made by this
instruction. Each item in accesses is one of either:
- A 3-tuple with fields (kind, node, parent). kind is either 'read' or 'write'. node is either a string or Name AST node. parent is an AST node where node occurs.
- A Name AST node
# TODO(dbieber): Use a single type for all accesses.
(optional) The source of the writes. For example in the for loop
for x in items: pass there is a instruction for the Name node "x". Its
source is ITERATOR, indicating that this instruction corresponds to x being assigned a value from an iterator. When source is not None, the Python code corresponding to the instruction does not coincide with the Python code corresponding to the instruction's node.