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,
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.
- 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,
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.
- 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,
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.
- 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,
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.
- 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,
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.
- 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,
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".
- 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,
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.
- 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,
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.
- 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,
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.
- 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,
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.
- 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,
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.
- 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,
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.
- 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,
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".
- 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,
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 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#
- 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_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.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:
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.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.
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.
- 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,
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.
- 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,
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#
- 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,
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).
- 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. 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.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 byvl-convert config-pathon 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, andexternal_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