.announce_new_data

class: AnnounceNewData

class AnnounceNewData(**kwargs)[source]

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

Class Inheritance
Inheritance diagram of AnnounceNewData

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 announcement_formatter: CallbackFunction | None

Optional JavaScript formatter callback for the announcement.

Expects a string containing JavaScript code. This code should be a JavaScript function that up to three arguments:

  1. The first argument is always an array of all series that received updates. If an announcement is already queued, the series that received updates for that announcement are also included in this array.

  2. The second argument is provided if chart.addSeries was called (in JavaScript), and there is a new series. In that case, this argument is a reference to the new series.

  3. The third argument, similarly, is provided if series.addPoint was called (in JavaScript), and there is a new point. In that case, this argument is a reference to the new point.

The JavaScript function should return a string with the text to announce to the user. Return an empty string to not announce anything. Return false to use the default announcement format.

Returns:

The code of the JavaScript function ot use as the formatter callback for the new data announcement.

Return type:

CallbackFunction or None

property enabled: bool | None

Enable the announcement of new data to screen reader users.

Defaults to False.

Returns:

Flag indicating whether new data announcements are enabled for the chart.

Return type:

bool or None

property interrupt_user: bool | None

Choose whether or not the announcements should interrupt the screen reader. Defaults to False.

If not enabled, the user will be notified once idle.

Hint

It is recommended not to enable this setting unless there is a specific reason to do so.

Returns:

Flag indicating whether new data announcements should interrupt the screen reader.

Return type:

bool or None

property minimum_announcement_interval: int | None

Minimum interval between announcements in milliseconds. Defaults to 5000.

Warning

Non-integer values will be coerced to an int.

If new data arrives before this amount of time has passed, it is queued for announcement.

If another new data event happens while an announcement is queued, the queued announcement is dropped, and the latest announcement is queued instead. Set to 0 to allow all announcements, but be warned that frequent announcements are disturbing to users.

Returns:

The minimum interval between announcements, expressed in milliseconds.

Return type:

int or None

Raises:

ValueError – if a negative value is supplied