.headless_export

class: ExportServer

class ExportServer(**kwargs)[source]

Class that provides methods for interacting with the Highcharts Export Server.

Note

By default, the ExportServer class operates using the Highcharts-provided export server. If you wish to use your own (or a custom) export server, you can configure the class using either the url, port, and path properties explicitly or by setting the HIGHCHARTS_EXPORT_SERVER_DOMAIN`, ``HIGHCHARTS_EXPORT_SERVER_PORT, or HIGHCHARTS_EXPORT_SERVER_PATH environment variables.

Class Inheritance
Inheritance diagram of ExportServer

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

classmethod get_chart(filename=None, auth_user=None, auth_password=None, timeout=3, **kwargs)[source]

Produce an exported chart image.

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.

Note

All other keyword arguments are as per the ExportServer constructor ExportServer.__init__()

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

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

classmethod is_export_supported(options) → bool[source]

Evaluates whether the Highcharts Export Server supports exporting the series types in options.

Return type:

bool

request_chart(filename=None, auth_user=None, auth_password=None, timeout=3, **kwargs)[source]

Execute a request against the export server based on the configuration in the instance.

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.

Note

All other keyword arguments are as per the ExportServer constructor ExportServer.__init__()

Returns:

The exported chart image, either as a bytes binary object or as a base-64 encoded string (depending on the use_base64 property).

Return type:

bytes 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

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

Parameters:

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

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

  • careful_validation – if True, will carefully validate JavaScript values

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

Warning

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

Return type:

str or None

to_json(filename=None, encoding='utf-8', for_export: bool = False)

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

Note

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

Parameters:

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

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

  • for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

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

Return type:

str or bytes

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

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

Parameters:

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

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

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

  • for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

Trimmed dict

Return type:

dict

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

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

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

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

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

  • for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Return type:

iterable

property async_rendering: bool

If True, will delay the (server-side) rendering of the exported chart until all scripts, functions, and event handlers provided have been executed and the (JavaScript) method highexp.done() is called. Defaults to False.

Return type:

bool

property callback: CallbackFunction | None

A JavaScript function to execute in the (JavaScript) Highcharts constructor.

Note

This setting is equivalent to providing the Chart.callback() setting.

Return type:

CallbackFunction or None

property constructor: str | None

The (JavaScript) constructor to use when generating the exported chart. Defaults to None.

Accepts:

  • 'Chart'

  • 'chart'

  • 'Stock'

  • 'stockChart'

  • 'Map'

  • 'mapChart'

  • 'Gantt'

  • 'ganttChart'

Return type:

str or None

property css: str | None

CSS code that will be loaded into context for the exported chart. Defaults to None.

Return type:

str or None

property custom_code: CallbackFunction | None

When data_options is not None, this (JavaScript) callback function is executed after the data options are applied. The only argument it receives is the complete set of HighchartsOptions (as a JS literal object), which will be passed to the Highcharts constructor on return. Defaults to None.

Return type:

CallbackFunction or None

property data_options: Data | None

Configuration of data options to add data to the chart from sources like CSV. Defaults to None.

Return type:

Data or None

property domain: str | None

The domain where the Export Server can be found. Defaults to the Highsoft-provided Export Server at 'export.highcharts.com', unless over-ridden by the HIGHCHARTS_EXPORT_SERVER_DOMAIN environment variable.

Tip

This property is set automatically by the HIGHCHARTS_EXPORT_SERVER_DOMAIN environment variable, if present.

Warning

If set to None, will fall back to the HIGHCHARTS_EXPORT_SERVER_DOMAIN value if available, and the Highsoft- provided server ('export.highcharts.com') if not.

Return type:

str

property files: List[str] | None

Collection of files that will be loaded into context for the export. Defaults to None.

Return type:

list of str or None

property format_: str | None

The format in which the exported chart should be returned. Defaults to 'png'.

Accepts:

  • 'png'

  • 'jpeg'

  • 'pdf'

  • 'svg'

  • 'image/svg+xml'

Return type:

str or None

property global_options: HighchartsOptions | None

The global options which will be passed to the (JavaScript) Highcharts.setOptions() method, and which will be applied to the exported chart. Defaults to None.

Return type:

HighchartsOptions

property height: int | float | None

The height that the exported chart should have. Defaults to None.

Warning

If explicitly set, this setting will override scale.

Return type:

numeric or None

property js: str | None

JavaScript code that will be loaded into context for the exported chart. Defaults to None.

Return type:

str or None

property no_download: bool

If True, will not send attachment headers in the HTTP response when exporting a chart. Defaults to False.

Return type:

bool

property options: HighchartsOptions | None

The HighchartsOptions which should be applied to render the exported chart. Defaults to None.

Return type:

HighchartsOptions or None

property path: str | None

The path (at the ExportServer.url()) where the Export Server can be reached. Defaults to None (for the Highsoft-provided export server), unless over-ridden by the HIGHCHARTS_EXPORT_SERVER_PATH environment variable.

Tip

This property is set automatically by the HIGHCHARTS_EXPORT_SERVER_PATH environment variable, if present.

Warning

If set to None, will fall back to the HIGHCHARTS_EXPORT_SERVER_PATH value if available. If unavailable, will revert to None.

Return type:

str

property port: int | None

The port on which the Export Server can be found. Defaults to None (for the Highsoft-provided export server), unless over-ridden by the HIGHCHARTS_EXPORT_SERVER_PORT environment variable.

Tip

This property is set automatically by the HIGHCHARTS_EXPORT_SERVER_PORT environment variable, if present.

Warning

If set to None, will fall back to the HIGHCHARTS_EXPORT_SERVER_PORT value if available. If unavailable, will revert to None.

Return type:

str

property protocol: str | None

The protocol over which the Highcharts for Python library should communicate with the Export Server. Accepts either 'https' or 'http'. Defaults to the HIGHCHARTS_EXPORT_SERVER_PROTOCOL environment variable if present, otherwise falls back to default of 'https'.

Tip

This property is set automatically by the HIGHCHARTS_EXPORT_SERVER_PROTOCOL environment variable, if present.

Warning

If set to None, will fall back to the HIGHCHARTS_EXPORT_SERVER_PROTOCOL value if available, and the Highsoft- provided server ('export.highcharts.com') if not.

Return type:

str

property referer: str | None

The referer to use when making requests to the export server. Defaults to the HIGHCHARTS_EXPORT_SERVER_REFERER environment variable if present, otherwise defaults to 'https://www.highcharts.com'.

Return type:

str or None

property resources: Dict | None

A dictionary of resources to be used in the export server.

Expects to contain up to three keys:

  • files which contains an array of JS filenames

  • js which contains a string representation of JS code

  • css which contains a string representation of CSS code that will applied to the chart on export

Defaults to None.

Return type:

dict or None

property scale: int | float | None

The scale factor by which the exported chart image should be scaled. Defaults to 1.

Tip

Use this setting to improve resolution when exporting PNG or JPEG images. For example, setting .scale = 2 on a chart whose width is 600px will produce an image with a width of 1200px.

Warning

If width is explicitly set, this setting will be overridden.

Return type:

numeric

property url: str | None

The fully-formed URL for the Export Server, consisting of a protocol, a domain, and optional port and path.

Note

If explicitly set, will override the values in related properties:

Return type:

str

property use_base64: bool

If True, returns the exported chart in base64 encoding. If False, returns the exported chart in binary. Defaults to False.

Return type:

bool

property user_agent: str | None

The user agent to use when making requests to the export server. Defaults to the HIGHCHARTS_EXPORT_SERVER_USER_AGENT environment variable if present, otherwise defaults to ``Highcharts Core for Python / v.<VERSION NUMBER>.

Return type:

str or None

property width: int | float | None

The width that the exported chart should have. Defaults to None.

Warning

If explicitly set, this setting will override scale.

Return type:

numeric or None