.buttons

---

class: ExportingButtons

class ExportingButtons(**kwargs)

Special dict class used to construct a collection of Highcharts button configurations. Each key represents the identifier of a button, while the object is a configuration of that button’s settings.

Keys are validated to be valid variable names, while each value is validated to be a ButtonConfiguration.

Class Inheritance

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

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)

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()

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 'utf8'.

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

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

---

class: ContextButtonConfiguration

class ContextButtonConfiguration(**kwargs)

Configuration options that apply to the Context Menu button.

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)

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 class_name: str | None

The class name of the context button. Defaults to 'highcharts-contextbutton'.

Return type:

str or None

property enabled: bool | None

If True, displays the button. If False, the button will be hidden but JavaScript API methods may still be available.

Defaults to True.

Returns:

Flag indicating whether the button is displayed on the chart.

Return type:

bool or None

property menu_class_name: str | None

The class name of the context menu that appears from the button. Defaults to 'highcharts-contextmenu'.

Return type:

str or None

property menu_items: List[str] | None

A collection of strings pointing to config options for the menu items.

The config options are defined in the Exporting.menu_item_definitions option.

Note

By default, the context menu contains “View in fullscreen” and “Print” menu items, plus one menu item for each of the available export types.

Defaults to:

[
    "viewFullscreen",
    "printChart",
    "separator",
    "downloadPNG",
    "downloadJPEG",
    "downloadPDF",
    "downloadSVG"
]

Return type:

list of str or None

property onclick: CallbackFunction | None

JavaScript event callback function which fires when the button is clicked.

Return type:

CallbackFunction or None

property symbol: str | None

The symbol to display on the button. Defaults to 'menu'.

Points to a definition function in the JavaScript Highcharts.Renderer.symbols collection.

The default menu function is part of the exporting module. Possible values are:

• "circle"

• "square"

• "diamond"

• "triangle"

• "triangle-down"

• "menu"

• "menuball"

• or a custom shape

Return type:

str or None

property symbol_fill: str | None

The color to use for the symbol. Defaults to '#666666'.

Return type:

str or None

property text: str | None

The text to display on the button.

Return type:

str or None

property theme: ButtonTheme | None

Configuration of the theme and styling to apply to the button.

Return type:

ButtonTheme or None

property title_key: str | None

The key to a Options.language option setting that is used for the button’s title tooltip.

When the key is 'contextButtonTitle', it refers to language.contextButtonTitle, whose value defaults to "Chart context menu".

Return type:

str or None

property x: int | float | Decimal | None

The horizontal offset of the button’s position relative to its align setting. Defaults to -10.

Return type:

numeric or None

property y: int | float | Decimal | None

The vertical offset of the button’s position relative to its verticalAlign setting. Defaults to 0.

Return type:

numeric or None

---

class: ButtonConfiguration

class ButtonConfiguration(**kwargs)

Configuration of options that apply to a given button.

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)

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, displays the button. If False, the button will be hidden but JavaScript API methods may still be available.

Defaults to True.

Returns:

Flag indicating whether the button is displayed on the chart.

Return type:

bool or None

property text: str | None

The text to display on the button.

Return type:

str or None

property theme: ButtonTheme | None

Configuration of the theme and styling to apply to the button.

Return type:

ButtonTheme or None

property y: int | float | Decimal | None

The vertical offset of the button’s position relative to its verticalAlign setting. Defaults to 0.

Return type:

numeric or None

---

class: ButtonTheme

class ButtonTheme(**kwargs)

Settings used to style buttons.

Class Inheritance

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

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)

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()

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 'utf8'.

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

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

property fill: str | Gradient | Pattern | None

The color of the button’s fill. The default fill exists only to capture hover events.

Return type:

str (for colors), Gradient for gradients, Pattern for pattern definitions, or None

property padding: int | float | Decimal | None

Padding for the button. Defaults to 5.

Return type:

numeric

property states: States | None

States to apply to the button. Defaults to None.

Return type:

States or None

property stroke: str | None

The color of the button’s stroke. Defaults to 'none'.

Return type:

str or None