0
# Error Messages and Warnings
1

2
Comprehensive message classes representing different types of analysis issues that pyflakes can detect. Each message class corresponds to a specific type of problem in Python code, from unused imports to syntax errors.
3

4
## Capabilities
5

6
### Base Message Class
7

8
Foundation class for all pyflakes messages, providing common attributes and initialization.
9

10
```python { .api }
11
class Message:
12
    """
13
    Base class for all pyflakes messages.
14
    
15
    Attributes:
16
    - message: ClassVar[str], message template string
17
    - message_args: tuple[Any, ...], arguments for message formatting
18
    - filename: Any, source file where issue occurs
19
    - lineno: int, line number of issue
20
    - col: int, column number of issue
21
    """
22
    
23
    def __init__(self, filename, loc: ast.AST) -> None:
24
        """
25
        Initialize message with location information.
26
        
27
        Parameters:
28
        - filename: source file path
29
        - loc: AST node where issue occurs
30
        """
31
```
32

33
### Import-Related Messages
34

35
Messages for issues with import statements, including unused imports, import conflicts, and star import problems.
36

37
```python { .api }
38
class UnusedImport(Message):
39
    """
40
    Unused import warning.
41
    
42
    Attributes:
43
    - message_args: tuple[Any], imported name
44
    """
45
    def __init__(self, filename, loc: ast.AST, name) -> None: ...
46

47
class RedefinedWhileUnused(Message):
48
    """
49
    Name redefined while original binding unused.
50
    
51
    Attributes:
52
    - message_args: tuple[Any, int], name and original line number
53
    """
54
    def __init__(self, filename, loc: ast.AST, name, orig_loc: ast.AST) -> None: ...
55

56
class ImportShadowedByLoopVar(Message):
57
    """
58
    Import shadowed by loop variable.
59
    
60
    Attributes:
61
    - message_args: tuple[Any, int], name and original line number
62
    """
63
    def __init__(self, filename, loc: ast.AST, name, orig_loc: ast.AST) -> None: ...
64

65
class ImportStarNotPermitted(Message):
66
    """
67
    Star import not permitted in this context.
68
    
69
    Attributes:
70
    - message_args: Any, module name
71
    """
72
    def __init__(self, filename, loc, modname) -> None: ...
73

74
class ImportStarUsed(Message):
75
    """
76
    Star import used (informational).
77
    
78
    Attributes:
79
    - message_args: tuple[Any], module name
80
    """
81
    def __init__(self, filename, loc: ast.AST, modname) -> None: ...
82

83
class ImportStarUsage(Message):
84
    """
85
    Name may be undefined due to star import.
86
    
87
    Attributes:
88
    - message_args: tuple[Any, Any], name and from_list
89
    """
90
    def __init__(self, filename, loc: ast.AST, name, from_list) -> None: ...
91
```
92

93
### Name Resolution Messages
94

95
Messages for undefined names, local variable issues, and export problems.
96

97
```python { .api }
98
class UndefinedName(Message):
99
    """
100
    Undefined name error.
101
    
102
    Attributes:
103
    - message_args: tuple[Any], undefined name
104
    """
105
    def __init__(self, filename, loc: ast.AST, name) -> None: ...
106

107
class UndefinedExport(Message):
108
    """
109
    Name in __all__ is not defined.
110
    
111
    Attributes:
112
    - message_args: tuple[Any], exported name
113
    """
114
    def __init__(self, filename, loc: ast.AST, name) -> None: ...
115

116
class UndefinedLocal(Message):
117
    """
118
    Local variable referenced before assignment.
119
    
120
    Attributes:
121
    - default: ClassVar[str], default message
122
    - builtin: ClassVar[str], builtin override message
123
    - message_args: tuple[Any, int], name and original line number
124
    """
125
    def __init__(self, filename, loc: ast.AST, name, orig_loc: ast.AST) -> None: ...
126

127
class UnusedVariable(Message):
128
    """
129
    Local variable assigned but never used.
130
    
131
    Attributes:
132
    - message_args: tuple[Any], variable names
133
    """
134
    def __init__(self, filename, loc: ast.AST, names) -> None: ...
135
```
136

137
### Function and Argument Messages
138

139
Messages for function definition and argument-related issues.
140

141
```python { .api }
142
class DuplicateArgument(Message):
143
    """
144
    Duplicate argument name in function definition.
145
    
146
    Attributes:
147
    - message_args: tuple[Any], argument name
148
    """
149
    def __init__(self, filename, loc: ast.AST, name) -> None: ...
150
```
151

152
### Dictionary and Data Structure Messages
153

154
Messages for issues with dictionary literals and data structures.
155

156
```python { .api }
157
class MultiValueRepeatedKeyLiteral(Message):
158
    """
159
    Dictionary has repeated key (literal).
160
    
161
    Attributes:
162
    - message_args: tuple[Any], repeated key
163
    """
164
    def __init__(self, filename, loc: ast.AST, key) -> None: ...
165

166
class MultiValueRepeatedKeyVariable(Message):
167
    """
168
    Dictionary has repeated key (variable).
169
    
170
    Attributes:
171
    - message_args: tuple[Any], repeated key variable
172
    """
173
    def __init__(self, filename, loc: ast.AST, key) -> None: ...
174
```
175

176
### Future Import Messages
177

178
Messages for __future__ import issues and timing problems.
179

180
```python { .api }
181
class LateFutureImport(Message):
182
    """
183
    __future__ import after other statements.
184
    
185
    Attributes:
186
    - message_args: tuple[()], empty tuple
187
    """
188
    def __init__(self, filename, loc: ast.AST) -> None: ...
189

190
class FutureFeatureNotDefined(Message):
191
    """
192
    __future__ feature name not recognized.
193
    
194
    Attributes:
195
    - message_args: tuple[Any], feature name
196
    """
197
    def __init__(self, filename, loc: ast.AST, name) -> None: ...
198
```
199

200
### Control Flow Messages
201

202
Messages for control flow statement issues and syntax problems.
203

204
```python { .api }
205
# Simple message classes (no additional parameters)
206
class ReturnOutsideFunction(Message):
207
    """'return' outside function."""
208

209
class YieldOutsideFunction(Message):
210
    """'yield' outside function."""
211

212
class ContinueOutsideLoop(Message):
213
    """'continue' not properly in loop."""
214

215
class BreakOutsideLoop(Message):
216
    """'break' outside loop."""
217

218
class ContinueInFinally(Message):
219
    """'continue' not supported inside 'finally' clause."""
220

221
class DefaultExceptNotLast(Message):
222
    """Default 'except:' must be last."""
223

224
class TwoStarredExpressions(Message):
225
    """Two starred expressions in assignment."""
226

227
class TooManyExpressionsInStarredAssignment(Message):
228
    """Too many expressions on left side of starred assignment."""
229
```
230

231
### Code Quality Messages
232

233
Messages for code quality issues and potential problems.
234

235
```python { .api }
236
class IfTuple(Message):
237
    """Use of tuple in if condition (likely missing comma)."""
238

239
class AssertTuple(Message):
240
    """Use of tuple in assert (likely missing comma)."""
241

242
class RaiseNotImplemented(Message):
243
    """Use 'raise NotImplementedError' instead of 'raise NotImplemented'."""
244

245
class InvalidPrintSyntax(Message):
246
    """Invalid print statement syntax (Python 3 style needed)."""
247

248
class IsLiteral(Message):
249
    """Use of 'is' with literal (should use '==')."""
250

251
class FStringMissingPlaceholders(Message):
252
    """f-string is missing placeholders."""
253
```
254

255
### Annotation Messages
256

257
Messages for type annotation syntax and parsing errors.
258

259
```python { .api }
260
class ForwardAnnotationSyntaxError(Message):
261
    """
262
    Syntax error in forward annotation.
263
    
264
    Attributes:
265
    - message_args: tuple[Any], annotation text
266
    """
267
    def __init__(self, filename, loc: ast.AST, annotation) -> None: ...
268

269
class CommentAnnotationSyntaxError(Message):
270
    """
271
    Syntax error in type comment annotation.
272
    
273
    Attributes:
274
    - message_args: tuple[Any], annotation text
275
    """
276
    def __init__(self, filename, loc: ast.AST, annotation) -> None: ...
277
```
278

279
### Doctest Messages
280

281
Messages for doctest-related issues.
282

283
```python { .api }
284
class DoctestSyntaxError(Message):
285
    """
286
    Syntax error in doctest block.
287
    
288
    Attributes:
289
    - message_args: tuple[()], empty tuple
290
    """
291
    def __init__(self, filename, loc: ast.AST, position: tuple[int, int] | None = ...) -> None: ...
292
```
293

294
### String Format Messages
295

296
Messages for string formatting validation, including both .format() and % formatting styles.
297

298
#### .format() Style Messages
299

300
```python { .api }
301
class StringDotFormatExtraPositionalArguments(Message):
302
    """
303
    Too many positional arguments for str.format().
304
    
305
    Attributes:
306
    - message_args: tuple[Any], extra positions
307
    """
308
    def __init__(self, filename, loc: ast.AST, extra_positions) -> None: ...
309

310
class StringDotFormatExtraNamedArguments(Message):
311
    """
312
    Unused named arguments in str.format().
313
    
314
    Attributes:
315
    - message_args: tuple[Any], extra keywords
316
    """
317
    def __init__(self, filename, loc: ast.AST, extra_keywords) -> None: ...
318

319
class StringDotFormatMissingArgument(Message):
320
    """
321
    Missing arguments for str.format().
322
    
323
    Attributes:
324
    - message_args: tuple[Any], missing arguments
325
    """
326
    def __init__(self, filename, loc: ast.AST, missing_arguments) -> None: ...
327

328
class StringDotFormatMixingAutomatic(Message):
329
    """Mixing automatic and manual field numbering in str.format()."""
330

331
class StringDotFormatInvalidFormat(Message):
332
    """
333
    Invalid format specification in str.format().
334
    
335
    Attributes:
336
    - message_args: tuple[Any], error description
337
    """
338
    def __init__(self, filename, loc: ast.AST, error) -> None: ...
339
```
340

341
#### Percent Formatting Messages
342

343
```python { .api }
344
class PercentFormatInvalidFormat(Message):
345
    """
346
    Invalid percent format specification.
347
    
348
    Attributes:
349
    - message_args: tuple[Any], error description
350
    """
351
    def __init__(self, filename, loc: ast.AST, error) -> None: ...
352

353
class PercentFormatMixedPositionalAndNamed(Message):
354
    """Cannot mix positional and named arguments in percent formatting."""
355

356
class PercentFormatUnsupportedFormatCharacter(Message):
357
    """
358
    Unsupported format character in percent formatting.
359
    
360
    Attributes:
361
    - message_args: tuple[Any], format character
362
    """
363
    def __init__(self, filename, loc: ast.AST, c) -> None: ...
364

365
class PercentFormatPositionalCountMismatch(Message):
366
    """
367
    Wrong number of arguments for percent formatting.
368
    
369
    Attributes:
370
    - message_args: tuple[int, int], expected and provided counts
371
    """
372
    def __init__(self, filename, loc: ast.AST, n_placeholders: int, n_substitutions: int) -> None: ...
373

374
class PercentFormatExtraNamedArguments(Message):
375
    """
376
    Unused named arguments in percent formatting.
377
    
378
    Attributes:
379
    - message_args: tuple[Any], extra keywords
380
    """
381
    def __init__(self, filename, loc: ast.AST, extra_keywords) -> None: ...
382

383
class PercentFormatMissingArgument(Message):
384
    """
385
    Missing arguments for percent formatting.
386
    
387
    Attributes:
388
    - message_args: tuple[Any], missing arguments
389
    """
390
    def __init__(self, filename, loc: ast.AST, missing_arguments) -> None: ...
391

392
class PercentFormatExpectedMapping(Message):
393
    """Percent formatting expected mapping object."""
394

395
class PercentFormatExpectedSequence(Message):
396
    """Percent formatting expected sequence object."""
397

398
class PercentFormatStarRequiresSequence(Message):
399
    """Percent formatting * requires sequence."""
400
```
401

402
**Usage Example:**
403

404
```python
405
from pyflakes.checker import Checker
406
from pyflakes.messages import UnusedImport, UndefinedName
407
import ast
408

409
# Check if specific message types are present
410
code = """
411
import os  # This will be unused
412
print(undefined_variable)  # This will be undefined
413
"""
414

415
tree = ast.parse(code)
416
checker = Checker(tree, "example.py")
417

418
for message in checker.messages:
419
    if isinstance(message, UnusedImport):
420
        print(f"Unused import: {message.message_args[0]}")
421
    elif isinstance(message, UndefinedName):
422
        print(f"Undefined name: {message.message_args[0]}")
423
```