`.shared_options`

class: `SharedMapsOptions`

class SharedMapsOptions(**kwargs)[source]

Python object which can be used to configure global settings that can apply to multiple Highcharts charts when serialized to JavaScript.

Class Inheritance

Inheritance diagram of SharedMapsOptions

add_series(*series)

Adds series to the series property.

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

copy(other=None, overwrite=True, **kwargs)

Copy the configuration settings from this instance to the other instance.

Parameters:

other (HighchartsMeta) – The target instance to which the properties of this instance should be copied. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
kwargs – Additional keyword arguments. Some special descendents of HighchartsMeta may have special implementations of this method which rely on additional keyword arguments.

Returns:

A mutated version of other with new property values

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file, allow_snake_case: bool = True)

Construct an instance of the class from a JSON string.

Parameters:

as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

classmethod from_options(options)[source]

Create a SharedMapsOptions instance from a HighchartsMapsOptions object.

Parameters:: options (HighchartsMapsOptions or coercable) – A HighchartsMapsOptions object to use for the shared options instance.
Returns:: A SharedMapsOptions instance :rtype: SharedMapsOptions

classmethod from_series(*series, kwargs=None)

Creates a new Options instance populated with series.

Parameters:

series (one or more SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one
kwargs (dict) –
Other properties to use as keyword arguments for the instance to be created.

Warning

If kwargs sets the .series property, that setting will be overridden by the contents of series.

Returns:

A new Options instance

Return type:

Options

get_required_modules(include_extension=False) → List[str]

Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list of str

to_dict() → dict

Generate a dict representation of the object compatible with the Highcharts JavaScript library.

Note

The dict representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8', careful_validation=False) → str | None[source]

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.
careful_validation – if True, will carefully validate JavaScript values

along the way using the esprima-python library. Defaults to False.

Warning

Setting this value to True will significantly degrade serialization performance, though it may prove useful for debugging purposes.

Note

Returns a JavaScript string which applies the Highcharts global options. The JavaScript returned by this method takes the (pseudo-code) form:

Highcharts.setOptions({... configuration options ... });

Return type:: str

to_json(filename=None, encoding='utf-8', for_export: bool = False)

Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

str or bytes

static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None, for_export: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Return type:

iterable

property accessibility: Accessibility | None

Options for configuring accessibility for the chart.

Note

Requires the accessibility module to be loaded in the browser. For a description of the module and information on its features, see Highcharts Accessibility.

Returns:: The accessibility configuration for the chart or None
Return type:: Accessibility / None
Raises:: HighchartsError – if setting the value to an incompatible type

property annotations: List[Annotation] | None

A basic type of an annotation. It allows adding custom labels or shapes. The items can be tied to points, axis coordinates or chart pixel coordinates.

Returns:: A collection of the annotations applied to the chart.
Return type:: list of Annotation objects or None if no annotations are applied

property boost: Boost | None

Options for the Boost module.

The Boost module allows certain series types to be rendered by WebGL instead of the default SVG. This allows hundreds of thousands of data points to be rendered in milliseconds. In addition to the WebGL rendering it saves time by skipping processing and inspection of the data wherever possible.

Warning

This introduces some limitations to what features are available in boost mode. See the docs for details.

Returns:: The Boost object.
Return type:: Boost

property caption: Caption | None

The chart’s caption, which will render below the chart and will be part of exported charts.

Note

The caption can be updated after chart initialization through the Chart.update or Chart.caption.update JavaScript methods.

Returns:: The chart’s caption or None
Return type:: Caption / None

property chart: ChartOptions | None

General options for the chart.

Note

This property is perhaps one of the most important properties you will use when configuring your Highcharts data visualization.

Returns:: A ChartOptions configuration object or None
Return type:: ChartOptions or None

property color_axis: List[ColorAxis] | None

A color axis for series.

Visually, the color axis will appear as a gradient or as separate items inside the legend, depending on whether the axis is scalar or based on data classes.

A scalar color axis is represented by a gradient. The colors either range between the minimum_color and the maximum_color, or for more fine grained control the colors can be defined in stops. Often times, the color axis needs to be adjusted to get the right color spread for the data. In addition to stops, consider using a logarithmic axis type, or setting min and max to avoid the colors being determined by outliers.

For supported color formats, please see the documentation article about colors.

When data_classes are used, the ranges are subdivided into separate classes like categories based on their values. This can be used for ranges between two values, but also for a true category. However, when your data is categorized, it may be as convenient to add each category to a separate series.

Warning

Color axis does not work with: sankey, sunburst, dependencywheel, networkgraph, wordcloud, venn, gauge and solidgauge series types.

See the Axis object for programmatic access to the axis.

Returns:: A collection of ColorAxis objects defining the color axis to apply, or None.
Return type:: list of ColorAxis or None

property colors: List[str | Gradient | Pattern] | None

An array containing the default colors for the chart’s series.

When all colors are used, new colors are pulled from the start again.

Default colors can also be set on a series or series.type basis, see Column.colors and Pie.colors.

Warning

In styled mode, the colors option does not exist.

Instead, colors are defined in CSS and applied either through series or point class names, or through the Chart.color_count option.

Defaults to:

[
    "#7cb5ec",
    "#434348",
    "#90ed7d",
    "#f7a35c",
    "#8085e9",
    "#f15c80",
    "#e4d354",
    "#2b908f",
    "#f45b5b",
    "#91e8e1"
]

Returns:: A collection of hex color strings.
Return type:: list of str

property credits: Credits | None

Highchart by default puts a credits label in the lower right corner of the chart. This can be changed using these options.

Returns:: Credits configuration or None
Return type:: Credits or None

property data: Data | None

The data property provides a simplified interface for adding data to a chart from sources like CVS, HTML tables, or grid views. See also the tutorial article on the Data module.

Warning

It requires the modules/data.js file to be loaded in the browser / client.

Warning

Please note that the default way of adding data in Highcharts, without the need of a module, is through the series.type.data property.

Returns:: The Data object or None
Return type:: Data object or None

property defs: MarkerDefinition | None

Options for configuring markers for annotations.

Returns:: A MarkerDefinition object or None
Return type:: MarkerDefinition or None

property drilldown: Drilldown | None

Options to configure drilldown functionality in the chart, which enables users to inspect increasingly high resolution data by clicking on chart items like columns or pie slices.

Note

The drilldown feature requires the drilldown.js file to be loaded in the browser/client. This file is found in the modules directory of the download package, or online at code.highcharts.com/modules/drilldown.js.

Returns:: The options to configure the chart’s drill down functionality.
Return type:: Drilldown or None

property exporting: Exporting | None

Options to configure the export functionality enabled for the chart.

Returns:: The configuration of the chart’s exporting functionality.
Return type:: Exporting or None

property language: Language | None

Language object which can be used to configure the specific text to use in the chart.

Note

When working in JavaScript, the lang configuration is global and it can’t be set on each chart initialization.

Instead, use Highcharts.setOptions() to set it before any chart is initialized.

Returns:: A Language object or None
Return type:: Language or None

property legend: Legend | None

The legend is a box containing a symbol and name for each series item or point item in the chart. Each series (or points in case of pie charts) is represented by a symbol and its name in the legend.

class: `SharedOptions`

class SharedOptions(**kwargs)[source]

Python object which can be used to configure global settings that can apply to multiple Highcharts charts when serialized to JavaScript.

Class Inheritance

add_series(*series)

Adds series to the series property.

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

copy(other=None, overwrite=True, **kwargs)

Copy the configuration settings from this instance to the other instance.

Parameters:

other (HighchartsMeta) – The target instance to which the properties of this instance should be copied. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
kwargs – Additional keyword arguments. Some special descendents of HighchartsMeta may have special implementations of this method which rely on additional keyword arguments.

Returns:

A mutated version of other with new property values

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file, allow_snake_case: bool = True)

Construct an instance of the class from a JSON string.

Parameters:

as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

classmethod from_options(options)[source]

Create a SharedOptions instance from a HighchartsOptions object.

Parameters:: options (HighchartsOptions or coercable) – A HighchartsOptions object to use for the shared options instance.
Returns:: A SharedOptions instance
Return type:: SharedOptions

classmethod from_series(*series, kwargs=None)

Creates a new Options instance populated with series.

Parameters:

series (one or more SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one
kwargs (dict) –
Other properties to use as keyword arguments for the instance to be created.

Warning

If kwargs sets the .series property, that setting will be overridden by the contents of series.

Returns:

A new Options instance

Return type:

Options

get_required_modules(include_extension=False) → List[str]

Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list of str

to_dict() → dict

Generate a dict representation of the object compatible with the Highcharts JavaScript library.

Note

The dict representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8', careful_validation=False) → str | None[source]

Return the object represented as a str containing the

JavaScript object literal.

param filename:: The name of a file to which the JavaScript object literal should be persisted. Defaults to None
type filename:: Path-like
param encoding:: The character encoding to apply to the resulting object. Defaults to 'utf-8'.
type encoding:: str

Parameters:

careful_validation –

if True, will carefully validate JavaScript values along the way using the esprima-python library. Defaults to False.

Warning

Setting this value to True will significantly degrade serialization performance, though it may prove useful for debugging purposes.

to_json(filename=None, encoding='utf-8', for_export: bool = False)

Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

str or bytes

static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None, for_export: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Return type:

iterable

property accessibility: Accessibility | None

Options for configuring accessibility for the chart.

Note

Requires the accessibility module to be loaded in the browser. For a description of the module and information on its features, see Highcharts Accessibility.

Returns:: The accessibility configuration for the chart or None
Return type:: Accessibility / None
Raises:: HighchartsError – if setting the value to an incompatible type

property annotations: List[Annotation] | None

A basic type of an annotation. It allows adding custom labels or shapes. The items can be tied to points, axis coordinates or chart pixel coordinates.

Returns:: A collection of the annotations applied to the chart.
Return type:: list of Annotation objects or None if no annotations are applied

property boost: Boost | None

Options for the Boost module.

The Boost module allows certain series types to be rendered by WebGL instead of the default SVG. This allows hundreds of thousands of data points to be rendered in milliseconds. In addition to the WebGL rendering it saves time by skipping processing and inspection of the data wherever possible.

Warning

This introduces some limitations to what features are available in boost mode. See the docs for details.

Returns:: The Boost object.
Return type:: Boost

property caption: Caption | None

The chart’s caption, which will render below the chart and will be part of exported charts.

Note

The caption can be updated after chart initialization through the Chart.update or Chart.caption.update JavaScript methods.

Returns:: The chart’s caption or None
Return type:: Caption / None

property chart: ChartOptions | None

General options for the chart.

Note

This property is perhaps one of the most important properties you will use when configuring your Highcharts data visualization.

Returns:: A ChartOptions configuration object or None
Return type:: ChartOptions or None

property color_axis: List[ColorAxis] | None

A color axis for series.

Visually, the color axis will appear as a gradient or as separate items inside the legend, depending on whether the axis is scalar or based on data classes.

A scalar color axis is represented by a gradient. The colors either range between the minimum_color and the maximum_color, or for more fine grained control the colors can be defined in stops. Often times, the color axis needs to be adjusted to get the right color spread for the data. In addition to stops, consider using a logarithmic axis type, or setting min and max to avoid the colors being determined by outliers.

For supported color formats, please see the documentation article about colors.

When data_classes are used, the ranges are subdivided into separate classes like categories based on their values. This can be used for ranges between two values, but also for a true category. However, when your data is categorized, it may be as convenient to add each category to a separate series.

Warning

Color axis does not work with: sankey, sunburst, dependencywheel, networkgraph, wordcloud, venn, gauge and solidgauge series types.

See the Axis object for programmatic access to the axis.

Returns:: A collection of ColorAxis objects defining the color axis to apply, or None.
Return type:: list of ColorAxis or None

property colors: List[str | Gradient | Pattern] | None

An array containing the default colors for the chart’s series.

When all colors are used, new colors are pulled from the start again.

Default colors can also be set on a series or series.type basis, see Column.colors and Pie.colors.

Warning

In styled mode, the colors option does not exist.

Instead, colors are defined in CSS and applied either through series or point class names, or through the Chart.color_count option.

Defaults to:

[
    "#7cb5ec",
    "#434348",
    "#90ed7d",
    "#f7a35c",
    "#8085e9",
    "#f15c80",
    "#e4d354",
    "#2b908f",
    "#f45b5b",
    "#91e8e1"
]

Returns:: A collection of hex color strings.
Return type:: list of str

property credits: Credits | None

Highchart by default puts a credits label in the lower right corner of the chart. This can be changed using these options.

Returns:: Credits configuration or None
Return type:: Credits or None

property data: Data | None

The data property provides a simplified interface for adding data to a chart from sources like CVS, HTML tables, or grid views. See also the tutorial article on the Data module.

Warning

It requires the modules/data.js file to be loaded in the browser / client.

Warning

Please note that the default way of adding data in Highcharts, without the need of a module, is through the series.type.data property.

Returns:: The Data object or None
Return type:: Data object or None

property defs: MarkerDefinition | None

Options for configuring markers for annotations.

Returns:: A MarkerDefinition object or None
Return type:: MarkerDefinition or None

property drilldown: Drilldown | None

Options to configure drilldown functionality in the chart, which enables users to inspect increasingly high resolution data by clicking on chart items like columns or pie slices.

Note

The drilldown feature requires the drilldown.js file to be loaded in the browser/client. This file is found in the modules directory of the download package, or online at code.highcharts.com/modules/drilldown.js.

Returns:: The options to configure the chart’s drill down functionality.
Return type:: Drilldown or None

property exporting: Exporting | None

Options to configure the export functionality enabled for the chart.

Returns:: The configuration of the chart’s exporting functionality.
Return type:: Exporting or None

property language: Language | None

Language object which can be used to configure the specific text to use in the chart.

Note

When working in JavaScript, the lang configuration is global and it can’t be set on each chart initialization.

Instead, use Highcharts.setOptions() to set it before any chart is initialized.

Returns:: A Language object or None
Return type:: Language or None

property legend: Legend | None

The legend is a box containing a symbol and name for each series item or point item in the chart. Each series (or points in case of pie charts) is represented by a symbol and its name in the legend.

.shared_options

class: SharedMapsOptions

class: SharedOptions

`.shared_options`

class: `SharedMapsOptions`

class: `SharedOptions`