0
# flake8-eradicate
1

2
A flake8 plugin that detects commented out (or so called "dead") code in Python files. It helps maintain code quality by identifying code that has been commented out but not removed, encouraging proper code cleanup practices.
3

4
## Package Information
5

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

10
## Core Imports
11

12
The plugin is used through flake8 and doesn't require direct imports in code:
13

14
```python
15
# No direct imports needed - plugin integrates with flake8
16
```
17

18
For programmatic usage (not typical):
19

20
```python
21
from flake8_eradicate import Checker
22
```
23

24
## Basic Usage
25

26
Install and use with flake8:
27

28
```bash
29
# Install the plugin
30
pip install flake8-eradicate
31

32
# Run flake8 with the plugin
33
flake8 your_file.py
34

35
# The plugin will automatically detect commented out code
36
# Example output:
37
# your_file.py:5:1: E800 Found commented out code
38
```
39

40
Configure options in setup.cfg:
41

42
```ini
43
[flake8]
44
eradicate-aggressive = True
45
eradicate-whitelist = noqa#fmt
46
```
47

48
Or via command line:
49

50
```bash
51
flake8 --eradicate-aggressive your_file.py
52
flake8 --eradicate-whitelist="pattern1#pattern2" your_file.py
53
```
54

55
## Capabilities
56

57
### Plugin Integration
58

59
Flake8 plugin class that integrates with the flake8 linting framework to detect commented out code.
60

61
```python { .api }
62
class Checker:
63
    """Flake8 plugin to find commented out code."""
64
    
65
    name: str
66
    version: str
67
    options: ClassVar[Optional[Dict[str, Any]]]
68
    
69
    def __init__(
70
        self,
71
        tree,
72
        file_tokens: List[tokenize.TokenInfo], 
73
        lines: Sequence[str]
74
    ) -> None:
75
        """
76
        Constructor called by flake8 for each file.
77
        
78
        Parameters:
79
        - tree: AST tree (unused by this plugin)
80
        - file_tokens: All tokens for the current file
81
        - lines: All lines in the current file
82
        """
83
    
84
    def run(self) -> Iterator[Tuple[int, int, str, Type['Checker']]]:
85
        """
86
        Main entry point called by flake8 to check for violations.
87
        
88
        Returns:
89
        Iterator yielding error tuples (line_no, column, message, checker_type)
90
        """
91
    
92
    @classmethod
93
    def add_options(cls, parser: OptionManager) -> None:
94
        """
95
        Registers plugin-specific command line options with flake8.
96
        
97
        Parameters:
98
        - parser: flake8 option parser instance
99
        """
100
    
101
    @classmethod 
102
    def parse_options(cls, options) -> None:
103
        """
104
        Stores parsed options for use by checker instances.
105
        
106
        Parameters:
107
        - options: Parsed options object from flake8
108
        """
109
```
110

111
### Configuration Options
112

113
The plugin supports three configuration options that can be specified via command line or configuration file.
114

115
#### Aggressive Mode
116

117
```python { .api }
118
# Command line option: --eradicate-aggressive
119
# Config file option: eradicate-aggressive = True/False
120
# Default: False
121
```
122

123
Enables aggressive mode for better detection but may produce false positives.
124

125
#### Custom Whitelist Override
126

127
```python { .api }
128
# Command line option: --eradicate-whitelist="pattern1#pattern2"
129
# Config file option: eradicate-whitelist = pattern1#pattern2
130
# Default: False
131
```
132

133
Custom whitelist patterns (# separated) that override default patterns. Patterns are interpreted as regex.
134

135
#### Custom Whitelist Extension
136

137
```python { .api }
138
# Command line option: --eradicate-whitelist-extend="pattern1#pattern2"
139
# Config file option: eradicate-whitelist-extend = pattern1#pattern2
140
# Default: False
141
```
142

143
Custom whitelist patterns (# separated) that extend default patterns. Takes precedence over `--eradicate-whitelist`. Patterns are interpreted as regex.
144

145
### Error Detection
146

147
The plugin detects a single type of error code.
148

149
#### E800 Error
150

151
```python { .api }
152
# Error Code: E800
153
# Message: "Found commented out code"
154
```
155

156
Reported when the plugin detects lines containing commented out Python code that should be removed.
157

158
## Types
159

160
```python { .api }
161
from typing import Any, ClassVar, Dict, Iterable, Iterator, List, Optional, Sequence, Tuple, Type
162
import tokenize
163
from flake8.options.manager import OptionManager
164

165
# Core types used by the plugin
166
TokenInfo = tokenize.TokenInfo
167
OptionManager = OptionManager
168

169
# Error tuple format returned by run()
170
ErrorTuple = Tuple[int, int, str, Type['Checker']]
171
```
172

173
## Integration Examples
174

175
### Configuration File Usage
176

177
```ini
178
# setup.cfg
179
[flake8]
180
# Enable aggressive mode
181
eradicate-aggressive = True
182

183
# Custom whitelist (overrides defaults)
184
eradicate-whitelist = noqa#fmt#type
185

186
# Extend default whitelist (preferred)
187
eradicate-whitelist-extend = custom_pattern#another_pattern
188
```
189

190
### Command Line Usage
191

192
```bash
193
# Basic usage - plugin runs automatically
194
flake8 myproject/
195

196
# With aggressive mode
197
flake8 --eradicate-aggressive myproject/
198

199
# With custom whitelist override
200
flake8 --eradicate-whitelist="noqa#fmt" myproject/
201

202
# With whitelist extension
203
flake8 --eradicate-whitelist-extend="custom" myproject/
204

205
# Select only E800 errors
206
flake8 --select=E800 myproject/
207
```
208

209
### Programmatic Usage (Advanced)
210

211
```python
212
import tokenize
213
from flake8_eradicate import Checker
214

215
# Setup options (normally done by flake8)
216
class MockOptions:
217
    eradicate_aggressive = False
218
    eradicate_whitelist = False
219
    eradicate_whitelist_extend = False
220

221
Checker.options = MockOptions()
222

223
# Read file content
224
with open('example.py', 'r') as f:
225
    lines = f.readlines()
226

227
# Tokenize file
228
with open('example.py', 'r') as f:
229
    tokens = list(tokenize.generate_tokens(f.readline))
230

231
# Create checker instance
232
checker = Checker(tree=None, file_tokens=tokens, lines=lines)
233

234
# Get violations
235
violations = list(checker.run())
236
for line_no, col, message, checker_type in violations:
237
    print(f"Line {line_no}: {message}")
238
```