0
# Flake8 Builtins
1

2
A Flake8 plugin that detects when Python built-in functions, classes, or modules are being shadowed by variable names, function parameters, class attributes, imports, or lambda arguments. This plugin helps prevent subtle bugs that can occur when developers accidentally use built-in names like `list`, `dict`, `max`, or `zip` as variable names, which can lead to unexpected behavior and hard-to-debug errors.
3

4
## Package Information
5

6
- **Package Name**: flake8-builtins
7
- **Package Type**: Flake8 plugin
8
- **Language**: Python
9
- **Installation**: `pip install flake8-builtins`
10

11
## Core Imports
12

13
This package integrates automatically with Flake8 through the plugin discovery system. No direct imports are needed in user code.
14

15
## Basic Usage
16

17
Once installed, the plugin is automatically discovered and activated by Flake8:
18

19
```bash
20
# Install the plugin
21
pip install flake8-builtins
22

23
# Run flake8 on your Python files
24
flake8 myfile.py
25

26
# Configure ignore list for specific builtins
27
flake8 --builtins-ignorelist id,copyright myfile.py
28

29
# Configure allowed module names
30
flake8 --builtins-allowed-modules logging,socket myfile.py
31
```
32

33
Example violations detected:
34

35
```python
36
def my_method(object, list, dict):  # A002 errors
37
    max = 5                         # A001 error
38
    min = 3                         # A001 error
39
    zip = (4, 3)                   # A001 error
40

41
class MyClass:
42
    list = []                      # A003 error
43
    
44
import json as dict                # A004 error
45

46
lambda max, min: max + min         # A006 errors
47
```
48

49
## Configuration Options
50

51
### Command-line Options
52

53
- `--builtins-ignorelist`: Comma-separated list of builtins to skip checking
54
- `--builtins-allowed-modules`: Comma-separated list of builtin module names to allow
55

56
### Configuration File Support
57

58
Options can be configured in setup.cfg, tox.ini, or pyproject.toml:
59

60
```ini
61
[flake8]
62
builtins-ignorelist = id,copyright,_
63
builtins-allowed-modules = logging,socket
64
```
65

66
## Error Codes
67

68
The plugin reports six different error codes for builtin name shadowing:
69

70
- **A001**: Variable is shadowing a Python builtin
71
- **A002**: Argument is shadowing a Python builtin  
72
- **A003**: Class attribute is shadowing a Python builtin
73
- **A004**: Import statement is shadowing a Python builtin
74
- **A005**: Module is shadowing a Python builtin module
75
- **A006**: Lambda argument is shadowing a Python builtin
76

77
## Capabilities
78

79
### Plugin Entry Point
80

81
The main checker class that Flake8 discovers and loads automatically.
82

83
```python { .api }
84
class BuiltinsChecker:
85
    """
86
    Main Flake8 plugin class for detecting builtin name shadowing.
87
    
88
    Attributes:
89
    - name (str): Plugin identifier 'flake8_builtins'
90
    - version (str): Plugin version '1.5.2'
91
    - assign_msg (str): Error message template for variable assignments (A001)
92
    - argument_msg (str): Error message template for function arguments (A002)
93
    - class_attribute_msg (str): Error message template for class attributes (A003)
94
    - import_msg (str): Error message template for import statements (A004)
95
    - module_name_msg (str): Error message template for module names (A005)
96
    - lambda_argument_msg (str): Error message template for lambda arguments (A006)
97
    - default_line_number (int): Default line number for errors (1)
98
    - default_column_offset (int): Default column offset for errors (1)
99
    - names (list): List of builtin names to check against
100
    - ignore_list (set): Set of builtin names to ignore by default
101
    - ignored_module_names (set): Set of module names to ignore
102
    - module_names (set): Set of stdlib module names to check against (Python 3.10+)
103
    """
104
    
105
    def __init__(self, tree, filename):
106
        """
107
        Initialize checker with AST tree and filename.
108
        
109
        Parameters:
110
        - tree: AST tree of the file being checked
111
        - filename (str): Path to the file being checked
112
        """
113
    
114
    @classmethod
115
    def add_options(cls, option_manager):
116
        """
117
        Add command-line options to Flake8.
118
        
119
        Parameters:
120
        - option_manager: Flake8's option manager instance
121
        """
122
    
123
    @classmethod
124
    def parse_options(cls, options):
125
        """
126
        Parse and process configuration options.
127
        
128
        Parameters:
129
        - options: Parsed options from Flake8
130
        """
131
    
132
    def run(self):
133
        """
134
        Main entry point that yields error tuples for detected violations.
135
        
136
        Yields:
137
        Tuple of (line_number, column_offset, message, checker_class)
138
        """
139
```
140

141
### Error Detection Methods
142

143
Methods that check different AST node types for builtin name shadowing.
144

145
```python { .api }
146
def check_assignment(self, statement):
147
    """
148
    Check assignment statements for builtin shadowing (A001/A003).
149
    
150
    Parameters:
151
    - statement: AST assignment node (Assign, AnnAssign, or NamedExpr)
152
    
153
    Yields:
154
    Error tuples for violations found
155
    """
156

157
def check_function_definition(self, statement):
158
    """
159
    Check function definitions and arguments (A001/A002/A003).
160
    
161
    Parameters:
162
    - statement: AST function definition node (FunctionDef or AsyncFunctionDef)
163
    
164
    Yields:
165
    Error tuples for violations found
166
    """
167

168
def check_lambda_definition(self, statement):
169
    """
170
    Check lambda function arguments for builtin shadowing (A006).
171
    
172
    Parameters:
173
    - statement: AST Lambda node
174
    
175
    Yields:
176
    Error tuples for violations found
177
    """
178

179
def check_for_loop(self, statement):
180
    """
181
    Check for loop target variables for builtin shadowing (A001).
182
    
183
    Parameters:
184
    - statement: AST For or AsyncFor node
185
    
186
    Yields:
187
    Error tuples for violations found
188
    """
189

190
def check_with(self, statement):
191
    """
192
    Check with statement context variables for builtin shadowing (A001).
193
    
194
    Parameters:
195
    - statement: AST With or AsyncWith node
196
    
197
    Yields:
198
    Error tuples for violations found
199
    """
200

201
def check_exception(self, statement):
202
    """
203
    Check exception handler variable names for builtin shadowing (A001).
204
    
205
    Parameters:
206
    - statement: AST excepthandler node
207
    
208
    Yields:
209
    Error tuples for violations found
210
    """
211

212
def check_comprehension(self, statement):
213
    """
214
    Check comprehension target variables for builtin shadowing (A001).
215
    
216
    Parameters:
217
    - statement: AST comprehension node (ListComp, SetComp, DictComp, GeneratorExp)
218
    
219
    Yields:
220
    Error tuples for violations found
221
    """
222

223
def check_import(self, statement):
224
    """
225
    Check import statement names for builtin shadowing (A004).
226
    
227
    Parameters:
228
    - statement: AST Import or ImportFrom node
229
    
230
    Yields:
231
    Error tuples for violations found
232
    """
233

234
def check_class(self, statement):
235
    """
236
    Check class definition names for builtin shadowing (A001).
237
    
238
    Parameters:
239
    - statement: AST ClassDef node
240
    
241
    Yields:
242
    Error tuples for violations found
243
    """
244

245
def check_module_name(self, filename: str):
246
    """
247
    Check if module name shadows builtin module (A005).
248
    
249
    Parameters:
250
    - filename (str): Path to the module file
251
    
252
    Yields:
253
    Error tuples for violations found
254
    """
255

256
def error(self, statement=None, variable=None, message=None):
257
    """
258
    Generate error tuple for Flake8.
259
    
260
    Parameters:
261
    - statement: AST node where error occurred (optional)
262
    - variable (str): Variable name causing the violation (optional)
263
    - message (str): Error message template (optional)
264
    
265
    Returns:
266
    Tuple of (line_number, column_offset, formatted_message, checker_class)
267
    """
268
```
269

270
## Default Ignore List
271

272
The plugin ignores these builtin names by default:
273

274
- `__name__`
275
- `__doc__`
276
- `credits`
277
- `_`
278

279
Additional builtins can be ignored using the `--builtins-ignorelist` option.
280

281
## Python Version Support
282

283
- **Minimum Python Version**: 3.9
284
- **Supported Versions**: 3.9, 3.10, 3.11, 3.12, 3.13
285
- **Implementations**: CPython, PyPy3
286

287
## Dependencies
288

289
- **Required**: `flake8` (runtime dependency)
290
- **Optional**: `pytest` (development/testing)
291

292
## Integration
293

294
The plugin integrates with Flake8 through the entry point system defined in `pyproject.toml`:
295

296
```toml
297
[project.entry-points."flake8.extension"]
298
A00 = "flake8_builtins:BuiltinsChecker"
299
```
300

301
This allows Flake8 to automatically discover and load the plugin when installed, making it seamlessly integrate into existing Flake8 workflows and CI/CD pipelines.