from .html import spec_to_html def spec_to_mimebundle( spec, format, mode=None, vega_version=None, vegaembed_version=None, vegalite_version=None, engine=None, **kwargs, ): """Convert a vega-lite specification to a mimebundle The mimebundle type is controlled by the ``format`` argument, which can be one of the following ['html', 'json', 'png', 'svg', 'pdf', 'vega', 'vega-lite'] Parameters ---------- spec : dict a dictionary representing a vega-lite plot spec format : string {'html', 'json', 'png', 'svg', 'pdf', 'vega', 'vega-lite'} the file format to be saved. mode : string {'vega-lite'} The rendering mode. vega_version : string The version of vega.js to use vegaembed_version : string The version of vegaembed.js to use vegalite_version : string The version of vegalite.js to use. Only required if mode=='vega-lite' engine: string {'vl-convert', 'altair_saver'} the conversion engine to use for 'png', 'svg', 'pdf', and 'vega' formats **kwargs : Additional arguments will be passed to the generating function Returns ------- output : dict a mime-bundle representing the image Note ---- The png, svg, pdf, and vega outputs require the altair_saver package """ if mode != "vega-lite": raise ValueError("mode must be 'vega-lite'") if format in ["png", "svg", "pdf", "vega"]: return _spec_to_mimebundle_with_engine( spec, format, mode, engine=engine, **kwargs ) if format == "html": html = spec_to_html( spec, mode=mode, vega_version=vega_version, vegaembed_version=vegaembed_version, vegalite_version=vegalite_version, **kwargs, ) return {"text/html": html} if format == "vega-lite": if vegalite_version is None: raise ValueError("Must specify vegalite_version") return {"application/vnd.vegalite.v{}+json".format(vegalite_version[0]): spec} if format == "json": return {"application/json": spec} raise ValueError( "format must be one of " "['html', 'json', 'png', 'svg', 'pdf', 'vega', 'vega-lite']" ) def _spec_to_mimebundle_with_engine(spec, format, mode, **kwargs): """Helper for Vega-Lite to mimebundle conversions that require an engine Parameters ---------- spec : dict a dictionary representing a vega-lite plot spec format : string {'png', 'svg', 'pdf', 'vega'} the format of the mimebundle to be returned mode : string {'vega-lite'} The rendering mode. engine: string {'vl-convert', 'altair_saver'} the conversion engine to use **kwargs : Additional arguments will be passed to the conversion function """ # Normalize the engine string (if any) by lower casing # and removing underscores and hyphens engine = kwargs.pop("engine", None) normalized_engine = _validate_normalize_engine(engine, format) if normalized_engine == "vlconvert": import vl_convert as vlc from ..vegalite import SCHEMA_VERSION # Compute VlConvert's vl_version string (of the form 'v5_2') # from SCHEMA_VERSION (of the form 'v5.2.0') vl_version = "_".join(SCHEMA_VERSION.split(".")[:2]) if format == "vega": vg = vlc.vegalite_to_vega(spec, vl_version=vl_version) return {"application/vnd.vega.v5+json": vg} elif format == "svg": svg = vlc.vegalite_to_svg(spec, vl_version=vl_version) return {"image/svg+xml": svg} elif format == "png": png = vlc.vegalite_to_png( spec, vl_version=vl_version, scale=kwargs.get("scale_factor", 1.0), ) return {"image/png": png} else: # This should be validated above # but raise exception for the sake of future development raise ValueError("Unexpected format {fmt!r}".format(fmt=format)) elif normalized_engine == "altairsaver": import altair_saver return altair_saver.render(spec, format, mode=mode, **kwargs) else: # This should be validated above # but raise exception for the sake of future development raise ValueError( "Unexpected normalized_engine {eng!r}".format(eng=normalized_engine) ) def _validate_normalize_engine(engine, format): """Helper to validate and normalize the user-provided engine engine : {None, 'vl-convert', 'altair_saver'} the user-provided engine string format : string {'png', 'svg', 'pdf', 'vega'} the format of the mimebundle to be returned """ # Try to import vl_convert try: import vl_convert as vlc except ImportError: vlc = None # Try to import altair_saver try: import altair_saver except ImportError: altair_saver = None # Normalize engine string by lower casing and removing underscores and hyphens normalized_engine = ( None if engine is None else engine.lower().replace("-", "").replace("_", "") ) # Validate or infer default value of normalized_engine if normalized_engine == "vlconvert": if vlc is None: raise ValueError( "The 'vl-convert' conversion engine requires the vl-convert-python package" ) if format == "pdf": raise ValueError( "The 'vl-convert' conversion engine does not support the {fmt!r} format.\n" "Use the 'altair_saver' engine instead".format(fmt=format) ) elif normalized_engine == "altairsaver": if altair_saver is None: raise ValueError( "The 'altair_saver' conversion engine requires the altair_saver package" ) elif normalized_engine is None: if vlc is not None and format != "pdf": normalized_engine = "vlconvert" elif altair_saver is not None: normalized_engine = "altairsaver" else: if format == "pdf": raise ValueError( "Saving charts in {fmt!r} format requires the altair_saver package: " "see http://github.com/altair-viz/altair_saver/".format(fmt=format) ) else: raise ValueError( "Saving charts in {fmt!r} format requires the vl-convert-python or altair_saver package: " "see http://github.com/altair-viz/altair_saver/".format(fmt=format) ) else: raise ValueError( "Invalid conversion engine {engine!r}. Expected one of {valid!r}".format( engine=engine, valid=("vl-convert", "altair_saver") ) ) return normalized_engine