0
# Radon
1

2
A comprehensive Python code analysis tool that computes various software metrics from source code to assess code quality and complexity. Radon calculates McCabe's cyclomatic complexity, raw metrics (SLOC, comments, blank lines), Halstead metrics for software complexity measurement, and the Maintainability Index for overall code maintainability assessment.
3

4
## Package Information
5

6
- **Package Name**: radon
7
- **Language**: Python
8
- **Installation**: `pip install radon`
9
- **Version**: 6.0.1
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import radon
16
```
17

18
For specific analysis modules:
19

20
```python
21
from radon import complexity, raw, metrics, visitors
22
```
23

24
For command-line interface:
25

26
```python
27
from radon.cli import program, Config
28
```
29

30
## Basic Usage
31

32
```python
33
from radon.complexity import cc_visit, cc_rank
34
from radon.raw import analyze
35
from radon.metrics import mi_visit, h_visit
36

37
# Analyze cyclomatic complexity
38
code = '''
39
def example_function(x, y):
40
    if x > 0:
41
        if y > 0:
42
            return x + y
43
        else:
44
            return x - y
45
    else:
46
        return 0
47
'''
48

49
# Get complexity blocks
50
blocks = cc_visit(code)
51
for block in blocks:
52
    print(f"{block.name}: {block.complexity} ({cc_rank(block.complexity)})")
53

54
# Get raw metrics
55
raw_metrics = analyze(code)
56
print(f"Lines of Code: {raw_metrics.loc}")
57
print(f"Logical Lines: {raw_metrics.lloc}")
58
print(f"Comments: {raw_metrics.comments}")
59

60
# Get maintainability index
61
mi_score = mi_visit(code, multi=True)
62
print(f"Maintainability Index: {mi_score}")
63

64
# Get Halstead metrics
65
halstead = h_visit(code)
66
print(f"Halstead Volume: {halstead.total.volume}")
67
print(f"Halstead Difficulty: {halstead.total.difficulty}")
68
```
69

70
## Architecture
71

72
Radon provides a layered architecture for code analysis:
73

74
- **AST Visitors**: Core analysis engines (ComplexityVisitor, HalsteadVisitor) that traverse Python AST
75
- **Analysis Modules**: High-level interfaces (complexity, raw, metrics) for specific metric calculations
76
- **CLI Interface**: Command-line tools with multiple output formats and configuration options
77
- **Harvester System**: Batch processing framework for analyzing multiple files and directories
78
- **Output Formatters**: Support for terminal, JSON, XML, Markdown, and Code Climate formats
79

80
## Capabilities
81

82
### Cyclomatic Complexity Analysis
83

84
McCabe's cyclomatic complexity analysis for measuring code complexity and maintainability. Provides complexity scoring, ranking (A-F grades), and detailed block-level analysis for functions, methods, and classes.
85

86
```python { .api }
87
def cc_visit(code, **kwargs): ...
88
def cc_visit_ast(ast_node, **kwargs): ...
89
def cc_rank(cc): ...
90
def average_complexity(blocks): ...
91
def sorted_results(blocks, order=SCORE): ...
92
```
93

94
[Cyclomatic Complexity](./complexity.md)
95

96
### Raw Code Metrics
97

98
Analysis of basic code metrics including lines of code (LOC), logical lines of code (LLOC), source lines of code (SLOC), comments, blank lines, and multi-line strings for comprehensive code statistics.
99

100
```python { .api }
101
def analyze(source): ...
102
class Module: ...  # namedtuple with loc, lloc, sloc, comments, multi, blank, single_comments
103
```
104

105
[Raw Metrics](./raw-metrics.md)
106

107
### Halstead Metrics
108

109
Software complexity measurement based on operators and operands analysis. Calculates vocabulary, length, volume, difficulty, effort, time, and bug predictions using Halstead's software science metrics.
110

111
```python { .api }
112
def h_visit(code): ...
113
def h_visit_ast(ast_node): ...
114
class HalsteadReport: ...  # namedtuple with h1, h2, N1, N2, vocabulary, length, etc.
115
```
116

117
[Halstead Metrics](./halstead.md)
118

119
### Maintainability Index
120

121
Compound metric combining Halstead volume, cyclomatic complexity, and lines of code to determine overall code maintainability. Uses the same formula as Visual Studio's maintainability index calculation.
122

123
```python { .api }
124
def mi_visit(code, multi): ...
125
def mi_compute(halstead_volume, complexity, sloc, comments): ...
126
def mi_parameters(code, count_multi=True): ...
127
def mi_rank(score): ...
128
```
129

130
[Maintainability Index](./maintainability.md)
131

132
### AST Visitors
133

134
Low-level AST visitor classes for custom analysis and integration. Provides the foundation for all radon analysis capabilities with extensible visitor pattern implementation.
135

136
```python { .api }
137
class ComplexityVisitor(CodeVisitor): ...
138
class HalsteadVisitor(CodeVisitor): ...
139
class Function: ...  # namedtuple representing function blocks
140
class Class: ...     # namedtuple representing class blocks
141
```
142

143
[AST Visitors](./visitors.md)
144

145
### Command Line Interface
146

147
Comprehensive CLI with four analysis commands (cc, raw, mi, hal) supporting multiple output formats, configuration files, and batch processing capabilities for integration with CI/CD pipelines.
148

149
```python { .api }
150
class Config: ...
151
def cc(paths, **kwargs): ...
152
def raw(paths, **kwargs): ...
153
def mi(paths, **kwargs): ...
154
def hal(paths, **kwargs): ...
155
```
156

157
[Command Line Interface](./cli.md)
158

159
## Types
160

161
### Core Data Types
162

163
```python { .api }
164
# Raw metrics container
165
Module = namedtuple('Module', [
166
    'loc',              # Lines of Code (total lines)
167
    'lloc',             # Logical Lines of Code
168
    'sloc',             # Source Lines of Code (non-blank, non-comment)
169
    'comments',         # Comment lines
170
    'multi',            # Multi-line strings (docstrings)
171
    'blank',            # Blank lines
172
    'single_comments'   # Single-line comments
173
])
174

175
# Function/method representation
176
Function = namedtuple('Function', [
177
    'name',        # Function name
178
    'lineno',      # Starting line number
179
    'col_offset',  # Column offset
180
    'endline',     # Ending line number
181
    'is_method',   # Boolean: is this a method?
182
    'classname',   # Class name if method, None if function
183
    'closures',    # List of nested functions
184
    'complexity'   # Cyclomatic complexity score
185
])
186

187
# Class representation
188
Class = namedtuple('Class', [
189
    'name',            # Class name
190
    'lineno',          # Starting line number
191
    'col_offset',      # Column offset
192
    'endline',         # Ending line number
193
    'methods',         # List of methods
194
    'inner_classes',   # List of nested classes
195
    'real_complexity'  # Class complexity score
196
])
197

198
# Halstead metrics report
199
HalsteadReport = namedtuple('HalsteadReport', [
200
    'h1',                  # Number of distinct operators
201
    'h2',                  # Number of distinct operands
202
    'N1',                  # Total number of operators
203
    'N2',                  # Total number of operands
204
    'vocabulary',          # h1 + h2
205
    'length',             # N1 + N2
206
    'calculated_length',   # h1 * log2(h1) + h2 * log2(h2)
207
    'volume',             # N * log2(h)
208
    'difficulty',         # h1 / 2 * N2 / h2
209
    'effort',             # D * V
210
    'time',               # E / 18 seconds
211
    'bugs'                # V / 3000 (error estimate)
212
])
213

214
# Combined Halstead results
215
Halstead = namedtuple('Halstead', [
216
    'total',      # HalsteadReport for entire file
217
    'functions'   # List of HalsteadReport for each function
218
])
219
```