.shape_options

class: AnnotationShape

class AnnotationShape(**kwargs)[source]

Configuration for an annotation shape applied to a specific point.

Used to override the global settings configured in ShapeOptions and applied via Annotation.shape_options().

Class Inheritance:

Inheritance diagram of AnnotationShape
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 dash_style: str | None

Name of the dash style to use for the shape’s stroke.

Accepts the following values:

  • 'Solid'

  • 'ShortDash'

  • 'ShortDot'

  • 'ShortDashDot'

  • 'ShortDashDotDot'

  • 'Dot'

  • 'Dash'

  • 'LongDash'

  • 'DashDot'

  • 'LongDashDot'

  • 'LongDashDotDot'

Returns:

The name of the dash style to apply to the shape’s stroke.

Return type:

str or None

property fill: str | Gradient | Pattern | None

The color of the shape’s fill. Defaults to 'rgba(0, 0, 0, 0.75)'.

Return type:

str (for colors), Gradient for gradients, Pattern for pattern definitions, or None

property height: int | float | Decimal | None

The height of the shape in pixels.

Return type:

numeric or None

property marker_end: str | None

ID of the marker which will be drawn at the final vertex of the path.

Note

Custom markers can be defined in the Options.defs() property.

Return type:

str or None

property marker_start: str | None

ID of the marker which will be drawn at the first vertex of the path.

Note

Custom markers can be defined in the Options.defs() property.

Return type:

str or None

property point: str | AnnotationPoint | None

Determines the point to which the shape 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 points: List[CallbackFunction | AnnotationPoint | str] | None

An array of points for the shape or a JavaScript callback function that returns that shape point.

Note

This option is available for shapes which can use multiple points such as path. A point can be either a AnnotationPoint object or a point’s id.

Return type:

list of CallbackFunction or str or AnnotationPoint or str, OR None

property r: int | float | Decimal | None

The radius of the shape in pixels. Defaults to 0.

Return type:

numeric or None

property ry: int | float | Decimal | None

The radius of the shape along the vertical dimension. Used to draw ellipses.

Return type:

numeric or None

property snap: int | float | Decimal | None

Defines additional snapping area around an annotation making this annotation to focus. Defined in pixels.

Defaults to 2.

Return type:

numeric or None

property src: str | None

The URL for an image to use as the annotation shape.

Note

ShapeOptions.type() has to be set to 'image'.

Return type:

str or None

Raises:

HighchartsValueError – if a value is supplied that is not a URL or not path-like

property stroke: str | None

The color of the shape’s stroke. Defaults to 'rgba(0, 0, 0, 0.75)'.

Return type:

str or None

property stroke_width: int | float | Decimal | None

The pixel stroke width of the shape. Defaults to 1.

Return type:

numeric or None

property type: str | None

The type of the shape. Defaults to 'rect'.

Accepts:

  • 'rect'

  • 'circle'

  • 'ellipse'

  • 'image'

Returns:

str or None

Raises:

HighchartsValueError – if type not supported

property width: int | float | Decimal | None

The width of the shape, expressed in pixels.

Return type:

numeric or None

property x_axis: int | None

The X-Axis index to which the points should be attached.

Note

Used for the ellipse type

Return type:

int or None

Raises:

ValueError – if set to a negative value

property y_axis: int | None

The Y-Axis index to which the points should be attached.

Note

Used for the ellipse type

Return type:

int or None

Raises:

ValueError – if set to a negative value

class: ShapeOptions

class ShapeOptions(**kwargs)[source]

Global options applied to all annotation shapes.

Class Inheritance:

Inheritance diagram of ShapeOptions
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 dash_style: str | None

Name of the dash style to use for the shape’s stroke.

Accepts the following values:

  • 'Solid'

  • 'ShortDash'

  • 'ShortDot'

  • 'ShortDashDot'

  • 'ShortDashDotDot'

  • 'Dot'

  • 'Dash'

  • 'LongDash'

  • 'DashDot'

  • 'LongDashDot'

  • 'LongDashDotDot'

Returns:

The name of the dash style to apply to the shape’s stroke.

Return type:

str or None

property fill: str | Gradient | Pattern | None

The color of the shape’s fill. Defaults to 'rgba(0, 0, 0, 0.75)'.

Return type:

str (for colors), Gradient for gradients, Pattern for pattern definitions, or None

property height: int | float | Decimal | None

The height of the shape in pixels.

Return type:

numeric or None

property r: int | float | Decimal | None

The radius of the shape in pixels. Defaults to 0.

Return type:

numeric or None

property ry: int | float | Decimal | None

The radius of the shape along the vertical dimension. Used to draw ellipses.

Return type:

numeric or None

property snap: int | float | Decimal | None

Defines additional snapping area around an annotation making this annotation to focus. Defined in pixels.

Defaults to 2.

Return type:

numeric or None

property src: str | None

The URL for an image to use as the annotation shape.

Note

ShapeOptions.type() has to be set to 'image'.

Return type:

str or None

Raises:

HighchartsValueError – if a value is supplied that is not a URL or not path-like

property stroke: str | None

The color of the shape’s stroke. Defaults to 'rgba(0, 0, 0, 0.75)'.

Return type:

str or None

property stroke_width: int | float | Decimal | None

The pixel stroke width of the shape. Defaults to 1.

Return type:

numeric or None

property type: str | None

The type of the shape. Defaults to 'rect'.

Accepts:

  • 'rect'

  • 'circle'

  • 'ellipse'

  • 'image'

Returns:

str or None

Raises:

HighchartsValueError – if type not supported

property width: int | float | Decimal | None

The width of the shape, expressed in pixels.

Return type:

numeric or None

property x_axis: int | None

The X-Axis index to which the points should be attached.

Note

Used for the ellipse type

Return type:

int or None

Raises:

ValueError – if set to a negative value

property y_axis: int | None

The Y-Axis index to which the points should be attached.

Note

Used for the ellipse type

Return type:

int or None

Raises:

ValueError – if set to a negative value