`.javascript_functions`

class: `CallbackFunction`

class CallbackFunction(**kwargs)[source]

Representation of a JavaScript callback function’s source code.

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. 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)[source]

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_python(callable, model='gpt-3.5-turbo', api_key=None, **kwargs)[source]

Return a CallbackFunction having converted a Python callable into a JavaScript function using the generative AI model indicated.

Note

Because this relies on the outside APIs exposed by OpenAI and Anthropic, if you wish to use one of their models you must supply your own API key. These are paid services which they provide, and so you will be incurring costs by using these generative AIs.

Parameters:

callable (callable) – The Python callable to convert.
model (str) –
The generative AI model to use. Defaults to 'gpt-3.5-turbo'. Accepts:
- 'gpt-3.5-turbo' (default)
- 'gpt-3.5-turbo-16k'
- 'gpt-4'
- 'gpt-4-32k'
- 'claude-instant-1'
- 'claude-2'
api_key (str or None) –
The API key used to authenticate against the generative AI provider. Defaults to None, which then tries to find the API key in the appropriate environment variable:
- OPENAI_API_KEY if using an OpenAI provided model
- ANTHROPIC_API_KEY if using an Anthropic provided model
**kwargs –
Additional keyword arguments which are passed to the underlying model API. Useful for advanced configuration of the model’s behavior.

Returns:

The CallbackFunction representation of the JavaScript code that does the same as the callable argument.

Warning

Generating the JavaScript source code is not deterministic. That means that it may not be correct, and we STRONGLY recommend reviewing it before using it in a production application.

Every single generative AI is known to have issues - whether “hallucinations”, biases, or incoherence. We cannot stress enough:

DO NOT RELY ON AI-GENERATED CODE IN PRODUCTION WITHOUT HUMAN REVIEW.

That being said, for “quick and dirty” EDA, fast prototyping, etc. the functionality may be “good enough”.

Return type:

CallbackFunction

Raises:

HighchartsValueError – if callable is not a Python callable
HighchartsValueError – if no api_key is available
HighchartsDependencyError – if a required dependency is not available in the runtime environment
HighchartsModerationError – if using an OpenAI model, and OpenAI detects that the supplied input violates their usage policies
HighchartsPythonConversionError – if the model was unable to convert callable into JavaScript source code

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[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 – 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(encoding='utf-8')[source]

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 arguments: List[str] | None

Collection of named arguments (parameters) that will be passed to the function.

Return type:: list of str, or None

property body: str | None

The source code of the function itself.

Note

Should not be wrapped in { ... }. It should just be the source code of the the function itself.

Hint

When writing this code in Python, it is best to use the three-quotation-mark string pattern, like so:

callback = CallbackFunction()
callback.body = """
... some JavaScript logic goes here
"""

Return type:: str or None

property function_name: str | None

An optional name to be given to the function.

Warning

Most Highcharts Callback function definitions are anonymous, meaning that they are named within the object into which they are embedded. As a result, this setting should be used sparingly.

Return type:: str

class: `JavaScriptClass`

class JavaScriptClass(**kwargs)[source]

Representation of a JavaScript class.

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. 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)[source]

Return a Python object representation of a JavaScript class.

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.
_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[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 – 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 class_name: str | None

The name of the JavaScript class.

Return type:: str or None

property methods: List[CallbackFunction] | None

Collection of methods that are to be defined within the class. Defaults to None.

Warning

All methods must have a function_name set.

Warning

One of the methods must have a function_name of 'constructor' and be used as a constructor for the class.

Note

For the sake of simplicity, the JavaScriptClass does not support ECMAScript’s more robust public/private field declaration syntax, nor does it support the definition of getters or generators.

Return type:: list of CallbackFunction, or None
Raises:: HighchartsJavaScriptError – if one or more methods lacks a function name OR if there is no constructor method included in .methods.

.javascript_functions

class: CallbackFunction

class: JavaScriptClass

`.javascript_functions`

class: `CallbackFunction`

class: `JavaScriptClass`