0
# Pyflakes
1

2
Pyflakes is a static analysis tool that detects errors in Python code without importing it, making it safe and fast. It analyzes programs by parsing source files and detects various programming errors like undefined variables, unused imports, and syntax issues. Unlike other linters, Pyflakes focuses solely on error detection without complaining about code style, maintaining a strict philosophy of minimizing false positives.
3

4
## Package Information
5

6
- **Package Name**: pyflakes
7
- **Language**: Python
8
- **Installation**: `pip install pyflakes`
9
- **Version**: 3.4.0
10
- **Python Support**: 3.9+
11

12
## Core Imports
13

14
```python
15
import pyflakes.api
16
import pyflakes.checker
17
import pyflakes.reporter
18
import pyflakes.messages
19
```
20

21
For basic usage:
22

23
```python
24
from pyflakes.api import check, checkPath, checkRecursive
25
from pyflakes.reporter import Reporter
26
```
27

28
## Basic Usage
29

30
```python
31
import pyflakes.api
32

33
# Check a code string
34
code = """
35
import os
36
x = 1
37
print(y)  # This will be flagged as undefined
38
"""
39
warnings = pyflakes.api.check(code, 'example.py')
40
print(f"Found {warnings} warnings")
41

42
# Check a file
43
warnings = pyflakes.api.checkPath('myfile.py')
44

45
# Check multiple paths recursively
46
from pyflakes.reporter import _makeDefaultReporter
47
reporter = _makeDefaultReporter()
48
warnings = pyflakes.api.checkRecursive(['src/', 'tests/'], reporter)
49
```
50

51
## Architecture
52

53
Pyflakes uses a multi-layered architecture:
54

55
- **API Layer**: High-level functions for checking code strings, files, and directories
56
- **Checker**: Core analysis engine that walks the AST and maintains scope information
57
- **Messages**: Structured error/warning types for different kinds of issues
58
- **Reporter**: Output formatting system for presenting results to users
59
- **Bindings & Scopes**: Internal representation of variable bindings and code scopes
60

61
This design enables Pyflakes to safely analyze Python code without importing it while maintaining detailed scope information to minimize false positives.
62

63
## Capabilities
64

65
### Core API Functions
66

67
Primary interface for checking Python code, supporting code strings, individual files, and recursive directory analysis. These functions provide the main entry points for integrating Pyflakes into development workflows.
68

69
```python { .api }
70
def check(codeString: str, filename: str, reporter=None) -> int: ...
71
def checkPath(filename: str, reporter=None) -> int: ...
72
def checkRecursive(paths: list, reporter) -> int: ...
73
def iterSourceCode(paths: list): ...
74
def isPythonFile(filename: str) -> bool: ...
75
def main(prog=None, args=None): ...
76
```
77

78
[Core API](./core-api.md)
79

80
### Checker System
81

82
Advanced code analysis engine that performs AST-based static analysis with comprehensive scope tracking, binding management, and AST node handling. The Checker class provides fine-grained control over the analysis process with 65+ methods covering all Python AST node types.
83

84
```python { .api }
85
class Checker:
86
    def __init__(self, tree, filename='(none)', builtins=None, withDoctest='PYFLAKES_DOCTEST' in os.environ, file_tokens=()): ...
87
    
88
    # Core attributes and properties
89
    messages: list
90
    deadScopes: list
91
    scopeStack: list
92
    futuresAllowed: bool
93
    annotationsFutureEnabled: bool
94
    
95
    # Core analysis methods
96
    def report(self, messageClass, *args, **kwargs): ...
97
    def handleNode(self, node, parent): ...
98
    def deferFunction(self, callable): ...
99
    def addBinding(self, node, value): ...
100
    
101
    # All AST node handlers (FUNCTIONDEF, IMPORT, CALL, etc.)
102
    # Complete binding system (Assignment, Importation, etc.)
103
    # Complete scope system (ModuleScope, FunctionScope, etc.)
104
```
105

106
[Checker System](./checker-system.md)
107

108
### Message Types
109

110
Comprehensive set of 48 structured warning and error classes representing different types of issues that can be detected in Python code. Each message type provides specific information about the problem and its location.
111

112
```python { .api }
113
class Message:
114
    def __init__(self, filename, loc): ...
115

116
class UndefinedName(Message): ...
117
class UnusedImport(Message): ...
118
class RedefinedWhileUnused(Message): ...
119
class FStringMissingPlaceholders(Message): ...
120
class PercentFormatInvalidFormat(Message): ...
121
# ... all 48 message types documented
122
```
123

124
[Message Types](./message-types.md)
125

126
### Reporter System
127

128
Flexible output formatting system for presenting analysis results to users. The Reporter class can be customized to integrate Pyflakes into different development environments and workflows.
129

130
```python { .api }
131
class Reporter:
132
    def __init__(self, warningStream, errorStream): ...
133
    def unexpectedError(self, filename, msg): ...
134
    def syntaxError(self, filename, msg, lineno, offset, text): ...
135
    def flake(self, message): ...
136
```
137

138
[Reporter System](./reporter-system.md)