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,
) → bytes#

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_convert logger.

  • 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=True in configure().

  • 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,
) → bytes#

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_convert logger.

  • 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=True in configure().

  • 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,
) → bytes#

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=True in configure().

  • 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,
) → str#

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_convert logger.

  • 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=True in configure().

  • bundle – If True, embed fonts and images as self-contained data URIs. If False (default), use @import references 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,
) → str#

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. If False (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=True in configure().

  • 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,
) → dict[str, Any] | bytes#

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_convert logger.

  • 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=True in configure().

  • 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 for format="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,
) → dict[str, Any]#

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_convert logger.

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,
) → bytes#

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=True in configure().

  • 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,
) → bytes#

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=True in configure().

  • 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,
) → bytes#

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=True in configure().

  • 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,
) → str#

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=True in configure().

  • bundle – If True, embed fonts and images as self-contained data URIs. If False (default), use @import references 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,
) → str#

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. If False (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=True in configure().

  • 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,
) → dict[str, Any] | bytes#

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=True in configure().

  • 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 for format="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,
) → bytes#

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 as vegaLite, Vega as vega, and lodash.debounce as lodashDebounce.

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 assigns vegaEmbed, vegaLite, and vega to 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_dirs are 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:

  1. VLC_GOOGLE_FONTS_CACHE_DIR=none: None (caching disabled, fonts always fetched fresh).

  2. VLC_GOOGLE_FONTS_CACHE_DIR=/some/path: that path.

  3. Unset: the OS cache directory joined with vl-convert/google-fonts (e.g. ~/Library/Caches/vl-convert/google-fonts on 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 None if 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.

None restores 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 None for the default. Positive integers are accepted. Passing 0 raises ValueError.

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,
) → list[FontInfo]#

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_face field 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,
) → list[FontInfo]#

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_face field 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,
) → None#

Configure defaults and resource policies for subsequent conversions.

Parameters:
  • num_workers – Worker count (must be >= 1). None resets to the built-in default (1). Passing 0 raises ValueError.

  • base_url – Base URL for resolving relative data and image paths in Vega specs. None or True resets to the default (vega-datasets CDN). False disables 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). None resets to the default (["http:", "https:"]). [] blocks all absolute data and image locations.

  • auto_google_fonts – Automatically download missing fonts from Google Fonts. None resets 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. None resets to the default (False).

  • subset_fonts – Subset fonts to only the characters used in the chart. Applies to SVG and HTML output. None resets to the built-in default (True).

  • missing_fonts – Missing-font behavior: "fallback" (silent), "warn", or "error". None resets 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. None resets to the built-in default (no cap). Passing 0 raises ValueError.

  • 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. None resets to the built-in default (no cap). Passing 0 raises ValueError, and values below 64 raise ValueError when 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. None resets to the built-in default (no cap). Passing 0 raises ValueError.

  • gc_after_conversion – Whether to run JavaScript garbage collection after each conversion. This can reduce retained heap but adds work. None resets 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 a vega object. 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_plugin parameter on conversion functions. None resets to the built-in default (False).

  • max_ephemeral_workers – Maximum temporary JavaScript workers for concurrent per-request plugins. Must be >= 1 if provided. None resets to the default (2). Passing 0 raises ValueError.

  • allow_google_fonts – Server policy for accepting google_fonts in HTTP request bodies. It does not restrict direct Python calls. None resets 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-request theme overrides this if set. None resets to the built-in default (no theme).

  • default_format_locale – Default d3-format locale name or dictionary applied to all conversions. Per-request format_locale overrides this if set. None resets 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_locale overrides this if set. None resets 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. Call configure() after load_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 path is 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 by vl-convert config-path on 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, and external_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