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.0rc5.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.0rc5-cp39-abi3-win_amd64.whl (43.8 MB view details)

Uploaded CPython 3.9+Windows x86-64

vl_convert_python-2.0.0rc5-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.0rc5-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.0rc5-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.0rc5-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.0rc5.tar.gz.

File metadata

  • Download URL: vl_convert_python-2.0.0rc5.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.0rc5.tar.gz
Algorithm Hash digest
SHA256 0ec262b81b115a7aa8d6aa0d1499f1d11cf20f6d66f1aa29884b5b6aa5781f06
MD5 8f9aaa2e4902f599936829ba5de6ee3a
BLAKE2b-256 3dfb556986a4028461ce839915bfbb3ad86c410cf7ae60ad5509c5b16baf2a84

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc5.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.0rc5-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc5-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 64ad67c9cf3a9edbaccc6e57a3c634aab1fa2221ee3798bc024a7397e4a9df29
MD5 9750788d31278e4c276c6d80dd8bca16
BLAKE2b-256 96184acd2201a3181fe89892e750ec3eb78d79ad657b8204f90a81433a1f5deb

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc5-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.0rc5-cp39-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc5-cp39-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 193509e294cf3030c0fd90fa4893a28cf6c4b2efaba705e9b3186047609ddde9
MD5 43d7c84478bcff8c13e5d239bbab1db3
BLAKE2b-256 991fcfd08806afbcff51b5850a4e69270323e3df0c0169f1589add3f687520fb

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc5-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.0rc5-cp39-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc5-cp39-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 91c236989d805d30aad1d69df5b61167dad4c05c33da75f4caccf9e4277f9f4e
MD5 a5beb3fe11f97d72636d530521141d5d
BLAKE2b-256 29204ffbd022b297417ce063ce0004ea11ac336a2c7e1deedf4c3ca498ee7234

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc5-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.0rc5-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc5-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d31c38bd54a6ee254a3d2b119c104503d57f6698c2ffb733f6a5f0db187339f1
MD5 f0429ae758031f542dca5df8eea33ca4
BLAKE2b-256 147872fe4118bfb74d1d74c6133846b197a00986353b22e8254b4d5d380ac20c

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc5-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.0rc5-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-2.0.0rc5-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 dfe8dfffa6eb897ec483fff241cf2e955a027ecf0e382be0628e37251801d253
MD5 f86e74ffd48094ec2b4d4f7d52e3cca7
BLAKE2b-256 4a36a5cdcac632b6a0f4a8d4ad9677c97e098480927b6098e85dd9df2ac45d9a

See more details on using hashes here.

Provenance

The following attestation bundles were made for vl_convert_python-2.0.0rc5-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.0rc5 This release

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