from typing import Optional
from decimal import Decimal
from collections import UserDict
from validator_collection import validators, checkers
from highcharts_core import constants, errors
from highcharts_core.decorators import class_sensitive
from highcharts_core.options.series.data.base import DataBase
from highcharts_core.options.plot_options.drag_drop import DragDropOptions
from highcharts_core.utility_classes.data_labels import DataLabel
[docs]class SinglePointBase(DataBase):
"""Data point that features a single and ``y`` value."""
def __init__(self, **kwargs):
self._data_labels = None
self._drag_drop = None
self._drilldown = None
self.data_labels = kwargs.get('data_labels', None)
self.drag_drop = kwargs.get('drag_drop', None)
self.drilldown = kwargs.get('drilldown', None)
super().__init__(**kwargs)
@property
def data_labels(self) -> Optional[DataLabel]:
"""Individual data label for the data point.
:rtype: :class:`DataLabel` or :obj:`None <python:None>`
"""
return self._data_labels
@data_labels.setter
@class_sensitive(DataLabel)
def data_labels(self, value):
self._data_labels = value
@property
def drag_drop(self) -> Optional[DragDropOptions]:
"""The draggable-points module allows points to be moved around or modified in the
chart.
In addition to the options mentioned under the dragDrop API structure, the module
fires three (JavaScript) events:
* ``point.dragStart``
* ``point.drag``
* ``point.drop``
:rtype: :class:`DragDropOptions` or :obj:`None <python:None>`
"""
return self._drag_drop
@drag_drop.setter
@class_sensitive(DragDropOptions)
def drag_drop(self, value):
self._drag_drop = value
@property
def drilldown(self) -> Optional[str]:
"""The :meth:`id <SeriesBase.id>` of a series in the ``drilldown.series`` array
to use as a drilldown destination for this point. Defaults to
:obj:`None <python:None>`.
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._drilldown
@drilldown.setter
def drilldown(self, value):
if isinstance(value, constants.EnforcedNullType):
self._drilldown = value
else:
self._drilldown = validators.string(value, allow_empty = True)
@classmethod
def _get_kwargs_from_dict(cls, as_dict):
"""Convenience method which returns the keyword arguments used to initialize the
class from a Highcharts Javascript-compatible :class:`dict <python:dict>` object.
:param as_dict: The HighCharts JS compatible :class:`dict <python:dict>`
representation of the object.
:type as_dict: :class:`dict <python:dict>`
:returns: The keyword arguments that would be used to initialize an instance.
:rtype: :class:`dict <python:dict>`
"""
kwargs = {
'accessibility': as_dict.get('accessibility', None),
'class_name': as_dict.get('className', None),
'color': as_dict.get('color', None),
'color_index': as_dict.get('colorIndex', None),
'custom': as_dict.get('custom', None),
'description': as_dict.get('description', None),
'events': as_dict.get('events', None),
'id': as_dict.get('id', None),
'label_rank': as_dict.get('labelrank',
None) or as_dict.get('labelRank',
None),
'name': as_dict.get('name', None),
'selected': as_dict.get('selected', None),
'data_labels': as_dict.get('dataLabels', None),
'drag_drop': as_dict.get('dragDrop', None),
'drilldown': as_dict.get('drilldown', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'dataLabels': self.data_labels,
'dragDrop': self.drag_drop,
'drilldown': self.drilldown,
'accessibility': self.accessibility,
'className': self.class_name,
'color': self.color,
'colorIndex': self.color_index,
'custom': self.custom,
'description': self.description,
'events': self.events,
'id': self.id,
'labelrank': self.label_rank,
'name': self.name,
'selected': self.selected,
}
return untrimmed
[docs]class SinglePointData(SinglePointBase):
"""Data point that features a single and ``y`` value."""
def __init__(self, **kwargs):
self._y = None
self.y = kwargs.get('y', None)
super().__init__(**kwargs)
@property
def y(self) -> Optional[int | float | Decimal | type(None) | constants.EnforcedNullType]:
"""The position of the data point on the Y-axis. Defaults to
:obj:`None <python:None>`.
:rtype: numeric or :class:`EnforcedNullType` or :obj:`None <python:None>`
"""
return self._y
@y.setter
def y(self, value):
if value is None or isinstance(value, constants.EnforcedNullType):
self._y = None
else:
self._y = validators.numeric(value)
[docs] @classmethod
def from_array(cls, value):
if not value:
return []
elif checkers.is_string(value):
try:
value = validators.json(value)
except (ValueError, TypeError):
pass
elif not checkers.is_iterable(value):
value = [value]
collection = []
for item in value:
if checkers.is_type(item, 'SinglePointData'):
as_obj = item
elif checkers.is_dict(item):
as_obj = cls.from_dict(item)
elif item is None or isinstance(item, constants.EnforcedNullType):
as_obj = cls(y = None)
elif checkers.is_numeric(item):
as_obj = cls(y = item)
elif checkers.is_iterable(item, forbid_literals = (str, bytes, dict, UserDict)):
if len(item) == 2:
as_obj = cls(name = item[0],
y = item[1])
elif len(item) == 1:
as_obj = cls(y = item[0])
else:
raise errors.HighchartsValueError(f'each data point supplied must either '
f'be a Single Point Data Point or be '
f'coercable to one. Could not coerce: '
f'{item}')
collection.append(as_obj)
return collection
@classmethod
def _get_kwargs_from_dict(cls, as_dict):
"""Convenience method which returns the keyword arguments used to initialize the
class from a Highcharts Javascript-compatible :class:`dict <python:dict>` object.
:param as_dict: The HighCharts JS compatible :class:`dict <python:dict>`
representation of the object.
:type as_dict: :class:`dict <python:dict>`
:returns: The keyword arguments that would be used to initialize an instance.
:rtype: :class:`dict <python:dict>`
"""
kwargs = {
'accessibility': as_dict.get('accessibility', None),
'class_name': as_dict.get('className', None),
'color': as_dict.get('color', None),
'color_index': as_dict.get('colorIndex', None),
'custom': as_dict.get('custom', None),
'description': as_dict.get('description', None),
'events': as_dict.get('events', None),
'id': as_dict.get('id', None),
'label_rank': as_dict.get('labelrank',
None) or as_dict.get('labelRank',
None),
'name': as_dict.get('name', None),
'selected': as_dict.get('selected', None),
'data_labels': as_dict.get('dataLabels', None),
'drag_drop': as_dict.get('dragDrop', None),
'drilldown': as_dict.get('drilldown', None),
'y': as_dict.get('y', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'y': self.y,
'dataLabels': self.data_labels,
'dragDrop': self.drag_drop,
'drilldown': self.drilldown,
'accessibility': self.accessibility,
'className': self.class_name,
'color': self.color,
'colorIndex': self.color_index,
'custom': self.custom,
'description': self.description,
'events': self.events,
'id': self.id,
'labelrank': self.label_rank,
'name': self.name,
'selected': self.selected,
}
return untrimmed
[docs]class SingleValueData(SinglePointBase):
"""Data point that features a single and ``value`` value."""
def __init__(self, **kwargs):
self._value = None
self.value = kwargs.get('value', None)
super().__init__(**kwargs)
@property
def value(self) -> Optional[int | float | Decimal | type(None) | constants.EnforcedNullType]:
"""The value of the data point. Defaults to
:obj:`None <python:None>`.
:rtype: numeric or :class:`EnforcedNullType` or :obj:`None <python:None>`
"""
return self._value
@value.setter
def value(self, value_):
if value_ is None or isinstance(value_, constants.EnforcedNullType):
self._value = None
else:
self._value = validators.numeric(value_)
[docs] @classmethod
def from_array(cls, value):
if not value:
return []
elif checkers.is_string(value):
try:
value = validators.json(value)
except (ValueError, TypeError):
pass
elif not checkers.is_iterable(value):
value = [value]
collection = []
for item in value:
if checkers.is_type(item, 'SingleValueData'):
as_obj = item
elif checkers.is_dict(item):
as_obj = cls.from_dict(item)
elif item is None or isinstance(item, constants.EnforcedNullType):
as_obj = cls(value = None)
elif checkers.is_numeric(item):
as_obj = cls(value = item)
else:
raise errors.HighchartsValueError(f'each data point supplied must either '
f'be a Single Value Data Point or be '
f'coercable to one. Could not coerce: '
f'{item}')
collection.append(as_obj)
return collection
@classmethod
def _get_kwargs_from_dict(cls, as_dict):
"""Convenience method which returns the keyword arguments used to initialize the
class from a Highcharts Javascript-compatible :class:`dict <python:dict>` object.
:param as_dict: The HighCharts JS compatible :class:`dict <python:dict>`
representation of the object.
:type as_dict: :class:`dict <python:dict>`
:returns: The keyword arguments that would be used to initialize an instance.
:rtype: :class:`dict <python:dict>`
"""
kwargs = {
'accessibility': as_dict.get('accessibility', None),
'class_name': as_dict.get('className', None),
'color': as_dict.get('color', None),
'color_index': as_dict.get('colorIndex', None),
'custom': as_dict.get('custom', None),
'description': as_dict.get('description', None),
'events': as_dict.get('events', None),
'id': as_dict.get('id', None),
'label_rank': as_dict.get('labelrank',
None) or as_dict.get('labelRank',
None),
'name': as_dict.get('name', None),
'selected': as_dict.get('selected', None),
'data_labels': as_dict.get('dataLabels', None),
'drag_drop': as_dict.get('dragDrop', None),
'drilldown': as_dict.get('drilldown', None),
'value': as_dict.get('value', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'value': self.value,
'dataLabels': self.data_labels,
'dragDrop': self.drag_drop,
'drilldown': self.drilldown,
'accessibility': self.accessibility,
'className': self.class_name,
'color': self.color,
'colorIndex': self.color_index,
'custom': self.custom,
'description': self.description,
'events': self.events,
'id': self.id,
'labelrank': self.label_rank,
'name': self.name,
'selected': self.selected,
}
return untrimmed
[docs]class SingleXData(SinglePointBase):
"""Data point that features a single labeled ``x`` value."""
def __init__(self, **kwargs):
self._x = None
self.x = kwargs.get('x', None)
super().__init__(**kwargs)
@property
def x(self) -> Optional[int | float | Decimal | type(None) | constants.EnforcedNullType]:
"""The position of the data point on the X-axis. Defaults to
:obj:`None <python:None>`.
:rtype: numeric or :class:`EnforcedNullType` or :obj:`None <python:None>`
"""
return self._x
@x.setter
def x(self, value):
if value is None or isinstance(value, constants.EnforcedNullType):
self._x = None
else:
self._x = validators.numeric(value)
[docs] @classmethod
def from_array(cls, value):
if not value:
return []
elif checkers.is_string(value):
try:
value = validators.json(value)
except (ValueError, TypeError):
pass
elif not checkers.is_iterable(value):
value = [value]
collection = []
for item in value:
if checkers.is_type(item, 'SinglePointData'):
as_obj = item
elif checkers.is_dict(item):
as_obj = cls.from_dict(item)
elif item is None or isinstance(item, constants.EnforcedNullType):
as_obj = cls(x = None)
elif checkers.is_numeric(item):
as_obj = cls(x = item)
else:
raise errors.HighchartsValueError(f'each data point supplied must either '
f'be a Single X-value Data Point or be '
f'coercable to one. Could not coerce: '
f'{item}')
collection.append(as_obj)
return collection
@classmethod
def _get_kwargs_from_dict(cls, as_dict):
"""Convenience method which returns the keyword arguments used to initialize the
class from a Highcharts Javascript-compatible :class:`dict <python:dict>` object.
:param as_dict: The HighCharts JS compatible :class:`dict <python:dict>`
representation of the object.
:type as_dict: :class:`dict <python:dict>`
:returns: The keyword arguments that would be used to initialize an instance.
:rtype: :class:`dict <python:dict>`
"""
kwargs = {
'accessibility': as_dict.get('accessibility', None),
'class_name': as_dict.get('className', None),
'color': as_dict.get('color', None),
'color_index': as_dict.get('colorIndex', None),
'custom': as_dict.get('custom', None),
'description': as_dict.get('description', None),
'events': as_dict.get('events', None),
'id': as_dict.get('id', None),
'label_rank': as_dict.get('labelrank',
None) or as_dict.get('labelRank',
None),
'name': as_dict.get('name', None),
'selected': as_dict.get('selected', None),
'data_labels': as_dict.get('dataLabels', None),
'drag_drop': as_dict.get('dragDrop', None),
'drilldown': as_dict.get('drilldown', None),
'x': as_dict.get('x', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'x': self.x,
'dataLabels': self.data_labels,
'dragDrop': self.drag_drop,
'drilldown': self.drilldown,
'accessibility': self.accessibility,
'className': self.class_name,
'color': self.color,
'colorIndex': self.color_index,
'custom': self.custom,
'description': self.description,
'events': self.events,
'id': self.id,
'labelrank': self.label_rank,
'name': self.name,
'selected': self.selected,
}
return untrimmed
[docs]class LabeledSingleXData(SingleXData):
"""Data point that features a single labeled ``x`` value."""
def __init__(self, **kwargs):
self._label = None
self.label = kwargs.get('label', None)
super().__init__(**kwargs)
@property
def label(self) -> Optional[str]:
"""The label for the event. Defaults to :obj:`None <python:None>`.
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._label
@label.setter
def label(self, value):
self._label = validators.string(value, allow_empty = True)
[docs] @classmethod
def from_array(cls, value):
if not value:
return []
elif checkers.is_string(value):
try:
value = validators.json(value)
except (ValueError, TypeError):
pass
elif not checkers.is_iterable(value):
value = [value]
collection = []
for item in value:
if checkers.is_type(item, 'LabeledSingleXData'):
as_obj = item
elif checkers.is_dict(item):
as_obj = cls.from_dict(item)
elif item is None or isinstance(item, constants.EnforcedNullType):
as_obj = cls(x = None)
elif checkers.is_numeric(item):
as_obj = cls(x = item)
else:
raise errors.HighchartsValueError(f'each data point supplied must either '
f'be a Single X-value Data Point or be '
f'coercable to one. Could not coerce: '
f'{item}')
collection.append(as_obj)
return collection
@classmethod
def _get_kwargs_from_dict(cls, as_dict):
"""Convenience method which returns the keyword arguments used to initialize the
class from a Highcharts Javascript-compatible :class:`dict <python:dict>` object.
:param as_dict: The HighCharts JS compatible :class:`dict <python:dict>`
representation of the object.
:type as_dict: :class:`dict <python:dict>`
:returns: The keyword arguments that would be used to initialize an instance.
:rtype: :class:`dict <python:dict>`
"""
kwargs = {
'accessibility': as_dict.get('accessibility', None),
'class_name': as_dict.get('className', None),
'color': as_dict.get('color', None),
'color_index': as_dict.get('colorIndex', None),
'custom': as_dict.get('custom', None),
'description': as_dict.get('description', None),
'events': as_dict.get('events', None),
'id': as_dict.get('id', None),
'label_rank': as_dict.get('labelrank',
None) or as_dict.get('labelRank',
None),
'name': as_dict.get('name', None),
'selected': as_dict.get('selected', None),
'data_labels': as_dict.get('dataLabels', None),
'drag_drop': as_dict.get('dragDrop', None),
'drilldown': as_dict.get('drilldown', None),
'label': as_dict.get('label', None),
'x': as_dict.get('x', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'label': self.label,
'x': self.x,
'dataLabels': self.data_labels,
'dragDrop': self.drag_drop,
'drilldown': self.drilldown,
'accessibility': self.accessibility,
'className': self.class_name,
'color': self.color,
'colorIndex': self.color_index,
'custom': self.custom,
'description': self.description,
'events': self.events,
'id': self.id,
'labelrank': self.label_rank,
'name': self.name,
'selected': self.selected,
}
return untrimmed
[docs]class ConnectedSingleXData(SingleXData):
"""Variant of :class:`SingleXData` which supports a connector."""
def __init__(self, **kwargs):
self._connector_color = None
self._connector_width = None
self.connector_color = kwargs.get('connector_color', None)
self.connector_width = kwargs.get('connector_width', None)
super().__init__(**kwargs)
@property
def connector_color(self) -> Optional[str]:
"""Color of the line that connects the dumbbell point's values. If
:obj:`None <python:None>`, applies the series' color. Defaults to
:obj:`None <python:None>`.
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._connector_color
@connector_color.setter
def connector_color(self, value):
self._connector_color = validators.string(value, allow_empty = True)
@property
def connector_width(self) -> Optional[int | float | Decimal]:
"""Pixel width of the line that connects the dumbbell point's values. Defaults to
``1``.
:rtype: numeric or :obj:`None <python:None>`
"""
return self._connector_width
@connector_width.setter
def connector_width(self, value):
self._connector_width = validators.numeric(value, allow_empty = True)
[docs] @classmethod
def from_array(cls, value):
if not value:
return []
elif checkers.is_string(value):
try:
value = validators.json(value)
except (ValueError, TypeError):
pass
elif not checkers.is_iterable(value):
value = [value]
collection = []
for item in value:
if checkers.is_type(item, 'ConnectedSingleXData'):
as_obj = item
elif checkers.is_dict(item):
as_obj = cls.from_dict(item)
elif item is None or isinstance(item, constants.EnforcedNullType):
as_obj = cls(x = None)
elif checkers.is_numeric(item):
as_obj = cls(x = item)
else:
raise errors.HighchartsValueError(f'each data point supplied must either '
f'be a Single X-value Data Point or be '
f'coercable to one. Could not coerce: '
f'{item}')
collection.append(as_obj)
return collection
@classmethod
def _get_kwargs_from_dict(cls, as_dict):
"""Convenience method which returns the keyword arguments used to initialize the
class from a Highcharts Javascript-compatible :class:`dict <python:dict>` object.
:param as_dict: The HighCharts JS compatible :class:`dict <python:dict>`
representation of the object.
:type as_dict: :class:`dict <python:dict>`
:returns: The keyword arguments that would be used to initialize an instance.
:rtype: :class:`dict <python:dict>`
"""
kwargs = {
'accessibility': as_dict.get('accessibility', None),
'class_name': as_dict.get('className', None),
'color': as_dict.get('color', None),
'color_index': as_dict.get('colorIndex', None),
'custom': as_dict.get('custom', None),
'description': as_dict.get('description', None),
'events': as_dict.get('events', None),
'id': as_dict.get('id', None),
'label_rank': as_dict.get('labelrank',
None) or as_dict.get('labelRank',
None),
'name': as_dict.get('name', None),
'selected': as_dict.get('selected', None),
'data_labels': as_dict.get('dataLabels', None),
'drag_drop': as_dict.get('dragDrop', None),
'drilldown': as_dict.get('drilldown', None),
'x': as_dict.get('x', None),
'connector_color': as_dict.get('connectorColor', None),
'connector_width': as_dict.get('connectorWidth', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'connectorColor': self.connector_color,
'connectorWidth': self.connector_width,
'x': self.x,
'dataLabels': self.data_labels,
'dragDrop': self.drag_drop,
'drilldown': self.drilldown,
'accessibility': self.accessibility,
'className': self.class_name,
'color': self.color,
'colorIndex': self.color_index,
'custom': self.custom,
'description': self.description,
'events': self.events,
'id': self.id,
'labelrank': self.label_rank,
'name': self.name,
'selected': self.selected,
}
return untrimmed