0
# Display System
1

2
IPython's rich output formatting and media display capabilities for presenting HTML, images, videos, interactive widgets, and custom representations. The display system enables rich media output in Jupyter notebooks and IPython terminals.
3

4
## Capabilities
5

6
### Core Display Functions
7

8
Primary functions for displaying objects and managing display output.
9

10
```python { .api }
11
def display(*objs, include=None, exclude=None, metadata=None, transient=None, display_id=None, **kwargs):
12
    """
13
    Display objects with rich formatting.
14
    
15
    Parameters:
16
    - *objs: objects to display
17
    - include: list, optional - MIME types to include
18
    - exclude: list, optional - MIME types to exclude  
19
    - metadata: dict, optional - Metadata for display
20
    - transient: dict, optional - Transient display data
21
    - display_id: str, optional - Unique ID for updating display
22
    - **kwargs: additional display arguments
23
    
24
    Returns:
25
    DisplayHandle or None
26
    """
27

28
def clear_output(wait=False):
29
    """
30
    Clear the output area.
31
    
32
    Parameters:
33
    - wait: bool - If True, wait until next output before clearing
34
    """
35

36
def update_display(obj, *, display_id, **kwargs):
37
    """
38
    Update an existing display.
39
    
40
    Parameters:
41
    - obj: object to display
42
    - display_id: str - ID of display to update
43
    - **kwargs: additional display arguments
44
    """
45

46
class DisplayHandle:
47
    """
48
    Handle for display updates.
49
    
50
    Returned by display() when display_id is provided,
51
    allows updating the display content.
52
    """
53
    
54
    def __init__(self, display_id=None):
55
        """Initialize display handle with optional ID."""
56
    
57
    def display(self, obj, **kwargs):
58
        """Display object using this handle."""
59
        
60
    def update(self, obj, **kwargs):
61
        """Update display using this handle."""
62

63
def publish_display_data(data, metadata=None, source=None, *, transient=None, **kwargs):
64
    """
65
    Publish display data for consumption by frontends.
66
    
67
    Parameters:
68
    - data: dict - Display data keyed by MIME type
69
    - metadata: dict, optional - Metadata for display
70
    - source: str, optional - Source of the display
71
    - transient: dict, optional - Transient display data
72
    """
73
```
74

75
Usage example:
76

77
```python
78
from IPython.display import display, clear_output, HTML, Image
79
import time
80

81
# Display various objects
82
display("Hello World")
83
display(HTML("<h1>HTML Content</h1>"))
84
display(Image("path/to/image.png"))
85

86
# Display with ID for later updates
87
display("Initial content", display_id="my_display")
88
time.sleep(1)
89
update_display("Updated content", display_id="my_display")
90

91
# Clear output
92
clear_output(wait=True)
93
display("New content after clear")
94
```
95

96
### Display Object Classes
97

98
Rich display objects for different media types and formats.
99

100
```python { .api }
101
class DisplayObject:
102
    """
103
    Base class for rich display objects.
104
    
105
    All display objects inherit from this class and can be displayed
106
    using the display() function or by being the last expression in a cell.
107
    """
108
    
109
    def __init__(self, data=None, url=None, filename=None, metadata=None):
110
        """
111
        Initialize display object.
112
        
113
        Parameters:
114
        - data: raw data for the object  
115
        - url: URL to fetch data from
116
        - filename: local filename to read data from
117
        - metadata: dict of metadata
118
        """
119

120
class HTML(DisplayObject):
121
    """HTML display object for rendering HTML content."""
122
    
123
    def __init__(self, data=None, url=None, filename=None, metadata=None):
124
        """Create HTML display object."""
125

126
class Markdown(DisplayObject):
127
    """Markdown display object for rendering Markdown content."""
128
    
129
    def __init__(self, data=None, url=None, filename=None, metadata=None):
130
        """Create Markdown display object."""
131

132
class Image(DisplayObject):
133
    """Image display object for displaying images."""
134
    
135
    def __init__(self, data=None, url=None, filename=None, format=None, 
136
                 embed=None, width=None, height=None, retina=False, 
137
                 unconfined=False, metadata=None):
138
        """
139
        Create image display object.
140
        
141
        Parameters:
142
        - format: str - Image format ('png', 'jpeg', 'svg', etc.)
143
        - embed: bool - Whether to embed image data
144
        - width: int - Display width in pixels
145
        - height: int - Display height in pixels  
146
        - retina: bool - Whether image is high-DPI
147
        - unconfined: bool - Whether to remove size constraints
148
        """
149

150
class Video(DisplayObject):
151
    """Video display object for displaying videos."""
152
    
153
    def __init__(self, data=None, url=None, filename=None, embed=False,
154
                 mimetype=None, width=None, height=None, html_attributes="controls"):
155
        """
156
        Create video display object.
157
        
158
        Parameters:
159
        - embed: bool - Whether to embed video data
160
        - mimetype: str - Video MIME type
161
        - html_attributes: str - HTML attributes for video element
162
        """
163

164
class Audio(DisplayObject):
165
    """Audio display object for displaying audio files."""
166
    
167
    def __init__(self, data=None, url=None, filename=None, rate=None,
168
                 autoplay=False, normalize=True, **kwargs):
169
        """
170
        Create audio display object.
171
        
172
        Parameters:
173
        - rate: int - Sample rate in Hz
174
        - autoplay: bool - Whether to autoplay
175
        - normalize: bool - Whether to normalize audio
176
        """
177
```
178

179
### Text and Code Display Objects
180

181
Specialized display objects for text-based content.
182

183
```python { .api }
184
class Pretty(DisplayObject):
185
    """Pretty-printed text display object."""
186
    
187
    def __init__(self, data, url=None, filename=None, metadata=None):
188
        """Create pretty-printed display object."""
189

190
class Code(DisplayObject):
191
    """Code display object with syntax highlighting."""
192
    
193
    def __init__(self, data=None, url=None, filename=None, language=''):
194
        """
195
        Create code display object.
196
        
197
        Parameters:
198
        - language: str - Programming language for syntax highlighting
199
        """
200

201
class JSON(DisplayObject):
202
    """JSON display object with interactive tree view."""
203
    
204
    def __init__(self, data=None, url=None, filename=None, expanded=False, 
205
                 metadata=None, root='root', **kwargs):
206
        """
207
        Create JSON display object.
208
        
209
        Parameters:
210
        - expanded: bool - Whether to expand tree by default
211
        - root: str - Root node name
212
        """
213

214
class Latex(DisplayObject):
215
    """LaTeX display object for mathematical expressions."""
216
    
217
    def __init__(self, data=None, url=None, filename=None, metadata=None):
218
        """Create LaTeX display object."""
219

220
class SVG(DisplayObject):
221
    """SVG display object for vector graphics."""
222
    
223
    def __init__(self, data=None, url=None, filename=None, metadata=None):
224
        """Create SVG display object."""
225

226
class Math(DisplayObject):
227
    """Math display object for mathematical expressions (alias for Latex)."""
228
    
229
    def __init__(self, data=None, url=None, filename=None, metadata=None):
230
        """Create Math display object."""
231

232
class Javascript(DisplayObject):
233
    """JavaScript display object for executing JavaScript code."""
234
    
235
    def __init__(self, data=None, url=None, filename=None, metadata=None, lib=None, css=None):
236
        """
237
        Create JavaScript display object.
238
        
239
        Parameters:
240
        - lib: list - JavaScript libraries to include
241
        - css: list - CSS stylesheets to include
242
        """
243

244
class GeoJSON(DisplayObject):
245
    """GeoJSON display object for geographic data visualization."""
246
    
247
    def __init__(self, data=None, url_template=None, layer_options=None, 
248
                 hovertext='', metadata=None, **kwargs):
249
        """
250
        Create GeoJSON display object.
251
        
252
        Parameters:
253
        - url_template: str - URL template for tile layers
254
        - layer_options: dict - Options for map layers
255
        - hovertext: str - Text to show on hover
256
        """
257

258
class ProgressBar(DisplayObject):
259
    """Progress bar display object for showing task progress."""
260
    
261
    def __init__(self, total, **kwargs):
262
        """
263
        Create progress bar display object.
264
        
265
        Parameters:
266
        - total: int - Total number of items to process
267
        """
268
```
269

270
### Web and Interactive Display Objects
271

272
Display objects for web content and interactive elements.
273

274
```python { .api }
275
class IFrame(DisplayObject):
276
    """IFrame display object for embedding web content."""
277
    
278
    def __init__(self, src, width=400, height=300, **kwargs):
279
        """
280
        Create IFrame display object.
281
        
282
        Parameters:
283
        - src: str - URL of content to embed
284
        - width: int - Frame width in pixels
285
        - height: int - Frame height in pixels
286
        """
287

288
class YouTubeVideo(DisplayObject):
289
    """YouTube video display object."""
290
    
291
    def __init__(self, id, width=400, height=300, **kwargs):
292
        """
293
        Create YouTube video display object.
294
        
295
        Parameters:
296
        - id: str - YouTube video ID
297
        """
298

299
class VimeoVideo(DisplayObject):
300
    """Vimeo video display object."""
301
    
302
    def __init__(self, id, width=400, height=300, **kwargs):
303
        """
304
        Create Vimeo video display object.
305
        
306
        Parameters:
307
        - id: str - Vimeo video ID
308
        """
309

310
class FileLink(DisplayObject):
311
    """File link display object for downloadable files."""
312
    
313
    def __init__(self, path, url_prefix='', result_html_prefix='', 
314
                 result_html_suffix='<br>'):
315
        """
316
        Create file link display object.
317
        
318
        Parameters:
319
        - path: str - Path to file
320
        - url_prefix: str - URL prefix for links  
321
        - result_html_prefix: str - HTML before link
322
        - result_html_suffix: str - HTML after link
323
        """
324

325
class FileLinks(DisplayObject):
326
    """Multiple file links display object."""
327
    
328
    def __init__(self, path, included_suffixes=None, **kwargs):
329
        """
330
        Create multiple file links display object.
331
        
332
        Parameters:
333
        - path: str - Directory path
334
        - included_suffixes: list - File extensions to include
335
        """
336
```
337

338
### Display Formatting Functions
339

340
Functions for specific MIME type formatting.
341

342
```python { .api }
343
def display_pretty(obj, raw=False, metadata=None):
344
    """Display pretty-printed representation of object."""
345

346
def display_html(obj, raw=False, metadata=None):
347
    """Display HTML representation of object."""
348

349
def display_markdown(obj, raw=False, metadata=None):
350
    """Display Markdown representation of object."""
351

352
def display_svg(obj, raw=False, metadata=None):
353
    """Display SVG representation of object."""
354

355
def display_png(obj, raw=False, metadata=None):
356
    """Display PNG representation of object."""
357

358
def display_jpeg(obj, raw=False, metadata=None):
359
    """Display JPEG representation of object."""
360

361
def display_latex(obj, raw=False, metadata=None):
362
    """Display LaTeX representation of object."""
363

364
def display_json(obj, raw=False, metadata=None):
365
    """Display JSON representation of object."""
366

367
def display_javascript(obj, raw=False, metadata=None):
368
    """Display JavaScript representation of object."""
369

370
def display_webp(obj, raw=False, metadata=None):
371
    """Display WebP representation of object."""
372

373
def display_pdf(obj, raw=False, metadata=None):
374
    """Display PDF representation of object."""
375
```
376

377
Usage example:
378

379
```python
380
from IPython.display import *
381

382
# Display various media types
383
display(HTML("<h2>HTML Content</h2>"))
384
display(Markdown("## Markdown Content"))
385
display(Image("image.png", width=300))
386
display(Video("video.mp4", width=500, height=300))
387

388
# Display code with syntax highlighting  
389
display(Code("""
390
def hello(name):
391
    print(f"Hello {name}!")
392
""", language='python'))
393

394
# Display interactive JSON
395
data = {"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}
396
display(JSON(data, expanded=True))
397

398
# Display LaTeX math
399
display(Latex(r"$\int_0^1 x^2 dx = \frac{1}{3}$"))
400

401
# Embed web content
402
display(YouTubeVideo("dQw4w9WgXcQ"))
403
display(IFrame("https://example.com", width=600, height=400))
404
```
405

406
## Types
407

408
```python { .api }
409
class DisplayHandle:
410
    """
411
    Handle for display updates.
412
    
413
    Returned by display() when display_id is provided,
414
    allows updating the display content.
415
    """
416
    
417
    def __init__(self, display_id=None):
418
        """Initialize display handle with optional ID."""
419
    
420
    def display(self, obj, **kwargs):
421
        """Display object using this handle."""
422
        
423
    def update(self, obj, **kwargs):
424
        """Update display using this handle."""
425

426
class DisplayPublisher:
427
    """
428
    Publisher for display data.
429
    
430
    Manages publication of display data to frontends
431
    and handles display ID tracking.
432
    """
433
    
434
    def publish(self, data, metadata=None, source=None, **kwargs):
435
        """Publish display data."""
436
```