0
# Types-PyFlakes
1

2
Type stubs for pyflakes, a Python source code analysis tool that detects errors in Python files without importing them. These type stubs enable static type checking for pyflakes functionality, supporting code linting tools, IDEs, and development workflows that require precise type information for pyflakes APIs.
3

4
## Package Information
5

6
- **Package Name**: types-pyflakes
7
- **Language**: Python
8
- **Installation**: `pip install types-pyflakes`
9
- **Provides Type Stubs For**: pyflakes
10

11
## Core Imports
12

13
```python
14
import pyflakes
15
from pyflakes import api
16
from pyflakes.checker import Checker
17
from pyflakes.messages import Message
18
from pyflakes.reporter import Reporter
19

20
# Access version information
21
print(pyflakes.__version__)
22
```
23

24
For checking code:
25

26
```python
27
from pyflakes.api import check, checkPath, checkRecursive
28
```
29

30
For custom analysis:
31

32
```python
33
from pyflakes.checker import Checker
34
from pyflakes.reporter import Reporter
35
```
36

37
## Basic Usage
38

39
```python
40
from pyflakes.api import check
41
from pyflakes.reporter import Reporter
42
import sys
43

44
# Check a code string
45
code = """
46
import os
47
import sys  # This will trigger UnusedImport
48
print("Hello world")
49
"""
50

51
# Create a reporter for output
52
reporter = Reporter(sys.stderr, sys.stderr)
53

54
# Check the code
55
result = check(code, "example.py", reporter)
56
print(f"Found {result} issues")
57

58
# Check a file
59
from pyflakes.api import checkPath
60
result = checkPath("myfile.py", reporter)
61
```
62

63
## Architecture
64

65
Pyflakes operates through a multi-stage analysis pipeline:
66

67
- **API Layer** (`pyflakes.api`): High-level functions for checking code strings, files, and directories
68
- **Checker** (`pyflakes.checker`): Core AST analysis engine with sophisticated scope and binding management
69
- **Messages** (`pyflakes.messages`): Comprehensive error and warning message classes for different issue types
70
- **Reporter** (`pyflakes.reporter`): Configurable output system for displaying analysis results
71

72
The checker performs static analysis by parsing Python code into Abstract Syntax Trees (AST), tracking variable bindings across scopes, and identifying issues like unused imports, undefined names, and syntax errors without executing the code.
73

74
## Capabilities
75

76
### Code Analysis API
77

78
High-level functions for checking Python code strings, individual files, and entire directory trees. Supports both simple error detection and custom reporting workflows.
79

80
```python { .api }
81
def check(codeString: str, filename: str, reporter: Reporter | None = ...) -> int: ...
82
def checkPath(filename, reporter: Reporter | None = ...) -> int: ...
83
def checkRecursive(paths: Iterable[Any], reporter: Reporter) -> int: ...
84
```
85

86
[Code Analysis API](./code-analysis.md)
87

88
### AST Checker and Analysis Engine
89

90
Core checker functionality providing detailed AST analysis, scope management, binding tracking, and extensible analysis capabilities for advanced use cases.
91

92
```python { .api }
93
class Checker:
94
    def __init__(
95
        self,
96
        tree: ast.AST,
97
        filename: str = ...,
98
        builtins: Iterable[str] | None = ...,
99
        withDoctest: bool = ...,
100
        file_tokens: tuple[Any, ...] = ...,
101
    ) -> None: ...
102
    
103
    def report(self, messageClass: Callable[_P, Message], *args: _P.args, **kwargs: _P.kwargs) -> None: ...
104
```
105

106
[AST Checker](./ast-checker.md)
107

108
### Error Messages and Warnings
109

110
Comprehensive message classes for different types of analysis issues including import problems, undefined names, syntax errors, and format string validation errors.
111

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

116
class UnusedImport(Message): ...
117
class UndefinedName(Message): ...
118
class ImportStarUsed(Message): ...
119
```
120

121
[Error Messages](./error-messages.md)
122

123
### Report Generation
124

125
Configurable reporting system for displaying analysis results to different output streams with support for custom error handling and formatting.
126

127
```python { .api }
128
class Reporter:
129
    def __init__(self, warningStream, errorStream) -> None: ...
130
    def flake(self, message) -> None: ...
131
    def syntaxError(self, filename, msg, lineno, offset, text) -> None: ...
132
```
133

134
[Report Generation](./report-generation.md)
135

136
## Types
137

138
```python { .api }
139
from collections.abc import Iterable, Iterator, Sequence, Callable
140
from re import Pattern
141
from typing import Any, ClassVar, TypeVar, overload
142
from typing_extensions import Literal, ParamSpec, TypeAlias
143
import ast
144

145
# Version information
146
__version__: str
147

148
# Type variables
149
_AnyFunction: TypeAlias = Callable[..., Any]
150
_F = TypeVar("_F", bound=_AnyFunction)
151
_P = ParamSpec("_P")
152
_T = TypeVar("_T")
153

154
# Format string types
155
_FormatType: TypeAlias = tuple[str | None, str | None, str | None, str | None, str]
156
_PercentFormat: TypeAlias = tuple[str, _FormatType | None]
157

158
# Omission type for AST traversal
159
_OmitType: TypeAlias = str | tuple[str, ...] | None
160
```