0
# Report Generation
1

2
Configurable reporting system for displaying analysis results from pyflakes. The Reporter class handles output formatting and stream management for different types of messages and errors.
3

4
## Capabilities
5

6
### Reporter Class
7

8
Main class for handling output of analysis results, providing configurable streams for warnings and errors with extensible formatting.
9

10
```python { .api }
11
class Reporter:
12
    """
13
    Reporter for pyflakes analysis results.
14
    
15
    Manages output streams and formatting for different types of messages
16
    including warnings, errors, and syntax errors.
17
    """
18
    
19
    def __init__(self, warningStream, errorStream) -> None:
20
        """
21
        Initialize reporter with output streams.
22
        
23
        Parameters:
24
        - warningStream: Output stream for warning messages
25
        - errorStream: Output stream for error messages
26
        """
27
```
28

29
### Message Reporting
30

31
Methods for outputting different types of analysis results with appropriate formatting and stream routing.
32

33
```python { .api }
34
def flake(self, message) -> None:
35
    """
36
    Report a pyflakes message (warning or error).
37
    
38
    Parameters:
39
    - message: Message instance to report
40
    
41
    Formats and outputs the message to the appropriate stream based on
42
    message type and severity.
43
    """
44
```
45

46
**Usage Example:**
47

48
```python
49
from pyflakes.reporter import Reporter
50
from pyflakes.api import check
51
import sys
52
import io
53

54
# Create string buffers to capture output
55
warnings_buffer = io.StringIO()
56
errors_buffer = io.StringIO()
57

58
# Create reporter with custom streams
59
reporter = Reporter(warnings_buffer, errors_buffer)
60

61
# Check some code
62
code = """
63
import os  # Unused import
64
print(undefined_var)  # Undefined name
65
"""
66

67
result = check(code, "example.py", reporter)
68

69
# Get captured output
70
warnings_output = warnings_buffer.getvalue()
71
errors_output = errors_buffer.getvalue()
72

73
print("Warnings:", warnings_output)
74
print("Errors:", errors_output)
75
```
76

77
### Syntax Error Reporting
78

79
Specialized method for reporting Python syntax errors with detailed location and context information.
80

81
```python { .api }
82
def syntaxError(self, filename, msg, lineno, offset, text) -> None:
83
    """
84
    Report a Python syntax error.
85
    
86
    Parameters:
87
    - filename: Name of file containing syntax error
88
    - msg: Error message describing the syntax problem
89
    - lineno: Line number where error occurs
90
    - offset: Character offset within the line
91
    - text: Source text line containing the error
92
    
93
    Provides detailed syntax error reporting with line context and
94
    position indicators.
95
    """
96
```
97

98
**Usage Example:**
99

100
```python
101
from pyflakes.reporter import Reporter
102
import sys
103

104
reporter = Reporter(sys.stderr, sys.stderr)
105

106
# Report a syntax error (typically called internally)
107
reporter.syntaxError(
108
    "badfile.py",
109
    "invalid syntax",
110
    lineno=5,
111
    offset=10,
112
    text="if x = 5:"  # Invalid assignment in if
113
)
114
```
115

116
### Unexpected Error Reporting
117

118
Method for reporting unexpected internal errors during analysis, useful for debugging and error handling.
119

120
```python { .api }
121
def unexpectedError(self, filename, msg) -> None:
122
    """
123
    Report an unexpected error during analysis.
124
    
125
    Parameters:
126
    - filename: Name of file being analyzed when error occurred
127
    - msg: Error message describing the unexpected condition
128
    
129
    Used for reporting internal errors or unexpected conditions that
130
    occur during the analysis process.
131
    """
132
```
133

134
## Custom Reporter Implementation
135

136
You can extend the Reporter class to customize output formatting, add logging, or integrate with other tools:
137

138
```python
139
from pyflakes.reporter import Reporter
140
import json
141
import sys
142

143
class JSONReporter(Reporter):
144
    """Custom reporter that outputs JSON-formatted results."""
145
    
146
    def __init__(self):
147
        super().__init__(sys.stdout, sys.stderr)
148
        self.results = []
149
    
150
    def flake(self, message):
151
        """Collect messages as structured data."""
152
        self.results.append({
153
            'type': type(message).__name__,
154
            'filename': message.filename,
155
            'line': message.lineno,
156
            'column': message.col,
157
            'message': str(message),
158
            'args': message.message_args
159
        })
160
    
161
    def syntaxError(self, filename, msg, lineno, offset, text):
162
        """Collect syntax errors as structured data."""
163
        self.results.append({
164
            'type': 'SyntaxError',
165
            'filename': filename,
166
            'line': lineno,
167
            'column': offset,
168
            'message': msg,
169
            'text': text
170
        })
171
    
172
    def output_json(self):
173
        """Output collected results as JSON."""
174
        print(json.dumps(self.results, indent=2))
175

176
# Usage
177
from pyflakes.api import check
178

179
reporter = JSONReporter()
180
check("import os\nprint(undefined)", "test.py", reporter)
181
reporter.output_json()
182
```
183

184
## Integration with Analysis Workflow
185

186
The Reporter works seamlessly with all pyflakes analysis functions:
187

188
```python
189
from pyflakes.api import check, checkPath, checkRecursive
190
from pyflakes.reporter import Reporter
191
import sys
192

193
# Create a reporter
194
reporter = Reporter(sys.stdout, sys.stderr)
195

196
# Use with different analysis functions
197
check("import unused", "string.py", reporter)
198
checkPath("myfile.py", reporter)
199
checkRecursive(["src/", "tests/"], reporter)
200
```
201

202
## Output Stream Configuration
203

204
Different configurations for various use cases:
205

206
```python
207
from pyflakes.reporter import Reporter
208
import sys
209
import io
210

211
# Standard output (warnings and errors to stderr)
212
reporter = Reporter(sys.stderr, sys.stderr)
213

214
# Separate streams
215
warnings_file = open("warnings.txt", "w")
216
errors_file = open("errors.txt", "w")
217
reporter = Reporter(warnings_file, errors_file)
218

219
# Capture to strings
220
warnings_buffer = io.StringIO()
221
errors_buffer = io.StringIO()
222
reporter = Reporter(warnings_buffer, errors_buffer)
223

224
# Silent reporter (no output)
225
null_stream = io.StringIO()
226
reporter = Reporter(null_stream, null_stream)
227
```