Python Async API Reference#

This page documents vl_convert.asyncio. For a usage example, see Python Async API.

These entries are generated from the async type stubs and share the synchronous functions’ parameter documentation. See Types for the types used by both APIs.

Await functions marked async. Functions without that marker return directly and must not be awaited. The return type shown for an async function is the value returned by await.

Vega-Lite Conversions#

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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".

async vl_convert.asyncio.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.

async vl_convert.asyncio.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#

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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".

async vl_convert.asyncio.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#

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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#

async vl_convert.asyncio.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#

async vl_convert.asyncio.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

async vl_convert.asyncio.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.asyncio.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.asyncio.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.asyncio.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.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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#

async vl_convert.asyncio.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).

async vl_convert.asyncio.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.asyncio.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.

async vl_convert.asyncio.get_config() → ConverterConfig#

Return the active converter configuration.

Returns:

Converter configuration dictionary.

Worker Diagnostics#

async vl_convert.asyncio.warm_up_workers() → None#

Start converter workers before the first conversion.

Use this during application startup when first-request latency matters.

async vl_convert.asyncio.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.asyncio.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.asyncio.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.

async vl_convert.asyncio.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.

async vl_convert.asyncio.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.asyncio.get_vega_version() → str#

Get the bundled version of Vega

Returns:

Vega version string (e.g. “5.30.0”)

vl_convert.asyncio.get_vega_themes_version() → str#

Get the bundled version of Vega-Themes

Returns:

Vega-Themes version string (e.g. “2.14.0”)

vl_convert.asyncio.get_vega_embed_version() → str#

Get the bundled version of Vega-Embed

Returns:

Vega-Embed version string (e.g. “6.26.0”)

vl_convert.asyncio.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