.bar

class: BarData

class BarData(**kwargs)[source]

Variant of CartesianData which is used for data points in a column or bar graph context.

Class Inheritance
Inheritance diagram of BarData

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_array(value)

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances or CartesianDataCollection

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

classmethod from_list(value)

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances

classmethod from_ndarray(value)[source]

Creates a collection of data points from a NumPy ndarray instance.

Returns:

A collection of data point values.

Return type:

DataPointCollection

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

populate_from_array(value)

Update the data point’s properties with values provided by an array (iterable).

This method is used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_data_point = CartesianData()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_data_point.populate_from_array([0, 0])
my_data_point.populate_from_array([1, 5])
my_data_point.populate_from_array([2, 3])
my_data_point.populate_from_array([3, 5])
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point property values.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

to_array(force_object=False) → List | Dict

Generate the array representation of the data point (the inversion of .from_array()).

Warning

If the data point cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data point as a fallback.

Parameters:

force_object (bool) – if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

Returns:

The array representation of the data point.

Return type:

list of values or dict

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 accessibility: DataPointAccessibility | None

Accessibility options for a data point.

Return type:

DataPointAccessibility or None

property border_color: str | Gradient | Pattern | None

The color of the border surrounding each column or bar. Defaults to None

Return type:

str or None

property border_width: int | float | Decimal | None

The width of the border surrounding each column or bar. Defaults to None.

Return type:

numeric or None

property class_name: str | None

The additional CSS class name to apply to the data point’s graphical elements.

Return type:

str or None

property color: str | Gradient | Pattern | None

The color of the individual data point. Defaults to None.

Return type:

None, Gradient, Pattern, or str

property color_index: int | None

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

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.

Return type:

int 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 bar or column. Defaults to None.

Accepts one of the following values:

  • ‘Dash’,

  • ‘DashDot’,

  • ‘Dot’,

  • ‘LongDash’,

  • ‘LongDashDot’,

  • ‘LongDashDotDot’,

  • ‘ShortDash’,

  • ‘ShortDashDot’,

  • ‘ShortDashDotDot’,

  • ‘ShortDot’,

  • ‘Solid’

Return type:

str or None

property data_labels: DataLabel | None

Individual data label for the data point.

Return type:

DataLabel or None

property description: str | None

A description of the data point to add to the screen reader information about the data point.

Return type:

str

property drag_drop: DragDropOptions | None

The draggable-points module allows points to be moved around or modified in the chart.

In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:

  • point.dragStart

  • point.drag

  • point.drop

Return type:

DragDropOptions or None

property drilldown: str | None

The id of a series in the drilldown.series array to use as a drilldown destination for this point. Defaults to None.

Return type:

str or None

property events: PointEvents | None

Event handlers for individual data points.

Return type:

PointEvents or None

property id: str | None

The id of the data point. Defaults to None.

Note

This can be used (in JavaScript) after render time to get a pointer to the point object through chart.get().

Return type:

str or None

property label_rank: int | float | Decimal | None

The rank for this point’s data label in the case of collision. Defaults to None.

Note

If two data labels are about to overlap, the data label for the point with the highest label_rank will be shown.

Return type:

numeric or None

property marker: Marker | None

Options for the point markers of line-like series.

Return type:

Marker or None

property name: str | None

The name to display for the point in data labels, tooltips, in legends, etc. Defaults to None.

Return type:

str or None

property point_width: int | float | Decimal | None

A pixel value specifying a fixed width for the column or bar. Defaults to None.

Note

If specified, overrides the point_width provided for the series as a whole.

Note

The point_width affects the dimension that is not based on the point value.

Return type:

numeric or None

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool

property selected: bool | None

If True, indicates that the data point is initially selected. Defaults to None, which behaves as False.

Return type:

bool or None

property x: str | date | datetime | int | float | Decimal | None

The point’s location on the x-axis. Defaults to None.

If None, the point’s position on the x-axis will be automatically determined based on its position in the series’ data array. The first point will be given an x value of 0, or the series’ point_start value. Each subsequent point will be incremented either by 1 or the value of point_interval.

Return type:

numeric or str or date or datetime or None

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

The position of the data point on the Y-axis. Defaults to None.

Return type:

numeric or EnforcedNullType or None

class: BarDataCollection

class BarDataCollection(**kwargs)[source]

A collection of BarData objects.

Note

When serializing to JS literals, if possible, the collection is serialized to a primitive array to boost performance within Python and JavaScript. However, this may not always be possible if data points have non-array-compliant properties configured (e.g. adjusting their style, names, identifiers, etc.). If serializing to a primitive array is not possible, the results are serialized as JS literal objects.

Class Inheritance
Inheritance diagram of BarDataCollection

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_array(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (iterable or numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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

classmethod from_ndarray(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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_array(force_object=False, force_ndarray=False) → List

Generate the array representation of the data points (the inversion of .from_array()).

Warning

If any data points cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data points as a fallback.

Parameters:

  • force_object (bool) –

    if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

    Warning

    Values in .ndarray are ignored within this operation in favor of data points stored in .data_points.

    However, if there are no data points in .data_points then data point objects will be assembled based on .ndarray.

  • force_ndarray (bool) –

    if True, forces the return of the instance’s data points as a numpy.ndarray. Defaults to False.

    Warning

    Properties of any .data_points are ignored within this operation if .ndarray is populated.

    However, if .ndarray is not populated, then a numpy.ndarray will be assembled from values in .data_points (ignoring properties that Highcharts (JS) cannot interpret as a primitive array).

Raises:

HighchartsValueError – if both force_object and force_ndarray are True

Returns:

The array representation of the data point collection.

Return type:

list

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 array: List | None

Primitive collection of values for data points in the collection. Used if NumPy is not available. Defaults to None.

Note

If NumPy is availalbe, will instead behave as an alias for .ndarray

Return type:

list or None

property data_points: List[DataBase] | None

The collection of data points for the series. Defaults to None.

Return type:

list of DataBase or None

property ndarray

A dict whose keys correspond to data point properties, and whose values are numpy.ndarray instances that contain the data point collection’s values.

Return type:

dict or None

property ndarray_length: int

The length of the array stored in .ndarray.

Return type:

int

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool

class: WaterfallData

class WaterfallData(**kwargs)[source]

Variant of CartesianData which is used for data points in a waterfall chart.

Class Inheritance
Inheritance diagram of WaterfallData

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_array(value)

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances or CartesianDataCollection

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

classmethod from_list(value)

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances

classmethod from_ndarray(value)[source]

Creates a collection of data points from a NumPy ndarray instance.

Returns:

A collection of data point values.

Return type:

DataPointCollection

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

populate_from_array(value)

Update the data point’s properties with values provided by an array (iterable).

This method is used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_data_point = CartesianData()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_data_point.populate_from_array([0, 0])
my_data_point.populate_from_array([1, 5])
my_data_point.populate_from_array([2, 3])
my_data_point.populate_from_array([3, 5])
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point property values.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

to_array(force_object=False) → List | Dict

Generate the array representation of the data point (the inversion of .from_array()).

Warning

If the data point cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data point as a fallback.

Parameters:

force_object (bool) – if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

Returns:

The array representation of the data point.

Return type:

list of values or dict

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 accessibility: DataPointAccessibility | None

Accessibility options for a data point.

Return type:

DataPointAccessibility or None

property class_name: str | None

The additional CSS class name to apply to the data point’s graphical elements.

Return type:

str or None

property color: str | Gradient | Pattern | None

The color of the individual data point. Defaults to None.

Return type:

None, Gradient, Pattern, or str

property color_index: int | None

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

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.

Return type:

int 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 data_labels: DataLabel | None

Individual data label for the data point.

Return type:

DataLabel or None

property description: str | None

A description of the data point to add to the screen reader information about the data point.

Return type:

str

property drag_drop: DragDropOptions | None

The draggable-points module allows points to be moved around or modified in the chart.

In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:

  • point.dragStart

  • point.drag

  • point.drop

Return type:

DragDropOptions or None

property drilldown: str | None

The id of a series in the drilldown.series array to use as a drilldown destination for this point. Defaults to None.

Return type:

str or None

property events: PointEvents | None

Event handlers for individual data points.

Return type:

PointEvents or None

property id: str | None

The id of the data point. Defaults to None.

Note

This can be used (in JavaScript) after render time to get a pointer to the point object through chart.get().

Return type:

str or None

property is_intermediate_sum: bool | None

When True, the point acts as a summary column for the values added or subtracted since the last intermediate sum, or since the start of the series. Defaults to None, which is interpreted as False.

Warning

The y value is ignored.

Return type:

bool or None

property is_sum: bool | None

When True, the point displays the total sum across the entire series. Defaults to None, which is interpreted as False.

Warning

The y value is ignored.

Return type:

bool or None

property label_rank: int | float | Decimal | None

The rank for this point’s data label in the case of collision. Defaults to None.

Note

If two data labels are about to overlap, the data label for the point with the highest label_rank will be shown.

Return type:

numeric or None

property marker: Marker | None

Options for the point markers of line-like series.

Return type:

Marker or None

property name: str | None

The name to display for the point in data labels, tooltips, in legends, etc. Defaults to None.

Return type:

str or None

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool

property selected: bool | None

If True, indicates that the data point is initially selected. Defaults to None, which behaves as False.

Return type:

bool or None

property x: str | date | datetime | int | float | Decimal | None

The point’s location on the x-axis. Defaults to None.

If None, the point’s position on the x-axis will be automatically determined based on its position in the series’ data array. The first point will be given an x value of 0, or the series’ point_start value. Each subsequent point will be incremented either by 1 or the value of point_interval.

Return type:

numeric or str or date or datetime or None

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

The position of the data point on the Y-axis. Defaults to None.

Return type:

numeric or EnforcedNullType or None

class: WaterfallDataCollection

class WaterfallDataCollection(**kwargs)[source]

A collection of BarData objects.

Note

When serializing to JS literals, if possible, the collection is serialized to a primitive array to boost performance within Python and JavaScript. However, this may not always be possible if data points have non-array-compliant properties configured (e.g. adjusting their style, names, identifiers, etc.). If serializing to a primitive array is not possible, the results are serialized as JS literal objects.

Class Inheritance
Inheritance diagram of WaterfallDataCollection

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_array(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (iterable or numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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

classmethod from_ndarray(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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_array(force_object=False, force_ndarray=False) → List

Generate the array representation of the data points (the inversion of .from_array()).

Warning

If any data points cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data points as a fallback.

Parameters:

  • force_object (bool) –

    if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

    Warning

    Values in .ndarray are ignored within this operation in favor of data points stored in .data_points.

    However, if there are no data points in .data_points then data point objects will be assembled based on .ndarray.

  • force_ndarray (bool) –

    if True, forces the return of the instance’s data points as a numpy.ndarray. Defaults to False.

    Warning

    Properties of any .data_points are ignored within this operation if .ndarray is populated.

    However, if .ndarray is not populated, then a numpy.ndarray will be assembled from values in .data_points (ignoring properties that Highcharts (JS) cannot interpret as a primitive array).

Raises:

HighchartsValueError – if both force_object and force_ndarray are True

Returns:

The array representation of the data point collection.

Return type:

list

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 array: List | None

Primitive collection of values for data points in the collection. Used if NumPy is not available. Defaults to None.

Note

If NumPy is availalbe, will instead behave as an alias for .ndarray

Return type:

list or None

property data_points: List[DataBase] | None

The collection of data points for the series. Defaults to None.

Return type:

list of DataBase or None

property ndarray

A dict whose keys correspond to data point properties, and whose values are numpy.ndarray instances that contain the data point collection’s values.

Return type:

dict or None

property ndarray_length: int

The length of the array stored in .ndarray.

Return type:

int

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool

class: WindBarbData

class WindBarbData(**kwargs)[source]

Variant of CartesianData which is used for data points in a windbarb chart.

Class Inheritance
Inheritance diagram of WindBarbData

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_array(value)

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances or CartesianDataCollection

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

classmethod from_list(value)[source]

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances

classmethod from_ndarray(value)[source]

Creates a collection of data points from a NumPy ndarray instance.

Returns:

A collection of data point values.

Return type:

DataPointCollection

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

populate_from_array(value)

Update the data point’s properties with values provided by an array (iterable).

This method is used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_data_point = CartesianData()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_data_point.populate_from_array([0, 0])
my_data_point.populate_from_array([1, 5])
my_data_point.populate_from_array([2, 3])
my_data_point.populate_from_array([3, 5])
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point property values.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

to_array(force_object=False) → List | Dict[source]

Generate the array representation of the data point (the inversion of .from_array()).

Warning

If the data point cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data point as a fallback.

Parameters:

force_object (bool) – if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

Returns:

The array representation of the data point.

Return type:

list of values or dict

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 accessibility: DataPointAccessibility | None

Accessibility options for a data point.

Return type:

DataPointAccessibility or None

property class_name: str | None

The additional CSS class name to apply to the data point’s graphical elements.

Return type:

str or None

property color: str | Gradient | Pattern | None

The color of the individual data point. Defaults to None.

Return type:

None, Gradient, Pattern, or str

property color_index: int | None

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

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.

Return type:

int 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 data_labels: DataLabel | None

Individual data label for the data point.

Return type:

DataLabel or None

property description: str | None

A description of the data point to add to the screen reader information about the data point.

Return type:

str

property direction: int | float | Decimal | None

The windirection in degrees, where 0 is north (pointing towards south). Defaults to None.

Return type:

numeric or None

property drag_drop: DragDropOptions | None

The draggable-points module allows points to be moved around or modified in the chart.

In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:

  • point.dragStart

  • point.drag

  • point.drop

Return type:

DragDropOptions or None

property drilldown: str | None

The id of a series in the drilldown.series array to use as a drilldown destination for this point. Defaults to None.

Return type:

str or None

property events: PointEvents | None

Event handlers for individual data points.

Return type:

PointEvents or None

property id: str | None

The id of the data point. Defaults to None.

Note

This can be used (in JavaScript) after render time to get a pointer to the point object through chart.get().

Return type:

str or None

property label_rank: int | float | Decimal | None

The rank for this point’s data label in the case of collision. Defaults to None.

Note

If two data labels are about to overlap, the data label for the point with the highest label_rank will be shown.

Return type:

numeric or None

property marker: Marker | None

Options for the point markers of line-like series.

Return type:

Marker or None

property name: str | None

The name to display for the point in data labels, tooltips, in legends, etc. Defaults to None.

Return type:

str or None

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool

property selected: bool | None

If True, indicates that the data point is initially selected. Defaults to None, which behaves as False.

Return type:

bool or None

property value: int | float | Decimal | None

The wind speed in meters per second. Defaults to None.

Return type:

numeric or None

property x: str | date | datetime | int | float | Decimal | None

The point’s location on the x-axis. Defaults to None.

If None, the point’s position on the x-axis will be automatically determined based on its position in the series’ data array. The first point will be given an x value of 0, or the series’ point_start value. Each subsequent point will be incremented either by 1 or the value of point_interval.

Return type:

numeric or str or date or datetime or None

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

The position of the data point on the Y-axis. Defaults to None.

Return type:

numeric or EnforcedNullType or None

class: WindBarbDataCollection

class WindBarbDataCollection(**kwargs)[source]

A collection of BarData objects.

Note

When serializing to JS literals, if possible, the collection is serialized to a primitive array to boost performance within Python and JavaScript. However, this may not always be possible if data points have non-array-compliant properties configured (e.g. adjusting their style, names, identifiers, etc.). If serializing to a primitive array is not possible, the results are serialized as JS literal objects.

Class Inheritance
Inheritance diagram of WindBarbDataCollection

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_array(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (iterable or numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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

classmethod from_ndarray(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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_array(force_object=False, force_ndarray=False) → List

Generate the array representation of the data points (the inversion of .from_array()).

Warning

If any data points cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data points as a fallback.

Parameters:

  • force_object (bool) –

    if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

    Warning

    Values in .ndarray are ignored within this operation in favor of data points stored in .data_points.

    However, if there are no data points in .data_points then data point objects will be assembled based on .ndarray.

  • force_ndarray (bool) –

    if True, forces the return of the instance’s data points as a numpy.ndarray. Defaults to False.

    Warning

    Properties of any .data_points are ignored within this operation if .ndarray is populated.

    However, if .ndarray is not populated, then a numpy.ndarray will be assembled from values in .data_points (ignoring properties that Highcharts (JS) cannot interpret as a primitive array).

Raises:

HighchartsValueError – if both force_object and force_ndarray are True

Returns:

The array representation of the data point collection.

Return type:

list

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 array: List | None

Primitive collection of values for data points in the collection. Used if NumPy is not available. Defaults to None.

Note

If NumPy is availalbe, will instead behave as an alias for .ndarray

Return type:

list or None

property data_points: List[DataBase] | None

The collection of data points for the series. Defaults to None.

Return type:

list of DataBase or None

property ndarray

A dict whose keys correspond to data point properties, and whose values are numpy.ndarray instances that contain the data point collection’s values.

Return type:

dict or None

property ndarray_length: int

The length of the array stored in .ndarray.

Return type:

int

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool

class: XRangeData

class XRangeData(**kwargs)[source]

Variant of CartesianData which is used for data points in an X-Range series.

Class Inheritance
Inheritance diagram of XRangeData

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_array(value)

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances or CartesianDataCollection

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

classmethod from_list(value)[source]

Creates a collection of data point instances, parsing the contents of value as an array (iterable). This method is specifically used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_series = LineSeries()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_series.data = [0, 5, 3, 5]

# An array containing 2-member arrays (corresponding to the X and Y values
# of the data point)
my_series.data = [
    [0, 0],
    [1, 5],
    [2, 3],
    [3, 5]
]

# An array of dict with named values
my_series.data = [
  {
      'x': 0,
      'y': 0,
      'name': 'Point1',
      'color': '#00FF00'
  },
  {
      'x': 1,
      'y': 5,
      'name': 'Point2',
      'color': '#CCC'
  },
  {
      'x': 2,
      'y': 3,
      'name': 'Point3',
      'color': '#999'
  },
  {
      'x': 3,
      'y': 5,
      'name': 'Point4',
      'color': '#000'
  }
]
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point instances.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

Returns:

Collection of data point instances (descended from DataBase)

Return type:

list of DataBase descendant instances

classmethod from_ndarray(value)[source]

Creates a collection of data points from a NumPy ndarray instance.

Returns:

A collection of data point values.

Return type:

DataPointCollection

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

populate_from_array(value)

Update the data point’s properties with values provided by an array (iterable).

This method is used to parse data that is input to Highcharts for Python without property names, in an array-organized structure as described in the Highcharts JS documentation.

See also

The specific structure of the expected array is highly dependent on the type of data point that the series needs, which itself is dependent on the series type itself.

Please review the detailed series documentation for series type-specific details of relevant array structures.

Note

An example of how this works for a simple LineSeries (which uses CartesianData data points) would be:

my_data_point = CartesianData()

# A simple array of numerical values which correspond to the Y value of the
# data point
my_data_point.populate_from_array([0, 0])
my_data_point.populate_from_array([1, 5])
my_data_point.populate_from_array([2, 3])
my_data_point.populate_from_array([3, 5])
Parameters:

value (iterable) –

The value that should contain the data which will be converted into data point property values.

Note

If value is not an iterable, it will be converted into an iterable to be further de-serialized correctly.

to_array(force_object=False) → List | Dict

Generate the array representation of the data point (the inversion of .from_array()).

Warning

If the data point cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data point as a fallback.

Parameters:

force_object (bool) – if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

Returns:

The array representation of the data point.

Return type:

list of values or dict

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 accessibility: DataPointAccessibility | None

Accessibility options for a data point.

Return type:

DataPointAccessibility or None

property class_name: str | None

The additional CSS class name to apply to the data point’s graphical elements.

Return type:

str or None

property color: str | Gradient | Pattern | None

The color of the individual data point. Defaults to None.

Return type:

None, Gradient, Pattern, or str

property color_index: int | None

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

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.

Return type:

int 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 data_labels: DataLabel | None

Individual data label for the data point.

Return type:

DataLabel or None

property description: str | None

A description of the data point to add to the screen reader information about the data point.

Return type:

str

property drag_drop: DragDropOptions | None

The draggable-points module allows points to be moved around or modified in the chart.

In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:

  • point.dragStart

  • point.drag

  • point.drop

Return type:

DragDropOptions or None

property drilldown: str | None

The id of a series in the drilldown.series array to use as a drilldown destination for this point. Defaults to None.

Return type:

str or None

property events: PointEvents | None

Event handlers for individual data points.

Return type:

PointEvents or None

property id: str | None

The id of the data point. Defaults to None.

Note

This can be used (in JavaScript) after render time to get a pointer to the point object through chart.get().

Return type:

str or None

property label_rank: int | float | Decimal | None

The rank for this point’s data label in the case of collision. Defaults to None.

Note

If two data labels are about to overlap, the data label for the point with the highest label_rank will be shown.

Return type:

numeric or None

property marker: Marker | None

Options for the point markers of line-like series.

Return type:

Marker or None

property name: str | None

The name to display for the point in data labels, tooltips, in legends, etc. Defaults to None.

Return type:

str or None

property partial_fill: PartialFillOptions | None

A partial fill for the data point, typically used to visualize how much of a task is performed. Defaults to None.

Return type:

PartialFillOptions or None

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool

property selected: bool | None

If True, indicates that the data point is initially selected. Defaults to None, which behaves as False.

Return type:

bool or None

property x: str | date | datetime | int | float | Decimal | None

The starting X-value of the range point. Defaults to None.

If None, the point’s position on the x-axis will be automatically determined based on its position in the series’ data array. The first point will be given an x value of 0, or the series’ point_start value. Each subsequent point will be incremented either by 1 or the value of point_interval.

Return type:

numeric or str or date or datetime or None

property x2: str | date | datetime | int | float | Decimal | None

The ending X-value of the range point. Defaults to None.

If None, the point’s position on the x-axis will be automatically determined based on its position in the series’ data array. The first point will be given an x2 value of 0, or the series’ point_start value. Each subsequent point will be incremented either by 1 or the value of point_interval.

Return type:

numeric or str or date or datetime or None

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

The position of the data point on the Y-axis. Defaults to None.

Return type:

numeric or EnforcedNullType or None

class: XRangeDataCollection

class XRangeDataCollection(**kwargs)[source]

A collection of XRangeData objects.

Note

When serializing to JS literals, if possible, the collection is serialized to a primitive array to boost performance within Python and JavaScript. However, this may not always be possible if data points have non-array-compliant properties configured (e.g. adjusting their style, names, identifiers, etc.). If serializing to a primitive array is not possible, the results are serialized as JS literal objects.

Class Inheritance
Inheritance diagram of XRangeDataCollection

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_array(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (iterable or numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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

classmethod from_ndarray(value)

Creates a DataPointCollection instance from an array of values.

Parameters:

value (numpy.ndarray) – The value that should contain the data which will be converted into data point instances.

Returns:

A single-object collection of data points.

Return type:

DataPointCollection or None

Raises:

HighchartsDependencyError – if NumPy is not installed

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_array(force_object=False, force_ndarray=False) → List

Generate the array representation of the data points (the inversion of .from_array()).

Warning

If any data points cannot be serialized to a JavaScript array, this method will instead return the untrimmed dict representation of the data points as a fallback.

Parameters:

  • force_object (bool) –

    if True, forces the return of the instance’s untrimmed dict representation. Defaults to False.

    Warning

    Values in .ndarray are ignored within this operation in favor of data points stored in .data_points.

    However, if there are no data points in .data_points then data point objects will be assembled based on .ndarray.

  • force_ndarray (bool) –

    if True, forces the return of the instance’s data points as a numpy.ndarray. Defaults to False.

    Warning

    Properties of any .data_points are ignored within this operation if .ndarray is populated.

    However, if .ndarray is not populated, then a numpy.ndarray will be assembled from values in .data_points (ignoring properties that Highcharts (JS) cannot interpret as a primitive array).

Raises:

HighchartsValueError – if both force_object and force_ndarray are True

Returns:

The array representation of the data point collection.

Return type:

list

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 array: List | None

Primitive collection of values for data points in the collection. Used if NumPy is not available. Defaults to None.

Note

If NumPy is availalbe, will instead behave as an alias for .ndarray

Return type:

list or None

property data_points: List[DataBase] | None

The collection of data points for the series. Defaults to None.

Return type:

list of DataBase or None

property ndarray

A dict whose keys correspond to data point properties, and whose values are numpy.ndarray instances that contain the data point collection’s values.

Return type:

dict or None

property ndarray_length: int

The length of the array stored in .ndarray.

Return type:

int

property requires_js_object: bool

Indicates whether or not the data point must be serialized to a JS literal object or whether it can be serialized to a primitive array.

Returns:

True if the data point must be serialized to a JS literal object. False if it can be serialized to an array.

Return type:

bool