0
# Lizard
1

2
An extensible cyclomatic complexity analyzer for many programming languages including C/C++, Java, JavaScript, Python, Ruby, Swift, Objective-C, and 20+ others. Lizard provides comprehensive code quality metrics including cyclomatic complexity, lines of code without comments (nloc), copy-paste detection (code clone/duplicate detection), and various other forms of static analysis.
3

4
## Package Information
5

6
- **Package Name**: lizard
7
- **Language**: Python
8
- **Installation**: `pip install lizard`
9

10
## Core Imports
11

12
```python
13
import lizard
14
```
15

16
For direct analysis functions:
17

18
```python
19
from lizard import analyze, analyze_files, main
20
```
21

22
For data classes:
23

24
```python
25
from lizard import FunctionInfo, FileInformation, FileAnalyzer
26
```
27

28
## Basic Usage
29

30
```python
31
import lizard
32

33
# Analyze source files in a directory
34
results = lizard.analyze(['src/'])
35
for file_info in results:
36
    print(f"File: {file_info.filename}")
37
    print(f"  NLOC: {file_info.nloc}")
38
    print(f"  CCN: {file_info.CCN}")
39
    for func in file_info.function_list:
40
        print(f"  Function {func.name}: CCN={func.cyclomatic_complexity}, NLOC={func.nloc}")
41

42
# Analyze specific files
43
files = ['app.py', 'utils.py']
44
results = lizard.analyze_files(files)
45

46
# Use command-line interface programmatically
47
import sys
48
lizard.main(['-l', 'python', 'src/'])
49
```
50

51
## Architecture
52

53
Lizard's extensible architecture consists of:
54

55
- **Core Analysis Engine**: The main `lizard.py` module with analysis functions and data models
56
- **Language Parsers**: The `lizard_languages` package supporting 26+ programming languages
57
- **Extensions System**: The `lizard_ext` package with analysis extensions and output formatters
58
- **Command-line Interface**: Full CLI with filtering, thresholds, and multiple output formats
59

60
This design enables comprehensive code analysis across multiple languages while maintaining extensibility for custom metrics and output formats.
61

62
## Capabilities
63

64
### Core Analysis Functions
65

66
Primary analysis functions for processing source code and extracting complexity metrics from files and directories.
67

68
```python { .api }
69
def analyze(paths, exclude_pattern=None, threads=1, exts=None, lans=None):
70
    """
71
    Main analysis function that processes source files.
72
    
73
    Args:
74
        paths: List of file/directory paths to analyze
75
        exclude_pattern: List of patterns to exclude from analysis  
76
        threads: Number of threads for parallel processing
77
        exts: List of extension objects for additional analysis
78
        lans: List of languages to analyze
79
        
80
    Returns:
81
        Iterator of FileInformation objects containing function statistics
82
    """
83

84
def analyze_files(files, threads=1, exts=None):
85
    """
86
    Analyzes specific files using FileAnalyzer.
87
    
88
    Args:
89
        files: List of file paths to analyze
90
        threads: Number of threads for parallel processing
91
        exts: List of extension objects for additional analysis
92
        
93
    Returns:
94
        Iterator of FileInformation objects
95
    """
96

97
def main(argv=None):
98
    """
99
    Command-line entry point for Lizard.
100
    
101
    Args:
102
        argv: Optional command-line arguments list
103
    """
104
```
105

106
[Core Analysis](./core-analysis.md)
107

108
### Data Models
109

110
Core data structures representing analysis results including function information, file statistics, and complexity metrics.
111

112
```python { .api }
113
class FunctionInfo:
114
    """Represents function information with complexity metrics."""
115
    
116
    name: str
117
    cyclomatic_complexity: int
118
    nloc: int  # Lines of code without comments
119
    token_count: int
120
    parameter_count: int
121
    length: int  # Total lines including comments
122
    location: str  # File path and line number
123

124
class FileInformation:
125
    """Contains file-level statistics and function list."""
126
    
127
    filename: str
128
    nloc: int
129
    function_list: list  # List of FunctionInfo objects
130
    average_nloc: float
131
    average_token_count: float
132
    average_cyclomatic_complexity: float
133
    CCN: int  # Total cyclomatic complexity
134
    ND: int   # Total of maximum nesting depths across all functions
135
```
136

137
[Data Models](./data-models.md)
138

139
### Language Support
140

141
Language parsing capabilities supporting 26+ programming languages through the lizard_languages package.
142

143
```python { .api }
144
def languages():
145
    """
146
    Returns list of all available language reader classes.
147
    
148
    Returns:
149
        List of language reader classes for supported languages
150
    """
151

152
def get_reader_for(filename):
153
    """
154
    Returns appropriate language reader class for a filename.
155
    
156
    Args:
157
        filename: File path or name to match
158
        
159
    Returns:
160
        Language reader class or None if no match found
161
    """
162
```
163

164
[Language Support](./language-support.md)
165

166
### Extensions System
167

168
Extension framework for custom analysis metrics and output formats through the lizard_ext package.
169

170
```python { .api }
171
def get_extensions(extension_names):
172
    """
173
    Loads and expands extension modules for analysis.
174
    
175
    Args:
176
        extension_names: List of extension names to load
177
        
178
    Returns:
179
        List of extension objects
180
    """
181
```
182

183
Available extensions include duplicate detection, nesting depth analysis, output formatters (HTML, CSV, XML, Checkstyle), and 20+ specialized analysis extensions.
184

185
[Extensions System](./extensions-system.md)
186

187
### Utility Functions
188

189
Helper functions for file processing, filtering, and output formatting.
190

191
```python { .api }
192
def get_all_source_files(paths, exclude_patterns, lans):
193
    """
194
    Gets all source files from paths with exclusion patterns.
195
    
196
    Args:
197
        paths: List of paths to search
198
        exclude_patterns: List of exclusion patterns
199
        lans: List of languages to filter
200
        
201
    Returns:
202
        Iterator of filtered source file paths
203
    """
204

205
def warning_filter(option, module_infos):
206
    """
207
    Filters functions that exceed specified thresholds.
208
    
209
    Args:
210
        option: Configuration object with threshold settings
211
        module_infos: Iterator of file information objects
212
        
213
    Returns:
214
        Generator yielding functions exceeding thresholds
215
    """
216
```
217

218
[Utility Functions](./utility-functions.md)
219

220
## Types
221

222
```python { .api }
223
class FileAnalyzer:
224
    """Main file analysis engine with extension support."""
225
    
226
    def __call__(self, filename: str) -> FileInformation:
227
        """Analyze a single file and return file information."""
228
    
229
    def analyze_source_code(self, filename: str, code: str) -> FileInformation:
230
        """Analyze source code string and return file information."""
231

232
class Nesting:
233
    """Base class representing one level of nesting."""
234
    
235
    name_in_space: str
236

237
class Namespace(Nesting):
238
    """Represents namespace nesting level."""
239
    
240
    def __init__(self, name: str):
241
        """Initialize namespace with given name."""
242

243
# Constants
244
DEFAULT_CCN_THRESHOLD: int = 15
245
DEFAULT_WHITELIST: str = "whitelizard.txt"  
246
DEFAULT_MAX_FUNC_LENGTH: int = 1000
247

248
analyze_file: FileAnalyzer
249
"""Pre-instantiated FileAnalyzer with default extensions for quick single-file analysis"""
250
```