richreports module

Library that supports the construction of human-readable, interactive static analysis reports that consist of decorated concrete syntax representations of programs.

class location(iterable=(), /)

Bases: Tuple[int, int]

Data structure for representing a location within a report as a tuple of two integers: the line number (where the first line in the report has a line number of 1) and the column on that line.

class report(string: str)

Bases: object

Data structure that represents the raw concrete syntax string as a two-dimensional array of two-sided stacks. Each stack holds delimiters (left and right) that may appear before or after that character in the rendered version of the report.

>>> r = report(
...    'def f(x, y):\n' +
...    '    return x + y'
... )

The individual lines in the supplied string can be retrieved via the lines attribute.

>>> list(r.lines)
['def f(x, y):', '    return x + y']

Delimiters can be added around a range within the report by specifying the locations corresponding to the endpoints (inclusive) of the range.

>>> r.enrich((2, 11), (2, 15), '(', ')')
>>> for line in r.render().split('\n'):
...     print(line)
def f(x, y):
    return (x + y)

The optional enrich_intermediate_lines parameter can be used to delimit all complete lines that appear between the supplied endpoints.

>>> r.enrich((1, 0), (2, 15), '<b>', '</b>', True)
>>> for line in r.render().split('\n'):
...     print(line)
<b>def f(x, y):</b>
<b>    return (x + y)</b>

By default, the enrich_intermediate_lines parameter is set to False.

>>> r.enrich((1, 0), (2, 15), '<div>\n', '\n</div>')
>>> for line in r.render().split('\n'):
...     print(line)
<div>
<b>def f(x, y):</b>
<b>    return (x + y)</b>
</div>

enrich(start: Union[tuple, location], end: Union[tuple, location], left: str, right: str, enrich_intermediate_lines=False)

Add a pair of left and right delimiters around a given range within this report instance.

>>> r = report(
...    'def f(x, y):\n' +
...    '    return x + y'
... )
>>> r.enrich((1, 0), (2, 15), '<b>', '</b>', True)
>>> for line in r.render().split('\n'):
...     print(line)
<b>def f(x, y):</b>
<b>    return x + y</b>

render() → str

Return the report (including all delimiters) as a string.

>>> r = report(
...    'def f(x, y):\n' +
...    '    return x + y'
... )
>>> for line in r.render().split('\n'):
...     print(line)
def f(x, y):
    return x + y