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
andHalsteadVisitor
. With the former one analyzes the cyclomatic complexity of the code, while the latter gathers the socalled 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 insideradon.metrics
. Finally, for raw metrics (that includes SLOC, LLOC, LOC, &c.) one can use the functionanalyze()
inside theradon.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
orClass
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  errorprone, 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 aClass
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 multiline strings
 single_comments: The number of lines which are just comments with
 no code
 blank: The number of blank lines (or whitespaceonly 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()
).