0
# Output Rendering
1
2
Multiple output formats for displaying profiling results with various renderers supporting different use cases from interactive HTML visualizations to console text output and integration formats for external tools.
3
4
## Capabilities
5
6
### Console Renderer
7
8
Text-based console output with support for Unicode, colors, different view modes, and customizable formatting options.
9
10
```python { .api }
11
class ConsoleRenderer:
12
"""
13
Renders profiling results as formatted console text.
14
"""
15
16
def __init__(
17
self,
18
unicode: bool = False,
19
color: bool = False,
20
show_all: bool = False,
21
timeline: bool = False,
22
time: Literal["seconds", "percent_of_total"] = "seconds",
23
flat: bool = False,
24
flat_time: FlatTimeMode = "self",
25
short_mode: bool = False,
26
processor_options: dict[str, Any] | None = None
27
):
28
"""
29
Initialize console renderer with display options.
30
31
Args:
32
unicode: Use Unicode box-drawing characters
33
color: Use ANSI color codes for highlighting
34
show_all: Show all frames including library code
35
timeline: Show chronological timeline view
36
time: Display format - "seconds" or "percent_of_total"
37
flat: Show flat profile instead of call tree
38
flat_time: For flat mode - "self" or "cumulative" time
39
short_mode: Use compact output format
40
processor_options: Frame processing configuration
41
"""
42
43
def render(self, session: Session) -> str:
44
"""
45
Render session data as formatted console text.
46
47
Args:
48
session: Profiling session to render
49
50
Returns:
51
Formatted text representation of profiling data
52
"""
53
```
54
55
### HTML Renderer
56
57
Interactive HTML output with timeline visualization, expandable call trees, and browser-based interface for exploring profiling results.
58
59
```python { .api }
60
class HTMLRenderer:
61
"""
62
Renders profiling results as interactive HTML with timeline view.
63
"""
64
65
def __init__(
66
self,
67
timeline: bool = False,
68
show_all: bool = False
69
):
70
"""
71
Initialize HTML renderer.
72
73
Args:
74
timeline: Include interactive timeline visualization
75
show_all: Show all frames including library code
76
"""
77
78
def render(self, session: Session) -> str:
79
"""
80
Render session data as interactive HTML.
81
82
Args:
83
session: Profiling session to render
84
85
Returns:
86
Complete HTML document with embedded JavaScript
87
"""
88
89
def open_in_browser(self, session: Session) -> None:
90
"""
91
Render session and open results in web browser.
92
93
Args:
94
session: Profiling session to display
95
"""
96
```
97
98
### JSON Renderer
99
100
Structured JSON output for programmatic analysis and integration with external tools.
101
102
```python { .api }
103
class JSONRenderer:
104
"""
105
Renders profiling results as structured JSON data.
106
"""
107
108
def render(self, session: Session) -> str:
109
"""
110
Render session data as JSON.
111
112
Args:
113
session: Profiling session to render
114
115
Returns:
116
JSON string containing structured profiling data
117
"""
118
```
119
120
### Speedscope Renderer
121
122
Output format compatible with speedscope.app for advanced timeline visualization and flame graph analysis.
123
124
```python { .api }
125
class SpeedscopeRenderer:
126
"""
127
Renders profiling results in speedscope.app compatible format.
128
"""
129
130
def render(self, session: Session) -> str:
131
"""
132
Render session data in speedscope format.
133
134
Args:
135
session: Profiling session to render
136
137
Returns:
138
JSON string compatible with speedscope.app
139
"""
140
```
141
142
### Pstats Renderer
143
144
Python cProfile/pstats compatible output for integration with existing Python profiling tools.
145
146
```python { .api }
147
class PstatsRenderer:
148
"""
149
Renders profiling results in Python pstats compatible format.
150
"""
151
152
def render(self, session: Session) -> str:
153
"""
154
Render session data in pstats format.
155
156
Args:
157
session: Profiling session to render
158
159
Returns:
160
pstats compatible data representation
161
"""
162
```
163
164
### Session Renderer
165
166
Internal renderer for session data serialization, typically used for saving session state.
167
168
```python { .api }
169
class SessionRenderer:
170
"""
171
Renders profiling results as session data for storage and loading.
172
"""
173
174
def __init__(self, tree_format: bool = False):
175
"""
176
Initialize session renderer.
177
178
Args:
179
tree_format: Whether to use tree format for output
180
"""
181
182
def render(self, session: Session) -> str:
183
"""
184
Render session data as JSON.
185
186
Args:
187
session: Profiling session to render
188
189
Returns:
190
JSON string of session data
191
"""
192
```
193
194
### Base Renderer Classes
195
196
Abstract base classes for implementing custom renderers.
197
198
```python { .api }
199
class Renderer:
200
"""Base class for all renderers."""
201
202
def render(self, session: Session) -> str:
203
"""
204
Render session data to string output.
205
206
Args:
207
session: Profiling session to render
208
209
Returns:
210
Rendered output as string
211
"""
212
213
class FrameRenderer(Renderer):
214
"""Base class for frame-based renderers with tree processing."""
215
```
216
217
## Usage Examples
218
219
### Console Output with Options
220
221
```python
222
from pyinstrument import Profiler
223
from pyinstrument.renderers import ConsoleRenderer
224
225
with Profiler() as profiler:
226
do_work()
227
228
# Custom console rendering
229
renderer = ConsoleRenderer(
230
color=True,
231
unicode=True,
232
show_all=True,
233
timeline=False
234
)
235
output = renderer.render(profiler.last_session)
236
print(output)
237
```
238
239
### HTML Output for Web Viewing
240
241
```python
242
from pyinstrument import Profiler
243
from pyinstrument.renderers import HTMLRenderer
244
245
with Profiler() as profiler:
246
process_data()
247
248
# Generate HTML with timeline
249
html_renderer = HTMLRenderer(timeline=True, show_all=False)
250
html_content = html_renderer.render(profiler.last_session)
251
252
# Save to file
253
with open('profile.html', 'w') as f:
254
f.write(html_content)
255
256
# Or open directly in browser
257
html_renderer.open_in_browser(profiler.last_session)
258
```
259
260
### JSON Export for Analysis
261
262
```python
263
from pyinstrument import Profiler
264
from pyinstrument.renderers import JSONRenderer
265
import json
266
267
with Profiler() as profiler:
268
analyze_data()
269
270
# Export as JSON
271
json_renderer = JSONRenderer()
272
json_output = json_renderer.render(profiler.last_session)
273
data = json.loads(json_output)
274
275
# Save for external analysis
276
with open('profile.json', 'w') as f:
277
json.dump(data, f, indent=2)
278
```
279
280
### Speedscope Integration
281
282
```python
283
from pyinstrument import Profiler
284
from pyinstrument.renderers import SpeedscopeRenderer
285
286
with Profiler() as profiler:
287
complex_computation()
288
289
# Generate speedscope format
290
speedscope_renderer = SpeedscopeRenderer()
291
speedscope_data = speedscope_renderer.render(profiler.last_session)
292
293
# Save for speedscope.app
294
with open('profile.speedscope.json', 'w') as f:
295
f.write(speedscope_data)
296
```
297
298
## Types
299
300
```python { .api }
301
FlatTimeMode = Literal["self", "cumulative"]
302
303
class ProcessorOptions:
304
"""Configuration options for frame processing."""
305
filter_threshold: float
306
hide_regex: str | None
307
show_regex: str | None
308
```