`.chart`

class: `Chart`

class Chart(**kwargs)[source]

Python representation of a Highcharts Chart object.

Class Inheritance

__repr__()

Generate an unambiguous and complete str representation of the object.

Returns:: An unambiguous and complete str representation of the object (which may have varying degrees of readability).
Return type:: str

__str__()[source]

Return a human-readable str representation of the chart.

Warning

To ensure that the result is human-readable, the chart’s options property will be rendered without its plot_options and series sub-properties.

Tip

If you would like a complete and unambiguous str representation, then you can:

use the __repr__() method,
call repr(my_chart), or
serialize the chart to JSON using my_chart.to_json().

Returns:: A str representation of the chart.
Return type:: str

add_series(*series)[source]

Adds series to the Chart.options.series property.

Parameters:: series (one or more SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one

copy(other=None, overwrite=True, **kwargs)[source]

Copy the configuration settings from this chart to the other chart.

Parameters:

other (Chart) – The target chart to which the properties of this chart should be copied. If None, will create a new chart 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.
preserve_data (bool) – If True, will preserve the data values in any series contained in other and the configuration of the options.data property, but will still copy other properties as applicable. If False, will overwrite data in other with data from 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

display(global_options=None, container=None, retries=5, interval=1000)[source]

Display the chart in Jupyter Labs or Jupyter Notebooks.

Parameters:

global_options (SharedOptions or None) – The shared options to use when rendering the chart. Defaults to None
container (str or None) –
The ID to apply to the HTML container when rendered in Jupyter Labs. Defaults to None, which applies the .container property if set, and 'highcharts_target_div' if not set.

Note

Highcharts for Python will append a 6-character random string to the value of container to ensure uniqueness of the chart’s container when rendering in a Jupyter Notebook/Labs context. The Chart instance will retain the mapping between container and the random string so long as the instance exists, thus allowing you to easily update the rendered chart by calling the .display() method again.

If you wish to create a new chart from the instance that does not update the existing chart, then you can do so by specifying a new container value.
retries (int) – The number of times to retry rendering the chart. Used to avoid race conditions with the Highcharts script. Defaults to 5.
interval (int) – The number of milliseconds to wait between retrying rendering the chart. Defaults to 1000 (1 second).

Raises:

HighchartsDependencyError – if ipython is not available in the runtime environment

download_chart(format='png', scale=1, width=None, filename=None, auth_user=None, auth_password=None, timeout=3, server_instance=None, **kwargs)[source]

Export a downloaded form of the chart using a Highcharts Export Server.

Parameters:

filename (Path-like or None) – The name of the file where the exported chart should (optionally) be persisted. Defaults to None.
auth_user (str or None) – The username to use to authenticate against the Export Server, using basic authentication. Defaults to None.
auth_password (str or None) – The password to use to authenticate against the Export Server (using basic authentication). Defaults to None.
timeout (numeric or None) – The number of seconds to wait before issuing a timeout error. The timeout check is passed if bytes have been received on the socket in less than the timeout value. Defaults to 3.
server_instance (ExportServer or None) – Provide an already-configured ExportServer instance to use to programmatically produce the exported chart. Defaults to None, which causes Highcharts for Python to instantiate a new ExportServer instance.

Note

All other keyword arguments are as per the ExportServer constructor.

Returns:: The exported chart image, either as a bytes binary object or as a base-64 encoded string (depending on the use_base64 keyword argument).
Return type:: bytes or str

classmethod from_array(value, series_type='line', series_kwargs=None, options_kwargs=None, chart_kwargs=None)[source]

Create a Chart instance with one series populated from the array contained in value.

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.

Parameters:

value (iterable) – The array to use to populate the series data.
series_type (str) – Indicates the series type that should be created from the array data. Defaults to 'line'.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.
options_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

Warning

If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the data in df.
chart_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

Warning

If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and the data in df instead.

Returns:

A Chart instance with its data populated from the data in value.

Return type:

Chart

classmethod from_csv(as_string_or_file, property_column_map=None, series_type='line', has_header_row=True, series_kwargs=None, options_kwargs=None, chart_kwargs=None, delimiter=',', null_text='None', wrapper_character="'", line_terminator='\r\n', wrap_all_strings=False, double_wrapper_character_when_nested=False, escape_character='\\', series_in_rows=False, series_index=None, **kwargs)[source]

Create a new Chart instance with data populated from a CSV string or file.

Note

For an example chart containing LineSeries instances, the minimum code required would be:
# EXAMPLE 1: The minimum code:
my_chart = Chart.from_csv('some-csv-file.csv', series_type = 'line')

# EXAMPLE 2: For more precise configuration and *one* series:
my_chart = Chart.from_csv('some-csv-file.csv',
                          property_column_map = {
                              'x': 0,
                              'y': 3,
                              'id': 'id'
                          },
                          series_type = 'line')

# EXAMPLE 3: For more precise configuration and *multiple* series:
my_chart = Chart.from_csv('some-csv-file.csv',
                          property_column_map = {
                              'x': 0,
                              'y': [3, 5, 8],
                              'id': 'id'
                          },
                          series_type = 'line')
As the example above shows, data is loaded into the my_chart instance from the CSV file with a filename some-csv-file.csv.

In EXAMPLE 1, the chart will contain one or more series where each series will default to having its .x values taken from the first (index 0) column in the CSV, and one LineSeries instance will be created for each subsequent column (which will populate that series’ .y values.

In EXAMPLE 2, the chart will contain one series, where the x values for each data point will be taken from the first (index 0) column in the CSV file. The y values will be taken from the fourth (index 3) column in the CSV file. And the id values will be taken from a column whose header row is labeled 'id' (regardless of its index).

In EXAMPLE 3, the chart will contain three series, all of which will have .x values taken from the first (index 0) column, .id values from the column whose header row is labeled 'id', and whose .y will be taken from the fourth (index 3) column for the first series, the sixth (index 5) column for the second series, and the ninth (index 8) column for the third series.

Parameters:

as_string_or_file (str or Path-like) –
The CSV data to use to pouplate data. Accepts either the raw CSV data as a str or a path to a file in the runtime environment that contains the CSV data.

Tip

Unwrapped empty column values are automatically interpreted as null (None).
property_column_map (dict) –
A dict used to indicate which data point property should be set to which CSV column. The keys in the dict should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or a str indicating the label for the CSV column. Defaults to None.
Note

If any of the values in property_column_map contain an iterable, then one series will be produced for each item in the iterable. For example, the following:
```
{
    'x': 0,
    'y': [3, 5, 8]
}
```
will return three series, each of which will have its .x value populated from the first column (index 0), and whose .y values will be populated from the fourth, sixth, and ninth columns (indices 3, 5, and 8), respectively.
Warning

If the property_column_map uses str values, the CSV file must have a header row (this is expected, by default). If there is no header row and a str value is found, a HighchartsCSVDeserializationError will be raised.
series_type (str) – Indicates the series type that should be created from the CSV data. Defaults to 'line'.
has_header_row (bool) – If True, indicates that the first row of as_string_or_file contains column labels, rather than actual data. Defaults to True.
series_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from the CSV file instead.
options_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

Warning

If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the CSV file instead.
chart_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

Warning

If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and CSV file instead.
delimiter (str) – The delimiter used between columns. Defaults to ,.
wrapper_character (str) – The string used to wrap string values when wrapping is applied. Defaults to '.
null_text (str) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.
line_terminator (str) –
The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.

Note

The Python csv currently ignores the line_terminator parameter and always applies '\r\n', by design. The Python docs say this may change in the future, so for future backwards compatibility we are including it here.
wrap_all_strings (bool) –
If True, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults to False.

Warning

If set to True, the csv module will try to coerce any value that is not wrapped in quotation marks to a float. This can cause unexpected behavior, and typically we recommend leaving this as False and then re-casting values after they have been parsed.
double_wrapper_character_when_nested (bool) – If True, quote character is doubled when appearing within a string value. If False, the escape_character is used to prefix quotation marks. Defaults to False.
escape_character (str) – A one-character string that indicates the character used to escape quotation marks if they appear within a string value that is already wrapped in quotation marks. Defaults to \\ (which is Python for '\', which is Python’s native escape character).
series_in_rows (bool) – if True, will attempt a streamlined cartesian series with x-values taken from column names, y-values taken from row values, and the series name taken from the row index. Defaults to False.
series_index (int, slice, or None) – if None, will attempt to populate the chart with multiple series from the CSV data. If an int is supplied, will populate the chart only with the series found at series_index.
**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.

Returns:

A Chart instance with its data populated from the CSV data.

Return type:

Chart

Raises:

HighchartsCSVDeserializationError – if property_column_map references CSV columns by their label, but the CSV data does not contain a header row

classmethod from_csv_in_rows(as_string_or_file, series_type='line', has_header_row=True, series_kwargs=None, options_kwargs=None, chart_kwargs=None, delimiter=',', null_text='None', wrapper_character="'", line_terminator='\r\n', wrap_all_strings=False, double_wrapper_character_when_nested=False, escape_character='\\', series_index=None, **kwargs)[source]

Create a new Chart instance with data populated from a CSV string or file.

Note

For an example LineSeries, the minimum code required would be:
my_chart = Chart.from_csv('some-csv-file.csv',
                          property_column_map = {
                              'x': 0,
                              'y': 3,
                              'id': 'id'
                          },
                          series_type = 'line')
As the example above shows, data is loaded into the my_chart instance from the CSV file with a filename some-csv-file.csv. The x values for each data point will be taken from the first (index 0) column in the CSV file. The y values will be taken from the fourth (index 3) column in the CSV file. And the id values will be taken from a column whose header row is labeled 'id' (regardless of its index).

Parameters:

as_string_or_file (str or Path-like) –
The CSV data to use to pouplate data. Accepts either the raw CSV data as a str or a path to a file in the runtime environment that contains the CSV data.

Tip

Unwrapped empty column values are automatically interpreted as null (None).
series_type (str) – Indicates the series type that should be created from the CSV data. Defaults to 'line'.
has_header_row (bool) – If True, indicates that the first row of as_string_or_file contains column labels, rather than actual data. Defaults to True.
series_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from the CSV file instead.
options_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

Warning

If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the CSV file instead.
chart_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

Warning

If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and CSV file instead.
delimiter (str) – The delimiter used between columns. Defaults to ,.
wrapper_character (str) – The string used to wrap string values when wrapping is applied. Defaults to '.
null_text (str) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.
line_terminator (str) –
The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.

Note

The Python csv currently ignores the line_terminator parameter and always applies '\r\n', by design. The Python docs say this may change in the future, so for future backwards compatibility we are including it here.
wrap_all_strings (bool) –
If True, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults to False.

Warning

If set to True, the csv module will try to coerce any value that is not wrapped in quotation marks to a float. This can cause unexpected behavior, and typically we recommend leaving this as False and then re-casting values after they have been parsed.
double_wrapper_character_when_nested (bool) – If True, quote character is doubled when appearing within a string value. If False, the escape_character is used to prefix quotation marks. Defaults to False.
escape_character (str) – A one-character string that indicates the character used to escape quotation marks if they appear within a string value that is already wrapped in quotation marks. Defaults to \\ (which is Python for '\', which is Python’s native escape character).
series_index (int, slice, or None) – If supplied, generate the chart with the series that Highcharts for Python generated from df at the series_index position. Defaults to None, which includes all series generated from df on the chart.
**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.

Returns:

A Chart instance with its data populated from the CSV data.

Return type:

Chart

Raises:

HighchartsCSVDeserializationError – if property_column_map references CSV columns by their label, but the CSV data does not contain a header row

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_options(options, chart_kwargs=None)[source]

Create a Chart instance from a HighchartsOptions object.

Parameters:

options (HighchartsOptions or coercable) – The configuration options to use to instantiate the chart.
chart_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the instance. Defaults to None.

Warning

If chart_kwargs contains an options key, options will be overwritten by the contents of options.

Returns:

The Chart instance

Return type:

Chart

classmethod from_pandas(df, property_map=None, series_type='line', series_kwargs=None, options_kwargs=None, chart_kwargs=None, series_in_rows=False, series_index=None, **kwargs)[source]

Create a Chart instance whose series are populated from a pandas DataFrame.

from highcharts_core.chart import Chart
from highcharts_core.options.series.area import LineSeries

# Create a chart with one or more LineSeries instances from
# the CSV file "some-csv-file.csv".

# EXAMPLE 1: The minimum code:

my_chart = Chart.from_csv('some-csv-file.csv', series_type = 'line')

# EXAMPLE 2: For more precise configuration and *one* series:

my_chart = Chart.from_csv('some-csv-file.csv',
                          property_column_map = {
                              'x': 0,
                              'y': 3,
                              'id': 'id'
                          },
                          series_type = 'line')

# EXAMPLE 3: For more precise configuration and *multiple* series:

my_chart = Chart.from_csv('some-csv-file.csv',
                          property_column_map = {
                              'x': 0,
                              'y': [3, 5, 8],
                              'id': 'id'
                          },
                          series_type = 'line')

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict or None) –
A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column. Defaults to None.
Note

If any of the values in property_map contain an iterable, then one series will be produced for each item in the iterable. For example, the following:
{ 'x': 'timestamp', 'y': ['value1', 'value2', 'value3'] }
will return three series, each of which will have its .x value populated from the column labeled 'timestamp', and whose .y values will be populated from the columns labeled 'value1', 'value2', and 'value3', respectively.
series_type (str) – Indicates the series type that should be created from the data in df. Defaults to 'line'.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.
options_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

Warning

If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the data in df.
chart_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

Warning

If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and the data in df instead.
series_in_rows (bool) – if True, will attempt a streamlined cartesian series with x-values taken from column names, y-values taken from row values, and the series name taken from the row index. Defaults to False.
series_index (int, slice, or None) – If supplied, generate the chart with the series that Highcharts for Python generated from df at the series_index position. Defaults to None, which includes all series generated from df on the chart.
**kwargs –
Additional keyword arguments that are - in turn - propagated to the series created from the df.

Returns:

A Chart instance with its data populated from the data in df.

Return type:

Chart

Raises:

HighchartsPandasDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if pandas is not available in the runtime environment

classmethod from_pandas_in_rows(df, series_type='line', series_kwargs=None, options_kwargs=None, chart_kwargs=None, series_index=None, **kwargs)[source]

Create a chart from a Pandas DataFrame, treating each row in the dataframe as a series instances.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
series_type (str) – Indicates the series type that should be created from the data in df. Defaults to 'line'.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.
options_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

Warning

If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the data in df.
chart_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

Warning

If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and the data in df instead.
series_index (int, slice, or None) – If supplied, generate the chart with the series that Highcharts for Python generated from df at the series_index position. Defaults to None, which includes all series generated from df on the chart.
**kwargs –
Additional keyword arguments that are - in turn - propagated to the series created from the df.

Returns:

A Chart instance with its data populated from the data in df.

Return type:

Chart

Raises:

HighchartsDependencyError –

if pandas is not available in the runtime environment

classmethod from_pyspark(df, property_map, series_type, series_kwargs=None, options_kwargs=None, chart_kwargs=None)[source]

Create a Chart instance whose data is populated from a PySpark DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.
series_type (str) – Indicates the series type that should be created from the data in df.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.
options_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

Warning

If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the data in df.
chart_kwargs (dict or None) –
An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

Warning

If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and the data in df instead.

Returns:

A Chart instance with its data populated from the data in df.

Return type:

Chart

Raises:

HighchartsPySparkDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if PySpark is not available in the runtime environment

classmethod from_series(*series, kwargs=None)[source]

Creates a new Chart instance populated with series.

Parameters:

series (one or more SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one
kwargs (dict) –
Other properties to use as keyword arguments for the instance to be created.

Warning

If kwargs sets the options.series property, that setting will be overridden by the contents of series.

Returns:

A new Chart instance

Return type:

Chart

get_required_modules(include_extension=False) → List[str][source]

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

get_script_tags(as_str=False) → List[str] | str[source]

Return the collection of <script/> tags needed to load the modules for the chart to render.

Parameters:: as_str (bool) – if True, will return the result as a str instance, rather than a list of str. Defaults to False.
Return type:: list of str or str

to_dict() → dict

Generate a dict representation of the object compatible with the Highcharts JavaScript library.

Note

The dict representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8', careful_validation=False, event_listener: str = 'DOMContentLoaded', event_listener_enabled: bool = True) → str | None[source]

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 (bool) –
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.
event_listener (str) – The name of the JS event to which a listener function should be attached. Defaults to 'DOMContentLoaded', which renders the chart once all DOM content has been loaded.
event_listener_enabled (bool) – If True, generates the JS literal as per the event listener supplied by the event_listener keyword argument. If False, generates directly executable JS code. Defaults to True.

Note

If variable_name is set, will render a string as a new JavaScript instance invocation in the (pseudo-code) form:

new VARIABLE_NAME = new Chart(...);

If variable_name is not set, will simply return the new Chart(...) portion in the string.

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

update_series(*series, add_if_unmatched=False)[source]

Replace existing series with the new versions supplied in series, matching them based on their .id property.

Parameters:

series (one or more SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one
add_if_unmatched (bool) – If True, will add a series that does not have a match. If False, will raise a HighchartsMissingSeriesError if a series does not have a match on the chart. Defaults to False.

property callback: CallbackFunction | None

A (JavaScript) function that is run when the chart has loaded and all external images have been loaded. Defaults to None.

Note

Setting this proprety is equivalent to setting a value for ChartOptions.events.load

Return type:: CallbackFunction or None

property container: str | None

The id of the <div> element in which your Highcharts chart should be rendered. Defaults to None.

Return type:: str or None

property module_url: str

The URL from which Highcharts modules should be downloaded when generating the <script/> tags. Will default to the HIGHCHARTS_MODULE_URL environment variable if available, and otherwise defaults to 'https://code.highcharts.com/'.

Tip

If you need to lock the version of Highharts used to render your charts, we recommend supplying one of the Highcharts CDN version paths, e.g.:

'https://code.highcharts.com/11.0.1/'

'https://code.highcharts.com/11.0.0/'

etc.

Warning

Module paths will be appended to this value without checking that they resolve to an actual file, e.g. the module module/accessibility.js will get appended as 'https://code.highcharts.com/module/accessibility.js'. Be sure to modify this default value carefully.

As a general rule of thumb, we strongly recommend that your URL always end in a slash ('/'), unless your custom URL is loading modules dynamically (e.g. requires a '?module=' or similar).

Returns:: The url from which Highcharts modules should be loaded.
Return type:: str

property options: HighchartsOptions | None

The Python representation of the Highcharts options configuration object Defaults to None.

Return type:: HighchartsOptions or None

property variable_name: str | None

The name given to the (JavaScript) variable to which the (JavaScript) Chart instance wil be assigned. Defaults to None.

Note

When the Chart object is converted to JavaScript code, the (JavaScript) chart instance is assigned to a variable in your JavaScript code. In the example code below, the Chart instance is assigned to a variable_name of chart1:

var chart1 = Highcharts.Chart('myTargetDiv', {});

Warning

If None, when converted to a JavaScript literal, the Chart instance will simply not be assigned to a variable.

Return type:: str or None

.chart

class: Chart

`.chart`

class: `Chart`