`.chart`

class: `Chart`

class Chart(**kwargs)[source]

Python representation of a Highcharts Chart object.

Class Inheritance

add_indicator(indicator_name, series, indicator_kwargs=None)[source]

Creates a new technical indicator series which calculates the indicator indicator_name for the series provided in series, and adds it to the chart’s .options.series.

Parameters:

indicator_name (str) – The name of the indicator that should be added to the series and chart. For the list of supported indicators, please review the Indicator List.
series (str or SeriesBase) – The series to which the indicator should be added. Accepts either a series’ .id as a str, or a SeriesBase (descendant) instance.
indicator_kwargs (dict or None) – Keyword arguments to apply when instantiating the new indicator series. Defaults to None.

Returns:

Nothing. It simply changes the composition of the chart instance’s series to now include a new series with the indicator.

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=0.5, 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 0.5.
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, is_gantt_chart=False)[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.
is_gantt_chart (bool) –
if True, enforces the use of HighchartsGanttOptions. If False, applies HighchartsOptions. Defaults to False.

Note

The value given to this argument will override any values specified in chart_kwargs.

Returns:

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

Return type:

Chart

classmethod from_asana(project_gid, section_gid=None, completed_since=None, use_html_description=True, personal_access_token=None, asana_client=None, api_request_params=None, connection_kwargs=None, connection_callback=None, series_kwargs=None, options_kwargs=None, chart_kwargs=None)[source]

Create a Gantt Chart instance from an Asana project.

Note

Highcharts Gantt for Python can create an Asana API client for you, authenticating using the Personal Access Token` method supported by the Asana API. However, if you wish to use the more-involved OAuth2 handshake process you will need to create your own Asana API client using the asana-python library.

The reason for this is because the OAuth2 handshake has various permutations involving redirects, token refreshes, etc. which are outside the scope of the Highcharts Gantt for Python library, and if you are integrating Highcharts Gantt for Python into a larger application you are likely already facilitating the OAuth2 dance in a fashion appropriate for your use case.

Parameters:

project_gid (str) – The globally unique ID of the Project whose tasks should be used to assemble the Gantt chart.
section_gid (str or None) – The optional unique ID of the section whose tasks should be used to assemble the Gantt chart. Defaults to None, which returns all tasks in the project.
completed_since (datetime or None) – An optional filter which only returns tasks that have been completed after this date. Defaults to None, which returns all tasks.
use_html_description (bool) – If True, will use the Asana task’s HTML notes in the data point’s .description field. If False, will use the non-HTML notes. Defaults to True.
personal_access_token (str or None) – A Personal Access Token created by Asana. Defaults to None, which tries to determine its value by looking in the ASANA_PERSONAL_ACCESS_TOKEN environment variable.
api_request_params (dict or None) – Collection of additional request parameters to submit to the Asana API. Defaults to None.
connection_kwargs (dict or None) – Set of keyword arugments to supply to the DataConnection constructor, besides the .to property which is derived from the task. Defaults to None
connection_callback (Callable or None) –
A custom Python function or method which accepts two keyword arguments: connection_target (which expects the dependency dict object from the Asana task), and asana_task (which expects the Asana task dict object). The function should return a DataConnection instance. Defaults to None

Tip

The connection_callback argument is useful if you want to customize the connection styling based on properties included in the Asana task.
series_kwargs (dict or None) – Collection of additional keyword arguments to use when instantiating the GanttSeries (besides the data argument, which will be determined from the Asana tasks). Defaults to None.
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 Gantt Chart instance

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='\\', is_gantt_chart=False, series_in_rows=False, **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).
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.

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).
is_gantt_chart (bool) – If True, indicates that the chart should be instantiated as a Highcharts Stock for Python chart. Defaults to False.
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.
**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_jira(project_key, server=None, jql=None, username=None, password_or_token=None, oauth_dict=None, client_kwargs=None, jira_client=None, connection_kwargs=None, connection_callback=None, series_kwargs=None, options_kwargs=None, chart_kwargs=None)[source]

Create a Chart instance from an Atlassian JIRA project.

Note

Highcharts Gantt for Python can create a JIRA API client for you, authenticating using either the Basic Authentication or Access Token methods supported by the JIRA API. However, if you wish to use the more-involved OAuth2 handshake, you can do so yourself and either

supply an oauth_dict argument containing the OAuth2 configuration details, or

supply a fully-authenticated jira_client

The reason for this is because the OAuth2 handshake has various permutations involving redirects, token refreshes, etc. which are outside the scope of the Highcharts Gantt for Python library, and if you are integrating Highcharts Gantt for Python into a larger application you are likely already facilitating the OAuth2 dance in a fashion appropriate for your use case.

Parameters:

project_key (str) – The globally unique key of the Project whose tasks should be used to assemble the Gantt chart. For example, JRA.
server (str or None) –
The URL of the JIRA instance from which data should be retrieved. Defaults to None, which looks for a value in the HIGHCHARTS_JIRA_SERVER environment variable. If no value is found there, will then fallback to JIRA Cloud: 'https://jira.atlasian.com'.

Note

This argument will override the comparable setting in client_kwargs if client_kwargs is supplied.
jql (str or None) – An optional JIRA Query Language query string to further narrow the issues returned from JIRA. Defaults to None.
username (str or None) –
The username to use when authenticating using either basic or token authentication. Defaults to None, which looks for a value in the HIGHCHARTS_JIRA_USERNAME environment variable.

Note

If oauth2_dict is supplied, the username argument will be ignored since OAuth2 authentication will be used.
password_or_token (str or None) –
The password or access token to use when authenticating using either basic or token authentication. Defaults to None, which looks for a vlaue in the HIGHCHARTS_JIRA_TOKEN environment variable.

Note

If oauth_dict is supplied, the password_or_token will be ignored since OAuth2 authentication will be used.
oauth_dict (dict or None) –
A dict of key/value pairs providing configuration of the Oauth2 authentication details. Expected keys are:
- 'access_token'
- 'access_token_secret'
- 'consumer_key'
- 'key_cert'
Defaults to None.

Note

To use OAuth2 authentication, an oauth_dict must be supplied. If you wish to force either basic or token authentication, make sure this argument remains None.
client_kwargs (dict or None) – An optional dict providing keyword arguments to use when instantiating the JIRA client.
jira_client (jira.client.JIRA instance that has been fully authenticated) – A fully-configured and fully-authenticated JIRA API client. Defaults to None.
connection_kwargs (dict or None) – Set of keyword arugments to supply to the DataConnection constructor, besides the .to property which is derived from the task. Defaults to None
connection_callback (Callable or None) –
A custom Python function or method which accepts two keyword arguments: connection_target (which expects the dependency Issue object from the initial Issue), and issue (which expects the initial Issue object). The function should return a DataConnection instance. Defaults to None.

Tip

The connection_callback argument is useful if you want to customize the connection styling based on properties included in the target issue.
series_kwargs (dict or None) – Collection of additional keyword arguments to use when instantiating the GanttSeries (besides the data argument, which will be determined from the JIRA issues). Defaults to None.

Returns:

A Gantt Chart instance

Return type:

GanttSeries

Raises:

HighchartsDependencyError – if the jira Python library is not available in the runtime environment
JIRAAuthenticationError – if authentication against the JIRA server fails
HighchartsValueError – if both template and property_column_map are empty

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_monday(board_id, api_token=None, template=None, property_column_map=None, connection_kwargs=None, connection_callback=None, series_kwargs=None, options_kwargs=None, chart_kwargs=None)[source]

Create a Chart instance from a Monday.com work board.

Parameters:

board_id (int) – The ID of the Monday.com board whose items should be retrieved to populate the Gantt series.
api_token (str or None) –
The Monday.com API token to use when authenticating your request against the Monday.com API. Defaults to None, which will then try to determine the token from the MONDAY_API_TOKEN environment variable.

Warning

If no token is either passed to the method or found in the MONDAY_API_TOKEN environment variable, calling this method will raise an error.
template (str or None) –
The name of a standard Mpnday.com board template supported by Highcharts for Python. If supplied, will override the property_column_map argument. Defaults to None.

Note

If property_column_map is set, the template argument will be ignored and overridden by property_column_map.
property_column_map (dict or None) –
A dict used to map Monday.com columns to their corresponding GanttSeries properties. Keys are expected to be GanttSeries properties, while values are expected to be Monday.com column field names. Defaults to None.

Note

If property_column_map is supplied, its settings override the template setting.
connection_kwargs (dict or None) – Set of keyword arugments to supply to the DataConnection constructor, besides the .to property which is derived from the task. Defaults to None
connection_callback (Callable or None) –
A custom Python function or method which accepts two keyword arguments: connection_target (which expects the dependency dict object from the Asana task), and asana_task (which expects the Asana task dict object). The function should return a DataConnection instance. Defaults to None

Tip

The connection_callback argument is useful if you want to customize the connection styling based on properties included in the Asana task.
series_kwargs (dict or None) – Collection of additional keyword arguments to use when instantiating the GanttSeries (besides the data argument, which will be determined from the Asana tasks). Defaults to None.
series_kwargs – Collection of additional keyword arguments to use when instantiating the GanttSeries (besides the data argument, which will be determined from the Asana tasks). Defaults to None.
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 Gantt Chart instance

Return type:

GanttSeries

Raises:

HighchartsDependencyError – if the monday Python library is not available in the runtime environment
MondayAuthenticationError – if there is no Monday.com API token supplied
HighchartsValueError – if both template and property_column_map are empty

classmethod from_options(options, chart_kwargs=None)[source]

Create a Chart instance from a HighchartsOptions or HighchartsGanttOptions object.

Parameters:

options (HighchartsOptions or related 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 data is populated from a pandas 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. Defaults to None.
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 IndicatorSeriesBase 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

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) → 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.

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')

Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

str or bytes

static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False, context: str = None)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.

Return type:

iterable

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 is_gantt_chart: bool

If True, indicates that the chart should be rendered as a Highcharts Gantt chart. If False, the chart will be rendered using the standard Highcharts JS constructor. Defaults to False.

Return type:: bool

property is_stock_chart: bool

If True, indicates that the chart should be rendered as a Highcharts Stock chart. If False, the chart will be rendered using the standard Highcharts JS constructor. Defaults to False.

Return type:: bool

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 | HighchartsGanttOptions | HighchartsStockOptions | None

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

Return type:: HighchartsOptions or HighchartsGanttOptions 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`