Quickstart: Patterns and Best Practices

Installation

To install Highcharts Stock for Python, just execute:

$ pip install highcharts-stock

Importing Highcharts Stock for Python Objects

Tip

Best Practice!

This method of importing Highcharts Stock for Python objects yields the fastest performance for the import statement. However, it is more verbose and requires you to navigate the extensive Highcharts Stock for Python API.

# Import classes using precise module indications. For example:
from highcharts_stock.chart import Chart
from highcharts_stock.global_options.shared_options import SharedStockOptions
from highcharts_stock.options import HighchartsStockOptions
from highcharts_stock.options.plot_options.bar import BarOptions
from highcharts_stock.options.series.bar import BarSeries

Standardizing Your Charts

Tip

Best practice!

We really like to use JS literals written as separate files in our codebase. It makes it super simple to instantiate a SharedStockOptions instance with one method call.

Let’s say you organize your files like so:

my_repository/
| — docs/
| — my_project/
| —— project_resources/
| ——— image_files/
| ——— data_files/
| ———— data-file-01.csv
| ———— data-file-02.csv
| ———— data-file-03.csv
| ——— highcharts_config/
| ———— shared_options.js
| ———— bar-template-01.js
| ———— bar-template-02.js
| ———— line-template.js
| ———— packed-bubble-template.js
| —— some_package/
| ——— __init__.py
| ——— package_module.py
| ——— another_module.py
| —— __init__.py
| —— __version__.py
| —— some_module.py
| — tests/
| — .gitignore
| — requirements.txt

You’ll notice that the organization has a project_resources folder. This is where you would put the various files that your application wlil reference, like your static images, or the files that contain data you might be using in your application. It also contains a highcharts_config folder, which contains several files with a .js extension. Of particular note is the file in bold, shared_options.js. This file should contain a JavaScript object literal version of the configuration settings you want to apply to all of your visualizations. This file might look something like this:

{
  chart: {
        backgroundColor: {
            linearGradient: {
              x1: 0,
              x2: 0,
              y1: 1,
              y2: 1
            },
            stops: [
                [0, 'rgb(255, 255, 255)'],
                [1, 'rgb(240, 240, 255)']
            ]
        },
        borderWidth: 2,
        plotBackgroundColor: 'rgba(255, 255, 255, .9)',
        plotBorderWidth: 1
  },
  caption: {
      align: 'center',
      floating: true,
      margin: 20,
      verticalAlign: 'top'
  },
  credits: {
      enabled: true,
      href: 'https://www.somewhere.com',
      style: {
          color: '#cccccc',
          fontSize: '8px'
      },
      text: 'Highcharts for Python'
  }
}

Now with this file, you can easily create a SharedStockOptions instance by executing:

from highcharts_stock.highcharts import SharedStockOptions

my_shared_options = SharedStockOptions.from_js_literal('../../project_resources/highcharts_config/shared_options.js')

And that’s it! Now you have a SharedStockOptions instance that can be used to apply your configuration standards to all of your charts. You can do that by delivering its JavaScript output to your front-end by calling:

js_code_snippet = my_shared_options.to_js_literal()

which will produce a string as follows:

Highcharts.setOptions({
  caption: {
    align: 'center',
    floating: true,
    margin: 20,
    verticalAlign: 'top'
  },
  chart: {
    backgroundColor: {
      linearGradient: {
        x1: 0.0,
        x2: 0.0,
        y1: 1.0,
        y2: 1.0
      },
      stops: [
        [0, 'rgb(255, 255, 255)'],
        [1, 'rgb(240, 240, 255)']
      ]
    },
    borderWidth: 2,
    plotBackgroundColor: 'rgba(255, 255, 255, .9)',
    plotBorderWidth: 1
  },
  credits: {
    enabled: true,
    href: 'https://www.somewhere.com',
    style: {
      color: '#cccccc',
      fontSize: '8px'
    },
    text: 'Highcharts for Python'
  }
});

And now you can deliver js_code_snippet to your HTML template or wherever it will be rendered.

Populating Series with Data

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the data
# point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values of the
# data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]

Warning

Technical indicators provided by Highcharts Stock for Python do not support the .data property because their data gets populated dynamically based on the series indicated in their .linked_to property.

See also

Adding Technical Indicators

Note

All standard series (descending from SeriesBase) have an .add_indicator() method which can be used to easily configure a new indicator tied to the series in question.

# Given a series instance in the variable "my_series"

# Create a Chart instance
my_chart = Chart.from_series(my_series)

# Adds a new Simple Moving Average indicator to the chart, based off of the
# "my_series" series.

my_chart = my_series.add_indicator(my_chart, indicator_name = 'sma')
Method Signature
.add_indicator(chart, indicator_name, indicator_kwargs=None)
Parameters:

  • chart (Chart) – The chart object in which the series is rendered and to which the indicator should be appended.

  • indicator_name (str) – The name of the indicator that should be added to the series and chart. For the list of supported indicators, please review the Indicator List.

  • indicator_kwargs (dict or None) – Keyword arguments to apply when instantiating the new indicator series. Defaults to None.

Returns:

chart with a new indicator series included in its list of configured series.

Return type:

Chart

Assembling Your Chart and Options

Note

.add_series() is supported by both the Chart and HighchartsStockOptions classes

my_chart = Chart()
my_chart.add_series(my_series1, my_series2)

my_series = LineSeries()
my_chart.add_series(my_series)
Method Signature
.add_series(self, *series)

Adds series to the Chart.options.series property.

Parameters:

series (SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one

Rendering Your Visualizations

from highcharts_stock.chart import Chart
from highcharts_stock.options.series.hlc import HLCSeries

my_chart = Chart(container = 'target_div',
                 options = {
                     'series': [
                         HLCSeries(data = [
                             [2, 0, 4],
                             [4, 2, 8],
                             [3, 9, 3]
                         ])
                     ]
                 },
                 variable_name = 'myChart',
                 is_stock_chart = True)

as_js_literal = my_chart.to_js_literal()

# This will produce a string equivalent to:
#
# document.addEventListener('DOMContentLoaded', function() {
#   const myChart = Highcharts.stockChart('target_div', {
#      series: {
#          type: 'hlc',
#          data: [
#            [2, 0, 4],
#            [4, 2, 8],
#            [3, 9, 3]
#          ]
#      }
#   });
# });

Downloading a Rendered Highcharts Visualization

from highcharts_stock.chart import Chart
from highcharts_stock.options.series.area import LineSeries

my_chart = Chart(container = 'target_div',
                 options = {
                     'series': [
                         LineSeries(data = [0, 5, 3, 5])
                     ]
                 },
                 variable_name = 'myChart',
                 is_stock_chart = True)

# 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'
)
Method Signature

See also

.download_chart(self, filename=None, format='png', server_instance=None, scale=1, width=None, auth_user=None, auth_password=None, timeout=0.5, global_options=None, **kwargs)

Export a downloaded form of the chart using a Highcharts Export Server.

Parameters:

  • filename (Path-like or None) – The name of the file where the exported chart should (optionally) be persisted. Defaults to None.

  • server_instance (ExportServer or None) – Provide an already-configured ExportServer instance to use to programmatically produce the exported chart. Defaults to None, which causes Highcharts for Python to instantiate a new ExportServer instance with all applicable defaults.

  • format (str) –

    The format in which the exported chart should be returned. Defaults to 'png'.

    Accepts:

    • 'png'

    • 'jpeg'

    • 'pdf'

    • 'svg'

  • scale (numeric) –

    The scale factor by which the exported chart image should be scaled. Defaults to 1.

    Tip

    Use this setting to improve resolution when exporting PNG or JPEG images. For example, setting scale = 2 on a chart whose width is 600px will produce an image file with a width of 1200px.

    Warning

    If width is explicitly set, this setting will be overridden.

  • width (numeric or None) –

    The width that the exported chart should have. Defaults to None.

    Warning

    If explicitly set, this setting will override scale.

  • auth_user (str or None) – The username to use to authenticate against the Export Server, using basic authentication. Defaults to None.

  • auth_password (str or None) – The password to use to authenticate against the Export Server (using basic authentication). Defaults to None.

  • timeout (numeric or None) – The number of seconds to wait before issuing a timeout error. The timeout check is passed if bytes have been received on the socket in less than the timeout value. Defaults to 0.5.

  • global_options (HighchartsStockOptions, HighchartsOptions or None) – The global options which will be passed to the (JavaScript) Highcharts.setOptions() method, and which will be applied to the exported chart. Defaults to None.

Note

All other keyword arguments are as per the ExportServer constructor.

Returns:

The exported chart image, either as a bytes binary object or as a base-64 encoded string (depending on the use_base64 keyword argument).

Return type:

bytes or str

Using Highcharts Stock Features

Stock tools are a custom toolbar that can be displayed on your chart which allows your users to interact with your chart in various ways. Using event bindings tied to the stock tools, you can toggle annotations, toggle technical indicators, or control the chart’s zoom level.

Stock Tools Example

To display the stock tools in your chart, you can use the HighchartsStockOptions.stock_tools setting, which can be configured using a StockTools instance.

my_stock_tools = StockTools(gui = { 'enabled': True })
my_options = HighchartsStockOptions(stock_tools = my_stock_tools)
my_chart = Chart.from_options(my_options)

See also