.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 theurl
,port
, andpath
properties explicitly or by setting theHIGHCHARTS_EXPORT_SERVER_DOMAIN`, ``HIGHCHARTS_EXPORT_SERVER_PORT
, orHIGHCHARTS_EXPORT_SERVER_PATH
environment variables.Class Inheritance
- 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. IfNone
, will create a new instance and populate it with properties copied fromself
. Defaults toNone
.overwrite (
bool
) – ifTrue
, properties inother
that are already set will be overwritten by their counterparts inself
. Defaults toTrue
.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.
- 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 astr
or as a filename which contains the JS object literal.allow_snake_case (
bool
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
._break_loop_on_failure (
bool
) – IfTrue
, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults toFalse
.
- 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
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
.
- 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 toNone
.auth_user (
str
orNone
) – The username to use to authenticate against the Export Server, using basic authentication. Defaults toNone
.auth_password (
str
orNone
) – The password to use to authenticate against the Export Server (using basic authentication). Defaults toNone
.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 thetimeout
value. Defaults to3
.
Note
All other keyword arguments are as per the
ExportServer
constructorExportServer.__init__()
- 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.
- classmethod is_export_supported(options) bool [source]
Evaluates whether the Highcharts Export Server supports exporting the series types in
options
.- Return type:
- 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 toNone
.auth_user (
str
orNone
) – The username to use to authenticate against the Export Server, using basic authentication. Defaults toNone
.auth_password (
str
orNone
) – The password to use to authenticate against the Export Server (using basic authentication). Defaults toNone
.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 thetimeout
value. Defaults to3
.
Note
All other keyword arguments are as per the
ExportServer
constructorExportServer.__init__()
- Returns:
The exported chart image, either as a
bytes
binary object or as a base-64 encoded string (depending on theuse_base64
property).- Return type:
- 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.
- 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:
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.
- 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 abytes
object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be abytes
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
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
A JSON representation of the object compatible with the Highcharts library.
- Return type:
- static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None, for_export: bool = False) dict
Remove keys from
untrimmed
whose values areNone
and convert values that have.to_dict()
methods.- Parameters:
untrimmed (
dict
) – Thedict
whose values may still beNone
or Python objects.to_json (
bool
) – IfTrue
, will remove all keys fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – 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 toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
Trimmed
dict
- Return type:
- static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = False)
Convert any
EnforcedNullType
values inuntrimmed
to'null'
.- Parameters:
untrimmed (iterable) – The iterable whose members may still be
None
or Python objects.to_json (
bool
) – IfTrue
, will remove all members fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – 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 toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- 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) methodhighexp.done()
is called. Defaults toFalse
.- Return type:
- 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
orNone
- 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'
- property css: str | None
CSS code that will be loaded into context for the exported chart. Defaults to
None
.
- property custom_code: CallbackFunction | None
When
data_options
is notNone
, this (JavaScript) callback function is executed after the data options are applied. The only argument it receives is the complete set ofHighchartsOptions
(as a JS literal object), which will be passed to the Highcharts constructor on return. Defaults toNone
.- Return type:
CallbackFunction
orNone
- 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
orNone
- 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 theHIGHCHARTS_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 theHIGHCHARTS_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
.
- 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'
- 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 toNone
.- 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
.
- property no_download: bool
If
True
, will not send attachment headers in the HTTP response when exporting a chart. Defaults toFalse
.- Return type:
- property options: HighchartsOptions | None
The
HighchartsOptions
which should be applied to render the exported chart. Defaults toNone
.- Return type:
HighchartsOptions
orNone
- property path: str | None
The path (at the
ExportServer.url()
) where the Export Server can be reached. Defaults toNone
(for the Highsoft-provided export server), unless over-ridden by theHIGHCHARTS_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 theHIGHCHARTS_EXPORT_SERVER_PATH
value if available. If unavailable, will revert toNone
.- 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 theHIGHCHARTS_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 theHIGHCHARTS_EXPORT_SERVER_PORT
value if available. If unavailable, will revert toNone
.- 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 theHIGHCHARTS_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 theHIGHCHARTS_EXPORT_SERVER_PROTOCOL
value if available, and the Highsoft- provided server ('export.highcharts.com'
) if not.- Return type:
- 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 filenamesjs
which contains a string representation of JS codecss
which contains a string representation of CSS code that will applied to the chart on export
Defaults to
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
, adomain
, and optionalport
andpath
.Note
If explicitly set, will override the values in related properties:
- Return type: