.title


class: AxisTitle

class AxisTitle(**kwargs)[source]

The axis title, shown next to the axis line.

Class Inheritance
Inheritance diagram of AxisTitle

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

Alignment of the title relative to the axis values. Defaults to middle.

Accepts:

  • 'low'

  • 'middle'

  • 'high'

Return type:

str

property margin: int | float | Decimal | None

The distance (in pixels) between the axis labels or line and the title. Defaults to None, which applies 0 for horizontal axes and 10 for vertical axes.

Return type:

numeric or None

property offset: int | float | Decimal | None

The explicitly-provided distance of the axis title from the axis line. Defaults to None.

When None, this distance is computed from the offset width of the labels, the labels’ distance from the axis, and the title’s margin. However when the offset option is set, all this gets overridden.

Return type:

numeric or None

property position_3d: str | None

Defines how the title is to be repositioned according to the 3D chart orientation. Defaults to None which applies the setting from AxisLabeLOptions.position_3d().

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 title. Defaults to True.

Return type:

bool or None

property rotation: int | float | Decimal | None

Rotation of the title in degrees, where 0 is horizontal and 270 is vertical reading from bottom to top. Defaults to 0.

Return type:

numeric or None

property skew_3d: bool | None

If True, the title will skewed to follow the perspective. Defaults to None, which applies the same setting as set for AxisLabeLOptions.skew_3d().

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 style: str | dict | None

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

Hint

If the title length is longer than the axis length, the title will wrap by default. The following three methods can all prevent the title from wrapping in such a situation:

  • Setting "textOverflow: 'ellipsis'" in the style

  • Setting "whiteSpace: 'nowrap'" in the style

  • Setting an explicit AxisTitle.width()

Return type:

str or dict or None

property text: EnforcedNullType | str | None

The actual text of the title.

Note

A subset of HTML is supported, e.g. <b>, <i>, <span> (with in-line styles), etc.

Return type:

str or None

property text_align: str | None

The text alignment for the title. Defaults to None, which applies behavior based on the AxisTitle.align() setting and the axis orientation:

  • For Horizontal Axes:

    • when align == 'low', defaults to 'left'

    • when align == 'middle', defaults to 'center'

    • when align == 'high', defaults to 'right'

  • For Vertical Axes:

    • when align == 'low' and NumericAxis.opposite() is True, defaults to 'right'

    • when align == 'low' and NumericAxis.opposite() is False, defaults to 'left'

    • when align == 'middle', defaults to 'center'

    • when align == 'high' and NumericAxis.opposite() is True, defaults to 'left'

    • when align == 'high' and NumericAxis.opposite() is True, defaults to 'right'

Possible values are:

  • 'left'

  • 'center'

  • 'right'

Return type:

str or None

property use_html: bool | None

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

Defaults to False.

Returns:

Flag indicating whether to render the title using HTML.

Return type:

bool or None

property x: int | float | Decimal | None

The x position offset of the title. Defaults to 0.

Return type:

numeric or None

property y: int | float | Decimal | None

The y position offset of the title. Defaults to 0.

Return type:

numeric or None