.treegraph

class: TreegraphOptions

class TreegraphOptions(**kwargs)[source]

General options to apply to all Treegraph series types.

A treegraph visualizes a relationship between ancestors and descendants with a clear parent-child relationship, e.g. a family tree or a directory structure.

Treegraph Example Chart
Class Inheritance
Inheritance diagram of TreegraphOptions

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: TypeOptionsAccessibility | None

Accessibility options for a series.

Return type:

TypeOptionsAccessibility or None

property allow_point_select: bool | None

Allow this series’ points to be selected by clicking on the graphic (columns, point markers, pie slices, map areas etc).

The selected points can be handled in JavaScript by point select and unselect events, or collectively by the (JavaScript) getSelectedPoints() function.

And alternative way of selecting points is through dragging.

Defaults to False.

Return type:

bool or None

property allow_traversing_tree: bool | None

If True, the user can click on a point which is a parent and zoom in on its children. Defaults to False.

Return type:

bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

  • defer: The animation delay time in milliseconds.

  • duration: The duration of the animation in milliseconds.

  • easing: Can be a string reference to an easing function set on the Math object or a function.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:

AnimationOptions or None

property animation_limit: int | float | Decimal | None

For some series, there is a limit that shuts down initial animation by default when the total number of points in the chart is too high. Defaults to None.

For example, for a column chart and its derivatives, animation does not run if there is more than 250 points totally. To disable this cap, set animation_limit to float("inf") (which represents infinity).

Return type:

numeric or None

property boost_blending: str | None

Sets the color blending in the boost module. Defaults to None.

Return type:

str or None

property boost_threshold: int | None

Set the point threshold for when a series should enter boost mode. Defaults to 5000.

Setting it to e.g. 2000 will cause the series to enter boost mode when there are 2,000 or more points in the series.

To disable boosting on the series, set the boost_threshold to 0. Setting it to 1 will force boosting.

Note

The AreaOptions.crop_threshold() also affects this setting.

When zooming in on a series that has fewer points than the crop_threshold, all points are rendered although outside the visible plot area, and the boost_threshold won’t take effect.

Return type:

int or None

property class_name: str | None

The additional CSS class name to apply to the series’ graphical elements.

Note

This option is additive to the default class names - it does not replace them.

Return type:

str or None

property clip: bool | None

If False, allows the series to be rendered in the entire plot area. If True, constrains where the series can be rendered within the plot area. Defaults to True.

Return type:

bool or None

property collapse_button: CollapseButtonConfiguration | None

Options applied to the Collapse Button, which is the small button that indicates the node is collapsible.

Return type:

CollapseButtonConfiguration or None

property color: str | Gradient | Pattern | None

The main color of the series.

In line type series it applies to the line and the point markers unless otherwise specified. In bar type series it applies to the bars unless a color is specified per point. The default value is pulled from the Options.colors() array.

Returns:

The main color applied to the series.

Return type:

str, Gradient, Pattern`, or None

property color_by_point: bool | None

When using automatic point colors pulled from the global colors or series-specific collections, this option determines whether the chart should receive one color per series (False) or one color per point (True).

Defaults to True.

Return type:

bool or None

property color_index: int | None

When operating in styled mode, a specific color index to use for the series, so that its graphic representations are given the class name highcharts-color-{n}.

Tip

New in version Highcharts: (JS) v.11

With Highcharts (JS) v.11, using CSS variables of the form --highcharts-color-{n} make changing the color scheme very simple.

Defaults to None.

Return type:

int or None

property compare: str | None

Determines whether to display the 'percent' or the 'value' of the indicator’s comparison against the main series. Defaults to None, which does not calculate the comparison.

Accepts:

  • 'percent' - returns the percentage calculation for the indicator

  • 'value' - returns the axis value calculation for the indicator

Return type:

str or None

property compare_base: int | None

When .compare is set to 'percent', this option determines whether to use 0 or 100 as the basis of comparison. Defaults to 0.

Accepts:

  • 0

  • 100

Return type:

int or None

property compare_start: bool | None

If True, the first point in the visible range will be used for the comparative calculation, essentially starting from 0. If False, the comparison will be performed based on the data point immediately prior to the visible range. Defaults to False.

Return type:

bool or None

property crisp: bool | None

If True, each point or column edge is rounded to its nearest pixel in order to render sharp on screen. Defaults to True.

Hint

In some cases, when there are a lot of densely packed columns, this leads to visible difference in column widths or distance between columns. In these cases, setting crisp to False may look better, even though each column is rendered blurry.

Return type:

bool or None

property crop_threshold: int | None

When the series contains less points than the crop threshold, all points are drawn, even if the points fall outside the visible plot area at the current zoom. Defaults to 300.

The advantage of drawing all points (including markers and columns), is that animation is performed on updates. On the other hand, when the series contains more points than the crop threshold, the series data is cropped to only contain points that fall within the plot area. The advantage of cropping away invisible points is to increase performance on large series.

Return type:

int or None

property cumulative: bool | None

If True, replaces points’ values with the following (logcical) formula:

sum of all previous visible points' values + current point's value

Caution

This calculation is only applied to points in the visible range.

If False, the point values remain unchanged and are presented as-is. Defaults to False.

Note

In JavaScript, each point object for the series will now have a new property - .cumulativeSum - available for use in formatter callback functions or format strings.

Return type:

bool or None

property cursor: str | None

The style of cursor to use when the user’s mouse hovers over the data series.

Acceptable values are:

  • 'alias'

  • 'all-scroll'

  • 'auto'

  • 'cell'

  • 'col-resize'

  • 'context-menu'

  • 'copy'

  • 'crosshair'

  • 'default'

  • 'e-resize'

  • 'ew-resize'

  • 'grab'

  • 'grabbing'

  • 'help'

  • 'move'

  • 'n-resize'

  • 'ne-resize'

  • 'nesw-resize'

  • 'no-drop'

  • 'none'

  • 'not-allowed'

  • 'ns-resize'

  • 'nw-resize'

  • 'nwse-resize'

  • 'pointer'

  • 'progress'

  • 'row-resize'

  • 's-resize'

  • 'se-resize'

  • 'sw-resize'

  • 'text'

  • 'vertical-text'

  • 'w-resize'

  • 'wait'

  • 'zoom-in'

  • 'zoom-out'

Return type:

str or None

property custom: JavaScriptDict | None

A reserved subspace to store options and values for customized functionality.

Here you can add additional data for your own event callbacks and formatter callbacks.

Return type:

dict or None

property dash_style: str | None

Name of the dash style to use for the graph, or for some series types the outline of each shape.

Accepts one of the following values:

  • ‘Dash’,

  • ‘DashDot’,

  • ‘Dot’,

  • ‘LongDash’,

  • ‘LongDashDot’,

  • ‘LongDashDotDot’,

  • ‘ShortDash’,

  • ‘ShortDashDot’,

  • ‘ShortDashDotDot’,

  • ‘ShortDot’,

  • ‘Solid’

Return type:

str or None

property data_as_columns: bool | None

If True, indicates that the data is structured as columns instead of as rows. Defaults to False.

Return type:

bool or None

property data_grouping: DataGroupingOptions | None

Data grouping configures sampling the data values into larger blocks in order to ease readability and increase performance of the JavaScript charts.

Highcharts Stock by default applies data grouping when the points become closer than the number of pixels specified by the .group_pixel_width setting.

Note

If data grouping is applied, the grouping information of grouped points can be read (in JavaScript) from Point.dataGroup.

Caution

If point options other than the data itself are set, for example name, color, or custom properties, the grouping logic will not know how to group it. In this case, the options of the first point instance are copied over to the group point. This can be altered through a custom approximation function.

property data_labels: DataLabel | List[DataLabel] | None

Options for the series data labels, appearing next to each data point.

Note

To have multiple data labels per data point, you can also supply a collection of DataLabel configuration settings.

Return type:

DataLabel, list of DataLabel, or None

property description: str | None

A description of the series to add to the screen reader information about the series.

Return type:

str or None

property enable_mouse_tracking: bool | None

If True, enables mouse tracking for the series (used to capture point tooltips, click events on graphs and points, etc.). If False, disables mouse tracking for the series (which can help performance). Defaults to True.

Return type:

bool or None

property events: TreegraphEvents | None

General event handlers for the series items.

Note

These event hooks can also be attached to the series at run time using the (JavaScript) Highcharts.addEvent() function.

Return type:

TreegraphEvents or None

property fill_space: bool | None

If True, the treegraph series should fill the entire plot area in the X-axis direction, even when there are collapsed points. Defaults to False.

Return type:

bool

property find_nearest_point_by: str | None

Determines whether the series should look for the nearest point in both dimensions or just the x-dimension when hovering the series.

If None, defaults to 'xy' for scatter series and 'x' for most other series. If the data has duplicate x-values, it is recommended to set this to 'xy' to allow hovering over all points.

Applies only to series types using nearest neighbor search (not direct hover) for tooltip.

Return type:

str or None

property gap_size: int | float | Decimal | None

In combination with .gap_unit defines when to display a gap in the graph. Defaults to 0.

Note

If .data_grouping is enabled, points can be grouped into a larger time span. This can make the grouped points have a greater distance than the absolute value of the .gap_size property, which would result in data disappearing from view completely. To prevent this situation, the mentioned distance between grouped points is applied rather than the explicitly supplied .gap_size.

Tip

In practice, this option is most often used to visualize gaps in time series. In a stock chart, intraday data is available for daytime hours, while gaps will appear in nights and weekends.

Return type:

numeric or None

property gap_unit: str | None

In combination with .gap_size defines when to display a gap in the graph. Defaults to 'relative'.

Accepts two possible values:

  • 'relative' - determines the gap based on a multiple of .gap_size. For example, with a .gap_size of 5, if the distance between two points is greater than 5x the two closest points, a gap will be rendered.

  • 'value' - determines the gap based on the absolute axis values, which on a datetime axis are expressed in milliseconds.

Return type:

str or None

property get_extremes_from_all: bool | None

If True, uses the Y extremes of the total chart width or only the zoomed area when zooming in on parts of the X axis. By default, the Y axis adjusts to the min and max of the visible data.

Warning

Applies to Cartesian series only.

Return type:

bool or None

property include_in_data_export: bool | None

If False, will prevent the data series from being included in any form of data export. Defaults to True.

Return type:

bool or None

property keys: List[str] | None

An array specifying which option maps to which key in the data point array.

This makes it convenient to work with unstructured data arrays from different sources.

Return type:

list of str, or None

property label: SeriesLabel | None

Series labels are placed as close to the series as possible in a natural way, seeking to avoid other series. The goal of this feature is to make the chart more easily readable, like if a human designer placed the labels in the optimal position.

Note

The series labels currently work with series types having a graph or an area.

Return type:

SeriesLabel or None

property last_price: LastPriceOptions | None

Configuration of a line marking the last price from all data points (whether visible or not). Defaults to None.

Return type:

LastPriceOptions or None

property last_visible_price: LastPriceOptions | None

Configuration of a line marking the last price from all visible data points. Defaults to None.

See also

Return type:

LastPriceOptions or None

property legend_symbol: str | None

The type of legend symbol to render for the series. Accepts either 'lineMarker' or 'rectangle'. Defaults to 'rectangle'.

Return type:

str

property levels: List[TreegraphLevelOptions] | None

Set options on specific levels.

Note

Takes precedence over series options, but not point options.

Return type:

TreemapLevelOptions or None

Link style options.

Return type:

LinkOptions or None

property linked_to: str | None

The id of another series to link to.

Hint

The value can be ':previous' to link to the previous series. When two series are linked, only the first one appears in the legend. Toggling the visibility of this also toggles the linked series.

Note

If the master series uses data sorting and linked series does not have its own sorting definition, the linked series will be sorted in the same order as the master one.

Return type:

str or None

property marker: Marker | None

Options for the point markers of line-like series.

Properties like fill_color, line_color and line_width define the visual appearance of the markers. Other series types, like column series, don’t have markers, but have visual options on the series level instead.

Return type:

Marker or None

property navigator_options: Navigator | None

Options for the corresponding navigator series if .show_in_navigator is True for this series. Defaults to None

Note

These options are merged with options in navigator.series, and will take precedence if the same option is defined both places.

Return type:

NavigatorOptions or None

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

The distance between nodes in a treegraph diagram in the longitudinal direction. Defaults to 30.

Note

The longitudinal direction means the direction that the chart flows - in a horizontal chart the distance is horizontal, in an inverted chart (vertical), the distance is vertical.

If a number is given, it denotes pixels. If a percentage string is given, the distance is a percentage of the rendered node width. A value of 100% will render equal widths for the nodes and the gaps between them.

Note

This option applies only when the .node_width option is 'auto', making the node width respond to the number of columns.

Return type:

str or numeric or None

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

The pixel width of each node in a treegraph, or the height in case the chart is inverted. Defaults to None.

For tree graphs, the node width is only applied if the marker symbol is 'rect', otherwise the marker sizing options apply.

Can be a number or a percentage string, or 'auto'. If 'auto', the nodes are sized to fill up the plot area in the longitudinal direction, regardless of the number of levels.

Return type:

str or numeric or None

property on_point: OnPointOptions | None

Options for the Series on point feature, which is currently only supported by pie and sunburst chargs.

Return type:

OnPointOptions or None

property opacity: float | None

Opacity of a series parts: line, fill (e.g. area), and labels.

Return type:

float

property point: Point | None

Properties for each single point.

Return type:

Point or None

property point_description_formatter: CallbackFunction | None

Same as for Accessibility.series.description_formatter(), only for an individual series. Overrides the chart-wide configuration.

Return type:

CallbackFunction or None

property point_interval: int | float | Decimal | None

If no x values are given for the points in a series, point_interval defines the interval of the x values. Defaults to 1.

For example, if a series contains one value every decade starting from year 0, set point_interval to 10. In true datetime axes, the point_interval is set in milliseconds.

Hint

point_interval can be also be combined with point_interval_unit to draw irregular time intervals.

Note

If combined with relative_x_value, an x value can be set on each point, and the point_interval is added x times to the point_start setting.

Warning

This options applies to the series data, not the interval of the axis ticks, which is independent.

Return type:

numeric or None

property point_interval_unit: str | None

On datetime series, this allows for setting the point_interval to irregular time units, day, month, and year.

A day is usually the same as 24 hours, but point_interval_unit also takes the DST crossover into consideration when dealing with local time.

Combine this option with point_interval to draw weeks, quarters, 6 month periods, 10 year periods, etc.

Warning

This options applies to the series data, not the interval of the axis ticks, which is independent.

Return type:

str or None

property point_range: EnforcedNullType | int | float | Decimal | None

The X axis range that each point is valid for, which determines the width of the column. Defaults to EnforcedNull, which computes the range automatically.

On a categorized axis, the range will be 1 by default (one category unit). On linear and datetime axes, the range will be computed as the distance between the two closest data points.

The default EnforcedNull means it is computed automatically, but the setting can be used to override the default value.

Note

If data_sorting is enabled, the default value is implicitly adjusted to 1.

Return type:

numeric or EnforcedNullType or None

property point_start: int | float | Decimal | None

If no x values are given for the points in a series, point_start defines on what value to start. For example, if a series contains one yearly value starting from 1945, set point_start to 1945. Defaults to 0.

Note

If combined with relative_x_value, an x value can be set on each point. The x value from the point options is multiplied by point_interval and added to point_start to produce a modified x value.

Return type:

numeric or None

property relative_x_value: bool | None

When True, X values in the data set are relative to the current point_start, point_interval, and point_interval_unit settings. This allows compression of the data for datasets with irregular X values. Defaults to False.

The real X values are computed on the formula f(x) = ax + b, where a is the point_interval (optionally with a time unit given by point_interval_unit), and b is the point_start.

Return type:

bool or None

property reversed: bool | None

If True, places the series on the other side of the plot area. Defaults to False.

Return type:

bool or None

property selected: bool | None

If True, the series is selected initially (by default, without user interaction). Defaults to False.

Note

If GenericTypeOptions.show_checkbox() is True, then the checkbox will be checked if selected is True.

Return type:

bool or None

property show_checkbox: bool | None

If True, a checkbox is displayed next to the legend item to allow selecting the series.

Note

The state of the checkbox is controlled by the GenericTypeOptions.selected() property.

Return type:

bool or None

property show_in_legend: bool | None

Whether to display this particular series or series type in the legend. Standalone series are shown in the legend by default, and linked series are not.

Return type:

bool or None

property show_in_navigator: bool | None

If True, shows the series in the navigator. Defaults to None.

Note

Takes precedence over Navigator.base_series if provided.

Return type:

bool or None

property skip_keyboard_navigation: bool | None

If True, the accessibility module will skip past this series when executing keyboard navigation.

Return type:

bool or None

property soft_threshold: bool | None

When True, the series will not cause the Y axis to cross the zero plane (or threshold option) unless the data actually crosses the plane. Defaults to True.

For example, if False, a series of 0, 1, 2, 3 will make the Y axis show negative values according to the min_padidng option. If True, the Y axis starts at 0.

Return type:

bool

property sonification: SeriesSonification | None

Sonification configuration for the series type/series.

Return type:

SeriesSonification or None

property stacking: str | None

Whether to stack the values of each series on top of each other. Defaults to None.

Acceptable values are:

  • None to disable stacking,

  • "normal" to stack by value or

  • "percent"

  • 'stream' (for streamgraph series type only)

  • 'overlap' (for waterfall series type only)

Note

When stacking is enabled, data must be sorted in ascending X order.

Return type:

str or None

property states: States | None

Configuration for state-specific configuration to apply to the data series.

Return type:

States or None

property step: str | None

Whether to apply steps to the line. Defaults to None.

Possible values are:

  • None

  • 'left'

  • 'center'

  • 'right'

Return type:

str or None

property sticky_tracking: bool | None

Sticky tracking of mouse events.

When True, the (JavaScript) mouseOut event on a series is not triggered until the mouse moves over another series, or out of the plot area.

When False, the (JavaScript) mouseOut event on a series is triggered when the mouse leaves the area around the series’ graph or markers. This also implies the tooltip when not shared.

When False and PlotOptions.tooltip.shared() is also False, the tooltip will be hidden when moving the mouse between series.

Defaults to True for line and area type series, but to False for columns, pies, etc.

Note

The boost module will force this option because of technical limitations.

Return type:

bool or None

property threshold: int | float | Decimal | EnforcedNullType | None

The Y axis value to serve as the base for the columns, for distinguishing between values above and below a threshold. Defaults to 0.

If EnforcedNullType, the columns extend from the padding Y axis minimum.

Return type:

numeric or EnforcedNullType or None

property tooltip: Tooltip | None

A configuration object for the tooltip rendering of each single series. Properties are inherited from tooltip, but only the following properties can be defined on a series level.

Return type:

Tooltip or None

property turbo_threshold: int | None

When a series contains a data array longer than this value, only one dimensional arrays of numbers, or two dimensional arrays with x and y values are allowed. Also, only the first point is tested, and the rest are assumed to be the same format. This saves expensive data checking and indexing in long series. Set it to 0 or None to disable.

Defaults to 1000.

Note

In boost mode, turbo threshold is forced. Only array of numbers or two dimensional arrays are allowed.

Return type:

int or None

property type: str

Indicates the type of series that is represented by this instance.

Warning

This proprety is read-only!

Return type:

str

property visible: bool | None

If True, the series is initially visible. If False, the series is hidden by default. Defaults to True.

Return type:

bool or None

class: TreegraphEvents

class TreegraphEvents(**kwargs)[source]

General event handlers for the series items.

Tip

These event hooks can also be attached to the series at run time using the Highcharts.addEvent() (JavaScript) function.

Class Inheritance
Inheritance diagram of TreegraphEvents

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 after_animate: CallbackFunction | None

JavaScript function that fires after the series has finished its initial animation, or if animation is disabled, immediately as the series is displayed.

Return type:

CallbackFunction or None

property checkbox_click: CallbackFunction | None

JavaScript function that fires when the checkbox next to the series’ name in the legend is clicked.

One parameter, event, is passed to the (JavaScript) function. The state of the checkbox is found by event.checked. The checked item is found by event.item. Return false to prevent the default action which is to toggle the select state of the series.

Return type:

CallbackFunction or None

property click: CallbackFunction | None

JavaScript function that fires when when the series is clicked.

One parameter, event, is passed to the (JavaScript) function, containing common event information. Additionally, event.point holds a pointer to the nearest point on the graph.

Return type:

CallbackFunction or None

property hide: CallbackFunction | None

JavaScript function that fires when the series is hidden after chart generation time, either by clicking the legend item or by calling (in JavaScript) .hide().

Return type:

CallbackFunction or None

property legend_item_click: CallbackFunction | None

JavaScript function that fires when the legend item belonging to the series is clicked.

One parameter, event, is passed to the (JavaScript) function. The default action is to toggle the visibility of the series. This can be prevented by returning false or calling (in JavaScript) event.preventDefault().

Return type:

CallbackFunction or None

property mouse_out: CallbackFunction | None

JavaScript function which fires when the mouse leaves the graph.

One parameter, event, is passed to the (JavaScript) function, containing common event information. If the stickyTracking option is true, the mouse_out event doesn’t happen before the mouse enters another graph or leaves the plot area.

Return type:

CallbackFunction or None

property mouse_over: CallbackFunction | None

JavaScript function which fires when the mouse enters the graph.

One parameter, event, is passed to the function, containing common event information.

Return type:

CallbackFunction or None

property set_root_node: CallbackFunction | None

Event handler that fires on a request to change the tree’s root node, before the update is made.

An event object is passed to the function, containing additional properties newRootId, previousRootId, redraw, and trigger.

Defaults to None

Return type:

CallbackFunction or None

property show: CallbackFunction | None

JavaScript function which fires when the series is shown after chart generation time, either by clicking the legend item or by calling (in JavaScript) .show().

Return type:

CallbackFunction or None