.exporting

class: Exporting

class Exporting(**kwargs)[source]

Options to configure the export functionality enabled for the chart.

Class Inheritance
Inheritance diagram of Exporting

copy(other=None, overwrite=True, **kwargs)

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

Parameters:

  • other (HighchartsMeta) – The target instance to which the properties of this instance should be copied. If None, will create a new instance and populate it with properties copied from self. Defaults to None.

  • overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.

  • kwargs – Additional keyword arguments. Some special descendents of HighchartsMeta may have special implementations of this method which rely on additional keyword arguments.

Returns:

A mutated version of other with new property values

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

  • as_dict (dict) – A dict representation of the object.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

  • as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

  • _break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file, allow_snake_case: bool = True)

Construct an instance of the class from a JSON string.

Parameters:

  • as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

get_required_modules(include_extension=False) → List[str]

Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.

Parameters:

include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.

Return type:

list of str

to_dict() → dict

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

Note

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

Returns:

A dict representation of the object.

Return type:

dict

to_js_literal(filename=None, encoding='utf-8', careful_validation=False) → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

  • filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None

  • encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

  • careful_validation – if True, will carefully validate JavaScript values

along the way using the esprima-python library. Defaults to False.

Warning

Setting this value to True will significantly degrade serialization performance, though it may prove useful for debugging purposes.

Return type:

str or None

to_json(filename=None, encoding='utf-8')

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

Note

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

Parameters:

  • filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None

  • encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Returns:

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

Return type:

str or bytes

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

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

Parameters:

  • untrimmed (dict) – The dict whose values may still be None or Python objects.

  • to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

  • context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.

Returns:

Trimmed dict

Return type:

dict

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

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

  • untrimmed (iterable) – The iterable whose members may still be None or Python objects.

  • to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

  • context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.

Return type:

iterable

property accessibility: ExportingAccessibilityOptions | None

Accessibility options for the exporting menu.

Return type:

ExportingAccessibilityOptions or None

property allow_html: bool | None

If True, allows HTML inside the chart (added using .use_html properties present on various chart components) to be added directly to the exported image. This allows you to preserve complicated HTML structures like tables or bi-directional text in exported charts.

Defaults to False.

Warning

This setting is EXPERIMENTAL.

The HTML is rendered in a foreignObject tag in the generated SVG. The official export server is based on PhantomJS, which supports this, but other SVG clients, like Batik, do not support it. This also applies to downloaded SVG that you want to open in a desktop client.

Returns:

Flag indicating whether to allow HTML in the exported image.

Return type:

bool or None

property buttons: ExportingButtons | None

Options for the export related buttons: print and export.

Note

In addition to the default buttons listed above, custom buttons can be added.

Warning

The .buttons property accepts an ExportingButtons instance as its value. This object is a descendent of the special JavaScriptDict which by default initially contains a ``’context

Return type:

ExportingButtons

property chart_options

Additional chart options to be merged into the chart before exporting to an image format. This does not apply to printing the chart via the export menu.

For example, a common use case is to add data labels to improve readability of the exported chart, or to add a printer-friendly color scheme to exported PDFs.

Warning

To avoid a circular import error, this property REQUIRES that you supply a value that is an Options instance (e.g. HighchartsOptions, HighchartsStockOptions, HighchartsMapsOptions, etc.). Unlike other Highcharts for Python properties, it does not accept dict or JSON (str) values.

Please be sure to either supply it a valid Options instance, or the value of None.

Return type:

Options or None

Raises:

HighchartsInstanceNeededError – if attempting to set it to a value that is not a Options (or descendent) instance.

property csv: ExportingCSV | None

Options for exporting data to CSV or Microsoft Excel, or displaying the data in a HTML table or a JavaScript structure.

This module adds data export options to the export menu and provides JavaScript functions like Chart.getCSV(), Chart.getTable(), Chart.getDataRows(), and Chart.viewData().

Warning

The XLS converter is limited and only creates a HTML string that is passed for download, which works but creates a warning before opening. The workaround for this is to use a third party XLSX converter.

Returns:

Configuration for exporting data to CSV or Microsoft Excel.

Return type:

ExportingCSV or None

property enabled: bool | None

If True, displays the export context button and allows for exporting the chart. If False, the context button will be hidden but JavaScript export API methods will still be available.

Defaults to True.

Returns:

Flag indicating whether the export menu is displayed on the chart.

Return type:

bool or None

property error: CallbackFunction | None

JavaScript function that is called if the offline-exporting module fails to export a chart on the client side, and Exporting.fallback_to_export_server() is disabled.

If None, a JavaScript exception is thrown instead. The JavaScript function receives two parameters, the exporting options, and the error from the module.

See also

Returns:

JavaScript function code

Return type:

CallbackFunction or None

property fallback_to_export_server: bool | None

If True, falls back to the export server if the offline-exporting module is unable to export the chart on the client side. Defaults to True.

This happens for certain browsers, and certain features (e.g. Exporting.allow_html()), depending on the image type exporting to.

Hint

For very complex charts, it is possible that export can fail in browsers that don’t support Blob objects, due to data URL length limits. It is recommended to define the Exporting.error() handler if disabling fallback, in order to notify users in case export fails.

Returns:

Flag indicating whether to fall back to the export server if chart export fails.

Return type:

bool or None

property fetch_options: dict | None

Options for the fetch request used when sending the SVG to the export server. Defaults to None.

See also

Returns:

The options for the fetch request, expressed as a Python dict

Return type:

dict or None

property filename: str | None

The filename (without file type extension) to use for the exported chart. Defaults to '{constants.DEFAULT_EXPORTING_FILENAME}'.

Return type:

str or None

property form_attributes: dict | None

An object containing additional key value data for the POST form that sends the SVG to the export server.

For example, a target can be set to make sure the generated image is received in another frame, or a custom enctype or encoding can be set.

Returns:

Additional form attributes to supply to the export server.

Return type:

dict or None

property lib_url: str | None

Path where Highcharts will look for export module dependencies to load on demand if they don’t already exist on window.

Should currently point to location of the CanVG library, jsPDF and svg2pdf.js, which are all required for client side export in certain browsers.

Return type:

str or None

property menu_item_definitions: MenuObject | None

An object consisting of definitions for the menu items in the context menu.

Each key value pair has a key that is referenced in the menu_items setting, and a value, which is an object with the following properties:

  • onclick: The click handler for the menu item

  • text: The text for the menu item

  • textKey: If internationalization is required, the key to a language string

Note

Custom text for "exitFullScreen" can be set only in language options (it is not a separate button).

Defaults to:

{
    "viewFullscreen": {},
    "printChart": {},
    "separator": {},
    "downloadPNG": {},
    "downloadJPEG": {},
    "downloadPDF": {},
    "downloadSVG": {}
}
Returns:

Definitions for menu items in the Exporting context menu.

Return type:

MenuObject or None

property pdf_font: PDFFontOptions | None

Settings for a custom font for the exported PDF, when using the offline-exporting module.

This is used for languages containing non-ASCII characters, like Chinese, Russian, Japanese etc.

As described in the jsPDF docs, the 14 standard fonts in PDF are limited to the ASCII-codepage. Therefore, in order to support other text in the exported PDF, one or more TTF font files have to be passed on to the exporting module.

Returns:

Additionl font settings for use in exporting PDFs.

Return type:

PDFFontOptions or None

property print_max_width: int | float | Decimal | None

When printing the chart from the menu item in the burger menu, if the on-screen chart exceeds this width, it is resized. After printing or cancelled, it is restored.

By default, set to 780 which makes the chart fit into typical paper format.

Note

This does not affect the chart when printing the web page as a whole.

Return type:

numeric or None

property scale: int | float | Decimal | None

Defines the scale or zoom factor for the exported image compared to the on-screen display. Defaults to 2.

While for instance a 600px wide chart may look good on a website, it will look bad in print. The default scale of 2 makes this chart export to a 1200px PNG or JPG.

Return type:

numeric or None

property show_export_in_progress: bool | None

If True, displays a message when export is in progress. Defaults to True.

Note

The message displayed can be adjusted in Language.export_in_progress.

Return type:

bool or None

property show_table: bool | None

If True, shows an HTML table below the chart with the chart’s current data. Defaults to False.

Returns:

Flag indicating whether to display an HTML table with the export.

Return type:

bool or None

property source_height: int | float | Decimal | None

The height of the original chart when exported, unless an explicit (JavaScript) chart.height is set, or a pixel width is set on the container.

The height exported raster image is then multiplied by Exporting.scale().

Return type:

numeric or None

property source_width: int | float | Decimal | None

The width of the original chart when exported, unless an explicit (JavaScript) chart.width is set, or a pixel width is set on the container.

The width exported raster image is then multiplied by Exporting.scale().

Return type:

numeric or None

property table_caption: bool | str | None

Caption for the data table. If not specified (None)`), will default to the chart title.

Also accepts a bool value of False, which disables the table caption entirely.

Returns:

Flag (value of False) indicating whether to disable the table caption, or the text of the table caption to use if different from the chart title.

Return type:

bool or str, or None

property type: str | None

Default MIME type for exporting if the JavaScript chart.exportChart() is called without specifying a type option.

Accepts:

  • 'image/png'

  • 'image/jpeg'

  • 'application/pdf'

  • 'image/svg+xml'

Defaults to 'image/png'.

Return type:

str or None

property url: str | None

The URL for the server module converting the SVG string to an image format. By default this points to Highchart’s free web service: '{constants.DEFAULT_EXPORTING_URL}'.

Return type:

str or None

Raises:

ValueError – if not a well-formed URL or path

property use_multi_level_headers: bool | None

If True, uses multi-level (nested) headers in the exported data table. Defaults to True.

Warning

If Exporting.csv.column_header_formatter is specified, then the formatter must return objects for multi-level headers to work properly.

Returns:

Flag indicating whether to use multi-level headers in the data table.

Return type:

bool or None

property use_rowspan_headers: bool | None

If True and using multi-level headers, uses rowspans in the data table for headers that only have one level. Defaults to True.

Returns:

Flag indicating whether to use rowspans for single-level headers in a data table using multi-level headers.

Return type:

bool or None

property width: int | float | Decimal | None

An explicitly set pixel width for charts exported to PNG or JPG. Defaults to None.

Note

If not specified (None), the default pixel width is a function of the Chart.width() or Exporting.source_width() and Exporting.scale().

Return type:

numeric or None

class: ExportingAccessibilityOptions

class ExportingAccessibilityOptions(**kwargs)[source]

Accessibility options for the exporting menu.

Class Inheritance
Inheritance diagram of ExportingAccessibilityOptions

copy(other=None, overwrite=True, **kwargs)

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

Parameters:

  • other (HighchartsMeta) – The target instance to which the properties of this instance should be copied. If None, will create a new instance and populate it with properties copied from self. Defaults to None.

  • overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.

  • kwargs – Additional keyword arguments. Some special descendents of HighchartsMeta may have special implementations of this method which rely on additional keyword arguments.

Returns:

A mutated version of other with new property values

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

  • as_dict (dict) – A dict representation of the object.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

  • as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

  • _break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file, allow_snake_case: bool = True)

Construct an instance of the class from a JSON string.

Parameters:

  • as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

get_required_modules(include_extension=False) → List[str]

Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.

Parameters:

include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.

Return type:

list of str

to_dict() → dict

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

Note

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

Returns:

A dict representation of the object.

Return type:

dict

to_js_literal(filename=None, encoding='utf-8', careful_validation=False) → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

  • filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None

  • encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

  • careful_validation – if True, will carefully validate JavaScript values

along the way using the esprima-python library. Defaults to False.

Warning

Setting this value to True will significantly degrade serialization performance, though it may prove useful for debugging purposes.

Return type:

str or None

to_json(filename=None, encoding='utf-8')

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

Note

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

Parameters:

  • filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None

  • encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Returns:

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

Return type:

str or bytes

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

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

Parameters:

  • untrimmed (dict) – The dict whose values may still be None or Python objects.

  • to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

  • context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.

Returns:

Trimmed dict

Return type:

dict

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

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

  • untrimmed (iterable) – The iterable whose members may still be None or Python objects.

  • to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

  • context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.

Return type:

iterable

property enabled: bool | None

If True, enables accessibility support for the export menu. Defaults to True.

Returns:

Flag indicating whether accessibility support is enabled for the export menu.

Return type:

bool or None

Sub-components

Module

Classes / Functions

.options.exporting

Exporting ExportingAccessibilityOptions

.options.exporting.csv

ExportingCSV CSVAnnotationOptions

.options.exporting.exporting.pdf_font

PDFFontOptions