Mercurial Repositories > Radon Code Metrics / file revision

'''This module contains the ComplexityVisitor class which is where all the
analysis concerning Cyclomatic Complexity is done. There is also the class
HalsteadVisitor, that counts Halstead metrics.'''

#
# patched to support Python 3.5 'async def'.
#

import ast
import operator
import collections


# Helper functions to use in combination with map()
GET_COMPLEXITY = operator.attrgetter('complexity')
GET_REAL_COMPLEXITY = operator.attrgetter('real_complexity')
NAMES_GETTER = operator.attrgetter('name', 'asname')
GET_ENDLINE = operator.attrgetter('endline')

BaseFunc = collections.namedtuple('Function', ['name', 'lineno', 'col_offset',
                                               'endline', 'is_method',
                                               'classname', 'closures',
                                               'complexity'])
BaseClass = collections.namedtuple('Class', ['name', 'lineno', 'col_offset',
                                             'endline', 'methods',
                                             'real_complexity'])


def code2ast(source):
    '''Convert a string object into an AST object. This function attempts to
    convert the string into bytes.
    '''
    try:
        source = source.encode('utf-8')  # necessary in Python 3
    except UnicodeDecodeError:  # pragma: no cover
        pass
    return ast.parse(source)


class Function(BaseFunc):
    '''Object represeting a function block.'''

    @property
    def letter(self):
        '''The letter representing the function. It is `M` if the function is
        actually a method, `F` otherwise.
        '''
        return 'M' if self.is_method else 'F'

    @property
    def fullname(self):
        '''The full name of the function. If it is a method, then the full name
        is:
                {class name}.{method name}
        Otherwise it is just the function name.
        '''
        if self.classname is None:
            return self.name
        return '{0}.{1}'.format(self.classname, self.name)

    def __str__(self):
        '''String representation of a function block.'''
        return '{0} {1}:{2}->{3} {4} - {5}'.format(self.letter, self.lineno,
                                                   self.col_offset,
                                                   self.endline,
                                                   self.fullname,
                                                   self.complexity)


class Class(BaseClass):
    '''Object representing a class block.'''

    letter = 'C'

    @property
    def fullname(self):
        '''The full name of the class. It is just its name. This attribute
        exists for consistency (see :data:`Function.fullname`).
        '''
        return self.name

    @property
    def complexity(self):
        '''The average complexity of the class. It corresponds to the average
        complexity of its methods plus one.
        '''
        if not self.methods:
            return self.real_complexity
        methods = len(self.methods)
        return int(self.real_complexity / float(methods)) + (methods > 1)

    def __str__(self):
        '''String representation of a class block.'''
        return '{0} {1}:{2}->{3} {4} - {5}'.format(self.letter, self.lineno,
                                                   self.col_offset,
                                                   self.endline, self.name,
                                                   self.complexity)


class CodeVisitor(ast.NodeVisitor):
    '''Base class for every NodeVisitors in `radon.visitors`. It implements a
    couple utility class methods and a static method.
    '''

    @staticmethod
    def get_name(obj):
        '''Shorthand for ``obj.__class__.__name__``.'''
        return obj.__class__.__name__

    @classmethod
    def from_code(cls, code, **kwargs):
        '''Instanciate the class from source code (string object). The
        `**kwargs` are directly passed to the `ast.NodeVisitor` constructor.
        '''
        return cls.from_ast(code2ast(code), **kwargs)

    @classmethod
    def from_ast(cls, ast_node, **kwargs):
        '''Instantiate the class from an AST node. The `**kwargs` are
        directly passed to the `ast.NodeVisitor` constructor.
        '''
        visitor = cls(**kwargs)
        visitor.visit(ast_node)
        return visitor


class ComplexityVisitor(CodeVisitor):
    '''A visitor that keeps track of the cyclomatic complexity of
    the elements.

    :param to_method: If True, every function is treated as a method. In this
        case the *classname* parameter is used as class name.
    :param classname: Name of parent class.
    :param off: If True, the starting value for the complexity is set to 1,
        otherwise to 0.
    '''

    def __init__(self, to_method=False, classname=None, off=True,
                 no_assert=False):
        self.off = off
        self.complexity = 1 if off else 0
        self.functions = []
        self.classes = []
        self.to_method = to_method
        self.classname = classname
        self.no_assert = no_assert
        self._max_line = float('-inf')

    @property
    def functions_complexity(self):
        '''The total complexity from all functions (i.e. the total number of
        decision points + 1).

        This is *not* the sum of all the complexity from the functions. Rather,
        it's the complexity of the code *inside* all the functions.
        '''
        return sum(map(GET_COMPLEXITY, self.functions)) - len(self.functions)

    @property
    def classes_complexity(self):
        '''The total complexity from all classes (i.e. the total number of
        decision points + 1).
        '''
        return sum(map(GET_REAL_COMPLEXITY, self.classes)) - len(self.classes)

    @property
    def total_complexity(self):
        '''The total complexity. Computed adding up the visitor complexity, the
        functions complexity, and the classes complexity.
        '''
        return (self.complexity + self.functions_complexity +
                self.classes_complexity + (not self.off))

    @property
    def blocks(self):
        '''All the blocks visited. These include: all the functions, the
        classes and their methods. The returned list is not sorted.
        '''
        blocks = []
        blocks.extend(self.functions)
        for cls in self.classes:
            blocks.append(cls)
            blocks.extend(cls.methods)
        return blocks

    @property
    def max_line(self):
        '''The maximum line number among the analyzed lines.'''
        return self._max_line

    @max_line.setter
    def max_line(self, value):
        '''The maximum line number among the analyzed lines.'''
        if value > self._max_line:
            self._max_line = value

    def generic_visit(self, node):
        '''Main entry point for the visitor.'''
        # Get the name of the class
        name = self.get_name(node)
        # Check for a lineno attribute
        if hasattr(node, 'lineno'):
            self.max_line = node.lineno
        # The Try/Except block is counted as the number of handlers
        # plus the `else` block.
        # In Python 3.3 the TryExcept and TryFinally nodes have been merged
        # into a single node: Try
        if name in ('Try', 'TryExcept'):
            self.complexity += len(node.handlers) + len(node.orelse)
        elif name == 'BoolOp':
            self.complexity += len(node.values) - 1
        # Ifs, with and assert statements count all as 1.
        # Note: Lambda functions are not counted anymore, see #68
        elif name in ('With', 'If', 'IfExp',  'AsyncWith'):
            self.complexity += 1
        # The For and While blocks count as 1 plus the `else` block.
        elif name in ('For', 'While', 'AsyncFor'):
            self.complexity += bool(node.orelse) + 1
        # List, set, dict comprehensions and generator exps count as 1 plus
        # the `if` statement.
        elif name == 'comprehension':
            self.complexity += len(node.ifs) + 1

        super(ComplexityVisitor, self).generic_visit(node)

    def visit_Assert(self, node):
        '''When visiting `assert` statements, the complexity is increased only
        if the `no_assert` attribute is `False`.
        '''
        self.complexity += not self.no_assert

    def visit_FunctionDef(self, node):
        '''When visiting functions a new visitor is created to recursively
        analyze the function's body.
        '''
        # The complexity of a function is computed taking into account
        # the following factors: number of decorators, the complexity
        # the function's body and the number of closures (which count
        # double).
        closures = []
        body_complexity = 1
        for child in node.body:
            visitor = ComplexityVisitor(off=False, no_assert=self.no_assert)
            visitor.visit(child)
            closures.extend(visitor.functions)
            # Add general complexity but not closures' complexity, see #68
            body_complexity += visitor.complexity

        func = Function(node.name, node.lineno, node.col_offset,
                        max(node.lineno, visitor.max_line), self.to_method,
                        self.classname, closures, body_complexity)
        self.functions.append(func)

    visit_AsyncFunctionDef = visit_FunctionDef

    def visit_ClassDef(self, node):
        '''When visiting classes a new visitor is created to recursively
        analyze the class' body and methods.
        '''
        # The complexity of a class is computed taking into account
        # the following factors: number of decorators and the complexity
        # of the class' body (which is the sum of all the complexities).
        methods = []
        # According to Cyclomatic Complexity definition it has to start off
        # from 1.
        body_complexity = 1
        classname = node.name
        visitors_max_lines = [node.lineno]
        for child in node.body:
            visitor = ComplexityVisitor(True, classname, off=False,
                                        no_assert=self.no_assert)
            visitor.visit(child)
            methods.extend(visitor.functions)
            body_complexity += (visitor.complexity +
                                visitor.functions_complexity)
            visitors_max_lines.append(visitor.max_line)

        cls = Class(classname, node.lineno, node.col_offset,
                    max(visitors_max_lines + list(map(GET_ENDLINE, methods))),
                    methods, body_complexity)
        self.classes.append(cls)


class HalsteadVisitor(CodeVisitor):
    '''Visitor that keeps track of operators and operands, in order to compute
    Halstead metrics (see :func:`radon.metrics.h_visit`).
    '''

    types = {ast.Num: 'n',
             ast.Name: 'id',
             ast.Attribute: 'attr'}

    def __init__(self, context=None):
        '''*context* is a string used to keep track the analysis' context.'''
        self.operators_seen = set()
        self.operands_seen = set()
        self.operators = 0
        self.operands = 0
        self.context = context

    @property
    def distinct_operators(self):
        '''The number of distinct operators.'''
        return len(self.operators_seen)

    @property
    def distinct_operands(self):
        '''The number of distinct operands.'''
        return len(self.operands_seen)

    def dispatch(meth):
        '''This decorator does all the hard work needed for every node.

        The decorated method must return a tuple of 4 elements:

            * the number of operators
            * the number of operands
            * the operators seen (a sequence)
            * the operands seen (a sequence)
        '''
        def aux(self, node):
            '''Actual function that updates the stats.'''
            results = meth(self, node)
            self.operators += results[0]
            self.operands += results[1]
            self.operators_seen.update(results[2])
            for operand in results[3]:
                new_operand = getattr(operand,
                                      self.types.get(type(operand), ''),
                                      operand)

                self.operands_seen.add((self.context, new_operand))
            # Now dispatch to children
            super(HalsteadVisitor, self).generic_visit(node)
        return aux

    @dispatch
    def visit_BinOp(self, node):
        '''A binary operator.'''
        return (1, 2, (self.get_name(node.op),), (node.left, node.right))

    @dispatch
    def visit_UnaryOp(self, node):
        '''A unary operator.'''
        return (1, 1, (self.get_name(node.op),), (node.operand,))

    @dispatch
    def visit_BoolOp(self, node):
        '''A boolean operator.'''
        return (1, len(node.values), (self.get_name(node.op),), node.values)

    @dispatch
    def visit_AugAssign(self, node):
        '''An augmented assign (contains an operator).'''
        return (1, 2, (self.get_name(node.op),), (node.target, node.value))

    @dispatch
    def visit_Compare(self, node):
        '''A comparison.'''
        return (len(node.ops), len(node.comparators) + 1,
                map(self.get_name, node.ops), node.comparators + [node.left])

    def visit_FunctionDef(self, node):
        '''When visiting functions, another visitor is created to recursively
        analyze the function's body.
        '''
        for child in node.body:
            visitor = HalsteadVisitor.from_ast(child, context=node.name)
            self.operators += visitor.operators
            self.operands += visitor.operands
            self.operators_seen.update(visitor.operators_seen)
            self.operands_seen.update(visitor.operands_seen)

    visit_AsyncFunctionDef = visit_FunctionDef