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

Atn

class understand.Atn

Bases: object

An Understand annotation

Annotations can be obtained for a database (understand.Db.annotations()) or for an entity (understand.Ent.annotations()).

Reads reflect the annotation as it was at the listing moment (like the Perl API): concurrent changes in the application do not alter an already-obtained object. retype() applies to the live annotation by identity and refreshes this object; it raises understand.UnderstandError if the annotation was deleted since the listing.

Methods Summary

author	Return the author who created the annotation.
date	Return the date the annotation was last modified.
ent	Return the entity this annotation belongs to.
line	Return the line number if applicable.
retype	Change the annotation to a different template.
template	Return the annotation template id, or an empty string for a freeform annotation.
text	Return the text of the annotation, as displayed: media is shown as readable text, and a templated annotation's fields are inlined as one "Label: value" line each, opening with "Template: <name>" -- the same lines an ignore comment carries, so a record parses identically wherever it came from.

Methods Documentation

author() → str

Return the author who created the annotation.

Return type:

str

Returns:

the author

date() → str

Return the date the annotation was last modified.

Return type:

str

Returns:

the date time as a string of the form YYYY-MM-DDTHH:MM:SS such as 2000-01-01T19:20:30.

ent() → understand.Ent

Return the entity this annotation belongs to.

Return type:

understand.Ent

Returns:

the entity this annotation belongs to or None if the annotation is orphaned.

line() → int

Return the line number if applicable.

Return type:

int

Returns:

the line number (in the file) of the annotation or -1 if the annotation is not a line annotation.

retype(template, preview=False) → list[str]

Change the annotation to a different template. Values whose field key exists in the new template and remains valid for it carry over; the rest are dropped. An empty template converts the annotation back to freeform.

Parameters:

• template (str) – the new template id, or an empty string

• preview (bool or None) – optional, when True report the dropped field keys without changing the annotation.

Return type:

list[str]

Returns:

the dropped field keys

Raises:

understand.UnderstandError – if the template is unknown, or the annotation was deleted since it was obtained

template() → str

Return the annotation template id, or an empty string for a freeform annotation.

Return type:

str

Returns:

the template id

text() → str

Return the text of the annotation, as displayed: media is shown as readable text, and a templated annotation’s fields are inlined as one “Label: value” line each, opening with “Template: <name>” – the same lines an ignore comment carries, so a record parses identically wherever it came from.

Return type:

str

Returns:

the annotation text