Library Internals

module: `.metaclasses`

The .metaclasses module contains - as one might expect - metaclasses that are used to ensure a consistent interface throughout the Highcharts Maps for Python library.

class: `HighchartsMeta`

class HighchartsMeta(**kwargs)[source]

Metaclass that is used to define the standard interface exposed for serializable objects.

Class Inheritance

classmethod _copy_dict_key(key, original, other, overwrite=True, **kwargs)[source]

Copies the value of key from original to other.

Parameters:

key (str) – The key that is to be copied.
original (dict) – The original dict from which it should be copied.
other (dict) – The dict to which it should be copied.

Returns:

The value that should be placed in other for key.

abstract classmethod _get_kwargs_from_dict(as_dict)[source]

Convenience method which returns the keyword arguments used to initialize the class from a Highcharts Javascript-compatible dict object.

Parameters:: as_dict (dict) – The HighCharts JS compatible dict representation of the object.
Returns:: The keyword arguments that would be used to initialize an instance.
Return type:: dict

_process_required_modules(scripts=None, 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:

scripts (list of str) – Initial set of scripts that are context-dependent.
include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.

Return type:

list

abstract _to_untrimmed_dict(in_cls=None) → dict[source]

Generate the first-level of the dict representation of the object.

Note

This method does not traverse the object structure to convert the object into a full dict representation - it merely goes “part” of the way there to replace the Highcharts for Python keys with their correpsond Highcharts JS keys.

Return type:: dict

_untrimmed_mro_ancestors(in_cls=None) → dict[source]

Walk through the parent classes and consolidate the results of their _to_untrimmed_dict() methods into a single dict.

Return type:: dict

classmethod _validate_js_literal(as_str, range=True, _break_loop_on_failure=False)[source]

Parse as_str as a valid JavaScript literal object.

Parameters:

as_str (str) – The string to parse as a JavaScript literal object.
range (bool) – If True, includes location and range data for each node in the AST returned. Defaults to False.
_break_loop_on_failure (bool) – If True, will not loop if the method fails to parse/validate as_str. Defaults to False.

Returns:

The parsed AST representation of as_str and the updated string.

Return type:

2-member tuple of esprima.nodes.Script and str

copy(other=None, overwrite=True, **kwargs)[source]

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

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

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][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 of str

to_dict() → dict[source]

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

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

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 _dot_path: str | None

The dot-notation path to the options key for the current class.

Return type:: str or None

class: `JavaScriptDict`

class JavaScriptDict(dict=None, /, **kwargs)[source]

Special dict class which constructs a JavaScript object that can be represented as a string.

Keys are validated to be valid variable names, while values are validated to be strings.

When serialized to str, keys are not wrapped in double quotes (as they would be in JSON) to ensure that the resulting string can be evaluated as JavaScript code.

Class Inheritance

classmethod _validate_js_literal(as_str, range=True, _break_loop_on_failure=False)[source]

Parse as_str as a valid JavaScript literal object.

Parameters:

as_str (str) – The string to parse as a JavaScript literal object.
range (bool) – If True, includes location and range data for each node in the AST returned. Defaults to False.
_break_loop_on_failure (bool) – If True, will not loop if the method fails to parse/validate as_str. Defaults to False.

Returns:

The parsed AST representation of as_str and the updated string.

Return type:

2-member tuple of esprima.nodes.Script and str

clear() → None. Remove all items from D.

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)[source]

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

Construct an instance of the class from a JSON string.

Parameters:: as_json (str or bytes) – The JSON string for the object.
Returns:: A Python objcet representation of as_json.
Return type:: HighchartsMeta

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair: as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

to_dict()[source]

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

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

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

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

module: `.decorators`

The .decorators module contains decorators and decorator-assisting functions used throughout the Highcharts Maps for Python library.

decorator: `@class_sensitive`

@class_sensitive(types=None, allow_dict=True, allow_json=True, allow_none=True, allow_js_literal=True, force_iterable=False)[source]

Validates that the values passed to a decorated function or method are de-serialized to the appropriate type.

Parameters:

types – type object or iterable of type objects used to indicate which types are allowed. The first (or only) item in types will indicate the primary type that value will be returned as.
allow_dict (bool) – If True, will accept a dict object as value. Defaults to True.
allow_json (bool) – If True, will accept a str object as value, under the assumption that is is deserializable as JSON. Defaults to True.
allow_none (bool) – If True, will accept an empty or None object as value. Defaults to True.
allow_js_literal (bool) – If True, will accept a str object as value, under the assumption that it is deserializable as a JavaScript object literal. Defaults to True.
force_iterable (bool) – If True, will accept an iterable object as value. Defaults to False (because most attributes are just singletons).

Types:

type or iterable of type

Note

To apply the decorator to a property setter method (the most-common use case), place it after the @<property name>.setter decorator and directly above the function name like so:

@some_property.setter
@class_sensitive(...)
def some_property(self, value):
    ...

Returns:

The result of the decorated function or method having validated the class typing.

Raises:

HighchartsImplementationError – if types is empty
HighchartsValueError – if types does not contain a type or iterable of type objects
HighchartsValueError – if the primary type does not conform to the HighchartsMeta interface definition

function: `validate_types()`

validate_types(value, types=None, allow_dict=True, allow_json=True, allow_none=True, allow_js_literal=True, force_iterable=False, function_name=None)[source]

Validates that value is one or more of the allowed types, where the first type passed in types is the primary type that it will be returned as.

Parameters:

value (Any) – The value to be validated.
types – type object or iterable of type objects used to indicate which types are allowed. The first (or only) item in types will indicate the primary type that value will be returned as.
allow_dict (bool) – If True, will accept a dict object as value. Defaults to True.
allow_json (bool) – If True, will accept a str object as value, under the assumption that is is deserializable as JSON. Defaults to True.
allow_none (bool) – If True, will accept an empty or None object as value. Defaults to True.
allow_js_literal (bool) – If True, will accept a str object as value, under the assumption that it is deserializable as a JavaScript object literal. Defaults to True.
force_iterable (bool) – If True, will accept an iterable object as value. Defaults to False (because most attributes are just singletons).
function_name (str) – The optional name of the function that was originally called.

Types:

type or iterable of type

Returns:

value de-serialized to the primary type (first type in types)

Return type:

first type in types

Raises:

HighchartsImplementationError – if types is empty
HighchartsValueError – if types does not contain a type or iterable of type objects
HighchartsValueError – if the primary type does not conform to the HighchartsMeta interface definition

module:: `.js_literal_functions`

The .js_literal_functions module contains functions that are used to parse, process, de-serialize, and serialize JavaScript literal notation.

function: `serialize_to_js_literal()`

serialize_to_js_literal(item, encoding='utf-8', ignore_to_array=False, careful_validation=False) → str | None[source]

Convert item to the contents of a JavaScript object literal code snippet.

Parameters:

item – A value that is to be converted into a JS object literal notation value.
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.
ignore_to_array (bool) – If True, will ignore handling of the .to_array() method to break recursion. Defaults to False.
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.

Returns:

A JavaScript object literal code snippet, expressed as a string. Or None if item is not serializable.

Return type:

str or None

function: `attempt_variable_declaration()`

attempt_variable_declaration(as_str)[source]

Attempt to coerce as_str to a JavaScript variable declaration form.

Parameters:: as_str (str) – The string to evaluate.
Returns:: True if as_str is a JavaScript function. False if not.
Return type:: bool

function: `is_js_function_or_class()`

is_js_function_or_class(as_str, careful_validation=False) → bool[source]

Determine whether as_str is a JavaScript function or not.

Parameters:

as_str (str) – The string to evaluate.
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.

Returns:

True if as_str is a JavaScript function. False if not.

Return type:

bool

function: `get_js_literal()`

get_js_literal(item, careful_validation=False) → str[source]

Convert the value of item into a JavaScript literal string.

Parameters:

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.

Returns:

The JavaScript literal string.

Return type:

str

function: `assemble_js_literal()`

assemble_js_literal(as_dict, keys_as_strings=False, careful_validation=False) → str | None[source]

Convert as_dict into a JavaScript object literal string.

Parameters:

as_dict (dict) – A dict representation of the JavaScript object.
keys_as_strings (bool) – if True, will return the keys as string values (wrapped in quotation marks). If False, will return the keys as object literals. Defaults to False.
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.

Returns:

The JavaScript object literal representation of as_dict.

Return type:

str or None

function: `convert_js_literal_to_python()`

convert_js_literal_to_python(literal_definition, original_str: None)[source]

Convert a esprima.nodes.Literal object into a Python literal.

Note

The esprima.nodes.Property objects are available in the value sub-item.

Return type:: Python objcet

function: `convert_js_property_to_python()`

convert_js_property_to_python(property_definition, original_str=None)[source]: Convert a esprima.nodes.Property object into a Python literal.

Note

The esprima.nodes.Property objects are available in the value sub-item.

function: `convert_js_to_python()`

convert_js_to_python(javascript, original_str=None)[source]: Convert a esprima.nodes.Property object into a Python literal.

Note

The esprima.nodes.Property objects are available in the value sub-item.

function: `get_key_value_pairs()`

get_key_value_pairs(properties, original_str)[source]

Return the key and value pairs for properties defined in properties.

Parameters:: properties (list of esprima.nodes.Property instances) – The definition of a JavaScript object Property.
Return type:: list of tuples of str and any value

`.utility_functions`

The .utility_functions module contains a small number of functions which serve as utilities across the Highcharts Maps for Python library. Think of it as a function “catch all” module.

function:: `mro_to_dict()`

mro_to_dict(obj)[source]

Work through obj’s multiple parent classes, executing the appropriate to_dict() method for each parent and consolidaitng the results to a single dict.

Parameters:: obj – An object that has a to_dict() method.
Return type:: dict

function:: `get_remaining_mro()`

get_remaining_mro(cls, in_cls=None, method='_to_untrimmed_dict')[source]

Retrieve the remaining classes that should be processed for method when traversing cls.

Parameters:

cls (HighchartsMeta) – The class whose ancestors are being traversed.
in_cls (type or None) – The class that the traversal currently finds itself in. Defaults to None
method (str) – The method to search for in the MRO. Defaults to '_to_untrimmed_dict'.

Returns:

List of classes that have method that occur after in_cls in the MRO for cls.

Return type:

list of type objects

function:: `mro__to_untrimmed_dict()`

mro__to_untrimmed_dict(obj, in_cls=None)[source]

Traverse the ancestor classes of obj and execute their _to_untrimmed_dict() methods.

Parameters:

obj (HighchartsMeta) – The object to be traversed.
in_cls (type or None) – The class from which mro__to_untrimmed_dict() was called.

Returns:

Collection of untrimmed dict representations in the same order as the MRO.

Return type:

list of dict

for each class in the MRO, execute _to_untrimmed_dict() do not repeat for each class

function:: `validate_color()`

validate_color(value)[source]

Validate that value is either a Gradient, Pattern, or a str.

Parameters:: value – The value to validate.
Returns:: The validated value.
Return type:: str, Gradient, Pattern`, or None

function:: `to_camelCase()`

to_camelCase(snake_case)[source]

Convert snake_case to camelCase.

Parameters:: snake_case (str) – A str which is likely to contain snake_case.
Returns:: A camelCase representation of snake_case.
Return type:: str

function:: `parse_csv()`

parse_csv(csv_data, has_header_row=True, delimiter=',', null_text='None', wrapper_character="'", wrap_all_strings=False, double_wrapper_character_when_nested=False, escape_character='\\', line_terminator='\r\n')[source]

Parse csv_data to return a list of dict objects, one for each record.

Parameters:

csv_data (str) – The CSV record expressed as a str
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.

Returns:

Collection of column names (or numerical keys) and CSV records as dict values

Return type:

tuple of a list of column names and list of dict