.accessibility

• .announce_new_data
• .keyboard_navigation
  • .focus_border
  • .series_navigation
• .point
• .screen_reader_section
• .series

---

class: Accessibility <highcharts_stock.options.accessibility.Accessibility>

class Accessibility(**kwargs)

Options for configuring accessibility for the chart.

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 announce_new_data: AnnounceNewData | None

Options for announcing new data to screen reader users.

Tip

Useful for dynamic data applications and drilldown.

Keep in mind that frequent announcements will not be useful to users, as they won’t have time to explore the new data. For these applications, consider making snapshots of the data accessible, and do the announcements in batches.

Returns:

Configuration for the announcement of new data to screen reader users.

Return type:

AnnounceNewData or None

property custom_components: CustomAccessibilityComponents | None

Property which supports the definition of custom components added to the accessibility module. Defaults to None.

Tip

Remember to add the component to the keyboard_navigation.order() for the keyboard navigation to be usable.

Returns:

Custom components that have been added to the accessibility module.

Return type:

CustomAccessibilityComponents or None

property description: str | None

A text description of the chart.

If the Accessibility module is loaded, this option is included by default as a long description of the chart in the hidden screen reader information region.

Warning

Prefer using Accessibility.linked_description() and Options.caption() instead.

Since Highcharts now supports captions and linked descriptions, it is preferred to define the description using those methods, as a visible caption/description benefits all users. If the accessibility.description option is defined, the linked description is ignored, and the caption is hidden from screen reader users.

Returns:

The description of the chart or None

Return type:

str or None

property enabled: bool | None

If True, enables accessibility functionality for the chart. Defaults to True.

See also

For more information on how to include these features, and why this is recommended, see Highcharts Accessibility

Note

Highcharts will by default emit a warning to the console if the accessibility module is not loaded. Setting this option to false will override and silence the warning.

Once the module is loaded, setting this option to false will disable the module for this chart.

Returns:

Flag indicating whether the Accessibility module is enabled for the chart.

Return type:

bool or None

property high_contrast_mode: str | None

Controls how

.high_contrast_theme is applied.

Note

Defaults to 'auto', which applies the high contrast theme when the user’s system has a high contrast theme active.

Return type:

str or None

property high_contrast_theme: Any

Theme to apply to the chart when Windows High Contrast Mode is detected.

By default, a high contrast theme matching the high contrast system system colors is used.

Returns:

Theme to apply to the chart when high contrast mode is detected.

Return type:

HighContrastTheme or None

property keyboard_navigation: KeyboardNavigation | None

Options for keyboard navigation.

Returns:

Configuration for keyboard navigation.

Return type:

KeyboardNavigation or None

property landmark_verbosity: str | None

Amount of landmarks/regions to create for screen reader users.

More landmarks can make navigation with screen readers easier, but can be distracting if there are lots of charts on the page.

Three modes are available:

• 'all': Adds regions for all series, legend, information region.

• 'one': Adds a single landmark per chart.

• 'disabled': No landmarks are added.

Defaults to 'all'.

Returns:

The landmark verbosity for screen readers to use.

Return type:

str or None

property linked_description: str | None

Link the chart to an HTML element describing the contents of the chart.

Hint

It is always recommended to describe charts using visible text, to improve SEO as well as accessibility for users with disabilities.

This option lets an HTML element with a description be linked to the chart, so that screen reader users can connect the two.

By setting this option to a string, Highcharts runs the string as an HTML selector query on the entire document. If there is only a single match, this element is linked to the chart. The content of the linked element will be included in the chart description for screen reader users.

By default, the chart looks for an adjacent sibling element with the highcharts-description (CSS) class.

The feature can be disabled by setting the option to an empty string, or overridden by providing the :meth`Accessibility.description` option. Alternatively, the HTML element to link can be passed in directly as an HTML node.

Hint

If you need the description to be part of the exported image, consider using the caption feature.

If you need the description to be hidden visually, use the Accessibility.description() option.

Defaults to '*[data-highcharts-chart="{index}"] + .highcharts-description'.

Returns:

The CSS selector used to indicate the HTML element containing a description of the chart.

Return type:

str or None

property point: AccessibilityPoint | None

Options for describing individual points.

Returns:

Configuration for how to describe individual points on the chart.

Return type:

AccessibilityPoint or None

property screen_reader_section: ScreenReaderSection | None

Accessibility options for the screen reader information sections added before and after the chart.

Returns:

Configuration for the screen reader sections before and after the chart.

Return type:

ScreenReaderSection or None

property series: SeriesAccessibility | None

Accessibility options global to all data series.

Hint

Individual series can also have specific accessibility options set.

Returns:

Global accessibility options applied to all data series.

Return type:

SeriesAccessibility or None

property type_description: str | None

A text description of the chart type.

If the Accessibility module is loaded, this will be included in the description of the chart in the screen reader information region.

Note

Highcharts will by default attempt to guess the chart type, but for more complex charts it is recommended to specify this property for clarity.

Returns:

A description fo the chart type.

Return type:

str or None

---

class: CustomAccessibilityComponents <highcharts_stock.options.accessibility.CustomAccessibilityComponents>

class CustomAccessibilityComponents(dict=None, /, **kwargs)

JavaScript object which contains a map of component names to instances of classes inheriting from the (JavaScript) Highcharts.AccessibilityComponent base class.

Tip

Remember to add the component to the keyboard_navigation.order() for the keyboard navigation to be usable.

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

---

Sub-components

Module	Classes / Functions
.options.accessibility	Accessibility CustomAccessibilityComponents
.options.accessibility.announce_new_data	AnnounceNewData
.options.accessibility.keyboard_navigation	KeyboardNavigation
.options.accessibility.keyboard_navigation.focus_border	FocusBorder FocusBorderStyle
.options.accessibility.keyboard_navigation.series_navigation	SeriesNavigation
options.accessibility.point	AccessibilityPoint
options.accessibility.screen_reader_section	ScreenReaderSection
options.accessibility.series	SeriesAccessibility