Exporting Static Charts using Highcharts for Python

Posted by Chris Modzelewski | 0 comments

Post categories:

Exporting Static Charts using Highcharts for Python

So you are using Highcharts Core to render beautiful interactive data visualizations, and you are relying on the Highcharts for Python toolkit to create those visualizations in your Python code. That’s great! But what if you need to programmatically create a data visualization and use that visualization somewhere besides a user’s web browser? Embedding visualizations in a presentation or a document is very, very common.

Well, Highcharts for Python has you covered. You can create static exports of your charts either client-side (in your user’s web browser when viewing the chart) or server-side (programmatically within Python).

Client-side Export

Using Highcharts for Python, you can configure client-side export within the Chart instance you create for your chart. In particular, you can create an Exporting instance and set it to your_chart.options.exporting.
The Exporting class lets you configure how your chart will support exporting from within the user’s browser when the chart is rendered. Here’s a quick example, assuming you have a Chart instance called my_chart:

# Import the Exporting class
from highcharts_core.options.exporting
import Exporting
exporting_options = Exporting(enabled = True,
  filename = 'your-exported-chart',
  show_table = True,
  table_caption = "Your Chart's Caption Goes Here",
  accessibility = {
    'enabled': True
  })
exporting_options.buttons['contextButton'].menu_items = ['printChart', 'separator', 'downloadPNG']
my_chart.options.exporting = exporting_options

And that’s it. With the code above you’ve now configured some basic logic that:

  • Enables client-side export of the my_chart visualization.
    Gives an exported chart image a default filename of “your-exported-chart” (not including the file’s extension).
  • Makes sure that the exported or printed version of your chart includes the chart’s underlying data table (thanks to the show_table property being set to True), and
  • Gives users the ability to either print the chart or download a PNG version of the chart, but nothing else (by setting the relevant buttons shown in the context menu).

Highcharts Core supports client-side export to a number of formats, including:

  • PNG
  • JPEG
  • SVG
  • CSV
  • Excel

And you can also configure the client-side export to fall back to server-side export should it fail. For more details on the extensive options, please take a look at the API Documentation: options.Exporting.

Programmatic (Server-side) Export

So now that your users can download a PNG image of your chart, maybe you want to create an image programmatically. Highcharts for Python makes that possible through an integration with the Highcharts Export Server. It’s actually trivially easy to do since you can do it with just one method call in your Python code:

# Download a PNG version of the chart in memory within your Python code.
my_png_image = my_chart.download_chart(format = 'png')
# Download a PNG version of the chart and save it the file "/images/my-chart-file.png"
my_png_image = my_chart.download_chart(
  format = 'png',
  filename = '/images/my-chart-file.png'
)

The two examples shown above both download a PNG of your chart:
The first example keeps that PNG image in your Python code only, storing its binary data in the my_png_image variable. The second example not only stores its binary data in the my_png_image variable, but it also saves the PNG image to the file “/images/my-chart-file.png”.
The format argument is really the one doing the heavy lifting above. In the example above, it tells the method to generate a PNG image, but you can also create “jpeg”, “pdf”, and “svg”.
And that’s it! There’s really nothing simpler.
Under the hood, this method defaults to calling the Highcharts Export Server that is maintained by Highsoft (creators of Highcharts Core). This publicly-available server is available to all licensees of Highcharts Core, and you are free to use it to generate downloadable versions of your data visualizations. However, it is rate-limited and it does mean transmitting your chart’s data across the wire. There are various situations in which this is inappropriate, which is why Highsoft allows you to configure and deploy your own Highcharts Export Server. And Highcharts for Python supports using your own custom Export Server for your programmatic chart exports.

Custom Export Server

Tip
While deploying your own Highcharts Export Server is beyond the scope of this tutorial, we strongly recommend that you review the Highcharts Export Server documentation

If you have your own Highcharts Export Server, you can override Highcharts for Python’s default to have your code rely on your own export server. While you can do this by creating an instance of highcharts_core.headless_export.ExportServer with your custom configuration and passing it to the .download_chart() method in the server_instance argument, it is far easier to simply set some environment variables wherever your Python code will be running:

  • HIGHCHARTS_EXPORT_SERVER_DOMAIN is the environment variable that specifies the domain where the Highcharts Export Server exists. If this environment variable is not set, it will default to "export.highcharts.com", which is the Highsoft-provided export server.
  • HIGHCHARTS_EXPORT_SERVER_PATH is the path at the domain where your Export Server is reachable. If this environment variable is not set, it will default to None since there is no path when using the Highsoft-provided export server.
  • HIGHCHARTS_EXPORT_SERVER_PORT is the port where your Export Server is reachable. If this environment variable is not set, it will default to None since there is no need to specify a port when using the Highsoft-provided export server.

In addition to the three environment variables above, the .download_chart() method also supports three additional arguments which may prove useful:

  • auth_user which is the user to supply to your custom Export Server using Basic authentication. This defaults to None (since the default Highsoft-provided Export Server has no authentication).
  • auth_password which is the password to supply to your custom Export Server using Basic authentication. This defaults to None (since the default Highsoft-provided Export Server has no authentication).
  • timeout which is the number of seconds to wait before issuing a timeout error. The timeout check is passed if any bytes have been received on the socket in less than this number of seconds. It defaults to 0.5, but you may want to adjust this when using your own custom Export Server.

More Resources

The above tutorial is just a really simple example of how you can create rich visualizations with just a handful of method calls using Highcharts for Python. But the library offers so much more! We recommend you take a look at the following additional resources which you may find useful: