.annotations

• .animation
• .control_point_options
• .events
• .label_options
• .points
• .shape_options

---

class: Annotation

class Annotation(**kwargs)

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

Class Inheritance

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

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

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

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=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.

Return type:

iterable

property animation: AnnotationAnimation | None

Enable or disable the initial animation when a series is displayed for the annotation. If not None, is enabled. Otherwise, disabled.

Warning

This option only applies to the initial animation.

For other animations, see chart.animation and the animation parameter under the API methods.

Returns:

The configuration settings for the annotation animation.

Return type:

AnnotationAnimation

property control_point_options: AnnotationControlPointOption | None

Options for annotation’s control points.

Each control point inherits options from this property, though the global options can be overwritten by options in a specific control point.

Returns:

Options configuring the annotations’ control points.

Return type:

AnnotationControlPointOption or None

property crop: bool | None

If True, hide the part of the annotation that is outside the plot area. Defaults to True.

Returns:

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

Return type:

bool or None

property draggable: str | None

Setting that allows an annotation to be draggable by a user. Defaults to 'xy'

Supports values:

• 'x'

• 'xy'

• 'y'

• '' (empty string - disables dragging)

Returns:

Configuration of annotation dragging by the user.

Return type:

str or None

Raises:

HighchartsValueError – if an unsupported value is supplied

property events: AnnotationEvent | None

JavaScript callback functions that fire in response to annotation-related events.

Returns:

Callback functions that fire in response to annotation-related events.

Return type:

AnnotationEvent or None

property id: str | None

Sets an ID for the annotation. Can be user later when removing an annotation using the JavaScript Chart.removeAnnotation(id) method.

Returns:

The ID for the annotation.

Return type:

str or None

property label_options: LabelOptions | None

Global options applied to all annotation labels.

Note

An option from the Annotation.label_options() can be overwritten by the configuration for a specific label.

Returns:

Configuration options for annotation labels.

Return type:

LabelOptions or None

property labels: List[AnnotationLabel] | None

An array of labels to display for annotations.

See also

• Annotation.label_options()

• LabelOptions

Returns:

A collection of labels to display for annotation.

Return type:

list of AnnotationLabel or None

property shape_options: ShapeOptions | None

Global options applied to all annotation shapes.

Note

An option from the Annotation.shape_options() can be overwritten by the configuration for a specific shape.

Returns:

Configuration options for annotation shapes.

Return type:

ShapeOptions or None

property shapes: List[AnnotationShape] | None

An array of shapes to display for annotations.

See also

• Annotation.shape_options()

• shapeOptions

Returns:

A collection of shapes to display for annotation.

Return type:

list of AnnotationShape or None

property visible: bool | None

If True, indicates the annotation is visible.

Returns:

Flag which indicates whether the annotation is visible or not.

Return type:

bool or None

property z_index: int | None

The Z-Index for the annotation. Defaults to 6.

Returns:

The z-index for the annotation.

Return type:

int or None

---

Sub-components

Module	Classes / Functions
.options.annotations	Annotation
.options.annotations.animation	AnnotationAnimation
.options.annotations.control_point_options	AnnotationControlPointOption
.options.annotations.events	AnnotationEvent
.options.annotations.label_options	AnnotationLabel AnnotationLabelOptionAccessibility LabelOptions
.options.annotations.options.annotations.points	AnnotationPoint
.options.annotations.shape_options	AnnotationShape ShapeOptions