Python Sync API Reference#
This page documents the synchronous vl_convert module. For vl_convert.asyncio, see Python Async API Reference.
These entries are generated from the version 2 type stubs. Vega and Vega-Lite specifications may be passed as JSON strings or dictionaries. PNG, JPEG, and PDF functions return bytes. SVG, HTML, and URL functions return str. Scenegraph functions return a dict by default, or MessagePack bytes with format="msgpack".
Start with Quick Start if you are choosing a conversion function for the first time.
Vega-Lite Conversions#
- vl_convert.vegalite_to_png(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- scale: float | None = None,
- ppi: float | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- show_warnings: bool | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega-Lite specification to PNG image data.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.scale – Image scale factor (default 1.0)
ppi – Pixels per inch (default 72)
config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
show_warnings – Deprecated and ignored. Vega-Lite warnings are always forwarded to the
vl_convertlogger.format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
PNG image data.
- vl_convert.vegalite_to_jpeg(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- scale: float | None = None,
- quality: int | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- show_warnings: bool | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega-Lite specification to JPEG image data.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.scale – Image scale factor (default 1.0)
quality – JPEG quality from 0 through 100. The default is 90.
config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
show_warnings – Deprecated and ignored. Vega-Lite warnings are always forwarded to the
vl_convertlogger.format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
JPEG image data.
- vl_convert.vegalite_to_pdf(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- scale: float | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega-Lite specification to a PDF document.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
scale –
Retained only for backward compatibility.
Deprecated since version 2.0.0: This parameter never affected PDF output. Only None and 1.0 are accepted. Other numeric values raise
ValueError.vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
PDF document bytes.
- vl_convert.vegalite_to_svg(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- show_warnings: bool | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- bundle: bool | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega-Lite specification to an SVG string.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
show_warnings – Deprecated and ignored. Vega-Lite warnings are always forwarded to the
vl_convertlogger.format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().bundle – If True, embed fonts and images as self-contained data URIs. If False (default), use
@importreferences for Google Fonts.google_fonts – Google Fonts to register for this conversion.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
SVG image string.
- vl_convert.vegalite_to_html(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- bundle: bool | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- renderer: Renderer | None = None,
- vega_plugin: str | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega-Lite spec to an HTML document, optionally bundling dependencies.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.bundle – If
True, include browser JavaScript dependencies in the document. IfFalse(default), load them from a CDN.google_fonts – Google Fonts to use for this conversion. Each entry is a family name string or a dict with
"family"and optional"variants".config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
renderer – Browser renderer:
"svg"(default),"canvas", or"hybrid".vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
HTML document.
- vl_convert.vegalite_to_scenegraph(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- show_warnings: bool | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- format: Literal[dict, msgpack] = 'dict',
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Compile and evaluate a Vega-Lite specification, then return its scenegraph.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
show_warnings – Deprecated and ignored. Vega-Lite warnings are always forwarded to the
vl_convertlogger.format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
format – Output format: “dict” returns a Python dictionary (default), “msgpack” returns raw MessagePack bytes
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
Scenegraph dictionary for
format="dict", or MessagePack bytes forformat="msgpack".
- vl_convert.vegalite_to_vega(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- show_warnings: bool | None = None,
Compile a Vega-Lite specification to Vega.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
show_warnings – Deprecated and ignored. Vega-Lite warnings are always forwarded to the
vl_convertlogger.
- Returns:
Vega JSON specification dict.
- vl_convert.vegalite_to_url(vl_spec: VlSpec, *, fullscreen: bool | None = None) str#
Convert a Vega-Lite spec to a URL that opens the chart in the Vega editor.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
fullscreen – Whether to open the chart in the editor’s full-screen view.
- Returns:
URL string.
Vega Conversions#
- vl_convert.vega_to_png(
- vg_spec: VlSpec,
- *,
- scale: float | None = None,
- ppi: float | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- config: str | dict[str, Any] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega spec to PNG image data.
- Parameters:
vg_spec – Vega JSON specification string or dict
scale – Image scale factor (default 1.0)
ppi – Pixels per inch (default 72)
format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
config – Vega config object merged with the specification’s config.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
PNG image data.
- vl_convert.vega_to_jpeg(
- vg_spec: VlSpec,
- *,
- scale: float | None = None,
- quality: int | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- config: str | dict[str, Any] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega spec to JPEG image data.
- Parameters:
vg_spec – Vega JSON specification string or dict
scale – Image scale factor (default 1.0)
quality – JPEG quality from 0 through 100. The default is 90.
format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
config – Vega config object merged with the specification’s config.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
JPEG image data.
- vl_convert.vega_to_pdf(
- vg_spec: VlSpec,
- *,
- scale: float | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- config: str | dict[str, Any] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega specification to a PDF document.
- Parameters:
vg_spec – Vega JSON specification string or dict
scale –
Retained only for backward compatibility.
Deprecated since version 2.0.0: This parameter never affected PDF output. Only None and 1.0 are accepted. Other numeric values raise
ValueError.format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
config – Vega config object merged with the specification’s config.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
PDF document bytes.
- vl_convert.vega_to_svg(
- vg_spec: VlSpec,
- *,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- vega_plugin: str | None = None,
- bundle: bool | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- config: str | dict[str, Any] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega spec to an SVG image string.
- Parameters:
vg_spec – Vega JSON specification string or dict
format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().bundle – If True, embed fonts and images as self-contained data URIs. If False (default), use
@importreferences for Google Fonts.google_fonts – Google Fonts to register for this conversion. Each entry is a family-name string or a dict with
"family"(required) and optionally"variants".config – Vega config object merged with the specification’s config.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
SVG image string.
- vl_convert.vega_to_html(
- vg_spec: VlSpec,
- *,
- bundle: bool | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- renderer: Renderer | None = None,
- vega_plugin: str | None = None,
- config: str | dict[str, Any] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Convert a Vega spec to an HTML document, optionally bundling dependencies.
- Parameters:
vg_spec – Vega JSON specification string or dict
bundle – If
True, include browser JavaScript dependencies in the document. IfFalse(default), load them from a CDN.google_fonts – Google Fonts to use for this conversion. Each entry is a family name string or a dict with
"family"and optional"variants".format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
renderer – Browser renderer:
"svg"(default),"canvas", or"hybrid".vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().config – Vega config object merged with the specification’s config.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
HTML document.
- vl_convert.vega_to_scenegraph(
- vg_spec: VlSpec,
- *,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- format: Literal[dict, msgpack] = 'dict',
- vega_plugin: str | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- config: str | dict[str, Any] | None = None,
- background: str | None = None,
- width: float | None = None,
- height: float | None = None,
Evaluate a Vega specification and return its scenegraph.
- Parameters:
vg_spec – Vega JSON specification string or dict
format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
format – Output format: “dict” returns a Python dictionary (default), “msgpack” returns raw MessagePack bytes
vega_plugin – Per-request Vega plugin (inline ESM string or URL). Requires
allow_per_request_plugins=Trueinconfigure().google_fonts – Google Fonts to register for this conversion.
config – Vega config object merged with the specification’s config.
background – Override the spec’s background color.
width – Override the spec’s width.
height – Override the spec’s height.
- Returns:
Scenegraph dictionary for
format="dict", or MessagePack bytes forformat="msgpack".
- vl_convert.vega_to_url(vg_spec: VlSpec, *, fullscreen: bool | None = None) str#
Convert a Vega spec to a URL that opens the chart in the Vega editor.
- Parameters:
vg_spec – Vega JSON specification string or dict
fullscreen – Whether to open the chart in the editor’s full-screen view.
- Returns:
URL string.
SVG Conversions#
- vl_convert.svg_to_png(svg: str, *, scale: float | None = None, ppi: float | None = None) bytes#
Convert an SVG image string to PNG image data.
- Parameters:
svg – SVG image string
scale – Image scale factor (default 1.0)
ppi – Pixels per inch (default 72)
- Returns:
PNG image data.
- vl_convert.svg_to_jpeg(
- svg: str,
- *,
- scale: float | None = None,
- quality: int | None = None,
Convert an SVG image string to JPEG image data.
- Parameters:
svg – SVG image string
scale – Image scale factor (default 1.0)
quality – JPEG quality from 0 through 100. The default is 90.
- Returns:
JPEG image data.
- vl_convert.svg_to_pdf(svg: str, *, scale: float | None = None) bytes#
Convert an SVG image string to PDF document data.
- Parameters:
svg – SVG image string
scale –
Retained only for backward compatibility.
Deprecated since version 2.0.0: This parameter never affected PDF output. Only None and 1.0 are accepted. Other numeric values raise
ValueError.
- Returns:
PDF document data.
JavaScript Bundling#
- vl_convert.javascript_bundle(snippet: str | None = None, *, vl_version: str | None = None) str#
Create a JavaScript bundle containing Vega, Vega-Lite, and Vega Embed.
An optional snippet can refer to Vega Embed as
vegaEmbed, Vega-Lite asvegaLite, Vega asvega, and lodash.debounce aslodashDebounce.The result includes these libraries and their dependencies. It can be used in an HTML
<script>tag without loading another JavaScript file. The default snippet assignsvegaEmbed,vegaLite, andvegato the global window object, making them available to other script tags.- Parameters:
snippet – JavaScript source to bundle. Imports must refer to dependencies already bundled with VlConvert.
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.
- Returns:
JavaScript bundle as a string.
Fonts#
- vl_convert.register_font_directory(font_dir: str) None#
Register a directory of fonts for use in subsequent conversions.
- Parameters:
font_dir – Absolute path to a directory containing font files
- vl_convert.set_font_directories(font_dirs: list[str]) None#
Replace the registered font directories with the given list.
Directories absent from
font_dirsare no longer used for later conversions. Pass an empty list to clear the registered directories.- Parameters:
font_dirs – Absolute paths to directories containing font files
- vl_convert.current_font_directories() list[str]#
Return the currently-registered font directories.
The directory list is shared by every converter in the process. It starts empty and changes only through these functions:
register_font_directory(path): append one path.set_font_directories(paths): replace the full list.
- Returns:
Absolute paths to the registered font directories.
- vl_convert.google_fonts_cache_dir() str | None#
Return the path of the on-disk Google Fonts cache directory.
Resolved once per process from the environment:
VLC_GOOGLE_FONTS_CACHE_DIR=none:None(caching disabled, fonts always fetched fresh).VLC_GOOGLE_FONTS_CACHE_DIR=/some/path: that path.Unset: the OS cache directory joined with
vl-convert/google-fonts(e.g.~/Library/Caches/vl-convert/google-fontson macOS).
The value is fixed for the lifetime of the process. There is no runtime setter.
- Returns:
Absolute path to the Google Fonts cache directory, or
Noneif caching is disabled.
- vl_convert.google_fonts_cache_size_mb() int#
Return the active capacity of the on-disk Google Fonts cache.
The capacity is shared by every converter in the process. It starts at 512 MB and changes when
set_google_fonts_cache_size_mb()is called.- Returns:
Active capacity in megabytes. The value is always positive.
- vl_convert.set_google_fonts_cache_size_mb(max_size_mb: int | None) None#
Set the capacity of the on-disk Google Fonts cache.
Nonerestores the default capacity of 512 MB. Cached fonts over the new limit are evicted immediately. The setting affects every converter in the process.- Parameters:
max_size_mb – New capacity in megabytes. Use
Nonefor the default. Positive integers are accepted. Passing0raisesValueError.
- vl_convert.vegalite_fonts(
- vl_spec: VlSpec,
- *,
- vl_version: str | None = None,
- config: dict[str, Any] | None = None,
- theme: VegaThemes | None = None,
- auto_google_fonts: bool | None = None,
- include_font_face: bool = False,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- subset_fonts: bool | None = None,
Return structured font metadata for a rendered Vega-Lite spec.
- Parameters:
vl_spec – Vega-Lite JSON specification string or dict
vl_version – Bundled Vega-Lite version, such as
"6.4". The default is the newest version bundled with this release.config – Chart configuration object to apply during conversion
theme – Named theme (e.g. “dark”) to apply during conversion
auto_google_fonts – Override auto-download from Google Fonts (default: use converter config)
include_font_face – Whether to populate each variant’s
font_facefield with CSS that embeds the font (default False)google_fonts – Google Fonts to use for this conversion. Each entry is a family name string or a dict with
"family"and optional"variants".format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
subset_fonts – Override font subsetting for this call. None uses the converter configuration. Applies to Google Fonts URLs and embedded font CSS.
- Returns:
Structured metadata for each font that VlConvert resolves for the chart.
- vl_convert.vega_fonts(
- vg_spec: VlSpec,
- *,
- auto_google_fonts: bool | None = None,
- include_font_face: bool = False,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- format_locale: FormatLocale | None = None,
- time_format_locale: TimeFormatLocale | None = None,
- subset_fonts: bool | None = None,
Return structured font metadata for a rendered Vega spec.
- Parameters:
vg_spec – Vega JSON specification string or dict
auto_google_fonts – Override auto-download from Google Fonts (default: use converter config)
include_font_face – Whether to populate each variant’s
font_facefield with CSS that embeds the font (default False)google_fonts – Google Fonts to use for this conversion. Each entry is a family name string or a dict with
"family"and optional"variants".format_locale – d3-format locale name or dictionary
time_format_locale – d3-time-format locale name or dictionary
subset_fonts – Override font subsetting for this call. None uses the converter configuration. Applies to Google Fonts URLs and embedded font CSS.
- Returns:
Structured metadata for each font that VlConvert resolves for the chart.
Configuration#
- vl_convert.configure(
- *,
- num_workers: int | None = None,
- base_url: str | bool | None = None,
- allowed_base_urls: list[str] | None = None,
- auto_google_fonts: bool | None = None,
- embed_local_fonts: bool | None = None,
- subset_fonts: bool | None = None,
- missing_fonts: Literal[fallback, warn, error] | None = None,
- google_fonts: list[str | GoogleFontSpec] | None = None,
- google_font_variant_threshold: int | None = None,
- max_v8_heap_size_mb: int | None = None,
- max_v8_execution_time_secs: int | None = None,
- gc_after_conversion: bool | None = None,
- vega_plugins: list[str] | None = None,
- plugin_import_domains: list[str] | None = None,
- allow_per_request_plugins: bool | None = None,
- max_ephemeral_workers: int | None = None,
- allow_google_fonts: bool | None = None,
- per_request_plugin_import_domains: list[str] | None = None,
- default_theme: str | None = None,
- default_format_locale: str | dict[str, Any] | None = None,
- default_time_format_locale: str | dict[str, Any] | None = None,
- themes: dict[str, dict[str, Any]] | None = None,
Configure defaults and resource policies for subsequent conversions.
- Parameters:
num_workers – Worker count (must be >= 1).
Noneresets to the built-in default (1). Passing0raisesValueError.base_url – Base URL for resolving relative data and image paths in Vega specs.
NoneorTrueresets to the default (vega-datasets CDN).Falsedisables relative path resolution. A string sets a custom base URL or filesystem path.allowed_base_urls – CSP-style allowlist for data and image access (HTTP URLs, filesystem paths). Examples:
"https:"(scheme),"https://example.com/"(prefix),"/data/"(filesystem),"*"(everything).Noneresets to the default (["http:", "https:"]).[]blocks all absolute data and image locations.auto_google_fonts – Automatically download missing fonts from Google Fonts.
Noneresets to the built-in default (False).embed_local_fonts – Embed locally available fonts as base64-encoded data URIs in SVG and HTML output. PNG and JPEG contain rendered pixels, and PDF output is self-contained.
Noneresets to the default (False).subset_fonts – Subset fonts to only the characters used in the chart. Applies to SVG and HTML output.
Noneresets to the built-in default (True).missing_fonts – Missing-font behavior:
"fallback"(silent),"warn", or"error".Noneresets to the built-in default ("fallback").google_fonts –
Google Fonts to register for all subsequent conversions. Each entry is a family-name string or a dict with
"family"(required) and optionally"variants"(list of(weight, style)tuples). Fonts are downloaded and registered on each conversion call.Replace semantics. Each call to
configure(google_fonts=[...])replaces the full configured list.None(or[]) resets to the built-in default (empty list).google_font_variant_threshold – Once the number of resolved Google Font variants reaches this threshold, the next font request fails the conversion. Configured, per-call, and automatically discovered families all count. A single request can take the total above the threshold. Must be >= 1 if provided.
Noneresets to the built-in default (no cap). Passing0raisesValueError.max_v8_heap_size_mb – Maximum JavaScript (V8) heap size per worker in megabytes. Must be at least 64 if provided, the smallest heap V8 accepts.
Noneresets to the built-in default (no cap). Passing0raisesValueError, and values below 64 raiseValueErrorwhen the converter is built.max_v8_execution_time_secs – Maximum JavaScript (V8) execution time in seconds. Must be >= 1 if provided. When exceeded, JavaScript execution stops and the conversion returns an error.
Noneresets to the built-in default (no cap). Passing0raisesValueError.gc_after_conversion – Whether to run JavaScript garbage collection after each conversion. This can reduce retained heap but adds work.
Noneresets to the default (False).vega_plugins – List of Vega plugins to load. Each entry is a file path (
.js/.mjs), URL (https://...), or inline ESM string. Plugins must be single-entry ESM modules with a default export function accepting avegaobject. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports.None(or[]) resets to the built-in default (empty list).plugin_import_domains – Domain patterns allowed for HTTP imports inside config-level plugins. Use
["*"]for any domain, or["esm.sh", "*.jsdelivr.net"].None(or[]) resets to the built-in default, an empty list that disables HTTP imports.allow_per_request_plugins – Whether to accept per-request plugins via the
vega_pluginparameter on conversion functions.Noneresets to the built-in default (False).max_ephemeral_workers – Maximum temporary JavaScript workers for concurrent per-request plugins. Must be >= 1 if provided.
Noneresets to the default (2). Passing0raisesValueError.allow_google_fonts – Server policy for accepting
google_fontsin HTTP request bodies. It does not restrict direct Python calls.Noneresets to the default (False).per_request_plugin_import_domains – Domain patterns allowed for HTTP imports inside per-request plugins. Separate from
plugin_import_domains.None(or[]) resets to the built-in default, an empty list that disables HTTP imports.default_theme – Default named theme (e.g.
"dark") applied to all Vega-Lite conversions. Per-requestthemeoverrides this if set.Noneresets to the built-in default (no theme).default_format_locale – Default d3-format locale name or dictionary applied to all conversions. Per-request
format_localeoverrides this if set.Noneresets to the built-in default (no locale).default_time_format_locale – Default d3-time-format locale name or dictionary applied to all conversions. Per-request
time_format_localeoverrides this if set.Noneresets to the built-in default (no locale).themes – Custom named themes mapping names to Vega config objects. Registered alongside built-in vega-themes. Custom themes take priority over built-in themes if names collide.
None(or{}) resets to the built-in default (empty map).
- vl_convert.load_config(path: str | None = None) None#
Load converter configuration from a JSONC file, replacing the active config.
Unlike
configure(), which patches individual fields,load_config()resets all settings to their defaults and then applies the file. Callconfigure()afterload_config()to override specific fields in code.- Parameters:
path – Path to the JSONC config file. When omitted, loads from the standard location returned by
get_config_path(). If that file does not exist, resets to built-in defaults.- Raises:
ValueError – If
pathis provided but the file cannot be read or parsed.
- vl_convert.get_config_path() str#
Return the platform-standard path for the vl-convert JSONC config file.
This is the path
load_config()reads when called without arguments, and the same path printed byvl-convert config-pathon the CLI. The file may not exist.- Returns:
Absolute path to the standard JSONC config file.
- vl_convert.get_config() ConverterConfig#
Return the active converter configuration.
- Returns:
Converter configuration dictionary.
Worker Diagnostics#
- vl_convert.warm_up_workers() None#
Start converter workers before the first conversion.
Use this during application startup when first-request latency matters.
- vl_convert.get_worker_memory_usage() list[WorkerMemoryUsage]#
Return JavaScript heap statistics for each conversion worker.
- Returns:
List of dicts with
worker_index,used_heap_size,total_heap_size,heap_size_limit, andexternal_memory(all sizes in bytes).
Locales and Themes#
- vl_convert.get_format_locale(name: FormatLocaleName) dict[str, Any]#
Return the d3-format locale dictionary for a built-in locale.
See d3/d3-format for available names.
- Parameters:
name – d3-format locale name, such as
"it-IT".- Returns:
d3-format locale dictionary.
- vl_convert.get_time_format_locale(name: TimeFormatLocaleName) dict[str, Any]#
Return the d3-time-format locale dictionary for a built-in locale.
See d3/d3-time-format for available names.
- Parameters:
name – d3-time-format locale name, such as
"it-IT".- Returns:
d3-time-format locale dictionary.
- vl_convert.get_themes() dict[VegaThemes, dict[str, Any]]#
Return the Vega config dictionary for each built-in theme.
- Returns:
Dictionary from theme name to config object.
- vl_convert.get_local_tz() str | None#
Return the local timezone name that Vega uses for time calculations.
- Returns:
Named local timezone (e.g. “America/New_York”), or None if the local timezone cannot be determined.
Bundled JavaScript Versions#
- vl_convert.get_vega_version() str#
Get the bundled version of Vega
- Returns:
Vega version string (e.g. “5.30.0”)
- vl_convert.get_vega_themes_version() str#
Get the bundled version of Vega-Themes
- Returns:
Vega-Themes version string (e.g. “2.14.0”)
- vl_convert.get_vega_embed_version() str#
Get the bundled version of Vega-Embed
- Returns:
Vega-Embed version string (e.g. “6.26.0”)
- vl_convert.get_vegalite_versions() list[str]#
Get the bundled versions of Vega-Lite
- Returns:
Vega-Lite version strings (e.g. [“5.8”, “5.9”, …, “5.21”])
Types#
These names appear in public signatures and return values.
VlSpec#
A Vega or Vega-Lite specification as a JSON string or a dictionary.
VlSpec = str | dict[str, Any]
Renderer#
The HTML browser renderer: "svg", "canvas", or "hybrid".
FormatLocale and TimeFormatLocale#
A built-in locale name or a locale dictionary.
FormatLocale = FormatLocaleName | dict[str, Any]
TimeFormatLocale = TimeFormatLocaleName | dict[str, Any]
Accepted number-format locale names
FormatLocaleName: TypeAlias = Literal[
"ar-001",
"ar-AE",
"ar-BH",
"ar-DJ",
"ar-DZ",
"ar-EG",
"ar-EH",
"ar-ER",
"ar-IL",
"ar-IQ",
"ar-JO",
"ar-KM",
"ar-KW",
"ar-LB",
"ar-LY",
"ar-MA",
"ar-MR",
"ar-OM",
"ar-PS",
"ar-QA",
"ar-SA",
"ar-SD",
"ar-SO",
"ar-SS",
"ar-SY",
"ar-TD",
"ar-TN",
"ar-YE",
"ca-ES",
"cs-CZ",
"da-DK",
"de-CH",
"de-DE",
"en-CA",
"en-GB",
"en-IE",
"en-IN",
"en-US",
"es-BO",
"es-ES",
"es-MX",
"fi-FI",
"fr-CA",
"fr-FR",
"he-IL",
"hu-HU",
"it-IT",
"ja-JP",
"ko-KR",
"mk-MK",
"nl-NL",
"pl-PL",
"pt-BR",
"pt-PT",
"ru-RU",
"sl-SI",
"sv-SE",
"uk-UA",
"zh-CN",
]
Accepted time-format locale names
TimeFormatLocaleName: TypeAlias = Literal[
"ar-EG",
"ar-SY",
"ca-ES",
"cs-CZ",
"da-DK",
"de-CH",
"de-DE",
"en-CA",
"en-GB",
"en-US",
"es-ES",
"es-MX",
"fa-IR",
"fi-FI",
"fr-CA",
"fr-FR",
"he-IL",
"hr-HR",
"hu-HU",
"it-IT",
"ja-JP",
"ko-KR",
"mk-MK",
"nb-NO",
"nl-BE",
"nl-NL",
"pl-PL",
"pt-BR",
"ru-RU",
"sv-SE",
"tr-TR",
"uk-UA",
"vi-VN",
"zh-CN",
"zh-TW",
]
GoogleFontSpec#
The google_fonts parameter accepts family-name strings or GoogleFontSpec dictionaries. A dictionary names a family and optional variants:
{
"family": "Inter",
"variants": [(400, "normal"), (700, "italic")],
}
FontInfo#
The dictionary returned for each font by vegalite_fonts() and vega_fonts(). It contains the font name, source, variants, and optional CSS helpers for Google-hosted fonts.
class FontVariant(TypedDict):
weight: str
style: str
font_face: str | None
class FontInfo(TypedDict):
name: str
source: FontSource
variants: list[FontVariant]
url: str | None
link_tag: str | None
import_rule: str | None
FontSource identifies whether the font comes from Google Fonts or a local file:
class GoogleFontSource(TypedDict):
type: Literal["google"]
font_id: str
class LocalFontSource(TypedDict):
type: Literal["local"]
FontSource: TypeAlias = GoogleFontSource | LocalFontSource
ConverterConfig#
The dictionary returned by get_config().
class ConverterConfig(TypedDict):
num_workers: int
base_url: str | bool
allowed_base_urls: list[str]
auto_google_fonts: bool
embed_local_fonts: bool
subset_fonts: bool
missing_fonts: Literal["fallback", "warn", "error"]
google_fonts: list[GoogleFontSpec]
google_font_variant_threshold: int | None
max_v8_heap_size_mb: int | None
max_v8_execution_time_secs: int | None
gc_after_conversion: bool
vega_plugins: list[str]
plugin_import_domains: list[str]
allow_per_request_plugins: bool
max_ephemeral_workers: int | None
allow_google_fonts: bool
per_request_plugin_import_domains: list[str]
default_theme: str | None
default_format_locale: str | dict[str, Any] | None
default_time_format_locale: str | dict[str, Any] | None
themes: dict[str, dict[str, Any]]
WorkerMemoryUsage#
The dictionary returned for each worker by get_worker_memory_usage(). Sizes are in bytes.
class WorkerMemoryUsage(TypedDict):
worker_index: int
used_heap_size: int
total_heap_size: int
heap_size_limit: int
external_memory: int