tessl/pypi-plotly

An open-source interactive data visualization library for Python

—

Pending

Overview

Eval results

Files

Input/Output Operations

Name: tessl/pypi-plotly
Author: tessl

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.

Capabilities

Display Functions

Functions for rendering and displaying figures in different environments.

def show(fig, renderer=None, validate=True, **kwargs):
    """
    Display a plotly figure.
    
    Parameters:
    - fig: Figure, plotly figure object to display
    - renderer: str, rendering backend ('browser', 'notebook', 'colab', 'kaggle', 'azure', 'databricks', 'json', 'png', 'jpeg', 'jpg', 'svg', 'pdf')
    - validate: bool, whether to validate figure before display
    - config: dict, plotly.js configuration options
    - engine: str, image export engine ('kaleido', 'orca') for static renderers
    - width: int, image width for static renderers
    - height: int, image height for static renderers
    - scale: float, image scale factor for static renderers
    
    Returns:
    None: Displays figure in specified renderer
    """

HTML Export Functions

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

def write_html(fig, file, config=None, auto_play=True, include_plotlyjs=True, 
               auto_open=False, validate=True, pretty=False, div_id=None, 
               default_width='100%', default_height='100%', **kwargs):
    """
    Write a figure to HTML file or string.
    
    Parameters:
    - fig: Figure, plotly figure object to export
    - file: str or file-like, output file path or file object
    - config: dict, plotly.js configuration options
    - auto_play: bool, whether to auto-play animations
    - include_plotlyjs: bool or str, how to include plotly.js library
        - True: include inline
        - 'cdn': link to CDN
        - 'inline': include inline
        - 'require': use require.js
        - str: path to custom plotly.js file
    - auto_open: bool, whether to open file in browser after creation
    - validate: bool, whether to validate figure before export
    - pretty: bool, whether to format HTML nicely
    - div_id: str, HTML div ID for the plot
    - default_width: str, default plot width
    - default_height: str, default plot height
    
    Returns:
    str: HTML string if file is None, else None
    """

def to_html(fig, config=None, auto_play=True, include_plotlyjs=True, 
            div_id=None, default_width='100%', default_height='100%', 
            validate=True, **kwargs):
    """
    Convert figure to HTML string.
    
    Parameters: Same as write_html except no file parameter
    
    Returns:
    str: HTML representation of the figure
    """

Static Image Export Functions

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

def write_image(fig, file, format=None, width=None, height=None, scale=None, 
                validate=True, engine='auto', **kwargs):
    """
    Write a figure to static image file.
    
    Parameters:
    - fig: Figure, plotly figure object to export
    - file: str or file-like, output file path or file object
    - format: str, image format ('png', 'jpg', 'jpeg', 'webp', 'svg', 'pdf', 'eps')
    - width: int, image width in pixels (default: 700)
    - height: int, image height in pixels (default: 500)
    - scale: float, image scale factor (default: 1)
    - validate: bool, whether to validate figure before export
    - engine: str, export engine ('kaleido', 'orca', 'auto')
    
    Kaleido-specific parameters:
    - timeout: float, timeout in seconds for image generation
    - scope: str, kaleido scope ('plotly', 'mathjax')
    
    Returns:
    None: Writes image to specified file
    """

def to_image(fig, format='png', width=None, height=None, scale=None, 
             validate=True, engine='auto', **kwargs):
    """
    Convert figure to static image bytes.
    
    Parameters: Same as write_image except no file parameter
    
    Returns:
    bytes: Image data in specified format
    """

JSON Export/Import Functions

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

def write_json(fig, file, validate=True, pretty=False, remove_uids=True, 
               engine=None, **kwargs):
    """
    Write figure to JSON file.
    
    Parameters:
    - fig: Figure, plotly figure object to export
    - file: str or file-like, output file path or file object
    - validate: bool, whether to validate figure before export
    - pretty: bool, whether to format JSON with indentation
    - remove_uids: bool, whether to remove trace UIDs from JSON
    - engine: str, JSON engine (reserved for future use)
    
    Returns:
    None: Writes JSON to specified file
    """

def to_json(fig, validate=True, pretty=False, remove_uids=True, engine=None, 
            **kwargs):
    """
    Convert figure to JSON string.
    
    Parameters: Same as write_json except no file parameter
    
    Returns:
    str: JSON representation of the figure
    """

def read_json(file, output_type='Figure', skip_invalid=True, engine=None):
    """
    Read figure from JSON file.
    
    Parameters:
    - file: str or file-like, input file path or file object
    - output_type: str, output type ('Figure', 'FigureWidget')
    - skip_invalid: bool, whether to skip invalid properties
    - engine: str, JSON engine (reserved for future use)
    
    Returns:
    Figure or FigureWidget: Reconstructed figure object
    """

def from_json(json_str, output_type='Figure', skip_invalid=True, engine=None):
    """
    Create figure from JSON string.
    
    Parameters:
    - json_str: str, JSON string representation of figure
    - output_type: str, output type ('Figure', 'FigureWidget')
    - skip_invalid: bool, whether to skip invalid properties
    - engine: str, JSON engine (reserved for future use)
    
    Returns:
    Figure or FigureWidget: Reconstructed figure object
    """

Renderer Configuration

System for configuring and managing output renderers.

# Renderer configuration object
renderers = RendererRegistry()

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

def renderers.list():
    """
    List all available renderers.
    
    Returns:
    list of str: Available renderer names
    """

def renderers.activate(name):
    """
    Activate a renderer by name.
    
    Parameters:
    - name: str, renderer name to activate
    """

def renderers.deactivate(name):
    """
    Deactivate a renderer by name.
    
    Parameters:
    - name: str, renderer name to deactivate
    """

def renderers.set_default(name):
    """
    Set default renderer.
    
    Parameters:
    - name: str, renderer name to set as default
    """

# Built-in renderer names:
# - 'browser': Open in web browser
# - 'notebook': Jupyter notebook inline display  
# - 'colab': Google Colab inline display
# - 'kaggle': Kaggle notebook inline display
# - 'azure': Azure notebook inline display
# - 'databricks': Databricks notebook inline display
# - 'json': JSON representation
# - 'png': PNG static image
# - 'jpeg'/'jpg': JPEG static image
# - 'svg': SVG vector image
# - 'pdf': PDF document

Template System

Theme and styling template management for consistent figure appearance.

# Template repository object
templates = TemplateRepository()

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

def templates.list():
    """
    List all available templates.
    
    Returns:
    list of str: Available template names
    """

def templates.__getitem__(name):
    """
    Get template by name.
    
    Parameters:
    - name: str, template name
    
    Returns:
    dict: Template configuration
    """

def templates.__setitem__(name, template):
    """
    Set custom template.
    
    Parameters:
    - name: str, template name
    - template: dict, template configuration
    """

# Built-in template names:
# - 'plotly': Default plotly template
# - 'plotly_white': White background variant
# - 'plotly_dark': Dark theme
# - 'ggplot2': ggplot2-inspired theme
# - 'seaborn': Seaborn-inspired theme
# - 'simple_white': Minimal white theme
# - 'none': No styling template

Kaleido Engine Configuration

Static image export engine configuration and settings.

# Kaleido configuration object
kaleido = KaleidoConfig()

# Configuration properties
kaleido.scope.plotly.default_format: str  # Default image format
kaleido.scope.plotly.default_width: int   # Default image width
kaleido.scope.plotly.default_height: int  # Default image height
kaleido.scope.plotly.default_scale: float # Default scale factor

def kaleido.scope.plotly.to_image(fig, format='png', width=None, height=None, 
                                  scale=None, **kwargs):
    """
    Convert figure to image using Kaleido.
    
    Parameters:
    - fig: dict, figure specification
    - format: str, output format
    - width: int, image width in pixels
    - height: int, image height in pixels  
    - scale: float, scale factor
    
    Returns:
    bytes: Image data
    """

Usage Examples

import plotly.io as pio
import plotly.express as px
import plotly.graph_objects as go

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

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

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

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

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

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

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

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

# List available renderers and templates
print(pio.renderers.list())
print(pio.templates.list())

# Apply template
fig.update_layout(template='plotly_dark')

# Set default template
pio.templates.default = 'seaborn'

# Custom template
custom_template = dict(
    layout=dict(
        font=dict(family="Arial", size=12),
        colorway=['#1f77b4', '#ff7f0e', '#2ca02c'],
        paper_bgcolor='white',
        plot_bgcolor='#f8f9fa'
    )
)
pio.templates['custom'] = custom_template

# Configuration examples
config = {
    'displayModeBar': True,
    'displaylogo': False,
    'modeBarButtonsToRemove': ['pan2d', 'lasso2d']
}

pio.show(fig, config=config)
pio.write_html(fig, 'configured_plot.html', config=config)

Install with Tessl CLI