.label_options

class: AnnotationLabel

class AnnotationLabel(**kwargs)[source]

Configuration for an annotation label applied to a specific point.

Used to override the global settings configured in LabelOptions and applied via Annotation.label_options().

Class Inheritance
Inheritance diagram of AnnotationLabel

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')

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'.

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) → 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.

Returns:

Trimmed dict

Return type:

dict

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

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.

Return type:

iterable

property accessibility: AnnotationLabelOptionAccessibility | None

Accessibility options applied to an annotation label.

Returns:

Accessibility options applied to an annotation label.

Return type:

AnnotationLabelOptionAccessibility or None

property align: str | None

The alignment of the annotation’s label. Defaults to 'center'.

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 or None

property allow_overlap: bool | None

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

Defaults to False.

Returns:

Flag indicating whether to allow annotation labels to overlap.

Return type:

bool or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the annotation’s label. Defaults to 'rgba(0, 0, 0, 0.75)'.

Returns:

The backgorund color for the annotation’s label.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | None

The border color for the annotation’s label. Defaults to '#000000'.

Returns:

The border color for the annotation’s label.

Return type:

str or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the annotation’s label. Defaults to 3.

Returns:

The border radius to apply to the annotation’s label.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the annotation’s label. Defaults to 1.

Returns:

The border width to apply to the annotation’s 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 crop: bool | None

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

Returns:

Flag indicating whether to clip an annotation label that extends beyond the plot area.

Return type:

bool or None

property distance: int | float | Decimal | None

The label’s distance in pixels from the point.

Returns:

The label’s distance in pixels from the point.

Return type:

numeric or None

property format: str | None

A format string to apply to the label.

Returns:

The format string to apply to the labels.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the annotation’s label.

Defaults to function () { return defined(this.y) ? this.y : 'Annotation label'; }.

Note

If a LabelOptions.format() or LabelOptions.text() value are specified, the formatter will be ignored.

Hint

In the callback function, the use of this refers to a point object.

Returns:

A JavaScript callback function.

Return type:

CallbackFunction or None

property include_in_data_export: bool | None

If True, the annotation is visible in the exported data table. Defaults to True.

Returns:

Flag indicating whether to include the annotation label in the chart’s exported data table.

Return type:

bool or None

property overflow: str | None

Configuration on how to handle an annotation label that overflows outside of the plot area. Defaults to 'justify'.

Accepts:

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

  • 'none' - which applies no change

Note

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

Returns:

Configuration of overflow setting.

Return type:

str or None

property padding: int | None

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

Defaults to 5.

Returns:

The padding to apply to the annotation label.

Return type:

int or None

property point: str | AnnotationPoint | None

Determines the point to which the label will be connected.

It can be either the ID of the point which exists in the series, or a new point with defined x, y properties and optionally axes.

Return type:

str or AnnotationPoint or None

Raises:

HighchartsValueError – if cannot resolve the value to an allowed type

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the annotation 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 'callout'.

Accepts:

  • 'connector'

  • 'rect'

  • 'circle'

  • 'diamond'

  • 'triangle'

  • 'callout'

Returns:

The shape to use for the border around the label.

Return type:

str or None

property style: str | dict | None

CSS styling to apply to the annotation’s label.

Return type:

str or None

property text: str | None

Alias for the LabelOptions.format() property.

Returns:

The format string to apply to the labels.

Return type:

str or None

property use_html: bool | None

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

Defaults to False.

Returns:

Flag indicating whether to render annotation labels using HTML.

Return type:

bool or None

property vertical_align: str | None

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

Accepts:

  • 'bottom'

  • 'middle'

  • 'top'

Return type:

str or None

property x: int | None

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

Note

If a LabelOptions.distance() is defined, the distance takes precedence.

Return type:

numeric or None

property y: int | None

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

Note

If a LabelOptions.distance() is defined, the distance takes precedence.

Return type:

numeric or None

class: AnnotationLabelOptionAccessibility

class AnnotationLabelOptionAccessibility(**kwargs)[source]

Accessibility options applied to an annotation label.

Class Inheritance
Inheritance diagram of AnnotationLabelOptionAccessibility

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')

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'.

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) → 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.

Returns:

Trimmed dict

Return type:

dict

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

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.

Return type:

iterable

property description: str | None

Description of an annotation label for screen readers and other assistive technology.

Returns:

Description of an annotation label

Return type:

str or None

class: LabelOptions

class LabelOptions(**kwargs)[source]

Options applied to all annotation labels.

Class Inheritance
Inheritance diagram of LabelOptions

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')

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'.

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) → 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.

Returns:

Trimmed dict

Return type:

dict

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

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.

Return type:

iterable

property accessibility: AnnotationLabelOptionAccessibility | None

Accessibility options applied to an annotation label.

Returns:

Accessibility options applied to an annotation label.

Return type:

AnnotationLabelOptionAccessibility or None

property align: str | None

The alignment of the annotation’s label. Defaults to 'center'.

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 or None

property allow_overlap: bool | None

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

Defaults to False.

Returns:

Flag indicating whether to allow annotation labels to overlap.

Return type:

bool or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the annotation’s label. Defaults to 'rgba(0, 0, 0, 0.75)'.

Returns:

The backgorund color for the annotation’s label.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | None

The border color for the annotation’s label. Defaults to '#000000'.

Returns:

The border color for the annotation’s label.

Return type:

str or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the annotation’s label. Defaults to 3.

Returns:

The border radius to apply to the annotation’s label.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the annotation’s label. Defaults to 1.

Returns:

The border width to apply to the annotation’s 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 crop: bool | None

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

Returns:

Flag indicating whether to clip an annotation label that extends beyond the plot area.

Return type:

bool or None

property distance: int | float | Decimal | None

The label’s distance in pixels from the point.

Returns:

The label’s distance in pixels from the point.

Return type:

numeric or None

property format: str | None

A format string to apply to the label.

Returns:

The format string to apply to the labels.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the annotation’s label.

Defaults to function () { return defined(this.y) ? this.y : 'Annotation label'; }.

Note

If a LabelOptions.format() or LabelOptions.text() value are specified, the formatter will be ignored.

Hint

In the callback function, the use of this refers to a point object.

Returns:

A JavaScript callback function.

Return type:

CallbackFunction or None

property include_in_data_export: bool | None

If True, the annotation is visible in the exported data table. Defaults to True.

Returns:

Flag indicating whether to include the annotation label in the chart’s exported data table.

Return type:

bool or None

property overflow: str | None

Configuration on how to handle an annotation label that overflows outside of the plot area. Defaults to 'justify'.

Accepts:

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

  • 'none' - which applies no change

Note

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

Returns:

Configuration of overflow setting.

Return type:

str or None

property padding: int | None

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

Defaults to 5.

Returns:

The padding to apply to the annotation label.

Return type:

int or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the annotation 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 'callout'.

Accepts:

  • 'connector'

  • 'rect'

  • 'circle'

  • 'diamond'

  • 'triangle'

  • 'callout'

Returns:

The shape to use for the border around the label.

Return type:

str or None

property style: str | dict | None

CSS styling to apply to the annotation’s label.

Return type:

str or None

property text: str | None

Alias for the LabelOptions.format() property.

Returns:

The format string to apply to the labels.

Return type:

str or None

property use_html: bool | None

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

Defaults to False.

Returns:

Flag indicating whether to render annotation labels using HTML.

Return type:

bool or None

property vertical_align: str | None

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

Accepts:

  • 'bottom'

  • 'middle'

  • 'top'

Return type:

str or None

property x: int | None

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

Note

If a LabelOptions.distance() is defined, the distance takes precedence.

Return type:

numeric or None

property y: int | None

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

Note

If a LabelOptions.distance() is defined, the distance takes precedence.

Return type:

numeric or None