Source code for highcharts_core.options

"""Implements the :class:`HighchartsOptions` class."""
from typing import Optional, List

from validator_collection import validators

from highcharts_core import utility_functions
from highcharts_core.metaclasses import HighchartsMeta
from highcharts_core.decorators import class_sensitive
from highcharts_core.utility_classes.gradients import Gradient
from highcharts_core.utility_classes.patterns import Pattern
from highcharts_core.options.series.series_generator import create_series_obj

from highcharts_core.options.accessibility import Accessibility
from highcharts_core.options.annotations import Annotation
from highcharts_core.options.boost import Boost
from highcharts_core.options.caption import Caption
from highcharts_core.options.chart import ChartOptions
from highcharts_core.options.axes.color_axis import ColorAxis
from highcharts_core.options.credits import Credits
from import Data
from highcharts_core.options.defs import MarkerDefinition
from highcharts_core.options.drilldown import Drilldown
from highcharts_core.options.exporting import Exporting
from highcharts_core.global_options.language import Language
from highcharts_core.options.legend import Legend
from highcharts_core.options.loading import Loading
from highcharts_core.options.navigation import Navigation
from highcharts_core.options.no_data import NoData
from highcharts_core.options.pane import Pane
from highcharts_core.options.plot_options import PlotOptions
from highcharts_core.options.plot_options.generic import GenericTypeOptions
from highcharts_core.options.responsive import Responsive
from highcharts_core.options.sonification import SonificationOptions
from highcharts_core.options.subtitle import Subtitle
from highcharts_core.options.time import Time
from highcharts_core.options.title import Title
from highcharts_core.options.tooltips import Tooltip
from highcharts_core.options.axes.x_axis import XAxis
from highcharts_core.options.axes.y_axis import YAxis
from highcharts_core.options.axes.z_axis import ZAxis

[docs]class Options(HighchartsMeta): """Metaclass which establishes properties shared across different variations of the Highcharts configuration objects.""" def __init__(self, **kwargs): self._accessibility = None self._annotations = None self._caption = None self._chart = None self._color_axis = None self._colors = None self._credits = None self._data = None self._defs = None self._exporting = None self._language = None self._legend = None self._loading = None self._navigation = None self._plot_options = None self._responsive = None self._series = None self._sonification = None self._subtitle = None self._time = None self._title = None self._tooltip = None self._x_axis = None self._y_axis = None self.accessibility = kwargs.get('accessibility', None) self.annotations = kwargs.get('annotations', None) self.caption = kwargs.get('caption', None) self.chart = kwargs.get('chart', None) self.color_axis = kwargs.get('color_axis', None) self.colors = kwargs.get('colors', None) self.credits = kwargs.get('credits', None) = kwargs.get('data', None) self.defs = kwargs.get('defs', None) self.exporting = kwargs.get('exporting', None) self.language = kwargs.get('language', None) self.legend = kwargs.get('legend', None) self.loading = kwargs.get('loading', None) self.navigation = kwargs.get('navigation', None) self.plot_options = kwargs.get('plot_options', None) self.responsive = kwargs.get('responsive', None) self.sonification = kwargs.get('sonification', None) self.subtitle = kwargs.get('subtitle', None) self.time = kwargs.get('time', None) self.title = kwargs.get('title', None) self.tooltip = kwargs.get('tooltip', None) self.x_axis = kwargs.get('x_axis', None) self.y_axis = kwargs.get('y_axis', None) self.series = kwargs.get('series', None)
[docs] def __str__(self): """Return a human-readable :class:`str <python:str>` representation of the chart configuration. .. warning:: To ensure that the result is human-readable, the result will be rendered *without* its ``plot_options`` and ``series`` sub-properties. .. tip:: If you would like a *complete* and *unambiguous* :class:`str <python:str>` representation, then you can: * use the :meth:`__repr__() <highcharts_core.options.Options.__repr__>` method, * call ``repr(my_options)``, or * serialize the chart to JSON using ``my_options.to_json()``. :returns: A :class:`str <python:str>` representation of the chart configuration. :rtype: :class:`str <python:str>` """ as_dict = self.to_dict() kwargs = {utility_functions.to_snake_case(key): as_dict[key] for key in as_dict if key not in ['series', 'plotOptions']} kwargs_as_str = ', '.join([f'{key} = {repr(kwargs[key])}' for key in kwargs]) return f'{self.__class__.__name__}({kwargs_as_str})'
@property def accessibility(self) -> Optional[Accessibility]: """Options for configuring accessibility for the chart. .. note:: Requires the accessibility module to be loaded in the browser. For a description of the module and information on its features, see `Highcharts Accessibility <>`_. :returns: The accessibility configuration for the chart or :obj:`None <python:None>` :rtype: :class:`Accessibility <highcharts.accessibility.Accessibility>` / :obj:`None <python:None>` :raise HighchartsError: if setting the value to an incompatible type """ return self._accessibility @accessibility.setter @class_sensitive(Accessibility) def accessibility(self, value: Optional[Accessibility | dict | str]): self._accessibility = value @property def annotations(self) -> Optional[List[Annotation]]: """A basic type of an annotation. It allows adding custom labels or shapes. The items can be tied to points, axis coordinates or chart pixel coordinates. :returns: A collection of the annotations applied to the chart. :rtype: :class:`list <python:list>` of :class:`Annotation` objects or :obj:`None <python:None>` if no annotations are applied """ return self._annotations @annotations.setter @class_sensitive(Annotation, force_iterable = True) def annotations(self, value): self._annotations = value @property def caption(self) -> Optional[Caption]: """The chart's caption, which will render below the chart and will be part of exported charts. .. note:: The caption can be updated after chart initialization through the ``Chart.update`` or ``Chart.caption.update`` JavaScript methods. :returns: The chart's caption or :obj:`None <python:None>` :rtype: :class:`Caption` / :obj:`None <python:None>` """ return self._caption @caption.setter @class_sensitive(Caption) def caption(self, value): self._caption = value @property def chart(self) -> Optional[ChartOptions]: """General options for the chart. .. note:: This property is perhaps one of the most important properties you will use when configuring your Highcharts data visualization. :returns: A :class:`ChartOptions` configuration object or :obj:`None <python:None>` :rtype: :class:`ChartOptions` or :obj:`None <python:None>` """ return self._chart @chart.setter @class_sensitive(ChartOptions) def chart(self, value): self._chart = value @property def color_axis(self) -> Optional[List[ColorAxis]]: """A color axis for series. Visually, the color axis will appear as a gradient or as separate items inside the legend, depending on whether the axis is scalar or based on data classes. A scalar color axis is represented by a gradient. The colors either range between the ``minimum_color`` and the ``maximum_color``, or for more fine grained control the colors can be defined in :ref:`stops <ColorAxis.stops>`. Often times, the color axis needs to be adjusted to get the right color spread for the data. In addition to stops, consider using a logarithmic axis type, or setting min and max to avoid the colors being determined by outliers. For supported color formats, please see `the documentation article about colors <>`_. When :ref:`data_classes <ColorAxis.data_classes>` are used, the ranges are subdivided into separate classes like categories based on their values. This can be used for ranges between two values, but also for a true category. However, when your data is categorized, it may be as convenient to add each category to a separate series. .. warning:: Color axis does not work with: ``sankey``, ``sunburst``, ``dependencywheel``, ``networkgraph``, ``wordcloud``, ``venn``, ``gauge`` and ``solidgauge`` series types. See the :ref:`Axis` object for programmatic access to the axis. :returns: A collection of :class:`ColorAxis` objects defining the color axis to apply, or :obj:`None <python:None>`. :rtype: :class:`list <python:list>` of :class:`ColorAxis` or :obj:`None <python:None>` """ return self._color_axis @color_axis.setter @class_sensitive(ColorAxis, force_iterable = True) def color_axis(self, value): self._color_axis = value @property def colors(self) -> Optional[List[str | Gradient | Pattern]]: """An array containing the default colors for the chart's series. When all colors are used, new colors are pulled from the start again. Default colors can also be set on a series or ``series.type`` basis, see :ref:`Column.colors` and :ref:`Pie.colors`. .. warning:: In styled mode, the colors option does not exist. Instead, colors are defined in CSS and applied either through series or point class names, or through the :ref:`Chart.color_count` option. Defaults to: .. code-block:: python [ "#7cb5ec", "#434348", "#90ed7d", "#f7a35c", "#8085e9", "#f15c80", "#e4d354", "#2b908f", "#f45b5b", "#91e8e1" ] :returns: A collection of hex color strings. :rtype: :class:`list <python:list>` of :class:`str <python:str>` """ return self._colors @colors.setter def colors(self, value): if not value: self._colors = None else: value = validators.iterable(value) self._colors = [utility_functions.validate_color(x) for x in value] @property def credits(self) -> Optional[Credits]: """Highchart by default puts a credits label in the lower right corner of the chart. This can be changed using these options. :returns: :class:`Credits` configuration or :obj:`None <python:None>` :rtype: :class:`Credits` or :obj:`None <python:None>` """ return self._credits @credits.setter @class_sensitive(Credits) def credits(self, value): self._credits = value @property def data(self) -> Optional[Data]: """The ``data`` property provides a simplified interface for adding data to a chart from sources like CVS, HTML tables, or grid views. See also `the tutorial article on the Data module <>`_. .. warning:: It requires the ``modules/data.js`` file to be loaded in the browser / client. .. warning:: Please note that the default way of adding data in Highcharts, without the need of a module, is through the ```` property. :returns: The :class:`Data` object or :obj:`None <python:None>` :rtype: :class:`Data` object or :obj:`None <python:None>` """ return self._data @data.setter @class_sensitive(Data) def data(self, value): self._data = value @property def defs(self) -> Optional[MarkerDefinition]: """Options for configuring markers for annotations. :returns: A :class:`MarkerDefinition` object or :obj:`None <python:None>` :rtype: :class:`MarkerDefinition` or :obj:`None <python:None>` """ return self._defs @defs.setter @class_sensitive(MarkerDefinition) def defs(self, value): self._defs = value @property def exporting(self) -> Optional[Exporting]: """Options to configure the export functionality enabled for the chart. :returns: The configuration of the chart's exporting functionality. :rtype: :class:`Exporting` or :obj:`None <python:None>` """ return self._exporting @exporting.setter @class_sensitive(Exporting) def exporting(self, value): self._exporting = value @property def language(self) -> Optional[Language]: """Language object which can be used to configure the specific text to use in the chart. .. note:: When working in JavaScript, the ``lang`` configuration is global and it can't be set on each chart initialization. Instead, use ``Highcharts.setOptions()`` to set it before any chart is initialized. :returns: A :class:`Language` object or :obj:`None <python:None>` :rtype: :class:`Language` or :obj:`None <python:None>` """ return self._language @language.setter @class_sensitive(Language) def language(self, value): self._language = value @property def legend(self) -> Optional[Legend]: """The legend is a box containing a symbol and name for each series item or point item in the chart. Each series (or points in case of pie charts) is represented by a symbol and its name in the legend. .. seealso:: It is possible to override the symbol creator function and create `custom legend symbols <>`_. :returns: The :class:`Legend` configuration or :obj:`None <python:None>` :rtype: :class:`Legend` or :obj:`None <python:None>` """ return self._legend @legend.setter @class_sensitive(Legend) def legend(self, value): self._legend = value @property def loading(self) -> Optional[Loading]: """The loading options control the appearance of the loading screen that covers the plot area on chart operations. This screen only appears after an explicit call to ``chart.showLoading()`` in the browser. It is a utility for developers to communicate to the end user that something is going on, for example while retrieving new data via an XHR connection. .. hint:: The "Loading..." text itself is **not** part of this configuration object, but is instead part of the :meth:`.language <Options.language>` configuration. :returns: The configuration of the loading screen or :obj:`None <python:None>` :rtype: :class:`Loading` or :obj:`None <python:None>` """ return self._loading @loading.setter @class_sensitive(Loading) def loading(self, value): self._loading = value @property def navigation(self) -> Optional[Navigation]: """A collection of options for buttons and menus appearing in the exporting module or in Stock Tools. :returns: The configuration of the navigation buttons. :rtype: ;class:`Navigation` or :obj:`None <python:None>` """ return self._navigation @navigation.setter @class_sensitive(Navigation) def navigation(self, value): self._navigation = value @property def plot_options(self) -> Optional[PlotOptions]: """A wrapper object for configurations applied to each series type. The config objects for each series can also be overridden for each series item as given in the series array. Configuration options for the series are given in three levels: * Options for all series in a chart are given in the :meth:`series <PlotOptions.series>` property. * Options for all series of a specific type are given in the corresponding property for that type, for example :meth:`plot_options.line <PlotOptions.line>`. * Finally, options for one single series are given in the :meth:`series <Options.series>` array. :returns: Configurations for how series should be plotted / displayed. :rtype: :class:`PlotOptions` or :obj:`None <python:None>` """ return self._plot_options @plot_options.setter @class_sensitive(PlotOptions) def plot_options(self, value): self._plot_options = value @property def responsive(self) -> Optional[Responsive]: """Rules to apply for different screen or chart sizes. .. note:: Each rule specifies additional chart options. :returns: Rules to apply for different screen or chart sizes. :rtype: :class:`Responsive` or :obj:`None <python:None>` """ return self._responsive @responsive.setter @class_sensitive(Responsive) def responsive(self, value): self._responsive = value @property def series(self) -> Optional[List[GenericTypeOptions]]: """Series options for specific data and the data itself. :returns: The series to display along with configuration and data. :rtype: :class:`Series` or :obj:`None <python:None>` """ return self._series @series.setter def series(self, value): value = validators.iterable(value, allow_empty = True) default_series_type = None if self.chart: default_series_type = self.chart.type if not value: self._series = None else: self._series = [create_series_obj(x, default_type = default_series_type) for x in value] @property def sonification(self) -> Optional[SonificationOptions]: """Configuration of global sonification settings for the entire chart. :rtype: :class:`SonificationOptions <highcharts_core.options.sonification.SonificationOptions>` or :obj:`None <python:None>` """ return self._sonification @sonification.setter @class_sensitive(SonificationOptions) def sonification(self, value): self._sonification = value @property def subtitle(self) -> Optional[Subtitle]: """The chart's subtitle. .. note:: This can be used both to display a subtitle below the main title, and to display random text anywhere in the chart. .. warning:: The subtitle can be updated after chart initialization through the ``Chart.setTitle`` JavaScript method. :returns: Configuration of the chart's subtitle. :rtype: :class:`Subtitle` or :obj:`None <python:None>` """ return self._subtitle @subtitle.setter @class_sensitive(Subtitle) def subtitle(self, value): self._subtitle = value @property def time(self) -> Optional[Time]: """Time options that can apply globally or to individual charts. These settings affect how datetime axes are laid out, how tooltips are formatted, how series :meth:`point_interval_unit <Series.point_interval_unit` works and how the Highcharts Stock range selector handles time. :returns: Configuration of applicable Time options. :rtype: :class:`Time` or :obj:`None <python:None>` """ return self._time @time.setter @class_sensitive(Time) def time(self, value): self._time = value @property def title(self) -> Optional[Title]: """Options for configuring the chart's main title. :returns: Configuration of the chart's main title. :rtype: :class:`Title` or :obj:`None <python:None>` """ return self._title @title.setter @class_sensitive(Title) def title(self, value): self._title = value @property def tooltip(self) -> Optional[Tooltip]: """Options for the tooltip that appears when the user hovers over a series or point. :returns: Configuration settings for tooltips to display above the chart. :rtype: :class:`Tooltip` or :obj:`None <python:None>` """ return self._tooltip @tooltip.setter @class_sensitive(Tooltip) def tooltip(self, value): self._tooltip = value @property def x_axis(self) -> Optional[List[XAxis]]: """The X axis or category axis. Normally this is the horizontal axis, though if the chart is inverted this is the vertical axis. :returns: A collection of :class:`XAxis` objects :rtype: :class:`list <python:list>` of :class:`XAxis` or :obj:`None <python:None>` """ return self._x_axis @x_axis.setter @class_sensitive(XAxis, force_iterable = True) def x_axis(self, value): self._x_axis = value @property def y_axis(self) -> Optional[List[YAxis]]: """The Y axis or value axis. Normally this is the vertical axis, though if the chart is inverted this is the horizontal axis. :returns: A collection of :class:`YAxis` objects :rtype: :class:`list <python:list>` of :class:`YAxis` or :obj:`None <python:None>` """ return self._y_axis @y_axis.setter @class_sensitive(YAxis, force_iterable = True) def y_axis(self, value): self._y_axis = value
[docs] def add_series(self, *series): """Adds ``series`` to the :meth:`series <highcharts_core.options.HighchartsOptions.series>` property. :param series: One or more :term:`series` instances (descended from :class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) or an instance (e.g. :class:`dict <python:dict>`, :class:`str <python:str>`, etc.) coercable to one :type series: one or more :class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>` or coercable """ new_series = [] for item in series: item_series = create_series_obj(item) new_series.append(item_series) if self.series: existing_series = [x for x in self.series] else: existing_series = [] updated_series = existing_series + new_series self.series = updated_series
[docs] @classmethod def from_series(cls, *series, kwargs = None): """Creates a new :class:`Options <highcharts_core.options.Options>` instance populated with ``series``. :param series: One or more :term:`series` instances (descended from :class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) or an instance (e.g. :class:`dict <python:dict>`, :class:`str <python:str>`, etc.) coercable to one :type series: one or more :class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>` or coercable :param kwargs: Other properties to use as keyword arguments for the instance to be created. .. warning:: If ``kwargs`` sets the :meth:`.series <highcharts_core.options.Options.series>` property, that setting will be *overridden* by the contents of ``series``. :type kwargs: :class:`dict <python:dict>` :returns: A new :class:`Options <highcharts_core.options.Options>` instance :rtype: :class:`Options <highcharts_core.options.Options>` """ kwargs = validators.dict(kwargs, allow_empty = True) or {} instance = cls(**kwargs) instance.add_series(series)
[docs]class HighchartsOptions(Options): """The Python representation of the `Highcharts <>`_ ``options`` `configuration object <>`_.""" def __init__(self, **kwargs): self._boost = None self._drilldown = None self._no_data = None self._pane = None self._z_axis = None self.boost = kwargs.get('boost', None) self.drilldown = kwargs.get('drilldown', None) self.no_data = kwargs.get('no_data', None) self.pane = kwargs.get('pane', None) self.z_axis = kwargs.get('z_axis', None) super().__init__(**kwargs) @property def boost(self) -> Optional[Boost]: """Options for the Boost module. The Boost module allows certain series types to be rendered by WebGL instead of the default SVG. This allows hundreds of thousands of data points to be rendered in milliseconds. In addition to the WebGL rendering it saves time by skipping processing and inspection of the data wherever possible. .. warning:: This introduces some limitations to what features are available in boost mode. See `the docs <>`_ for details. .. note: In addition to the global boost option, each series has a ``boostThreshold`` that defines when the boost should kick in. :returns: The :class:`Boost <Boost>` object. :rtype: :class:`Boost <highcharts.boost.Boost>` """ return self._boost @boost.setter @class_sensitive(Boost) def boost(self, value): self._boost = value @property def drilldown(self) -> Optional[Drilldown]: """Options to configure :term:`drilldown` functionality in the chart, which enables users to inspect increasingly high resolution data by clicking on chart items like columns or pie slices. .. note:: The drilldown feature requires the ``drilldown.js`` file to be loaded in the browser/client. This file is found in the modules directory of the download package, or online at ` <>`_. :returns: The options to configure the chart's drill down functionality. :rtype: :class:`Drilldown` or :obj:`None <python:None>` """ return self._drilldown @drilldown.setter @class_sensitive(Drilldown) def drilldown(self, value): self._drilldown = value @property def no_data(self) -> Optional[NoData]: """Options for displaying a message like "No data to display". .. warning:: This feature requires the file ``no-data-to-display.js`` to be loaded in the page. .. tip:: The actual text to display is set in the :meth:`language <Options.language>` options. :returns: Configuration of how to display a no data message. :rtype: :class:`NoData` or :obj:`None <python:None>` """ return self._no_data @no_data.setter @class_sensitive(NoData) def no_data(self, value): self._no_data = value @property def pane(self) -> Optional[Pane]: """The pane serves as a container for axes and backgrounds for circular gauges and polar charts. :returns: The Pane configuration options. :rtype: :class:`Pane` or :obj:`None <python:None>` """ return self._pane @pane.setter @class_sensitive(Pane) def pane(self, value): self._pane = value @property def z_axis(self) -> Optional[List[ZAxis]]: """The Z axis or depth axis for 3D plots. :returns: A collection of :class:`ZAxis` objects :rtype: :class:`list <python:list>` of :class:`ZAxis` or :obj:`None <python:None>` """ return self._z_axis @z_axis.setter @class_sensitive(ZAxis, force_iterable = True) def z_axis(self, value): self._z_axis = value @classmethod def _get_kwargs_from_dict(cls, as_dict): as_dict = validators.dict(as_dict, allow_empty = True) or {} kwargs = { 'accessibility': as_dict.get('accessibility', None), 'annotations': as_dict.get('annotations', None), 'boost': as_dict.get('boost', None), 'caption': as_dict.get('caption', None), 'chart': as_dict.get('chart', None), 'color_axis': as_dict.get('colorAxis', None), 'colors': as_dict.get('colors', None), 'credits': as_dict.get('credits', None), 'data': as_dict.get('data', None), 'defs': as_dict.get('defs', None), 'drilldown': as_dict.get('drilldown', None), 'exporting': as_dict.get('exporting', None), 'language': as_dict.get('lang', None) or as_dict.get('language', None), 'legend': as_dict.get('legend', None), 'loading': as_dict.get('loading', None), 'navigation': as_dict.get('navigation', None), 'no_data': as_dict.get('noData', None), 'pane': as_dict.get('pane', None), 'plot_options': as_dict.get('plotOptions', None), 'responsive': as_dict.get('responsive', None), 'series': as_dict.get('series', None), 'sonification': as_dict.get('sonification', None), 'subtitle': as_dict.get('subtitle', None), 'time': as_dict.get('time', None), 'title': as_dict.get('title', None), 'tooltip': as_dict.get('tooltip', None), 'x_axis': as_dict.get('xAxis', None), 'y_axis': as_dict.get('yAxis', None), 'z_axis': as_dict.get('zAxis', None) } return kwargs def _to_untrimmed_dict(self, in_cls = None) -> dict: untrimmed = { 'accessibility': self.accessibility, 'annotations': self.annotations, 'boost': self.boost, 'caption': self.caption, 'chart': self.chart, 'colorAxis': self.color_axis, 'colors': self.colors, 'credits': self.credits, 'data':, 'defs': self.defs, 'drilldown': self.drilldown, 'exporting': self.exporting, 'lang': self.language, 'legend': self.legend, 'loading': self.loading, 'navigation': self.navigation, 'noData': self.no_data, 'pane': self.pane, 'plotOptions': self.plot_options, 'responsive': self.responsive, 'series': self.series, 'sonification': self.sonification, 'subtitle': self.subtitle, 'time': self.time, 'title': self.title, 'tooltip': self.tooltip, 'xAxis': self.x_axis, 'yAxis': self.y_axis, 'zAxis': self.z_axis } return untrimmed