The Understand Python API gives scripts access to everything Understand knows about your code — entities, references, metrics, and dependencies — and powers custom checks, graphs, and reports.

Python API: getting started · Sample & solution scripts

Ref

class understand.Ref

Bases: object

An Understand reference.

A reference connects is a connection between two entities. For example func1 calls func2 is a reference where func1 is the scope and func2 is the referenced ent. The reference kind would be “call” represented with a Kind object. The string version of the kind is available with kindname and the direction (“call” versus “callby”) is available with isforward.

References occur a location in the code. The location can be retrieved with file, line and column. A reference may have come from a macro expansion. In that case, the text can be retrieved with macroexpansion.

Reference line and column numbers are 1-based.

Methods Summary

column	Return the column in source where the reference occurred.
ent	Return the entity being referenced.
file	Return the file where the reference occurred.
isforward	Return True if the reference is the first of a pair of refs (eg, use vs useby).
kind	Return the reference kind.
kindname	Return the short name of the reference kind
line	Return the line in source where the reference occurred.
macroexpansion	Return the macro expansion text for the refence file, line and column.
scope	Return the entity performing the reference.

Methods Documentation

column() → int

Return the column in source where the reference occurred.

Return type:

int

Returns:

the column

ent() → understand.Ent

Return the entity being referenced.

Return type:

understand.Ent

Returns:

the referenced entity

file() → understand.Ent

Return the file where the reference occurred.

Return type:

understand.Ent

Returns:

the file entity containing the reference.

isforward() → bool

Return True if the reference is the first of a pair of refs (eg, use vs useby).

Return type:

bool

Returns:

True if the reference is forward.

kind() → understand.Kind

Return the reference kind.

Return type:

understand.Kind

Returns:

the reference kind

kindname() → str

Return the short name of the reference kind

Return type:

str

Returns:

the kind name

This is similar to ref.kind().name(), but does not create a Kind object.

line() → int

Return the line in source where the reference occurred.

Return type:

int

Returns:

the line

macroexpansion() → str

Return the macro expansion text for the refence file, line and column.

Return type:

str

Returns:

the macro expansion text or None if no text is available

scope() → understand.Ent

Return the entity performing the reference.

Return type:

understand.Ent

Returns:

the scope entity