Using radon programmatically

Radon has a set of functions and classes that you can call from within your program to analyze files.

Radon’s API is composed of three layers:

  • at the very bottom (the lowest level) there are the Visitors: with these classes one can build an AST out of the code and get basic metrics. Currently, there are two available visitors: ComplexityVisitor and HalsteadVisitor. With the former one analyzes the cyclomatic complexity of the code, while the latter gathers the so-called Halstead metrics. With those and other raw metrics one can compute the Maintainability Index. Example:

    >>> from radon.visitors import ComplexityVisitor
>>> v = ComplexityVisitor.from_code('''
def factorial(n):
    if n < 2: return 1
    return n * factorial(n - 1)

def foo(bar):
    return sum(i for i in range(bar ** 2) if bar % i)
''')
>>> v.functions
[Function(name='factorial', lineno=2, col_offset=0, endline=4, is_method=False,
classname=None, closures=[], complexity=2),
Function(name='foo', lineno=6, col_offset=0, endline=7, is_method=False, classname=None,
closures=[], complexity=3)]

  • at a higher level, there are helper functions residing in separate modules. For cyclomatic complexity, one can use those inside radon.complexity. For Halstead metrics and MI index those inside radon.metrics. Finally, for raw metrics (that includes SLOC, LLOC, LOC, &c.) one can use the function analyze() inside the radon.raw module. With the majority of these functions the result is an object (Module object in the case of raw metrics) or a list of objects (Function or Class objects for cyclomatic complexity). Example:

    >>> from radon.complexity import cc_rank, cc_visit
>>> cc_rank(4), cc_rank(9), cc_rank(14), cc_rank(23)
('A', 'B', 'C', 'D')
>>> cc_visit('''
class A(object):
    def meth(self):
        return sum(i for i in range(10) if i - 2 < 5)

def fib(n):
    if n < 2: return 1
    return fib(n - 1) + fib(n - 2)
''')

[Function(name='fib', lineno=6, col_offset=0, endline=8, is_method=False, classname=None,
closures=[], complexity=2), Class(name='A', lineno=2, col_offset=0, endline=4,
methods=[Function(name='meth', lineno=3, col_offset=4, endline=4, is_method=True,
classname='A', closures=[], complexity=3)], real_complexity=3),
Function(name='meth', lineno=3, col_offset=4, endline=4, is_method=True, classname='A',
closures=[], complexity=3)]

>>> from radon.raw import analyze
>>> analyze("""def _split_tokens(tokens, token, value):
    '''Split a list of tokens on the specified token pair (token, value),
    where *token* is the token type (i.e. its code) and *value* its actual
    value in the code.
    '''
    res = [[]]
    for token_values in tokens:
        if (token, value) == token_values[:2]:
            res.append([])
            continue
        res[-1].append(token_values)
    return res
""")
>>> Module(loc=12, lloc=9, sloc=12, comments=0, multi=4, blank=0)

  • at the highest level there are the Harvesters. A Harvester implements all the business logic of the CLI interface. To use a Harvester, it’s sufficient to create a Config object (which contains all the config values) and pass it to the Harvester instance along with a list of paths to analyze. An Harvester can then export its result to various formats (for cyclomatic complexity both JSON and XML are available). It’s possible to find an example for this in the Xenon project.

Cyclomatic Complexity

radon.complexity.cc_visit(code, **kwargs)

Visit the given code with ComplexityVisitor. All the keyword arguments are directly passed to the visitor.

radon.complexity.cc_visit_ast(ast_node, **kwargs)

Visit the AST node with ComplexityVisitor. All the keyword arguments are directly passed to the visitor.

radon.complexity.cc_rank(cc)

Rank the complexity score from A to F, where A stands for the simplest and best score and F the most complex and worst one:

1 - 5 A (low risk - simple block)
6 - 10 B (low risk - well structured and stable block)
11 - 20 C (moderate risk - slightly complex block)
21 - 30 D (more than moderate risk - more complex block)
31 - 40 E (high risk - complex block, alarming)
41+ F (very high risk - error-prone, unstable block)

Here block is used in place of function, method or class.

The formula used to convert the score into an index is the following:

\[\text{rank} = \left \lceil \dfrac{\text{score}}{10} \right \rceil - H(5 - \text{score})\]

where H(s) stands for the Heaviside Step Function. The rank is then associated to a letter (0 = A, 5 = F).

radon.complexity.sorted_results(blocks, order=SCORE)

Given a ComplexityVisitor instance, returns a list of sorted blocks with respect to complexity. A block is a either Function object or a Class object. The blocks are sorted in descending order from the block with the highest complexity.

The optional order parameter indicates how to sort the blocks. It can be:

  • LINES: sort by line numbering;
  • ALPHA: sort by name (from A to Z);
  • SCORE: sorty by score (descending).

Default is SCORE.

Raw metrics

radon.raw.analyze(source)

Analyze the source code and return a namedtuple with the following fields:

  • loc: The number of lines of code (total)
  • lloc: The number of logical lines of code
  • sloc: The number of source lines of code (not necessarily
    corresponding to the LLOC)
  • comments: The number of Python comment lines
  • multi: The number of lines which represent multi-line strings
  • single_comments: The number of lines which are just comments with
    no code
  • blank: The number of blank lines (or whitespace-only ones)

The equation \(sloc + blanks + multi + single_comments = loc\) should always hold. Multiline strings are not counted as comments, since, to the Python interpreter, they are not comments but strings.

Other metrics

radon.metrics.h_visit(code)

Compile the code into an AST tree and then pass it to h_visit_ast().

radon.metrics.h_visit_ast(ast_node)

Visit the AST node using the HalsteadVisitor visitor. The results are HalsteadReport namedtuples with the following fields:

  • h1: the number of distinct operators
  • h2: the number of distinct operands
  • N1: the total number of operators
  • N2: the total number of operands
  • h: the vocabulary, i.e. h1 + h2
  • N: the length, i.e. N1 + N2
  • calculated_length: h1 * log2(h1) + h2 * log2(h2)
  • volume: V = N * log2(h)
  • difficulty: D = h1 / 2 * N2 / h2
  • effort: E = D * V
  • time: T = E / 18 seconds
  • bugs: B = V / 3000 - an estimate of the errors in the implementation

The actual return of this function is a namedtuple with the following fields:

  • total: a HalsteadReport namedtuple for the entire scanned file
  • functions: a list of `HalsteadReport`s for each toplevel function

Nested functions are not tracked.

radon.metrics.mi_visit(code, multi)

Visit the code and compute the Maintainability Index (MI) from it.

radon.metrics.mi_rank(score)

Rank the score with a letter:

  • A if \(\text{score} > 19\);
  • B if \(9 < \text{score} \le 19\);
  • C if \(\text{score} \le 9\).
radon.metrics.mi_parameters(code, count_multi=True)

Given a source code snippet, compute the necessary parameters to compute the Maintainability Index metric. These include:

  • the Halstead Volume
  • the Cyclomatic Complexity
  • the number of LLOC (Logical Lines of Code)
  • the percent of lines of comment
Parameters:multi – If True, then count multiline strings as comment lines as well. This is not always safe because Python multiline strings are not always docstrings.
radon.metrics.mi_compute(halstead_volume, complexity, sloc, comments)

Compute the Maintainability Index (MI) given the Halstead Volume, the Cyclomatic Complexity, the SLOC number and the number of comment lines. Usually it is not used directly but instead mi_visit() is preferred.

Visitors

class radon.visitors.ComplexityVisitor(to_method=False, classname=None, off=True, no_assert=False)

A visitor that keeps track of the cyclomatic complexity of the elements.

Parameters:
  • to_method – If True, every function is treated as a method. In this case the classname parameter is used as class name.
  • classname – Name of parent class.
  • off – If True, the starting value for the complexity is set to 1, otherwise to 0.
class radon.visitors.HalsteadVisitor(context=None)

Visitor that keeps track of operators and operands, in order to compute Halstead metrics (see radon.metrics.h_visit()).

Harvesters