0
# Code Analysis API
1

2
High-level functions for checking Python code that provide the main entry points for pyflakes functionality. These functions handle code strings, individual files, and directory traversal with integrated error reporting.
3

4
## Capabilities
5

6
### Code String Analysis
7

8
Check Python code directly from strings, useful for runtime code validation, editor integrations, and dynamic analysis workflows.
9

10
```python { .api }
11
def check(codeString: str, filename: str, reporter: Reporter | None = ...) -> int:
12
    """
13
    Check Python code string for errors.
14
    
15
    Parameters:
16
    - codeString: str, Python source code to analyze
17
    - filename: str, filename for error reporting (can be virtual)
18
    - reporter: Reporter | None, output handler for messages (None creates default)
19
    
20
    Returns:
21
    int: Number of errors found
22
    """
23
```
24

25
**Usage Example:**
26

27
```python
28
from pyflakes.api import check
29
from pyflakes.reporter import Reporter
30
import sys
31

32
code = """
33
import os
34
import sys  # Unused import
35
x = undefined_variable  # Undefined name
36
"""
37

38
reporter = Reporter(sys.stderr, sys.stderr)
39
error_count = check(code, "example.py", reporter)
40
print(f"Found {error_count} issues")
41
```
42

43
### File Analysis
44

45
Analyze individual Python files on disk, automatically handling file reading and encoding detection.
46

47
```python { .api }
48
def checkPath(filename, reporter: Reporter | None = ...) -> int:
49
    """
50
    Check Python file at given path.
51
    
52
    Parameters:
53
    - filename: path to Python file to analyze
54
    - reporter: Reporter | None, output handler for messages
55
    
56
    Returns:
57
    int: Number of errors found
58
    """
59
```
60

61
**Usage Example:**
62

63
```python
64
from pyflakes.api import checkPath
65
from pyflakes.reporter import Reporter
66
import sys
67

68
reporter = Reporter(sys.stderr, sys.stderr)
69
error_count = checkPath("mymodule.py", reporter)
70
if error_count == 0:
71
    print("No issues found!")
72
```
73

74
### Directory Tree Analysis
75

76
Recursively analyze Python files in directory trees, with automatic Python file detection and parallel processing capabilities.
77

78
```python { .api }
79
def checkRecursive(paths: Iterable[Any], reporter: Reporter) -> int:
80
    """
81
    Recursively check Python files in given paths.
82
    
83
    Parameters:
84
    - paths: Iterable[Any], directories and files to analyze recursively
85
    - reporter: Reporter, output handler for messages (required)
86
    
87
    Returns:
88
    int: Total number of errors found across all files
89
    """
90
```
91

92
**Usage Example:**
93

94
```python
95
from pyflakes.api import checkRecursive
96
from pyflakes.reporter import Reporter
97
import sys
98

99
reporter = Reporter(sys.stderr, sys.stderr)
100
paths = ["src/", "tests/", "scripts/single_file.py"]
101
total_errors = checkRecursive(paths, reporter)
102
print(f"Total errors across all files: {total_errors}")
103
```
104

105
### Python File Detection
106

107
Utility function to determine if a given file is a Python source file, checking file extensions and shebang lines.
108

109
```python { .api }
110
def isPythonFile(filename) -> bool:
111
    """
112
    Check if a file is a Python source file.
113
    
114
    Parameters:
115
    - filename: path to file to check
116
    
117
    Returns:
118
    bool: True if file is a Python source file, False otherwise
119
    """
120
```
121

122
**Usage Example:**
123

124
```python
125
from pyflakes.api import isPythonFile
126

127
if isPythonFile("script.py"):
128
    print("This is a Python file")
129

130
if isPythonFile("#!/usr/bin/env python\nprint('hello')"):
131
    print("This has a Python shebang")
132
```
133

134
### Source Code Iteration
135

136
Iterator for traversing and collecting Python source files from mixed path collections, handling both files and directories.
137

138
```python { .api }
139
def iterSourceCode(paths: Iterable[Any]) -> Iterator[Any]:
140
    """
141
    Iterate over Python source code files in given paths.
142
    
143
    Parameters:
144
    - paths: Iterable[Any], collection of files and directories
145
    
146
    Yields:
147
    Iterator[Any]: Python source files found in paths
148
    """
149
```
150

151
### Command Line Interface
152

153
Main entry point for command-line usage, handling argument parsing, output formatting, and exit codes.
154

155
```python { .api }
156
def main(prog: str | None = ..., args: Sequence[Any] | None = ...) -> None:
157
    """
158
    Main command-line entry point.
159
    
160
    Parameters:
161
    - prog: str | None, program name for help text
162
    - args: Sequence[Any] | None, command line arguments (None uses sys.argv)
163
    
164
    Returns:
165
    None: Exits with appropriate code based on analysis results
166
    """
167
```
168

169
## Constants
170

171
### Python Detection Pattern
172

173
```python { .api }
174
PYTHON_SHEBANG_REGEX: Pattern[bytes]
175
```
176

177
Regular expression pattern used for detecting Python files by shebang line, supporting various Python interpreter names and paths.
178

179
## Module Exports
180

181
The module explicitly exports the following functions:
182

183
```python { .api }
184
__all__ = ["check", "checkPath", "checkRecursive", "isPythonFile", "iterSourceCode", "main"]
185
```