AST Nodes

The analysis package takes standard compiler.ast nodes and annotates them with additional information which is then used in subsequent activities such as code generation and documentation. Below are tables showing the annotations used for various AST nodes:

General

Node Annotation Purpose
* _contexts Indicates the types that the node is considered to have, along with the context in which it has them. A dictionary mapping contexts to types/references.
* _parent Indicates the parent node of a node - useful for adding sibling nodes (specialisations of functions) or for tracking the processing of expressions (assignment processing).
Function
For
While
_counterIndicates the number of contexts recorded in the node graph at a particular point in time, typically upon visiting one of the affected nodes. This number is checked again and compared to the current number of contexts in the node graph to see if any additional information has surfaced and whether it is necessary to analyse the node (and its descendants) again.

Names and Symbols

Node Annotation Purpose
Function
Module
Class
Reference
Stmt
_namespace A dictionary mapping names to lists of defining nodes for each name. Some Stmt nodes have _namespace annotations when employed by conditional or loop nodes.
Function _globals Provides a list of globals used in the function.
Function_specialsProvides a list of names which are global to the function but which are not "true" globals. Typically, this affects local classes and functions, where their names would not be stored in the global namespace but must still be available within their body.
Name _scope Indicates which scope the name uses to refer to a variable.
Examples: "locals", "specials", "globals".
Name
AssName
Class
Function
Getattr
_name_context Indicates the kind of local scope in which the name resides, or in the case of Getattr the kind of scope from which the attribute was retrieved. (This does not apply to AssAttr since the kind of scope can be inferred from the type of node involved, whereas Getattr may involve either class or instance attribute access.)
Examples: "class", "instance".
Module _constants_table A list of constants in the module.
Module
Name
Function
Import
_module_name The name of the module within which a name is defined. On Module nodes, this is the same as _qualified_name. On Function nodes, this is used to initialise namespaces and to build qualified names for globals referenced from those namespaces.
Name
AssName
Module
Class
Function
_qualified_name Provides a qualified name for use in generated code (where appropriate) - see _name_context for additional guidance.
Import_namesProvides a list of name nodes referring to other modules. Each node contains an expr attribute referring to the module, along with module_name and as_name attributes referring to the naming details of the import operation. Additionally, a name attribute provides the resulting name to which the module is bound in the current namespace.

Classes and Instantiation

Node Annotation Purpose
Reference _class
Indicates the class of a particular reference.
Class _instances A list of instances (references) for a given class.
CallFunc
Const
List
Compare
_instantiates Indicates that the node instantiates a particular reference.
*_raisesIndicates that the node instantiates a particular reference as a possible exception.
Class_inheritedA dictionary mapping names to superclasses which contain the definitions of such names for the annotated class.

Additional Symbols

Node Annotation Purpose
Slice _none
A reference to None as a default argument to a __getslice__ method.
Compare_defaultA reference, typically to False, as a default result of comparisons which cannot be supported by their participants.

Attribute Access

Node Annotation Purpose
AssAttr
AugAssign
Getattr
_undesirable
Indicates object types which may occur when attempting to obtain the named attribute, but which do not support access to such an attribute.
AssAttr
AugAssign
Getattr
_permittedIndicates object types which may occur and which do support access to the named attribute.

Operations and Invocations

Node Annotation Purpose
AugAssign_opThe operation which provides support for the augmented assignment.
Compare _ops
A list of operator objects summarising the binary operations employed in the comparison.
If _tests A dictionary of helper nodes used to represent invocations of __true__ methods on tests associated with an if statement. The dictionary maps test nodes to their corresponding helper node.
While _test A helper node used to represent invocations of __true__ methods on the continuation test of the while statement.
And
Or
_nodes A list of helper nodes, corresponding to elements in the nodes attribute of the affected node, where each represents invocations of __true__ methods on the corresponding original node.
Not_true_callA helper node representing an invocation of the __true__ method on the affected expression.
AssTuple_next_callA helper node used to represent invocations of next methods on any iterator found through its parent node.
List
Print
Printnl
Tuple
_callsA list of helper nodes used to represent invocations of methods that implement the behaviour of the annotated node. List and Tuple nodes employ invocations of append methods, whereas Print and Printnl nodes employ invocations of __str__ methods.
* _ignored Indicates that the block associated with a test in a conditional statement would be ignored due to the test always yielding a false value.
* _short_circuited Indicates that the block associated with a test in a conditional statement would always be executed in preference to following blocks and that such following blocks and their associated test nodes need not be generated.
* _original Indicates the original node used to produce a node within a specialisation.
Function
(specialisation)
_specialises An attribute whose presence indicates that the node and its children represent a specialisation (as opposed to an original function), indicating the original function on which the specialisation is based.
Function
(original)
_signatures A list of signatures each corresponding to a specialisation in the _specialisations annotation; together, these annotations should be considered as a table. (See also _signatures for invocation nodes below.)
Function
(original)
_specialisations A list of specialisations created for a particular function.
Function
(specialisation)
_signatureA list of type names for each function parameter, used for convenience in finding suitable specialisations for callers.
Function
(specialisation)
_localsA list of locals for each function parameter, similar to _signature but containing actual node information.
CallFunc
AssTuple
AssList
AssAttr
AssName
List
For
_targets A list of specialisations that may be involved in a function or method invocation.
CallFunc
AssTuple
AssList
AssAttr
AssName
List
For
_argnames A list of argument name lists that are associated with each possible specialisation from _targets.
CallFunc
AssTuple
AssList
AssAttr
AssName
List
For
_argnodes A dictionary mapping argument names to argument nodes. Taking a name from _argnames and using it as a key in this dictionary should yield the argument node in the AST.
CallFunc
AssTuple
AssList
AssAttr
AssName
List
For
_argnodes_keysA list of keys to the _argnodes dictionary ordered in correspondence with the _targets, _locals, _argnames and _refcontexts annotations.
CallFunc
AssTuple
AssList
AssAttr
AssName
List
For
_locals A list of argument reference lists that are associated with each possible specialisation from _targets. This is similar to _signatures (below) but provides actual reference information.
CallFunc
AssTuple
AssList
AssAttr
AssName
List
For
_signatures A list of argument signature lists that are associated with each possible specialisation from _targets. This provides a list of possible type/reference names for each argument.
CallFunc
AssTuple
AssList
AssAttr
AssName
List
For
_refcontexts A list containing the meaning of references employed in the node's arguments. This is used to generate code for parameters and also to generate invocation target selection tests.
Examples: "new" (used in instantiation), "context" (used in method calls), "top" (used to obtain the current subexpression).
Generally, such information is not relevant in the analysis phase, since exactly how generated code remembers arguments and subsequently manipulates them is strictly a concern for the code generator itself.