.labels

class: AxisLabelOptions

class AxisLabelOptions(**kwargs)[source]

Settings for the axis labels, which show the number or category for each tick.

Class Inheritance
Inheritance diagram of AxisLabelOptions

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

The part of the string the given position is anchored to. If 'left', the left side of the string is at the axis position. Defaults to None, which leads Highcharts to determine the label alignment based on which side of the chart the axis is placed on and the rotation of the label.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Return type:

str

property allow_overlap: bool | None

If True, allows the axis labels to overlap. When False, overlapping labels are hidden. Defaults to False.

Return type:

bool

property auto_rotation: List[int | float | Decimal | Type[None]] | None

For horizontal axes, provides the allowed degrees of label rotation to prevent overlapping labels.

If there is enough space, labels are not rotated. As the chart gets narrower, it will start rotating the labels by the measurements contained in auto_rotation in sequence. If they still do not fit, then Highcharts will start removing every second label, and rotating through the sequence again, etc.

Include None in the collection to disable automatic rotation, at that step in the sequence - which will cause the labels to word-wrap if possible.

If set to None, defaults to [-45] on bottom and top axes, and None (word-wrapping) on left and right axes.

Return type:

None, or list of numeric/None values

property auto_rotation_limit: int | None

The category width threshold at which auto rotation ceases to be applied. When each category width is more than this many pixels, auto rotation is not applied. Instead, the axis label is laid out with word wrapping. Defaults to 80.

Hint

A lower limit makes sense when the label contains multiple short words that don’t extend the available horizontal space for each label.

Return type:

int

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

The label’s pixel distance from the perimeter of the plot area.

Changed in version Highcharts: for Python v.1.2.0 + Highcharts Core (JS) v.11.1

If not specified, defaults to 8.

Warning

On cartesian charts, this is overridden if the .x property is set.

On polar charts, if it’s a percentage string, it is interpreted the same as SolidGaugeOptions.radius, so that the label can be aligned under the gauge’s shape.

Return type:

numeric, str, or None

property enabled: bool | None

Enable or disable the axis labels. Setting to None behaves as if set to True.

Return type:

bool or None

property format: str | None

Format string that is applied to the axis labels. Defaults to None.

Context is available as format string variables. For example, you can use '{text}' to insert the default formatted text. The recommended way of adding units for the label is using text, for example '{text} km'.

To add custom numeric or datetime formatting, use '{value}' with formatting, for example '{value:.1f}' or '{value:%Y-%m-%d}'.

Return type:

str or None

property formatter: CallbackFunction | None

JavaScript callback function to format the axis label. Defaults to None, which applies a built-in function which returns a formatted string depending on whether the axis is a category, datetime, linear/logarithmic, etc. axis type.

Note

The value is available in (JavaScript) this.value. Additional properties for this are axis, chart, isFirst, isLast, and text which holds the value of the default formatter.

Return type:

str or None

property overflow: str | None

Configuration on how to handle an axis label on the horizontal axis that overflows. If set to 'allow', it will not be aligned at all. Defaults to 'justify', which attempts to align the label to the edge of the axis and on failure removes the label.

Accepts:

  • 'justify' - which attempts to fit the label to the edge of the axis

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

Return type:

str or None

property padding: int | float | Decimal | None

The padding for axis labels, expressed in pixels (used to ensure white space between the labels). Defaults to 5.

Return type:

int or None

property position_3d: str | None

Defines how the labels are to be repositioned according to the 3D chart orientation. Defaults to 'offset'.

Accepts the following values:

  • 'offset' (the default) - maintains a fixed horizontal/vertical distance from the tick marks, despite the chart orientation. This is backwards-compatible behavior, and causes skewing of X and Z axes.

  • 'chart' - preserve the 3D position relative to the chart. This looks nice, but it is hard to read if the text isn’t forward-facing.

  • 'flap' - rotated text along the axis to compensate for the chart orientation. This tries to maintain text as legible as possible on all orientations.

  • 'ortho' - rotates text along the axis direction so that the labels are orthogonal to the axis. This is very similar to 'flap', but prevents skewing the labels (X and Y scaling are still present).

Return type:

str or None

property reserve_space: bool | None

If True, reserve space for the labels. If None, by default space is reserved for the labels in these cases:

This can be turned off (set to False), for example, when the labels are rendered inside the plot area instead of outside.

Return type:

bool or None

property rotation: int | float | Decimal | None

Rotation of the axis label in degrees. When None, the auto_rotation setting takes precedence but otherwise defaults to 0.

Return type:

numeric or None

property skew_3d: bool | None

If True, the axis labels will skewed to follow the perspective. Defaults to False.

Note

Setting this to True will fix overlapping labels and titles, but texts become less legible due to the distortion. The final appearance depends heavily on position_3d.

Return type:

bool or None

property stagger_lines: int | None

The number of lines to spread the labels over to make room or tighter labels. Defaults to 0.

Hint

Setting the value to 0 disables staggering.

Warning

Only applies to horizontal axes only.

Return type:

int or None

property step: int | None

To show only every n th label on the axis, set the step to n. For example, setting the step to 2 will render every other label. Defaults to 0.

Warning

When set to 0, the step is automatically calculated to avoid overlap. To prevent this behavior, set to 1. This usually only happens on a category axis, and is often a sign that you have chosen the wrong axis type.

Return type:

int or None

property style: str | dict | None

CSS styling to apply to the axis label. Defaults to None.

Hint

Use "whiteSpace: 'nowrap'" to prevent wrapping of category labels.

Hint

Use "textOverflow: 'one'" to prevent ellipsis (three dots).

Return type:

str or dict or None

property use_html: bool | None

If True, will use HTML to render the axis 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 x: int | float | Decimal | None

The x position offset of all labels relative to the tick positions on the axis.

Changed in version Highcharts: Core for Python v.2.0.0 / Highcharts Core (JS) v.11.

Note

If set, overrides the .distance property.

Return type:

numeric or None

property y: int | float | Decimal | None

The y position offset of all labels relative to the tick positions on the axis. Defaults to None, which makes it adapt to the font size of the bottom axis.

Return type:

numeric or None

property z_index: int | float | Decimal | None

The Z index for the axis labels. Defaults to 7.

Return type:

numeric or None

class: PlotBandLabel

class PlotBandLabel(**kwargs)[source]

Text label for a Plot Band.

Class Inheritance
Inheritance diagram of PlotBandLabel

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

Horizontal alignment of the label.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Return type:

str

property rotation: int | float | Decimal | None

Rotation of the label in degrees. Defaults to 0.

Return type:

numeric or None

property style: str | dict | None

CSS styling to apply to the label. Defaults to None.

Return type:

str or None

property text: str | None

The string text itself.

Note

A subset of HTML is supported, e.g. <b>, <i>, etc.

Return type:

str or None

property text_align: str | None

The text alignment for the label. Defaults to None, which applies the same value as the PlotBandLabel.align() setting.

Note

While PlotBandLabel.align() determines where the text’s anchor point is placed within the plot band, text_align determines how the text is aligned against its anchor point.

Possible values are:

  • 'left'

  • 'center'

  • 'right'

Return type:

str

property use_html: bool | None

If True, will use HTML to render the 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

Vertical alignment of the label relative to the plot band. Defaults to 'top'.

Accepts:

  • 'top'

  • 'middle'

  • 'bottom'

Return type:

str or None

property x: int | float | Decimal | None

The horizontal position offset relative to the alignment position. Defaults to None, which adjusts the default based on the chart’s orientation.

Return type:

numeric or None

property y: int | float | Decimal | None

Vertical position of the text baseline, relative to the vertical alignment. Defaults to None, which adjusts the default behavior based on the chart’s orientation.

Return type:

numeric or None

class: PlotLineLabel

class PlotLineLabel(**kwargs)[source]

Text label applied to a Plot Line.

Class Inheritance
Inheritance diagram of PlotLineLabel

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

Horizontal alignment of the label.

Accepts:

  • 'left'

  • 'center'

  • 'right'

Return type:

str

property formatter: CallbackFunction | None

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

Hint

Useful properties like the value of the plot line or the range of the plot band (PlotBand.from() & to properties) can be found in the (JavaScript) this.options object.

Return type:

CallbackFunction or None

property rotation: int | float | Decimal | None

Rotation of the label in degrees. Defaults to 0.

Return type:

numeric or None

property style: str | dict | None

CSS styling to apply to the label. Defaults to None.

Return type:

str or None

property text: str | None

The string text itself.

Note

A subset of HTML is supported, e.g. <b>, <i>, etc.

Return type:

str or None

property text_align: str | None

The text alignment for the label. Defaults to None, which applies the same value as the PlotBandLabel.align() setting.

Note

While PlotBandLabel.align() determines where the text’s anchor point is placed within the plot band, text_align determines how the text is aligned against its anchor point.

Possible values are:

  • 'left'

  • 'center'

  • 'right'

Return type:

str

property use_html: bool | None

If True, will use HTML to render the 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

Vertical alignment of the label relative to the plot band. Defaults to 'top'.

Accepts:

  • 'top'

  • 'middle'

  • 'bottom'

Return type:

str or None

property x: int | float | Decimal | None

The horizontal position offset relative to the alignment position. Defaults to None, which adjusts the default based on the chart’s orientation.

Return type:

numeric or None

property y: int | float | Decimal | None

Vertical position of the text baseline, relative to the vertical alignment. Defaults to None, which adjusts the default behavior based on the chart’s orientation.

Return type:

numeric or None