0
# Pylint
1
2
A comprehensive static code analysis tool for Python that performs deep code inspection without executing the program. Pylint uses advanced inference techniques through its internal astroid representation to understand code semantics beyond simple syntax checking, enabling it to detect complex issues like incorrect API usage even when imports are aliased. The tool enforces coding standards, identifies potential bugs, detects code smells, and provides refactoring suggestions while being highly configurable to adapt to different project requirements.
3
4
## Package Information
5
6
- **Package Name**: pylint
7
- **Language**: Python
8
- **Installation**: `pip install pylint`
9
- **Documentation**: https://pylint.readthedocs.io/
10
11
## Core Imports
12
13
```python
14
import pylint
15
```
16
17
For direct API access:
18
19
```python
20
from pylint import run_pylint, run_pyreverse, run_symilar
21
from pylint.lint import PyLinter
22
from pylint.checkers import BaseChecker
23
from pylint.reporters import BaseReporter
24
```
25
26
## Basic Usage
27
28
```python
29
import pylint
30
31
# Run pylint on files from Python code
32
pylint.run_pylint(['mymodule.py', '--output-format=json'])
33
34
# Generate UML diagrams
35
pylint.run_pyreverse(['mypackage/', '--output-format=svg'])
36
37
# Find code duplicates
38
pylint.run_symilar(['mymodule.py', '--min-lines=5'])
39
40
# Programmatic linting
41
from pylint.lint import PyLinter
42
from pylint.reporters import TextReporter
43
import io
44
45
output = io.StringIO()
46
reporter = TextReporter(output)
47
linter = PyLinter()
48
linter.set_reporter(reporter)
49
linter.check(['mymodule.py'])
50
print(output.getvalue())
51
```
52
53
## Architecture
54
55
Pylint's modular architecture enables comprehensive static analysis:
56
57
- **PyLinter**: Core controller that manages the checking process, configuration, and message collection
58
- **Checker System**: 78+ specialized checkers that analyze different aspects of code (variables, imports, format, type checking, etc.)
59
- **Extension System**: 25+ optional extensions for additional specialized checks
60
- **Reporter System**: Multiple output formats (text, JSON, HTML) and custom reporter support
61
- **Message System**: Structured message definitions with confidence levels and categorization
62
- **Configuration System**: Hierarchical configuration from files, command line, and programmatic sources
63
64
This design allows users to customize analysis depth, enable/disable specific checks, create custom checkers, and integrate pylint into diverse development workflows.
65
66
## Capabilities
67
68
### Core Linting API
69
70
Main entry points for running pylint analysis programmatically, including the primary linting functions, configuration management, and result collection.
71
72
```python { .api }
73
def run_pylint(argv=None):
74
"""Run pylint analysis from command line arguments."""
75
76
def modify_sys_path():
77
"""Modify sys.path for execution as Python module."""
78
79
class PyLinter:
80
"""Main linter class controlling the checking process."""
81
def check(self, files_or_modules): ...
82
def register_checker(self, checker): ...
83
def add_message(self, msgid, line, node, args, confidence, col_offset): ...
84
```
85
86
[Core Linting](./core-linting.md)
87
88
### Checker Development
89
90
Framework for creating custom checkers that analyze specific code patterns. Includes base classes, message definition system, and integration with the linter.
91
92
```python { .api }
93
class BaseChecker:
94
"""Abstract base class for all checkers."""
95
name: str
96
msgs: dict
97
options: tuple
98
99
class BaseRawFileChecker(BaseChecker):
100
"""Base class for raw file checkers."""
101
102
class BaseTokenChecker(BaseChecker):
103
"""Base class for token-based checkers."""
104
```
105
106
[Checker Development](./checker-development.md)
107
108
### Built-in Checkers
109
110
Comprehensive set of 78+ built-in checkers covering variables, imports, formatting, type checking, classes, design analysis, and more specialized areas.
111
112
```python { .api }
113
# Core checker modules (examples)
114
import pylint.checkers.variables
115
import pylint.checkers.imports
116
import pylint.checkers.format
117
import pylint.checkers.typecheck
118
import pylint.checkers.exceptions
119
import pylint.checkers.classes
120
```
121
122
[Built-in Checkers](./built-in-checkers.md)
123
124
### Extensions System
125
126
Optional extensions providing 33+ additional specialized checkers for code style, complexity analysis, docstring validation, and advanced pattern detection.
127
128
```python { .api }
129
# Extension initialization pattern
130
def initialize(linter):
131
"""Register extension checker with linter."""
132
133
# Available extensions (examples)
134
import pylint.extensions.code_style
135
import pylint.extensions.mccabe
136
import pylint.extensions.docparams
137
```
138
139
[Extensions](./extensions.md)
140
141
### Reporters and Output
142
143
Flexible reporting system supporting multiple output formats (text, JSON, HTML) and custom reporter development for integration with different tools and workflows.
144
145
```python { .api }
146
class BaseReporter:
147
"""Abstract base for all reporters."""
148
def handle_message(self, msg): ...
149
def set_output(self, output): ...
150
151
class TextReporter(BaseReporter): ...
152
class JSONReporter(BaseReporter): ...
153
class MultiReporter(BaseReporter): ...
154
```
155
156
[Reporters](./reporters.md)
157
158
### Configuration Management
159
160
Hierarchical configuration system that handles command-line arguments, configuration files, and programmatic settings with validation and default values.
161
162
```python { .api }
163
def find_default_config_files():
164
"""Locate default configuration files."""
165
166
class ArgumentsManager:
167
"""Command-line argument management."""
168
169
def find_pylintrc():
170
"""Find pylintrc configuration file."""
171
```
172
173
[Configuration](./configuration.md)
174
175
### Message System
176
177
Structured message definitions with categories, confidence levels, and detailed location information for precise error reporting and filtering.
178
179
```python { .api }
180
class Message:
181
"""Individual message/warning representation."""
182
msg_id: str
183
symbol: str
184
msg: str
185
confidence: str
186
line: int
187
column: int
188
189
class MessageDefinition:
190
"""Message type definition."""
191
```
192
193
[Messages](./messages.md)
194
195
### Pyreverse (UML Generation)
196
197
UML diagram generation tool that analyzes Python code structure and creates class diagrams, package diagrams, and dependency visualizations in multiple formats.
198
199
```python { .api }
200
def run_pyreverse(argv=None):
201
"""Generate UML diagrams from Python code."""
202
203
class PackageDiagram: ...
204
class ClassDiagram: ...
205
class DotWriter: ...
206
class PlantUmlWriter: ...
207
```
208
209
[Pyreverse](./pyreverse.md)
210
211
### Test Utilities
212
213
Testing framework for developing and validating custom checkers, including test case base classes, message validation, and functional testing support.
214
215
```python { .api }
216
class CheckerTestCase:
217
"""Base class for checker unit tests."""
218
219
class UnittestLinter:
220
"""Test-specific linter implementation."""
221
222
def set_config(**kwargs):
223
"""Set configuration for tests."""
224
```
225
226
[Test Utilities](./test-utilities.md)
227
228
## Type Definitions
229
230
```python { .api }
231
# Confidence levels
232
HIGH: str = "HIGH"
233
CONTROL_FLOW: str = "CONTROL_FLOW"
234
INFERENCE: str = "INFERENCE"
235
INFERENCE_FAILURE: str = "INFERENCE_FAILURE"
236
UNDEFINED: str = "UNDEFINED"
237
238
# Message types
239
MSG_TYPES: dict = {
240
'I': 'info',
241
'C': 'convention',
242
'R': 'refactor',
243
'W': 'warning',
244
'E': 'error',
245
'F': 'fatal'
246
}
247
248
# File extensions
249
PY_EXTS: tuple = ('.py', '.pyw', '.pyc', '.pyo')
250
```
251
252
## Constants
253
254
```python { .api }
255
__version__: str # Package version
256
version: str # Version alias
257
258
# Message type mappings
259
MSG_TYPES_STATUS: dict
260
PY310_PLUS: bool # Python 3.10+ version flag
261
PY311_PLUS: bool # Python 3.11+ version flag
262
PY312_PLUS: bool # Python 3.12+ version flag
263
```
264
265
## Exception Classes
266
267
```python { .api }
268
class InvalidMessageError(Exception):
269
"""Invalid message creation error."""
270
271
class UnknownMessageError(Exception):
272
"""Unregistered message error."""
273
274
class DeletedMessageError(Exception):
275
"""Deleted message encountered error."""
276
277
class EmptyReportError(Exception):
278
"""Empty report generation error."""
279
280
class InvalidReporterError(Exception):
281
"""Invalid reporter configuration error."""
282
```