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 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 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 - 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 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 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¶
-
class
radon.cli.harvest.
Harvester
(paths, config)¶ Base class defining the interface of a Harvester object.
A Harvester has the following lifecycle:
- Initialization: h = Harvester(paths, config)
- Execution: r = h.results. results holds an iterable object.
The first time results is accessed, h.run() is called. This method
should not be subclassed. Instead, the
gobble()
method should be implemented. - Reporting: the methods as_json and as_xml return a string with the corrisponding format. The method to_terminal is a generator that yields the lines to be printed in the terminal.
This class is meant to be subclasses and cannot be used directly, since the methods
gobble()
,as_xml()
andto_terminal()
are not implemented.-
__init__
(paths, config)¶ Initialize the Harvester.
paths is a list of paths to analyze. config is a
Config
object holding the configuration values specific to the Harvester.
-
as_codeclimate_issues
()¶ Format the results as Code Climate issues.
-
as_json
()¶ Format the results as JSON.
-
as_md
()¶ Format the results as Markdown.
-
as_xml
()¶ Format the results as XML.
-
gobble
(fobj)¶ Subclasses must implement this method to define behavior.
This method is called for every file to analyze. fobj is the file object. This method should return the results from the analysis, preferably a dictionary.
-
results
¶ This property holds the results of the analysis.
The first time it is accessed, an iterator is returned. Its elements are cached into a list as it is iterated over. Therefore, if results is accessed multiple times after the first one, a list will be returned.
-
run
()¶ Start the analysis. For every file, this method calls the
gobble()
method. Results are yielded as tuple:(filename, analysis_results)
.
-
to_terminal
()¶ Yields tuples representing lines to be printed to a terminal.
The tuples have the following format:
(line, args, kwargs)
. The line is then formatted with line.format(*args, **kwargs).
-
class
radon.cli.harvest.
CCHarvester
(paths, config)¶ A class that analyzes Python modules’ Cyclomatic Complexity.
-
class
radon.cli.harvest.
RawHarvester
(paths, config)¶ A class that analyzes Python modules’ raw metrics.
-
class
radon.cli.harvest.
MIHarvester
(paths, config)¶ A class that analyzes Python modules’ Maintainability Index.