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

class radon.cli.harvest.Harvester(paths, config)

Base class defining the interface of a Harvester object.

A Harvester has the following lifecycle:

1. Initialization: h = Harvester(paths, config)
2. 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.
3. 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() and to_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_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.