Pre-release

This release is a pre-release and may not be stable for production use.

Overview

vl-convert-python is a dependency-free Python package for converting Vega-Lite chart specifications into static images (SVG or PNG) or Vega chart specifications.

Since an Altair chart can generate Vega-Lite, this package can be used to easily create static images from Altair charts.

Try it out on Binder!
Binder

Installation

vl-convert-python can be installed using pip with

$ pip install vl-convert-python

Usage

The vl-convert-python package provides a series of conversion functions under the vl_convert module.

Convert Vega-Lite to SVG, PNG, and Vega

The vegalite_to_svg and vegalite_to_png functions can be used to convert Vega-Lite specifications to static SVG and PNG images respectively. The vegalite_to_vega function can be used to convert a Vega-Lite specification to a Vega specification.

import vl_convert as vlc
import json

vl_spec = r"""
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {"url": "https://raw.githubusercontent.com/vega/vega-datasets/next/data/movies.json"},
  "mark": "circle",
  "encoding": {
    "x": {
      "bin": {"maxbins": 10},
      "field": "IMDB Rating"
    },
    "y": {
      "bin": {"maxbins": 10},
      "field": "Rotten Tomatoes Rating"
    },
    "size": {"aggregate": "count"}
  }
}
"""

# Create SVG image string and then write to a file
svg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)
with open("chart.svg", "wt") as f:
    f.write(svg_str)

# Create PNG image data and then write to a file
png_data = vlc.vegalite_to_png(vl_spec=vl_spec, scale=2)
with open("chart.png", "wb") as f:
    f.write(png_data)

# Create low-level Vega representation of chart and write to file
vg_spec = vlc.vegalite_to_vega(vl_spec)
with open("chart.vg.json", "wt") as f:
    json.dump(vg_spec, f)

Convert Altair Chart to SVG, PNG, and Vega

The Altair visualization library provides a Pythonic API for generating Vega-Lite visualizations. As such, vl-convert-python can be used to convert Altair charts to PNG, SVG, or Vega. The vegalite_* functions support an optional vl_version argument that can be used to specify the particular version of the Vega-Lite JavaScript library to use. Version 4.2 of the Altair package uses Vega-Lite version 4.17, so this is the version that should be specified when converting Altair charts.

import altair as alt
from vega_datasets import data
import vl_convert as vlc
import json

source = data.barley()

chart = alt.Chart(source).mark_bar().encode(
    x='sum(yield)',
    y='variety',
    color='site'
)

# Create SVG image string and then write to a file
svg_str = vlc.vegalite_to_svg(chart.to_json(), vl_version="4.17")
with open("altair_chart.svg", "wt") as f:
    f.write(svg_str)

# Create PNG image data and then write to a file
png_data = vlc.vegalite_to_png(chart.to_json(), vl_version="4.17", scale=2)
with open("altair_chart.png", "wb") as f:
    f.write(png_data)

# Create low-level Vega representation of chart and write to file
vg_spec = vlc.vegalite_to_vega(chart.to_json(), vl_version="4.17")
with open("altair_chart.vg.json", "wt") as f:
    json.dump(vg_spec, f)

Configure Worker Parallelism

By default, vl-convert-python uses 1 converter worker. You can configure this globally:

import vl_convert as vlc

cfg = vlc.get_config()
print(cfg["num_workers"])  # 1

vlc.configure(num_workers=4)  # enable parallel worker pool
vlc.warm_up_workers()  # optional: pre-initialize workers before first conversion

This setting applies to subsequent conversions and enables parallel work across Python threads.

Google Fonts

Charts that reference Google Fonts can download and register them automatically. There are two approaches:

Explicit Registration

Use register_google_fonts_font to download specific font families before conversion:

import vl_convert as vlc

# Download all variants of Roboto
vlc.register_google_fonts_font("Roboto")

# Download specific weight/style variants
vlc.register_google_fonts_font("Playfair Display", variants=[(400, "normal"), (700, "italic")])

svg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)

Automatic Detection

Enable auto_google_fonts to have vl-convert scan the chart specification for font references and download matching Google Fonts automatically:

import vl_convert as vlc

vlc.configure(auto_google_fonts=True)

# Fonts referenced in the spec are downloaded automatically
svg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)

Cache Configuration

Downloaded fonts are cached on disk (default ~/.cache/vl-convert/google-fonts/). You can limit the cache size:

vlc.configure(google_fonts_cache_size_mb=500)

Asyncio API

An async API with matching function names is available under vl_convert.asyncio.

import asyncio
import vl_convert.asyncio as vlca

vl_spec = {
    "data": {"values": [{"a": "A", "b": 1}, {"a": "B", "b": 2}]},
    "mark": "bar",
    "encoding": {
        "x": {"field": "a", "type": "nominal"},
        "y": {"field": "b", "type": "quantitative"},
    },
}

async def main():
    await vlca.configure(num_workers=4)
    await vlca.warm_up_workers()  # optional

    svg = await vlca.vegalite_to_svg(vl_spec, "v5_16")
    print(svg[:5])

    svgs = await asyncio.gather(
        *[vlca.vegalite_to_svg(vl_spec, "v5_16") for _ in range(8)]
    )
    print(len(svgs))

asyncio.run(main())

The top-level sync API (vl_convert.<function>) is unchanged. The async namespace is additive.

How it works

This crate uses PyO3 to wrap the vl-convert-rs Rust crate as a Python library. The vl-convert-rs crate is a self-contained Rust library for converting Vega-Lite visualization specifications into various formats. The conversions are performed using the Vega-Lite and Vega JavaScript libraries running in a v8 JavaScript runtime provided by the deno_runtime crate. Font metrics and SVG-to-PNG conversions are provided by the resvg crate.

Of note, vl-convert-python is fully self-contained and has no dependency on an external web browser or Node.js runtime.

Development setup

Create development conda environment

$ conda create -n vl-convert-dev -c conda-forge python=3.10 deno maturin altair pytest black black-jupyter scikit-image

Activate environment and pip install remaining dependencies

$ conda activate vl-convert-dev
$ pip install pypdfium2

Change to Python package directory

$ cd vl-convert-python

Build Rust python package with maturin in develop mode

$ maturin develop --release

Run tests

$ pytest tests

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Stable release available (1.9.0.post1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jmmease from gravatar.com jmmease

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.9

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vl_convert_python-2.0.0rc6.tar.gz (6.1 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

vl_convert_python-2.0.0rc6-cp39-abi3-win_amd64.whl (43.8 MB view details)

Uploaded CPython 3.9+Windows x86-64

vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_x86_64.whl (46.3 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.28+ x86-64

vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_aarch64.whl (46.2 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.28+ ARM64

vl_convert_python-2.0.0rc6-cp39-abi3-macosx_11_0_arm64.whl (41.2 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

vl_convert_python-2.0.0rc6-cp39-abi3-macosx_10_12_x86_64.whl (41.9 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file vl_convert_python-2.0.0rc6.tar.gz.

File metadata

  • Download URL: vl_convert_python-2.0.0rc6.tar.gz
  • Upload date:
  • Size: 6.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vl_convert_python-2.0.0rc6.tar.gz
Algorithm Hash digest
SHA256 d3f11e17b6ec63fd0dad1a3e3a3322ae032b47961f769d8a61e1b25182e9c5a9
MD5 63d8cc2089a978109318ed4b2714fde6
BLAKE2b-256 280c6d8863b653649da53a67169169de86752ca94a5e1048dfc59a772a8b8f79

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc6.tar.gz:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc6-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc6-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 035266a07021363785f9fc782119e455f4c51a5c52cc05399c19d8d965a195db
MD5 1919be2a26ae2afd6d5cb25a50781721
BLAKE2b-256 72b82fbd488bc242009dd00676cde973f2d96e50e7635ef3cf120e23a825b87a

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc6-cp39-abi3-win_amd64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d2e37b39fdec25adc0a17ecd8a1aaad74a5bb6f3c21abfadd8d1dbc11b62162d
MD5 a8697caa5c28e22260b9bbbacd4ff572
BLAKE2b-256 61a53c0ed8656c76903c3dc09b5da9cae30da565f92dc5706997aa9312b2b62b

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_x86_64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 f7ce351d67e5bd405aeea682a1d24c9751c3b0b82aaa9586eddcc3eec6702240
MD5 29ca6036cb24e78b0df0034bbd529d8e
BLAKE2b-256 503e82043387482bf354c46bf0bdf31617ac5ff434cc129bfbea47237e90a4e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc6-cp39-abi3-manylinux_2_28_aarch64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc6-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc6-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e4af6b57e72b3a3c23fa4107ac0d33c755231558e2ed1e6157c80c81501ba41c
MD5 016563f9991448550842b62237e4feff
BLAKE2b-256 66dbafa26e5809aef490c0666ee13614475ed35c3b54e841b05edf45c8ee4f93

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc6-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vl_convert_python-2.0.0rc6-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc6-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 4cd0566e7e81d826f716c40c3a08088e0632ac2e8e0759608f88ae97126cdea0
MD5 f93a659be924157b3d2b85edc9f24c44
BLAKE2b-256 7d72eb28b13cfc6f50f6089a75f3945f877f3ff51cadf9082272479680224cd6

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc6-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: Release.yml on vega/vl-convert

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release
Pre-release

2.0.0rc6 This release

6 files

Pre-release

2.0.0rc5

6 files

Pre-release

2.0.0rc3

5 files

Pre-release

2.0.0rc2

6 files

Pre-release

2.0.0rc1

6 files

1.9.0.post1

6 files

1.9.0

6 files

1.8.0

6 files

1.7.0

6 files

1.6.1

6 files

1.6.0

6 files

1.5.1

5 files

1.5.0

5 files

1.4.0

6 files

1.3.0

6 files

1.2.4

6 files

1.2.3

6 files

1.2.2

6 files

1.2.1

6 files

1.2.0

6 files

1.1.0

6 files

1.0.1

6 files

Pre-release

1.0.1rc1

6 files

1.0.0

6 files

0.14.0

6 files

0.13.1

6 files

0.13.0

6 files

0.12.0

6 files

0.11.2

6 files

0.11.1

26 files

0.11.0

26 files

0.10.3

26 files

0.10.2

26 files

0.10.1

26 files

0.10.0

26 files

0.9.0

26 files

0.8.1

26 files

0.8.0

26 files

0.7.0

25 files

0.6.0

25 files

0.5.0

25 files

0.4.0

25 files

0.3.2

25 files

0.3.1

25 files

0.3.0

25 files

0.2.0

20 files

0.1.0

16 files

0.0.1

16 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page