A Python client for the quickchart.io image charts web service.

Use the quickchart library in this project, or install through pip:

pip install quickchart.io

Version 3.0.0 and later require Python 3.9 or later. If you need support for Python 3.7 or 3.8, use version 2.0.0; for earlier versions of Python, use version 1.0.1.

This library provides a QuickChart class. Import and instantiate it. Then set properties on it and specify a Chart.js config:

from quickchart import QuickChart

qc = QuickChart()
qc.width = 500
qc.height = 300
qc.config = {
    "type": "bar",
    "data": {
        "labels": ["Hello world", "Test"],
        "datasets": [{
            "label": "Foo",
            "data": [1, 2]
        }]
    }
}

Use get_url() on your quickchart object to get the encoded URL that renders your chart:

print(qc.get_url())
# https://quickchart.io/chart?c=%7B%22chart%22%3A+%7B%22type%22%3A+%22bar%22%2C+%22data%22%3A+%7B%22labels%22%3A+%5B%22Hello+world%22%2C+%22Test%22%5D%2C+%22datasets%22%3A+%5B%7B%22label%22%3A+%22Foo%22%2C+%22data%22%3A+%5B1%2C+2%5D%7D%5D%7D%7D%7D&w=600&h=300&bkg=%23ffffff&devicePixelRatio=2.0&f=png

If you have a long or complicated chart, use get_short_url() to get a fixed-length URL using the quickchart.io web service (note that these URLs only persist for a short time unless you have a subscription):

print(qc.get_short_url())
# https://quickchart.io/chart/render/f-a1d3e804-dfea-442c-88b0-9801b9808401

The URLs will render an image of a chart:

Chart.js sometimes relies on Javascript functions (e.g. for formatting tick labels). There are a couple approaches:

• Build chart configuration as a string instead of a Python object. See examples/simple_example_with_function.py.
• Build chart configuration as a Python object and include a placeholder string for the Javascript function. Then, find and replace it.
• Use the provided QuickChartFunction class. See examples/using_quickchartfunction.py for a full example.

A short example using QuickChartFunction:

qc = QuickChart()
qc.config = {
    "type": "bar",
    "data": {
        "labels": ["A", "B"],
        "datasets": [{
            "label": "Foo",
            "data": [1, 2]
        }]
    },
    "options": {
        "scales": {
            "yAxes": [{
                "ticks": {
                    "callback": QuickChartFunction('(val) => val + "k"')
                }
            }],
            "xAxes": [{
                "ticks": {
                    "callback": QuickChartFunction('''function(val) {
                      return val + '???';
                    }''')
                }
            }]
        }
    }
}

print(qc.get_url())

You can set the following properties:

The actual Chart.js chart configuration.

If your chart configuration is JSON-compatible, it's usually easiest to pass an object (example). If your chart configuration contains a Javascript function, you may pass it as a string (example) or use QuickChartFunction (example).

Width of the chart image in pixels. Defaults to 500

Height of the chart image in pixels. Defaults to 300

Format of the chart. Defaults to png. svg is also valid.

The background color of the chart. Any valid HTML color works. Defaults to #ffffff (white). Also takes rgb, rgba, and hsl values.

The device pixel ratio of the chart. This will multiply the number of pixels by the value. This is usually used for retina displays. Defaults to 1.0.

The version of Chart.js to use. Acceptable values are documented here. Usually used to select Chart.js 3+.

The protocol to use. Defaults to https.

Override the host of the chart render server. Defaults to quickchart.io.

Set an API key that will be included with the request.

Timeout in seconds for the network requests made by get_bytes(), get_short_url(), and to_file(). Defaults to 60.0. Set to None to disable the timeout.

There are two ways to get a URL for your chart object.

Returns a URL that will display the chart image when loaded.

Uses the quickchart.io web service to create a fixed-length chart URL that displays the chart image. Returns a URL such as https://quickchart.io/chart/render/f-a1d3e804-dfea-442c-88b0-9801b9808401.

Note that short URLs expire after a few days for users of the free service. You can subscribe to keep them around longer.

Returns the bytes representing the chart image.

Writes the chart image to a file path.

Checkout the examples directory to see other usage.

This project uses Poetry for packaging and dependency management.

# Install dependencies (including dev tools)
poetry install --with dev

# Run the test suite
poetry run python -m pytest tests.py

# Lint and format
poetry run ruff check .
poetry run ruff format .

The tests that hit the live quickchart.io service are skipped by default. Set QUICKCHART_NETWORK_TESTS=1 to run them:

QUICKCHART_NETWORK_TESTS=1 poetry run python -m pytest tests.py