.data_labels

class: DataLabel

class DataLabel(**kwargs)[source]

Options for the series data labels, appearing next to each data point.

Class Inheritance
Inheritance diagram of DataLabel

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

The alignment of the data label compared to the point. Defaults to None.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Hint

If right, the right side of the label should be touching the point.

Returns:

The alignment of the annotation’s label.

Return type:

str

property allow_overlap: bool | None

If True, data labels are allowed to overlap each other.

Defaults to False.

Hint

To make the labels less sensitive for overlapping, the DataLabel.padding() can be set to 0.

Returns:

Flag indicating whether to allow data labels to overlap.

Return type:

bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation for the data labels when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

  • defer: The animation delay time in milliseconds.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:

AnimationOptions or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the data label. Defaults to None.

Returns:

The backgorund color for the data label.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | None

The border color for the data label. Defaults to None

Returns:

The border color for the data label.

Return type:

str or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the data label. Defaults to 0.

Returns:

The border radius to apply to the data label.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the data label. Defaults to 0.

Returns:

The border width to apply to the data label.

Return type:

numeric or None

property class_name: str | None

A classname to apply styling using CSS. Defaults to 'highcharts-no-tooltip'.

Returns:

The classname to apply to enable styling via CSS.

Return type:

str or None

property color: str | None

The text color for the data labels. Defaults to None.

Note

For certain series types, like column or map, the data labels can be drawn inside the points. In this case the data label will be drawn with maximum contrast by default. Additionally, it will be given a text-outline style with the opposite color, to further increase the contrast. This can be overridden by setting the text-outline style to none in the DataLabel.style() setting.

Return type:

str or None

property crop: bool | None

If True, hide part of the data label that falls outside the plot area. Defaults to False.

Note

By default, the data label is moved inside the plot area as per the DataLabel.overflow() setting.

Returns:

Flag indicating whether to clip a data label that extends beyond the plot area.

Return type:

bool or None

property defer: bool | int | None

Whether to defer displaying the data labels until the initial series animation has finished. If None, behaves as if set to True.

Setting to False renders the data label immediately.

If set to True inherits the defer time set in PlotOptions.series.animation().

If set to a number, defers the animation by that number of milliseconds.

Return type:

bool or int or None

property enabled: bool | None

Enable or disable the data labels. Setting to None behaves as if set to False.

Return type:

bool or None

property filter: Filter | None

A declarative filter to control of which data labels to display.

The declarative filter is designed for use when JavaScript callback functions are not available, like when the chart options require a pure JSON structure or for use with graphical editors. For programmatic control, use the DataLabel.formatter() instead, and return undefined to disable a single data label.

Return type:

Filter or None

property format: str | None

A format string to apply to the label. Defaults to 'point.value'.

Warning

If your format string begins with { and ends with }, Highcharts for Python may interpret it as a JavaScript or JSON object. To prevent this, please add a $ before the opening curly brace, like so: ${value}.

Returns:

The format string to apply to the labels.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the data label. Defaults to None.

Note

If a DataLabel.format() is specified, the formatter will be ignored.

Returns:

A JavaScript callback function.

Return type:

CallbackFunction or None

property inside: bool | None

For points with an extent, like columns or map areas, whether to align the data label inside the box or to the actual value point. Defaults to :obj:`None <python:None>`, which behaves like ``False in most cases but True in stacked columns.

Return type:

bool or None

property null_format: str | None

Format for points with the value of null. Defaults to None.

Note

Works analogously to DataLabel.format().

Warning

Can only be applied only to series which support displaying null points.

Return type:

str or None

property null_formatter: CallbackFunction | None

JavaScript callback function to format the text of the data label for visible null points.

Note

Works analogously to DataLabel.formatter().

Warning

Can only be applied only to series which support displaying null points.

Return type:

CallbackFunction or None

property overflow: str | None

Configuration on how to handle a data label that overflows outside of the plot area. Defaults to 'justify', which aligns them inside the plot area. For columns and bars, this means the data label will be moved inside the bar.

Hint

To display data labels outside the plot area, set overflow to 'allow' and DataLabel.crop() to False.

Accepts:

  • 'justify' - which forces the label back into the plot area

  • 'allow' - which allows data labels to overflow outside of the plot area

Note

The overflow treatment is also affected by the DataLabel.crop() setting.

Returns:

Configuration of overflow setting.

Return type:

str or None

property padding: int | None

The padding within the border box when either DataLabel.border_width() or DataLabel.background_color() is set.

Defaults to 5.

Returns:

The padding to apply to the data label.

Return type:

int or None

property position: str | None

Aligns data labels relative to points. Defaults to 'center'.

Accepts the following values:

  • 'center' (the default)

  • 'left'

  • 'right'

Note

If center is not possible, aligns to right.

Return type:

str

property rotation: int | float | Decimal | None

Text rotation in degrees. Defaults to 0

Warning

Due to a more complex structure, backgrounds, borders and padding will be lost on a rotated data label.

Return type:

numeric or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the data label box. Defaults to False.

If False, no shadow is applied.

Returns:

The shadow configuration to apply or False.

Return type:

bool or ShadowOptions or None

property shape: str | None

The name of the symbol to use for the border around the label. Defaults to 'square'.

Accepts:

  • 'rect'

  • 'square'

  • 'circle'

  • 'diamond'

  • 'triangle'

  • 'callout'

Returns:

The shape to use for the border around the label.

Return type:

str or None

property style: dict | str | None

CSS styling to apply to the annotation’s label.

The default color setting is "contrast", which is a pseudo color that Highcharts picks up and applies the maximum contrast to the underlying point item, for example the bar in a bar chart.

textOutline is a pseudo property that applies an outline of the given width with the given color, which by default is the maximum contrast to the text. So a bright text color will result in a black text outline for maximum readability on a mixed background. In some cases, especially with grayscale text, the text outline doesn’t work well, in which cases it can be disabled by setting it to "none". When DataLabel.use_html() is True, the textOutline will not be picked up. In this, case, the same effect can be acheived through the text-shadow CSS property.

For some series types, where each point has an extent, like for example tree maps, the data label may overflow the point. There are two strategies for handling overflow. By default, the text will wrap to multiple lines. The other strategy is to set textOverflow to ellipsis, which will keep the text on one line plus it will break inside long words.

Return type:

dict or str or None

property text_path: TextPath | None

Options for a label text which should follow marker’s shape.

Note

Border and background are disabled for a label that follows a path.

Return type:

str or None

property use_html: bool | None

If True, will use HTML to render the data label. If False, will use SVG or WebGL as applicable.

Defaults to False.

Returns:

Flag indicating whether to render data labels using HTML.

Return type:

bool or None

property vertical_align: str | None

The vertical alignment of the annotation’s label. Defaults to None.

If None, the alignment will depend on the data. For example, in a column chart, the label would be above positive values and below negative values.

Accepts:

  • 'bottom'

  • 'middle'

  • 'top'

  • None

Return type:

str or None

property x: int | float | Decimal | None

The x position offset of the label relative to the point. Defaults to 0.

Return type:

numeric or None

property y: int | float | Decimal | None

The y position offset of the label relative to the point. Defaults to None.

Return type:

numeric

property z: int | None

The Z index of the data labels. Defaults to 6.

If None, will be placed above the series.

Hint

Use a Z index of 2 to display it behind the series.

Return type:

numeric or None

class: OrganizationDataLabel

class OrganizationDataLabel(**kwargs)[source]

Variant of DataLabel used for organization series.

Class Inheritance
Inheritance diagram of OrganizationDataLabel

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

The alignment of the data label compared to the point. Defaults to None.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Hint

If right, the right side of the label should be touching the point.

Returns:

The alignment of the annotation’s label.

Return type:

str

property allow_overlap: bool | None

If True, data labels are allowed to overlap each other.

Defaults to False.

Hint

To make the labels less sensitive for overlapping, the DataLabel.padding() can be set to 0.

Returns:

Flag indicating whether to allow data labels to overlap.

Return type:

bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation for the data labels when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

  • defer: The animation delay time in milliseconds.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:

AnimationOptions or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the data label. Defaults to None.

Returns:

The backgorund color for the data label.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | None

The border color for the data label. Defaults to None

Returns:

The border color for the data label.

Return type:

str or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the data label. Defaults to 0.

Returns:

The border radius to apply to the data label.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the data label. Defaults to 0.

Returns:

The border width to apply to the data label.

Return type:

numeric or None

property class_name: str | None

A classname to apply styling using CSS. Defaults to 'highcharts-no-tooltip'.

Returns:

The classname to apply to enable styling via CSS.

Return type:

str or None

property color: str | None

The text color for the data labels. Defaults to None.

Note

For certain series types, like column or map, the data labels can be drawn inside the points. In this case the data label will be drawn with maximum contrast by default. Additionally, it will be given a text-outline style with the opposite color, to further increase the contrast. This can be overridden by setting the text-outline style to none in the DataLabel.style() setting.

Return type:

str or None

property crop: bool | None

If True, hide part of the data label that falls outside the plot area. Defaults to False.

Note

By default, the data label is moved inside the plot area as per the DataLabel.overflow() setting.

Returns:

Flag indicating whether to clip a data label that extends beyond the plot area.

Return type:

bool or None

property defer: bool | int | None

Whether to defer displaying the data labels until the initial series animation has finished. If None, behaves as if set to True.

Setting to False renders the data label immediately.

If set to True inherits the defer time set in PlotOptions.series.animation().

If set to a number, defers the animation by that number of milliseconds.

Return type:

bool or int or None

property enabled: bool | None

Enable or disable the data labels. Setting to None behaves as if set to False.

Return type:

bool or None

property filter: Filter | None

A declarative filter to control of which data labels to display.

The declarative filter is designed for use when JavaScript callback functions are not available, like when the chart options require a pure JSON structure or for use with graphical editors. For programmatic control, use the DataLabel.formatter() instead, and return undefined to disable a single data label.

Return type:

Filter or None

property format: str | None

A format string to apply to the label. Defaults to 'point.value'.

Warning

If your format string begins with { and ends with }, Highcharts for Python may interpret it as a JavaScript or JSON object. To prevent this, please add a $ before the opening curly brace, like so: ${value}.

Returns:

The format string to apply to the labels.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the data label. Defaults to None.

Note

If a DataLabel.format() is specified, the formatter will be ignored.

Returns:

A JavaScript callback function.

Return type:

CallbackFunction or None

property inside: bool | None

For points with an extent, like columns or map areas, whether to align the data label inside the box or to the actual value point. Defaults to :obj:`None <python:None>`, which behaves like ``False in most cases but True in stacked columns.

Return type:

bool or None

The format string specifying what to show for links in the organization chart.

Tip

Best to use with .link_text_path enabled.

rtype:

str or None

JavaScript callback function to format data labels for links in the organization chart.

Note

The .link_format property takes precedence over the link_formatter.

Return type:

CallbackFunction or None

property link_text_path: TextPath | None

Options for a label text which should follow the link’s shape.

Note

Border and background are disabled for a label that follows a path.

Return type:

TextPath or None

property null_format: str | None

Format for points with the value of null. Defaults to None.

Note

Works analogously to DataLabel.format().

Warning

Can only be applied only to series which support displaying null points.

Return type:

str or None

property null_formatter: CallbackFunction | None

JavaScript callback function to format the text of the data label for visible null points.

Note

Works analogously to DataLabel.formatter().

Warning

Can only be applied only to series which support displaying null points.

Return type:

CallbackFunction or None

property overflow: str | None

Configuration on how to handle a data label that overflows outside of the plot area. Defaults to 'justify', which aligns them inside the plot area. For columns and bars, this means the data label will be moved inside the bar.

Hint

To display data labels outside the plot area, set overflow to 'allow' and DataLabel.crop() to False.

Accepts:

  • 'justify' - which forces the label back into the plot area

  • 'allow' - which allows data labels to overflow outside of the plot area

Note

The overflow treatment is also affected by the DataLabel.crop() setting.

Returns:

Configuration of overflow setting.

Return type:

str or None

property padding: int | None

The padding within the border box when either DataLabel.border_width() or DataLabel.background_color() is set.

Defaults to 5.

Returns:

The padding to apply to the data label.

Return type:

int or None

property position: str | None

Aligns data labels relative to points. Defaults to 'center'.

Accepts the following values:

  • 'center' (the default)

  • 'left'

  • 'right'

Note

If center is not possible, aligns to right.

Return type:

str

property rotation: int | float | Decimal | None

Text rotation in degrees. Defaults to 0

Warning

Due to a more complex structure, backgrounds, borders and padding will be lost on a rotated data label.

Return type:

numeric or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the data label box. Defaults to False.

If False, no shadow is applied.

Returns:

The shadow configuration to apply or False.

Return type:

bool or ShadowOptions or None

property shape: str | None

The name of the symbol to use for the border around the label. Defaults to 'square'.

Accepts:

  • 'rect'

  • 'square'

  • 'circle'

  • 'diamond'

  • 'triangle'

  • 'callout'

Returns:

The shape to use for the border around the label.

Return type:

str or None

property style: dict | str | None

CSS styling to apply to the annotation’s label.

The default color setting is "contrast", which is a pseudo color that Highcharts picks up and applies the maximum contrast to the underlying point item, for example the bar in a bar chart.

textOutline is a pseudo property that applies an outline of the given width with the given color, which by default is the maximum contrast to the text. So a bright text color will result in a black text outline for maximum readability on a mixed background. In some cases, especially with grayscale text, the text outline doesn’t work well, in which cases it can be disabled by setting it to "none". When DataLabel.use_html() is True, the textOutline will not be picked up. In this, case, the same effect can be acheived through the text-shadow CSS property.

For some series types, where each point has an extent, like for example tree maps, the data label may overflow the point. There are two strategies for handling overflow. By default, the text will wrap to multiple lines. The other strategy is to set textOverflow to ellipsis, which will keep the text on one line plus it will break inside long words.

Return type:

dict or str or None

property text_path: TextPath | None

Options for a label text which should follow marker’s shape.

Note

Border and background are disabled for a label that follows a path.

Return type:

str or None

property use_html: bool | None

If True, will use HTML to render the data label. If False, will use SVG or WebGL as applicable.

Defaults to False.

Returns:

Flag indicating whether to render data labels using HTML.

Return type:

bool or None

property vertical_align: str | None

The vertical alignment of the annotation’s label. Defaults to None.

If None, the alignment will depend on the data. For example, in a column chart, the label would be above positive values and below negative values.

Accepts:

  • 'bottom'

  • 'middle'

  • 'top'

  • None

Return type:

str or None

property x: int | float | Decimal | None

The x position offset of the label relative to the point. Defaults to 0.

Return type:

numeric or None

property y: int | float | Decimal | None

The y position offset of the label relative to the point. Defaults to None.

Return type:

numeric

property z: int | None

The Z index of the data labels. Defaults to 6.

If None, will be placed above the series.

Hint

Use a Z index of 2 to display it behind the series.

Return type:

numeric or None

class: PieDataLabel

class PieDataLabel(**kwargs)[source]

Variant of DataLabel used for pie (and related) series.

Class Inheritance
Inheritance diagram of PieDataLabel

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

The alignment of the data label compared to the point. Defaults to None.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Hint

If right, the right side of the label should be touching the point.

Returns:

The alignment of the annotation’s label.

Return type:

str

property allow_overlap: bool | None

If True, data labels are allowed to overlap each other.

Defaults to False.

Hint

To make the labels less sensitive for overlapping, the DataLabel.padding() can be set to 0.

Returns:

Flag indicating whether to allow data labels to overlap.

Return type:

bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation for the data labels when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

  • defer: The animation delay time in milliseconds.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:

AnimationOptions or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the data label. Defaults to None.

Returns:

The backgorund color for the data label.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | None

The border color for the data label. Defaults to None

Returns:

The border color for the data label.

Return type:

str or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the data label. Defaults to 0.

Returns:

The border radius to apply to the data label.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the data label. Defaults to 0.

Returns:

The border width to apply to the data label.

Return type:

numeric or None

property class_name: str | None

A classname to apply styling using CSS. Defaults to 'highcharts-no-tooltip'.

Returns:

The classname to apply to enable styling via CSS.

Return type:

str or None

property color: str | None

The text color for the data labels. Defaults to None.

Note

For certain series types, like column or map, the data labels can be drawn inside the points. In this case the data label will be drawn with maximum contrast by default. Additionally, it will be given a text-outline style with the opposite color, to further increase the contrast. This can be overridden by setting the text-outline style to none in the DataLabel.style() setting.

Return type:

str or None

property crop: bool | None

If True, hide part of the data label that falls outside the plot area. Defaults to False.

Note

By default, the data label is moved inside the plot area as per the DataLabel.overflow() setting.

Returns:

Flag indicating whether to clip a data label that extends beyond the plot area.

Return type:

bool or None

property defer: bool | int | None

Whether to defer displaying the data labels until the initial series animation has finished. If None, behaves as if set to True.

Setting to False renders the data label immediately.

If set to True inherits the defer time set in PlotOptions.series.animation().

If set to a number, defers the animation by that number of milliseconds.

Return type:

bool or int or None

property distance: int | float | Decimal | str | None

The distance of the data label from the pie’s edge.

Note

Negative numbers put the data label on top of the pie slices.

Tip

Can also be defined as a percentage of pie’s radius.

Warning

Connectors are only shown for data labels outside the pie.

Return type:

numeric or str or None

property enabled: bool | None

Enable or disable the data labels. Setting to None behaves as if set to False.

Return type:

bool or None

property filter: Filter | None

A declarative filter to control of which data labels to display.

The declarative filter is designed for use when JavaScript callback functions are not available, like when the chart options require a pure JSON structure or for use with graphical editors. For programmatic control, use the DataLabel.formatter() instead, and return undefined to disable a single data label.

Return type:

Filter or None

property format: str | None

A format string to apply to the label. Defaults to 'point.value'.

Warning

If your format string begins with { and ends with }, Highcharts for Python may interpret it as a JavaScript or JSON object. To prevent this, please add a $ before the opening curly brace, like so: ${value}.

Returns:

The format string to apply to the labels.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the data label. Defaults to None.

Note

If a DataLabel.format() is specified, the formatter will be ignored.

Returns:

A JavaScript callback function.

Return type:

CallbackFunction or None

property inside: bool | None

For points with an extent, like columns or map areas, whether to align the data label inside the box or to the actual value point. Defaults to :obj:`None <python:None>`, which behaves like ``False in most cases but True in stacked columns.

Return type:

bool or None

property null_format: str | None

Format for points with the value of null. Defaults to None.

Note

Works analogously to DataLabel.format().

Warning

Can only be applied only to series which support displaying null points.

Return type:

str or None

property null_formatter: CallbackFunction | None

JavaScript callback function to format the text of the data label for visible null points.

Note

Works analogously to DataLabel.formatter().

Warning

Can only be applied only to series which support displaying null points.

Return type:

CallbackFunction or None

property overflow: str | None

Configuration on how to handle a data label that overflows outside of the plot area. Defaults to 'justify', which aligns them inside the plot area. For columns and bars, this means the data label will be moved inside the bar.

Hint

To display data labels outside the plot area, set overflow to 'allow' and DataLabel.crop() to False.

Accepts:

  • 'justify' - which forces the label back into the plot area

  • 'allow' - which allows data labels to overflow outside of the plot area

Note

The overflow treatment is also affected by the DataLabel.crop() setting.

Returns:

Configuration of overflow setting.

Return type:

str or None

property padding: int | None

The padding within the border box when either DataLabel.border_width() or DataLabel.background_color() is set.

Defaults to 5.

Returns:

The padding to apply to the data label.

Return type:

int or None

property position: str | None

Aligns data labels relative to points. Defaults to 'center'.

Accepts the following values:

  • 'center' (the default)

  • 'left'

  • 'right'

Note

If center is not possible, aligns to right.

Return type:

str

property rotation: int | float | Decimal | None

Text rotation in degrees. Defaults to 0

Warning

Due to a more complex structure, backgrounds, borders and padding will be lost on a rotated data label.

Return type:

numeric or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the data label box. Defaults to False.

If False, no shadow is applied.

Returns:

The shadow configuration to apply or False.

Return type:

bool or ShadowOptions or None

property shape: str | None

The name of the symbol to use for the border around the label. Defaults to 'square'.

Accepts:

  • 'rect'

  • 'square'

  • 'circle'

  • 'diamond'

  • 'triangle'

  • 'callout'

Returns:

The shape to use for the border around the label.

Return type:

str or None

property style: dict | str | None

CSS styling to apply to the annotation’s label.

The default color setting is "contrast", which is a pseudo color that Highcharts picks up and applies the maximum contrast to the underlying point item, for example the bar in a bar chart.

textOutline is a pseudo property that applies an outline of the given width with the given color, which by default is the maximum contrast to the text. So a bright text color will result in a black text outline for maximum readability on a mixed background. In some cases, especially with grayscale text, the text outline doesn’t work well, in which cases it can be disabled by setting it to "none". When DataLabel.use_html() is True, the textOutline will not be picked up. In this, case, the same effect can be acheived through the text-shadow CSS property.

For some series types, where each point has an extent, like for example tree maps, the data label may overflow the point. There are two strategies for handling overflow. By default, the text will wrap to multiple lines. The other strategy is to set textOverflow to ellipsis, which will keep the text on one line plus it will break inside long words.

Return type:

dict or str or None

property text_path: TextPath | None

Options for a label text which should follow marker’s shape.

Note

Border and background are disabled for a label that follows a path.

Return type:

str or None

property use_html: bool | None

If True, will use HTML to render the data label. If False, will use SVG or WebGL as applicable.

Defaults to False.

Returns:

Flag indicating whether to render data labels using HTML.

Return type:

bool or None

property vertical_align: str | None

The vertical alignment of the annotation’s label. Defaults to None.

If None, the alignment will depend on the data. For example, in a column chart, the label would be above positive values and below negative values.

Accepts:

  • 'bottom'

  • 'middle'

  • 'top'

  • None

Return type:

str or None

property x: int | float | Decimal | None

The x position offset of the label relative to the point. Defaults to 0.

Return type:

numeric or None

property y: int | float | Decimal | None

The y position offset of the label relative to the point. Defaults to None.

Return type:

numeric

property z: int | None

The Z index of the data labels. Defaults to 6.

If None, will be placed above the series.

Hint

Use a Z index of 2 to display it behind the series.

Return type:

numeric or None

class: SunburstDataLabel

class SunburstDataLabel(**kwargs)[source]

Variant of DataLabel used for sunburst series.

Class Inheritance
Inheritance diagram of SunburstDataLabel

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

The alignment of the data label compared to the point. Defaults to None.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Hint

If right, the right side of the label should be touching the point.

Returns:

The alignment of the annotation’s label.

Return type:

str

property allow_overlap: bool | None

If True, data labels are allowed to overlap each other.

Defaults to False.

Hint

To make the labels less sensitive for overlapping, the DataLabel.padding() can be set to 0.

Returns:

Flag indicating whether to allow data labels to overlap.

Return type:

bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation for the data labels when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

  • defer: The animation delay time in milliseconds.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:

AnimationOptions or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the data label. Defaults to None.

Returns:

The backgorund color for the data label.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | None

The border color for the data label. Defaults to None

Returns:

The border color for the data label.

Return type:

str or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the data label. Defaults to 0.

Returns:

The border radius to apply to the data label.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the data label. Defaults to 0.

Returns:

The border width to apply to the data label.

Return type:

numeric or None

property class_name: str | None

A classname to apply styling using CSS. Defaults to 'highcharts-no-tooltip'.

Returns:

The classname to apply to enable styling via CSS.

Return type:

str or None

property color: str | None

The text color for the data labels. Defaults to None.

Note

For certain series types, like column or map, the data labels can be drawn inside the points. In this case the data label will be drawn with maximum contrast by default. Additionally, it will be given a text-outline style with the opposite color, to further increase the contrast. This can be overridden by setting the text-outline style to none in the DataLabel.style() setting.

Return type:

str or None

property crop: bool | None

If True, hide part of the data label that falls outside the plot area. Defaults to False.

Note

By default, the data label is moved inside the plot area as per the DataLabel.overflow() setting.

Returns:

Flag indicating whether to clip a data label that extends beyond the plot area.

Return type:

bool or None

property defer: bool | int | None

Whether to defer displaying the data labels until the initial series animation has finished. If None, behaves as if set to True.

Setting to False renders the data label immediately.

If set to True inherits the defer time set in PlotOptions.series.animation().

If set to a number, defers the animation by that number of milliseconds.

Return type:

bool or int or None

property enabled: bool | None

Enable or disable the data labels. Setting to None behaves as if set to False.

Return type:

bool or None

property filter: Filter | None

A declarative filter to control of which data labels to display.

The declarative filter is designed for use when JavaScript callback functions are not available, like when the chart options require a pure JSON structure or for use with graphical editors. For programmatic control, use the DataLabel.formatter() instead, and return undefined to disable a single data label.

Return type:

Filter or None

property format: str | None

A format string to apply to the label. Defaults to 'point.value'.

Warning

If your format string begins with { and ends with }, Highcharts for Python may interpret it as a JavaScript or JSON object. To prevent this, please add a $ before the opening curly brace, like so: ${value}.

Returns:

The format string to apply to the labels.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the data label. Defaults to None.

Note

If a DataLabel.format() is specified, the formatter will be ignored.

Returns:

A JavaScript callback function.

Return type:

CallbackFunction or None

property inside: bool | None

For points with an extent, like columns or map areas, whether to align the data label inside the box or to the actual value point. Defaults to :obj:`None <python:None>`, which behaves like ``False in most cases but True in stacked columns.

Return type:

bool or None

property null_format: str | None

Format for points with the value of null. Defaults to None.

Note

Works analogously to DataLabel.format().

Warning

Can only be applied only to series which support displaying null points.

Return type:

str or None

property null_formatter: CallbackFunction | None

JavaScript callback function to format the text of the data label for visible null points.

Note

Works analogously to DataLabel.formatter().

Warning

Can only be applied only to series which support displaying null points.

Return type:

CallbackFunction or None

property overflow: str | None

Configuration on how to handle a data label that overflows outside of the plot area. Defaults to 'justify', which aligns them inside the plot area. For columns and bars, this means the data label will be moved inside the bar.

Hint

To display data labels outside the plot area, set overflow to 'allow' and DataLabel.crop() to False.

Accepts:

  • 'justify' - which forces the label back into the plot area

  • 'allow' - which allows data labels to overflow outside of the plot area

Note

The overflow treatment is also affected by the DataLabel.crop() setting.

Returns:

Configuration of overflow setting.

Return type:

str or None

property padding: int | None

The padding within the border box when either DataLabel.border_width() or DataLabel.background_color() is set.

Defaults to 5.

Returns:

The padding to apply to the data label.

Return type:

int or None

property position: str | None

Aligns data labels relative to points. Defaults to 'center'.

Accepts the following values:

  • 'center' (the default)

  • 'left'

  • 'right'

Note

If center is not possible, aligns to right.

Return type:

str

property rotation: int | float | Decimal | None

Text rotation in degrees. Defaults to 0

Warning

Due to a more complex structure, backgrounds, borders and padding will be lost on a rotated data label.

Return type:

numeric or None

property rotation_mode: str | None

Determines how the data label will be rotated relative to the perimeter of the sunburst.

Valid values are:

  • 'circular'

  • 'auto'

  • 'parallel'

  • 'perpendicular'.

Defaults to 'circular'.

Note

When 'circular', the best fit will be computed for the point, so that the label is curved around the center when there is room for it, otherwise perpendicular.

The legacy 'auto' option works similiarly to 'circular', but instead of curving the labels, they are tangented to the perimiter.

Warning

The .rotation property takes precedence over .rotation_mode.

Return type:

str or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the data label box. Defaults to False.

If False, no shadow is applied.

Returns:

The shadow configuration to apply or False.

Return type:

bool or ShadowOptions or None

property shape: str | None

The name of the symbol to use for the border around the label. Defaults to 'square'.

Accepts:

  • 'rect'

  • 'square'

  • 'circle'

  • 'diamond'

  • 'triangle'

  • 'callout'

Returns:

The shape to use for the border around the label.

Return type:

str or None

property style: dict | str | None

CSS styling to apply to the annotation’s label.

The default color setting is "contrast", which is a pseudo color that Highcharts picks up and applies the maximum contrast to the underlying point item, for example the bar in a bar chart.

textOutline is a pseudo property that applies an outline of the given width with the given color, which by default is the maximum contrast to the text. So a bright text color will result in a black text outline for maximum readability on a mixed background. In some cases, especially with grayscale text, the text outline doesn’t work well, in which cases it can be disabled by setting it to "none". When DataLabel.use_html() is True, the textOutline will not be picked up. In this, case, the same effect can be acheived through the text-shadow CSS property.

For some series types, where each point has an extent, like for example tree maps, the data label may overflow the point. There are two strategies for handling overflow. By default, the text will wrap to multiple lines. The other strategy is to set textOverflow to ellipsis, which will keep the text on one line plus it will break inside long words.

Return type:

dict or str or None

property text_path: TextPath | None

Options for a label text which should follow marker’s shape.

Note

Border and background are disabled for a label that follows a path.

Return type:

str or None

property use_html: bool | None

If True, will use HTML to render the data label. If False, will use SVG or WebGL as applicable.

Defaults to False.

Returns:

Flag indicating whether to render data labels using HTML.

Return type:

bool or None

property vertical_align: str | None

The vertical alignment of the annotation’s label. Defaults to None.

If None, the alignment will depend on the data. For example, in a column chart, the label would be above positive values and below negative values.

Accepts:

  • 'bottom'

  • 'middle'

  • 'top'

  • None

Return type:

str or None

property x: int | float | Decimal | None

The x position offset of the label relative to the point. Defaults to 0.

Return type:

numeric or None

property y: int | float | Decimal | None

The y position offset of the label relative to the point. Defaults to None.

Return type:

numeric

property z: int | None

The Z index of the data labels. Defaults to 6.

If None, will be placed above the series.

Hint

Use a Z index of 2 to display it behind the series.

Return type:

numeric or None

class: NodeDataLabel

class NodeDataLabel(**kwargs)[source]

Variant of DataLabel used for node-based charts/diagrams.

Class Inheritance
Inheritance diagram of NodeDataLabel

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

The alignment of the data label compared to the point. Defaults to None.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Hint

If right, the right side of the label should be touching the point.

Returns:

The alignment of the annotation’s label.

Return type:

str

property allow_overlap: bool | None

If True, data labels are allowed to overlap each other.

Defaults to False.

Hint

To make the labels less sensitive for overlapping, the DataLabel.padding() can be set to 0.

Returns:

Flag indicating whether to allow data labels to overlap.

Return type:

bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation for the data labels when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

  • defer: The animation delay time in milliseconds.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:

AnimationOptions or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the data label. Defaults to None.

Returns:

The backgorund color for the data label.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | None

The border color for the data label. Defaults to None

Returns:

The border color for the data label.

Return type:

str or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the data label. Defaults to 0.

Returns:

The border radius to apply to the data label.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the data label. Defaults to 0.

Returns:

The border width to apply to the data label.

Return type:

numeric or None

property class_name: str | None

A classname to apply styling using CSS. Defaults to 'highcharts-no-tooltip'.

Returns:

The classname to apply to enable styling via CSS.

Return type:

str or None

property color: str | None

The text color for the data labels. Defaults to None.

Note

For certain series types, like column or map, the data labels can be drawn inside the points. In this case the data label will be drawn with maximum contrast by default. Additionally, it will be given a text-outline style with the opposite color, to further increase the contrast. This can be overridden by setting the text-outline style to none in the DataLabel.style() setting.

Return type:

str or None

property crop: bool | None

If True, hide part of the data label that falls outside the plot area. Defaults to False.

Note

By default, the data label is moved inside the plot area as per the DataLabel.overflow() setting.

Returns:

Flag indicating whether to clip a data label that extends beyond the plot area.

Return type:

bool or None

property defer: bool | int | None

Whether to defer displaying the data labels until the initial series animation has finished. If None, behaves as if set to True.

Setting to False renders the data label immediately.

If set to True inherits the defer time set in PlotOptions.series.animation().

If set to a number, defers the animation by that number of milliseconds.

Return type:

bool or int or None

property enabled: bool | None

Enable or disable the data labels. Setting to None behaves as if set to False.

Return type:

bool or None

property filter: Filter | None

A declarative filter to control of which data labels to display.

The declarative filter is designed for use when JavaScript callback functions are not available, like when the chart options require a pure JSON structure or for use with graphical editors. For programmatic control, use the DataLabel.formatter() instead, and return undefined to disable a single data label.

Return type:

Filter or None

property format: str | None

A format string to apply to the label. Defaults to 'point.value'.

Warning

If your format string begins with { and ends with }, Highcharts for Python may interpret it as a JavaScript or JSON object. To prevent this, please add a $ before the opening curly brace, like so: ${value}.

Returns:

The format string to apply to the labels.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the data label. Defaults to None.

Note

If a DataLabel.format() is specified, the formatter will be ignored.

Returns:

A JavaScript callback function.

Return type:

CallbackFunction or None

property inside: bool | None

For points with an extent, like columns or map areas, whether to align the data label inside the box or to the actual value point. Defaults to :obj:`None <python:None>`, which behaves like ``False in most cases but True in stacked columns.

Return type:

bool or None

property node_format: str | None

The format string which determines what to render for nodes in a sankey, organization, or similar diagram. Defaults to None.

Return type:

str or None

property node_formatter: CallbackFunction | None

JavaScript callback function to format data labels for nodes in a sankey or organization diagram. Defaults to None.

Note

The node_format takes precedence over the node_formatter.

Return type:

CallbackFunction or None

property null_format: str | None

Format for points with the value of null. Defaults to None.

Note

Works analogously to DataLabel.format().

Warning

Can only be applied only to series which support displaying null points.

Return type:

str or None

property null_formatter: CallbackFunction | None

JavaScript callback function to format the text of the data label for visible null points.

Note

Works analogously to DataLabel.formatter().

Warning

Can only be applied only to series which support displaying null points.

Return type:

CallbackFunction or None

property overflow: str | None

Configuration on how to handle a data label that overflows outside of the plot area. Defaults to 'justify', which aligns them inside the plot area. For columns and bars, this means the data label will be moved inside the bar.

Hint

To display data labels outside the plot area, set overflow to 'allow' and DataLabel.crop() to False.

Accepts:

  • 'justify' - which forces the label back into the plot area

  • 'allow' - which allows data labels to overflow outside of the plot area

Note

The overflow treatment is also affected by the DataLabel.crop() setting.

Returns:

Configuration of overflow setting.

Return type:

str or None

property padding: int | None

The padding within the border box when either DataLabel.border_width() or DataLabel.background_color() is set.

Defaults to 5.

Returns:

The padding to apply to the data label.

Return type:

int or None

property position: str | None

Aligns data labels relative to points. Defaults to 'center'.

Accepts the following values:

  • 'center' (the default)

  • 'left'

  • 'right'

Note

If center is not possible, aligns to right.

Return type:

str

property rotation: int | float | Decimal | None

Text rotation in degrees. Defaults to 0

Warning

Due to a more complex structure, backgrounds, borders and padding will be lost on a rotated data label.

Return type:

numeric or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the data label box. Defaults to False.

If False, no shadow is applied.

Returns:

The shadow configuration to apply or False.

Return type:

bool or ShadowOptions or None

property shape: str | None

The name of the symbol to use for the border around the label. Defaults to 'square'.

Accepts:

  • 'rect'

  • 'square'

  • 'circle'

  • 'diamond'

  • 'triangle'

  • 'callout'

Returns:

The shape to use for the border around the label.

Return type:

str or None

property style: dict | str | None

CSS styling to apply to the annotation’s label.

The default color setting is "contrast", which is a pseudo color that Highcharts picks up and applies the maximum contrast to the underlying point item, for example the bar in a bar chart.

textOutline is a pseudo property that applies an outline of the given width with the given color, which by default is the maximum contrast to the text. So a bright text color will result in a black text outline for maximum readability on a mixed background. In some cases, especially with grayscale text, the text outline doesn’t work well, in which cases it can be disabled by setting it to "none". When DataLabel.use_html() is True, the textOutline will not be picked up. In this, case, the same effect can be acheived through the text-shadow CSS property.

For some series types, where each point has an extent, like for example tree maps, the data label may overflow the point. There are two strategies for handling overflow. By default, the text will wrap to multiple lines. The other strategy is to set textOverflow to ellipsis, which will keep the text on one line plus it will break inside long words.

Return type:

dict or str or None

property text_path: TextPath | None

Options for a label text which should follow marker’s shape.

Note

Border and background are disabled for a label that follows a path.

Return type:

str or None

property use_html: bool | None

If True, will use HTML to render the data label. If False, will use SVG or WebGL as applicable.

Defaults to False.

Returns:

Flag indicating whether to render data labels using HTML.

Return type:

bool or None

property vertical_align: str | None

The vertical alignment of the annotation’s label. Defaults to None.

If None, the alignment will depend on the data. For example, in a column chart, the label would be above positive values and below negative values.

Accepts:

  • 'bottom'

  • 'middle'

  • 'top'

  • None

Return type:

str or None

property x: int | float | Decimal | None

The x position offset of the label relative to the point. Defaults to 0.

Return type:

numeric or None

property y: int | float | Decimal | None

The y position offset of the label relative to the point. Defaults to None.

Return type:

numeric

property z: int | None

The Z index of the data labels. Defaults to 6.

If None, will be placed above the series.

Hint

Use a Z index of 2 to display it behind the series.

Return type:

numeric or None

class: Filter

class Filter(**kwargs)[source]

A declarative filter to control of which data labels to display.

The declarative filter is designed for use when JavaScript callback functions are not available, like when the chart options require a pure JSON structure or for use with graphical editors. For programmatic control, use the DataLabel.formatter() instead, and return undefined to disable a single data label.

Class Inheritance
Inheritance diagram of Filter

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

The operator to compare by. Defaults to None.

Accepts:

  • '>'

  • '<'

  • '>='

  • '<='

  • '=='

  • '==='

Return type:

str or None

property property_: str | None

The point property to filter by. Defaults to None.

Point options are passed directly to properties, additionally there are y value, percentage.

Return type:

str or None

property value: int | float | Decimal | None

The value to compare against. Defaults to None.

Return type:

str or None