0
# Input/Output Operations
1

2
Export and import functionality supporting multiple formats including HTML, static images, and JSON serialization. The I/O module provides comprehensive file handling capabilities with support for various renderers and backends.
3

4
## Capabilities
5

6
### Display Functions
7

8
Functions for rendering and displaying figures in different environments.
9

10
```python { .api }
11
def show(fig, renderer=None, validate=True, **kwargs):
12
    """
13
    Display a plotly figure.
14
    
15
    Parameters:
16
    - fig: Figure, plotly figure object to display
17
    - renderer: str, rendering backend ('browser', 'notebook', 'colab', 'kaggle', 'azure', 'databricks', 'json', 'png', 'jpeg', 'jpg', 'svg', 'pdf')
18
    - validate: bool, whether to validate figure before display
19
    - config: dict, plotly.js configuration options
20
    - engine: str, image export engine ('kaleido', 'orca') for static renderers
21
    - width: int, image width for static renderers
22
    - height: int, image height for static renderers
23
    - scale: float, image scale factor for static renderers
24
    
25
    Returns:
26
    None: Displays figure in specified renderer
27
    """
28
```
29

30
### HTML Export Functions
31

32
Functions for converting figures to HTML format for web embedding and standalone files.
33

34
```python { .api }
35
def write_html(fig, file, config=None, auto_play=True, include_plotlyjs=True, 
36
               auto_open=False, validate=True, pretty=False, div_id=None, 
37
               default_width='100%', default_height='100%', **kwargs):
38
    """
39
    Write a figure to HTML file or string.
40
    
41
    Parameters:
42
    - fig: Figure, plotly figure object to export
43
    - file: str or file-like, output file path or file object
44
    - config: dict, plotly.js configuration options
45
    - auto_play: bool, whether to auto-play animations
46
    - include_plotlyjs: bool or str, how to include plotly.js library
47
        - True: include inline
48
        - 'cdn': link to CDN
49
        - 'inline': include inline
50
        - 'require': use require.js
51
        - str: path to custom plotly.js file
52
    - auto_open: bool, whether to open file in browser after creation
53
    - validate: bool, whether to validate figure before export
54
    - pretty: bool, whether to format HTML nicely
55
    - div_id: str, HTML div ID for the plot
56
    - default_width: str, default plot width
57
    - default_height: str, default plot height
58
    
59
    Returns:
60
    str: HTML string if file is None, else None
61
    """
62

63
def to_html(fig, config=None, auto_play=True, include_plotlyjs=True, 
64
            div_id=None, default_width='100%', default_height='100%', 
65
            validate=True, **kwargs):
66
    """
67
    Convert figure to HTML string.
68
    
69
    Parameters: Same as write_html except no file parameter
70
    
71
    Returns:
72
    str: HTML representation of the figure
73
    """
74
```
75

76
### Static Image Export Functions
77

78
Functions for exporting figures to static image formats using Kaleido or Orca engines.
79

80
```python { .api }
81
def write_image(fig, file, format=None, width=None, height=None, scale=None, 
82
                validate=True, engine='auto', **kwargs):
83
    """
84
    Write a figure to static image file.
85
    
86
    Parameters:
87
    - fig: Figure, plotly figure object to export
88
    - file: str or file-like, output file path or file object
89
    - format: str, image format ('png', 'jpg', 'jpeg', 'webp', 'svg', 'pdf', 'eps')
90
    - width: int, image width in pixels (default: 700)
91
    - height: int, image height in pixels (default: 500)
92
    - scale: float, image scale factor (default: 1)
93
    - validate: bool, whether to validate figure before export
94
    - engine: str, export engine ('kaleido', 'orca', 'auto')
95
    
96
    Kaleido-specific parameters:
97
    - timeout: float, timeout in seconds for image generation
98
    - scope: str, kaleido scope ('plotly', 'mathjax')
99
    
100
    Returns:
101
    None: Writes image to specified file
102
    """
103

104
def to_image(fig, format='png', width=None, height=None, scale=None, 
105
             validate=True, engine='auto', **kwargs):
106
    """
107
    Convert figure to static image bytes.
108
    
109
    Parameters: Same as write_image except no file parameter
110
    
111
    Returns:
112
    bytes: Image data in specified format
113
    """
114
```
115

116
### JSON Export/Import Functions
117

118
Functions for serializing figures to JSON format and reading them back.
119

120
```python { .api }
121
def write_json(fig, file, validate=True, pretty=False, remove_uids=True, 
122
               engine=None, **kwargs):
123
    """
124
    Write figure to JSON file.
125
    
126
    Parameters:
127
    - fig: Figure, plotly figure object to export
128
    - file: str or file-like, output file path or file object
129
    - validate: bool, whether to validate figure before export
130
    - pretty: bool, whether to format JSON with indentation
131
    - remove_uids: bool, whether to remove trace UIDs from JSON
132
    - engine: str, JSON engine (reserved for future use)
133
    
134
    Returns:
135
    None: Writes JSON to specified file
136
    """
137

138
def to_json(fig, validate=True, pretty=False, remove_uids=True, engine=None, 
139
            **kwargs):
140
    """
141
    Convert figure to JSON string.
142
    
143
    Parameters: Same as write_json except no file parameter
144
    
145
    Returns:
146
    str: JSON representation of the figure
147
    """
148

149
def read_json(file, output_type='Figure', skip_invalid=True, engine=None):
150
    """
151
    Read figure from JSON file.
152
    
153
    Parameters:
154
    - file: str or file-like, input file path or file object
155
    - output_type: str, output type ('Figure', 'FigureWidget')
156
    - skip_invalid: bool, whether to skip invalid properties
157
    - engine: str, JSON engine (reserved for future use)
158
    
159
    Returns:
160
    Figure or FigureWidget: Reconstructed figure object
161
    """
162

163
def from_json(json_str, output_type='Figure', skip_invalid=True, engine=None):
164
    """
165
    Create figure from JSON string.
166
    
167
    Parameters:
168
    - json_str: str, JSON string representation of figure
169
    - output_type: str, output type ('Figure', 'FigureWidget')
170
    - skip_invalid: bool, whether to skip invalid properties
171
    - engine: str, JSON engine (reserved for future use)
172
    
173
    Returns:
174
    Figure or FigureWidget: Reconstructed figure object
175
    """
176
```
177

178
### Renderer Configuration
179

180
System for configuring and managing output renderers.
181

182
```python { .api }
183
# Renderer configuration object
184
renderers = RendererRegistry()
185

186
# Available renderer properties and methods
187
renderers.default: str  # Default renderer name
188
renderers.render_on_display: bool  # Auto-render on figure display
189

190
def renderers.list():
191
    """
192
    List all available renderers.
193
    
194
    Returns:
195
    list of str: Available renderer names
196
    """
197

198
def renderers.activate(name):
199
    """
200
    Activate a renderer by name.
201
    
202
    Parameters:
203
    - name: str, renderer name to activate
204
    """
205

206
def renderers.deactivate(name):
207
    """
208
    Deactivate a renderer by name.
209
    
210
    Parameters:
211
    - name: str, renderer name to deactivate
212
    """
213

214
def renderers.set_default(name):
215
    """
216
    Set default renderer.
217
    
218
    Parameters:
219
    - name: str, renderer name to set as default
220
    """
221

222
# Built-in renderer names:
223
# - 'browser': Open in web browser
224
# - 'notebook': Jupyter notebook inline display  
225
# - 'colab': Google Colab inline display
226
# - 'kaggle': Kaggle notebook inline display
227
# - 'azure': Azure notebook inline display
228
# - 'databricks': Databricks notebook inline display
229
# - 'json': JSON representation
230
# - 'png': PNG static image
231
# - 'jpeg'/'jpg': JPEG static image
232
# - 'svg': SVG vector image
233
# - 'pdf': PDF document
234
```
235

236
### Template System
237

238
Theme and styling template management for consistent figure appearance.
239

240
```python { .api }
241
# Template repository object
242
templates = TemplateRepository()
243

244
# Available template properties and methods
245
templates.default: str  # Default template name
246

247
def templates.list():
248
    """
249
    List all available templates.
250
    
251
    Returns:
252
    list of str: Available template names
253
    """
254

255
def templates.__getitem__(name):
256
    """
257
    Get template by name.
258
    
259
    Parameters:
260
    - name: str, template name
261
    
262
    Returns:
263
    dict: Template configuration
264
    """
265

266
def templates.__setitem__(name, template):
267
    """
268
    Set custom template.
269
    
270
    Parameters:
271
    - name: str, template name
272
    - template: dict, template configuration
273
    """
274

275
# Built-in template names:
276
# - 'plotly': Default plotly template
277
# - 'plotly_white': White background variant
278
# - 'plotly_dark': Dark theme
279
# - 'ggplot2': ggplot2-inspired theme
280
# - 'seaborn': Seaborn-inspired theme
281
# - 'simple_white': Minimal white theme
282
# - 'none': No styling template
283
```
284

285
### Kaleido Engine Configuration
286

287
Static image export engine configuration and settings.
288

289
```python { .api }
290
# Kaleido configuration object
291
kaleido = KaleidoConfig()
292

293
# Configuration properties
294
kaleido.scope.plotly.default_format: str  # Default image format
295
kaleido.scope.plotly.default_width: int   # Default image width
296
kaleido.scope.plotly.default_height: int  # Default image height
297
kaleido.scope.plotly.default_scale: float # Default scale factor
298

299
def kaleido.scope.plotly.to_image(fig, format='png', width=None, height=None, 
300
                                  scale=None, **kwargs):
301
    """
302
    Convert figure to image using Kaleido.
303
    
304
    Parameters:
305
    - fig: dict, figure specification
306
    - format: str, output format
307
    - width: int, image width in pixels
308
    - height: int, image height in pixels  
309
    - scale: float, scale factor
310
    
311
    Returns:
312
    bytes: Image data
313
    """
314
```
315

316
## Usage Examples
317

318
```python
319
import plotly.io as pio
320
import plotly.express as px
321
import plotly.graph_objects as go
322

323
# Create sample figure
324
df = px.data.iris()
325
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species")
326

327
# Display in different renderers
328
pio.show(fig, renderer='browser')  # Open in web browser
329
pio.show(fig, renderer='notebook') # Jupyter notebook inline
330
pio.show(fig, renderer='png')      # PNG image
331

332
# Export to HTML
333
pio.write_html(fig, 'my_plot.html', include_plotlyjs='cdn')
334

335
# Export to static images  
336
pio.write_image(fig, 'my_plot.png', width=800, height=600, scale=2)
337
pio.write_image(fig, 'my_plot.pdf', width=800, height=600)
338
pio.write_image(fig, 'my_plot.svg', width=800, height=600)
339

340
# Convert to bytes for embedding
341
img_bytes = pio.to_image(fig, format='png', width=400, height=300)
342

343
# JSON serialization
344
pio.write_json(fig, 'my_plot.json', pretty=True)
345
json_str = pio.to_json(fig, pretty=True)
346

347
# Read figure back from JSON
348
loaded_fig = pio.read_json('my_plot.json')
349
fig_from_str = pio.from_json(json_str)
350

351
# Configure default renderer
352
pio.renderers.default = 'browser'
353
fig.show()  # Will use browser renderer
354

355
# List available renderers and templates
356
print(pio.renderers.list())
357
print(pio.templates.list())
358

359
# Apply template
360
fig.update_layout(template='plotly_dark')
361

362
# Set default template
363
pio.templates.default = 'seaborn'
364

365
# Custom template
366
custom_template = dict(
367
    layout=dict(
368
        font=dict(family="Arial", size=12),
369
        colorway=['#1f77b4', '#ff7f0e', '#2ca02c'],
370
        paper_bgcolor='white',
371
        plot_bgcolor='#f8f9fa'
372
    )
373
)
374
pio.templates['custom'] = custom_template
375

376
# Configuration examples
377
config = {
378
    'displayModeBar': True,
379
    'displaylogo': False,
380
    'modeBarButtonsToRemove': ['pan2d', 'lasso2d']
381
}
382

383
pio.show(fig, config=config)
384
pio.write_html(fig, 'configured_plot.html', config=config)
385
```