.series

class: SeriesLanguageOptions

class SeriesLanguageOptions(**kwargs)[source]

Language configuration for different series types.

Hint

For more dynamic control over the series element descriptions, see Accessibility.series_description_formatter().

Class Inheritance
Inheritance diagram of SeriesLanguageOptions

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

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

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.

Return type:

str or None

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 description: str | None

User supplied description text. Defaults to: ''.

Note

This is added in the point comment description by default if present.

Return type:

str or None

property null_point_value: str | None

Description for the value of null points. Defaults to: ''.

Return type:

str or None

property point_annotations_description: str | None

Description for annotations on a point, as it is made available to assistive technology. Defaults to: ''.

Return type:

str or None

property summary: SeriesSummaryLanguageOptions | None

Language configuration for the series main summary.

Each series type has two modes:

  1. This series type is the only series type used in the chart

  2. This is a combination chart with multiple series types

Note

If a definition does not exist for the specific series type and mode, the 'default' language definitions are used.

Chart and its subproperties can be accessed with the {chart} variable. The series and its subproperties can be accessed with the {series} variable.

The series index (starting from 1) can be accessed with the {seriesNumber} variable.

Return type:

SeriesSummaryLanguageOptions or None

property x_axis_description: str | None

xAxis description for series if there are multiple xAxes in the chart. Defaults to: ''.

Return type:

str or None

property y_axis_description: str | None

yAxis description for series if there are multiple yAxes in the chart. Defaults to: ''.

Return type:

str or None

class: SeriesSummaryLanguageOptions

class SeriesSummaryLanguageOptions(**kwargs)[source]

Language configuration for the series main summary.

Each series type has two modes:

  1. This series type is the only series type used in the chart

  2. This is a combination chart with multiple series types

Note

If a definition does not exist for the specific series type and mode, the 'default' language definitions are used.

Chart and its subproperties can be accessed with the {chart} variable. The series and its subproperties can be accessed with the {series} variable.

The series index (starting from 1) can be accessed with the {seriesNumber} variable.

Class Inheritance
Inheritance diagram of SeriesSummaryLanguageOptions

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

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

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.

Return type:

str or None

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 bar: str | None

Defaults to '{series.name}, bar series {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, bars, bar)}.'.

Return type:

str or None

property bar_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Bar series with {series.points.length} {#plural(series.points.length, bars, bar)}.'.

Return type:

str or None

property boxplot: str | None

Defaults to '{series.name}, boxplot {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, boxes, box)}.'.

Return type:

str or None

property boxplot_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Boxplot with {series.points.length} {#plural(series.points.length, boxes, box)}.'.

Return type:

str or None

property bubble: str | None

Defaults to '{series.name}, bubble series {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, bubbles, bubble)}.'.

Return type:

str or None

property bubble_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Bubble series with {series.points.length} {#plural(series.points.length, bubbles, bubble)}.'.

Return type:

str or None

property column: str | None

Defaults to '{series.name}, bar series {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, bars, bar)}.'.

Return type:

str or None

property column_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Bar series with {series.points.length} {#plural(series.points.length, bars, bar)}.'.

Return type:

str or None

property default: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length} with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property default_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length} with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property line: str | None

Defaults to '{series.name}, line {seriesNumber} of {chart.series.length} with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property line_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Line with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property map: str | None

Defaults to '{series.name}, map {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, areas, area)}.'.

Return type:

str or None

property map_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Map with {series.points.length} {#plural(series.points.length, areas, area)}.'.

Return type:

str or None

property mapbubble: str | None

Defaults to '{series.name}, bubble series {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, bubbles, bubble)}.'.

Return type:

str or None

property mapbubble_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Bubble series with {series.points.length} {#plural(series.points.length, bubbles, bubble)}.'.

Return type:

str or None

property mapline: str | None

Defaults to '{series.name}, line {seriesNumber} of {chart.series.length} with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property mapline_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Line with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property pie: str | None

Defaults to '{series.name}, pie {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, slices, slice)}.'.

Return type:

str or None

property pie_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Pie with {series.points.length} {#plural(series.points.length, slices, slice)}.'.

Return type:

str or None

property scatter: str | None

Defaults to '{series.name}, scatter plot {seriesNumber} of {chart.series.length} with {series.points.length} {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property scatter_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}, scatter plot with {series.points.length} {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property spline: str | None

Defaults to '{series.name}, line {seriesNumber} of {chart.series.length} with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

property spline_combination: str | None

Defaults to '{series.name}, series {seriesNumber} of {chart.series.length}. Line with {series.points.length} data {#plural(series.points.length, points, point)}.'.

Return type:

str or None

class: SeriesTypeDescriptions

class SeriesTypeDescriptions(**kwargs)[source]

Descriptions of lesser known series types. The relevant description is added to the screen reader information region when these series types are used.

Class Inheritance
Inheritance diagram of SeriesTypeDescriptions

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

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

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.

Return type:

str or None

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 arearange: str | None

Defaults to 'Arearange charts are line charts displaying a range between a lower and higher value for each point.'.

Return type:

str or None

property areasplinerange: str | None

Defaults to 'These charts are line charts displaying a range between a lower and higher value for each point.'.

Return type:

str or None

property boxplot: str | None

Defaults to 'Box plot charts are typically used to display groups of statistical data. Each data point in the chart can have up to 5 values: minimum, lower quartile, median, upper quartile, and maximum.'.

Return type:

str or None

property bubble: str | None

Defaults to 'Bubble charts are scatter charts where each data point also has a size value.'.

Return type:

str or None

property columnrange: str | None

Defaults to 'Columnrange charts are column charts displaying a range between a lower and higher value for each point.'.

Return type:

str or None

property errorbar: str | None

Defaults to 'Errorbar series are used to display the variability of the data.'.

Return type:

str or None

property funnel: str | None

Defaults to 'Funnel charts are used to display reduction of data in stages.'.

Return type:

str or None

property pyramid: str | None

Defaults to 'Pyramid charts consist of a single pyramid with item heights corresponding to each point value.'.

Return type:

str or None

property waterfall: str | None

Defaults to 'A waterfall chart is a column chart where each column contributes towards a total end value.'.

Return type:

str or None