0
# Output Rendering
1

2
Renders dependency trees in multiple formats including text, JSON, GraphViz, Mermaid, and freeze formats with extensive customization options.
3

4
## Capabilities
5

6
### Main Render Function
7

8
Primary entry point for rendering dependency trees in various formats.
9

10
```python { .api }
11
def render(options: Options, tree: PackageDAG) -> None:
12
    """
13
    Render dependency tree in the format specified by options.
14
    
15
    Automatically selects the appropriate renderer based on options:
16
    - JSON output if options.json is True
17
    - Nested JSON tree if options.json_tree is True  
18
    - Mermaid diagram if options.mermaid is True
19
    - GraphViz output if options.output_format is specified
20
    - Freeze format if options.freeze is True
21
    - Text format (default) for all other cases
22
    
23
    Parameters:
24
    - options: CLI options specifying output format and settings
25
    - tree: PackageDAG to render
26
    """
27
```
28

29
### Text Rendering
30

31
Human-readable hierarchical text output with optional licensing information.
32

33
```python { .api }
34
def render_text(
35
    tree: PackageDAG,
36
    max_depth: float,
37
    encoding: str,
38
    list_all: bool,
39
    include_license: bool,
40
) -> None:
41
    """
42
    Render dependency tree as indented text to stdout.
43
    
44
    Parameters:
45
    - tree: PackageDAG to render
46
    - max_depth: Maximum depth to display (float('inf') for unlimited)
47
    - encoding: Character encoding for output
48
    - list_all: Whether to list all dependencies at top level
49
    - include_license: Whether to include license information
50
    """
51
```
52

53
### JSON Rendering
54

55
Machine-readable JSON output formats for programmatic consumption.
56

57
```python { .api }
58
def render_json(tree: PackageDAG) -> str:
59
    """
60
    Render dependency tree as flat JSON array.
61
    
62
    Each package is represented as an object with dependencies listed
63
    as separate objects in the same array structure.
64
    
65
    Parameters:
66
    - tree: PackageDAG to render
67
    
68
    Returns:
69
    JSON string representation
70
    """
71

72
def render_json_tree(tree: PackageDAG) -> str:
73
    """
74
    Render dependency tree as nested JSON structure.
75
    
76
    Creates a hierarchical JSON structure that mirrors the text output
77
    format with nested dependency relationships.
78
    
79
    Parameters:
80
    - tree: PackageDAG to render
81
    
82
    Returns:
83
    Nested JSON string representation
84
    """
85
```
86

87
### Freeze Format Rendering
88

89
pip freeze-compatible output format for requirements files.
90

91
```python { .api }
92
def render_freeze(
93
    tree: PackageDAG,
94
    max_depth: float,
95
    list_all: bool,
96
) -> None:
97
    """
98
    Render dependency tree in pip freeze format to stdout.
99
    
100
    Produces output compatible with pip freeze, including:
101
    - Editable packages with -e flag
102
    - VCS URLs for packages installed from git/etc
103
    - Standard package==version format
104
    
105
    Parameters:
106
    - tree: PackageDAG to render
107
    - max_depth: Maximum depth to include
108
    - list_all: Whether to list all dependencies at top level
109
    """
110

111
def dist_to_frozen_repr(dist: Distribution) -> str:
112
    """
113
    Convert a Distribution object to pip freeze-compatible representation.
114
    
115
    Creates freeze format strings including editable packages with -e flag,
116
    VCS URLs for packages installed from git/etc, and standard package==version format.
117
    
118
    Parameters:
119
    - dist: importlib.metadata.Distribution object to convert
120
    
121
    Returns:
122
    String in pip freeze format
123
    """
124
```
125

126
### GraphViz Rendering
127

128
Visual graph output using GraphViz for creating diagrams and images.
129

130
```python { .api }
131
def render_graphviz(
132
    tree: PackageDAG,
133
    output_format: str,
134
    reverse: bool,
135
) -> None:
136
    """
137
    Render dependency tree using GraphViz for visual output.
138
    
139
    Generates GraphViz DOT format and optionally renders to image formats.
140
    Supports all GraphViz output formats: png, svg, pdf, dot, etc.
141
    
142
    Parameters:
143
    - tree: PackageDAG to render
144
    - output_format: GraphViz output format (png, svg, pdf, dot, etc.)
145
    - reverse: Whether tree is in reverse mode (affects node coloring)
146
    """
147
```
148

149
### Mermaid Rendering
150

151
Mermaid flow diagram format for web-based visualization.
152

153
```python { .api }
154
def render_mermaid(tree: PackageDAG) -> str:
155
    """
156
    Render dependency tree as Mermaid flow diagram.
157
    
158
    Creates a Mermaid-compatible flow diagram showing package dependencies
159
    that can be rendered in GitHub, web browsers, or Mermaid tools.
160
    
161
    Parameters:
162
    - tree: PackageDAG to render
163
    
164
    Returns:
165
    Mermaid diagram string
166
    """
167
```
168

169
## Usage Examples
170

171
### Basic Text Rendering
172

173
```python
174
from pipdeptree._render import render_text
175
from pipdeptree._models import PackageDAG
176
from pipdeptree._discovery import get_installed_distributions
177

178
# Create dependency tree
179
distributions = get_installed_distributions()
180
tree = PackageDAG.from_pkgs(distributions)
181

182
# Render as text with licenses
183
render_text(
184
    tree=tree,
185
    max_depth=float('inf'),
186
    encoding='utf-8', 
187
    list_all=False,
188
    include_license=True
189
)
190
```
191

192
### JSON Output Formats
193

194
```python
195
from pipdeptree._render import render_json, render_json_tree
196
import json
197

198
# Flat JSON format
199
json_output = render_json(tree)
200
data = json.loads(json_output)
201
print(f"Found {len(data)} packages")
202

203
# Nested JSON tree format  
204
tree_output = render_json_tree(tree)
205
tree_data = json.loads(tree_output)
206
print("Dependency tree structure:")
207
for pkg in tree_data:
208
    print(f"- {pkg['package_name']} ({pkg['installed_version']})")
209
```
210

211
### Using the Main Render Function
212

213
```python
214
from pipdeptree._cli import get_options
215
from pipdeptree._render import render
216

217
# Parse options and render accordingly
218
options = get_options(['--json-tree', '--depth', '2'])
219
render(options, tree)
220

221
# Different output formats
222
options_json = get_options(['--json'])
223
render(options_json, tree)
224

225
options_mermaid = get_options(['--mermaid']) 
226
render(options_mermaid, tree)
227
```
228

229
### Freeze Format Output
230

231
```python
232
from pipdeptree._render import render_freeze
233

234
# Generate pip freeze compatible output
235
render_freeze(
236
    tree=tree,
237
    max_depth=float('inf'),
238
    list_all=True  # Include all packages at top level
239
)
240

241
# Output can be redirected to create requirements file:
242
# python -c "render_freeze(...)" > requirements.txt
243
```
244

245
### GraphViz Visual Output
246

247
```python
248
from pipdeptree._render import render_graphviz
249

250
# Generate PNG image
251
render_graphviz(
252
    tree=tree,
253
    output_format='png',
254
    reverse=False
255
)
256

257
# Generate SVG for web display
258
render_graphviz(
259
    tree=tree, 
260
    output_format='svg',
261
    reverse=False
262
)
263

264
# Generate DOT source for further processing
265
render_graphviz(
266
    tree=tree,
267
    output_format='dot', 
268
    reverse=False
269
)
270
```
271

272
## Output Format Details
273

274
### Text Format
275

276
The default text format shows hierarchical dependency relationships:
277

278
```
279
Flask==2.3.2
280
  - blinker [required: >=1.6.2, installed: 1.6.2]
281
  - click [required: >=8.1.3, installed: 8.1.3]
282
    - colorama [required: Any, installed: 0.4.6]
283
  - itsdangerous [required: >=2.1.2, installed: 2.1.2]
284
  - Jinja2 [required: >=3.1.2, installed: 3.1.2]
285
    - MarkupSafe [required: >=2.0, installed: 2.2.1]
286
  - Werkzeug [required: >=2.3.6, installed: 2.3.6]
287
```
288

289
With licenses enabled:
290
```
291
Flask==2.3.2 (BSD License)
292
  - blinker [required: >=1.6.2, installed: 1.6.2] (MIT License)
293
```
294

295
### JSON Format
296

297
Flat JSON array with each package as a separate object:
298

299
```json
300
[
301
  {
302
    "key": "flask",
303
    "package_name": "Flask", 
304
    "installed_version": "2.3.2",
305
    "dependencies": [
306
      {
307
        "key": "blinker",
308
        "package_name": "blinker",
309
        "installed_version": "1.6.2",
310
        "required_version": ">=1.6.2"
311
      }
312
    ]
313
  }
314
]
315
```
316

317
### JSON Tree Format
318

319
Nested structure mirroring the text hierarchy:
320

321
```json
322
[
323
  {
324
    "package_name": "Flask",
325
    "installed_version": "2.3.2", 
326
    "dependencies": [
327
      {
328
        "package_name": "blinker",
329
        "installed_version": "1.6.2",
330
        "required_version": ">=1.6.2",
331
        "dependencies": []
332
      }
333
    ]
334
  }
335
]
336
```
337

338
### Freeze Format
339

340
pip freeze compatible output:
341

342
```
343
Flask==2.3.2
344
blinker==1.6.2
345
click==8.1.3
346
colorama==0.4.6
347
-e git+https://github.com/user/repo.git@abc123#egg=mypackage
348
```
349

350
### Mermaid Format
351

352
Flow diagram syntax:
353

354
```mermaid
355
graph TD
356
    Flask --> blinker
357
    Flask --> click
358
    click --> colorama
359
    Flask --> itsdangerous
360
    Flask --> Jinja2
361
    Jinja2 --> MarkupSafe
362
    Flask --> Werkzeug
363
```
364

365
### GraphViz DOT Format
366

367
DOT language for graph visualization:
368

369
```dot
370
digraph {
371
    "Flask" [label="Flask\n2.3.2"];
372
    "blinker" [label="blinker\n1.6.2"];
373
    "Flask" -> "blinker";
374
}
375
```
376

377
## Rendering Configuration
378

379
Each render function accepts specific configuration parameters:
380

381
### Text Rendering Options
382
- **max_depth**: Limit tree depth display
383
- **encoding**: Character encoding for output  
384
- **list_all**: Show all packages at top level vs. tree structure
385
- **include_license**: Add license information to output
386

387
### Freeze Rendering Options
388
- **max_depth**: Limit which packages to include
389
- **list_all**: Include all dependencies vs. just top-level
390

391
### GraphViz Options
392
- **output_format**: Image format (png, svg, pdf) or dot source
393
- **reverse**: Affects node coloring for reverse dependency trees
394

395
The rendering system integrates with pipdeptree's warning system and respects the configured warning levels for error handling during output generation.