from typing import Optional, List, Dict
from decimal import Decimal
import datetime
from validator_collection import validators, checkers
try:
import numpy as np
HAS_NUMPY = True
except ImportError:
HAS_NUMPY = False
from highcharts_core import constants, errors
from highcharts_core.decorators import class_sensitive
from highcharts_core.options.series.data.cartesian import CartesianData, CartesianDataCollection
from highcharts_core.utility_classes.gradients import Gradient
from highcharts_core.utility_classes.patterns import Pattern
from highcharts_core.utility_classes.partial_fill import PartialFillOptions
[docs]class BarData(CartesianData):
"""Variant of :class:`CartesianData` which is used for data points in a column or bar
graph context."""
def __init__(self, **kwargs):
self._border_color = None
self._border_width = None
self._dash_style = None
self._point_width = None
self.border_color = kwargs.get('border_color', None)
self.border_width = kwargs.get('border_width', None)
self.dash_style = kwargs.get('dash_style', None)
self.point_width = kwargs.get('point_width', None)
super().__init__(**kwargs)
@property
def border_color(self) -> Optional[str | Gradient | Pattern]:
"""The color of the border surrounding each column or bar. Defaults to
:obj:`None <python:None>`
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._border_color
@border_color.setter
def border_color(self, value):
from highcharts_core import utility_functions
self._border_color = utility_functions.validate_color(value)
@property
def border_width(self) -> Optional[int | float | Decimal]:
"""The width of the border surrounding each column or bar. Defaults to
:obj:`None <python:None>`.
:rtype: numeric or :obj:`None <python:None>`
"""
return self._border_width
@border_width.setter
def border_width(self, value):
self._border_width = validators.numeric(value,
allow_empty = True,
minimum = 0)
@property
def dash_style(self) -> Optional[str]:
"""Name of the dash style to use for bar or column. Defaults to
:obj:`None <python:None>`.
Accepts one of the following values:
* 'Dash',
* 'DashDot',
* 'Dot',
* 'LongDash',
* 'LongDashDot',
* 'LongDashDotDot',
* 'ShortDash',
* 'ShortDashDot',
* 'ShortDashDotDot',
* 'ShortDot',
* 'Solid'
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._dash_style
@dash_style.setter
def dash_style(self, value):
if not value:
self._dash_style = None
else:
value = validators.string(value)
if value not in constants.SUPPORTED_DASH_STYLE_VALUES:
raise errors.HighchartsValueError(f'dash_style expects a recognized value'
f', but received: {value}')
self._dash_style = value
@property
def point_width(self) -> Optional[int | float | Decimal]:
"""A pixel value specifying a fixed width for the column or bar. Defaults to
:obj:`None <python:None>`.
.. note::
If specified, overrides the :meth:`point_width <BaseBarOptions.point_width>`
provided for the series as a whole.
.. note::
The ``point_width`` affects the dimension that is *not* based on the point
value.
:rtype: numeric or :obj:`None <python:None>`
"""
return self._point_width
@point_width.setter
def point_width(self, value):
self._point_width = validators.numeric(value, allow_empty = True)
[docs] @classmethod
def from_ndarray(cls, value):
"""Creates a collection of data points from a `NumPy <https://numpy.org>`__
:class:`ndarray <numpy:ndarray>` instance.
:returns: A collection of data point values.
:rtype: :class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`
"""
return BarDataCollection.from_ndarray(value)
@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),
'marker': as_dict.get('marker', None),
'x': as_dict.get('x', None),
'y': as_dict.get('y', None),
'border_color': as_dict.get('borderColor', None),
'border_width': as_dict.get('borderWidth', None),
'dash_style': as_dict.get('dashStyle', None),
'point_width': as_dict.get('pointWidth', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'borderColor': self.border_color,
'borderWidth': self.border_width,
'dashStyle': self.dash_style,
'pointWidth': self.point_width,
}
parent_as_dict = super()._to_untrimmed_dict(in_cls = in_cls) or {}
for key in parent_as_dict:
untrimmed[key] = parent_as_dict[key]
return untrimmed
[docs]class BarDataCollection(CartesianDataCollection):
"""A collection of :class:`BarData` objects.
.. note::
When serializing to JS literals, if possible, the collection is serialized to a primitive
array to boost performance within Python *and* JavaScript. However, this may not always be
possible if data points have non-array-compliant properties configured (e.g. adjusting their
style, names, identifiers, etc.). If serializing to a primitive array is not possible, the
results are serialized as JS literal objects.
"""
@classmethod
def _get_data_point_class(cls):
"""The Python class to use as the underlying data point within the Collection.
:rtype: class object
"""
return BarData
[docs]class WaterfallData(CartesianData):
"""Variant of :class:`CartesianData` which is used for data points in a waterfall
chart."""
def __init__(self, **kwargs):
self._is_intermediate_sum = None
self._is_sum = None
self.is_intermediate_sum = kwargs.get('is_intermediate_sum', None)
self.is_sum = kwargs.get('is_sum', None)
super().__init__(**kwargs)
@property
def is_intermediate_sum(self) -> Optional[bool]:
"""When ``True``, the point acts as a summary column for the values added or
subtracted since the last intermediate sum, or since the start of the series.
Defaults to :obj:`None <python:None>`, which is interpreted as ``False``.
.. warning::
The ``y`` value is ignored.
:rtype: :class:`bool <python:bool>` or :obj:`None <python:None>`
"""
return self._is_intermediate_sum
@is_intermediate_sum.setter
def is_intermediate_sum(self, value):
if value is None:
self._is_intermediate_sum = None
else:
self._is_intermediate_sum = bool(value)
@property
def is_sum(self) -> Optional[bool]:
"""When ``True``, the point displays the total sum across the entire series.
Defaults to :obj:`None <python:None>`, which is interpreted as ``False``.
.. warning::
The ``y`` value is ignored.
:rtype: :class:`bool <python:bool>` or :obj:`None <python:None>`
"""
return self._is_sum
@is_sum.setter
def is_sum(self, value):
if value is None:
self._is_sum = None
else:
self._is_sum = bool(value)
[docs] @classmethod
def from_ndarray(cls, value):
"""Creates a collection of data points from a `NumPy <https://numpy.org>`__
:class:`ndarray <numpy:ndarray>` instance.
:returns: A collection of data point values.
:rtype: :class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`
"""
return WaterfallDataCollection.from_ndarray(value)
@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),
'marker': as_dict.get('marker', None),
'x': as_dict.get('x', None),
'y': as_dict.get('y', None),
'is_intermediate_sum': as_dict.get('isIntermediateSum', None),
'is_sum': as_dict.get('isSum', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'isIntermediateSum': self.is_intermediate_sum,
'isSum': self.is_sum,
}
parent_as_dict = super()._to_untrimmed_dict(in_cls = in_cls) or {}
for key in parent_as_dict:
untrimmed[key] = parent_as_dict[key]
return untrimmed
[docs]class WaterfallDataCollection(CartesianDataCollection):
"""A collection of :class:`BarData` objects.
.. note::
When serializing to JS literals, if possible, the collection is serialized to a primitive
array to boost performance within Python *and* JavaScript. However, this may not always be
possible if data points have non-array-compliant properties configured (e.g. adjusting their
style, names, identifiers, etc.). If serializing to a primitive array is not possible, the
results are serialized as JS literal objects.
"""
@classmethod
def _get_data_point_class(cls):
"""The Python class to use as the underlying data point within the Collection.
:rtype: class object
"""
return WaterfallData
[docs]class WindBarbData(CartesianData):
"""Variant of :class:`CartesianData` which is used for data points in a windbarb
chart."""
def __init__(self, **kwargs):
self._direction = None
self._value = None
self.direction = kwargs.get('direction', None)
self.value = kwargs.get('value', None)
super().__init__(**kwargs)
@property
def direction(self) -> Optional[int | float | Decimal]:
"""The windirection in degrees, where 0 is north (pointing towards south).
Defaults to :obj:`None <python:None>`.
:rtype: numeric or :obj:`None <python:None>`
"""
return self._direction
@direction.setter
def direction(self, value):
self._direction = validators.numeric(value, allow_empty = True)
@property
def value(self) -> Optional[int | float | Decimal]:
"""The wind speed in meters per second. Defaults to :obj:`None <python:None>`.
:rtype: numeric or :obj:`None <python:None>`
"""
return self._value
@value.setter
def value(self, value_):
self._value = validators.numeric(value_, allow_empty = True)
@classmethod
def _get_supported_dimensions(cls) -> List[int]:
"""Returns a list of the supported dimensions for the data point.
:rtype: :class:`list <python:list>` of :class:`int <python:int>`
"""
return [1, 3, 4]
[docs] @classmethod
def from_list(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, 'WindBarbData'):
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,
value = None,
direction = None,
y = None)
elif checkers.is_iterable(item):
if len(item) == 4:
as_dict = {
'x': item[0],
'value': item[1],
'direction': item[2],
'y': item[3]
}
elif len(item) == 3:
as_dict = {
'x': item[0],
'value': item[1],
'direction': item[2]
}
else:
raise errors.HighchartsValueError(f'data expects either a 4D or 3D '
f'collection. Collection received '
f'had {len(item)} dimensions.')
as_obj = cls.from_dict(as_dict)
if checkers.is_string(as_obj.x):
as_obj.name = as_obj.x
as_obj.x = None
else:
raise errors.HighchartsValueError(f'each data point supplied must either '
f'be a WindBarb Data Point or be '
f'coercable to one. Could not coerce: '
f'{item}')
collection.append(as_obj)
return collection
[docs] @classmethod
def from_ndarray(cls, value):
"""Creates a collection of data points from a `NumPy <https://numpy.org>`__
:class:`ndarray <numpy:ndarray>` instance.
:returns: A collection of data point values.
:rtype: :class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`
"""
return WindBarbDataCollection.from_ndarray(value)
@classmethod
def _get_props_from_array(cls, length = None) -> List[str]:
"""Returns a list of the property names that can be set using the
:meth:`.from_array() <highcharts_core.options.series.data.base.DataBase.from_array>`
method.
:param length: The length of the array, which may determine the properties to
parse. Defaults to :obj:`None <python:None>`, which returns the full list of
properties.
:type length: :class:`int <python:int>` or :obj:`None <python:None>`
:rtype: :class:`list <python:list>` of :class:`str <python:str>`
"""
prop_list = {
None: ['x', 'value', 'direction', 'y', 'name'],
4: ['x', 'value', 'direction', 'y'],
3: ['x', 'value', 'direction']
}
return cls._get_props_from_array_helper(prop_list, length)
[docs] def to_array(self, force_object = False) -> List | Dict:
"""Generate the array representation of the data point (the inversion
of
:meth:`.from_array() <highcharts_core.options.series.data.base.DataBase.from_array>`).
.. warning::
If the data point *cannot* be serialized to a JavaScript array,
this method will instead return the untrimmed :class:`dict <python:dict>`
representation of the data point as a fallback.
:param force_object: if ``True``, forces the return of the instance's
untrimmed :class:`dict <python:dict>` representation. Defaults to ``False``.
:type force_object: :class:`bool <python:bool>`
:returns: The array representation of the data point.
:rtype: :class:`list <python:list>` of values or :class:`dict <python:dict>`
"""
if self.requires_js_object or force_object:
return self._to_untrimmed_dict()
if self.x is None and self.name is not None:
x = self.name
elif self.x is not None:
x = self.x
else:
x = constants.EnforcedNull
if self.y is not None:
y = self.y
else:
y = constants.EnforcedNull
if self.value is not None:
value = self.value
else:
value = constants.EnforcedNull
if self.direction is not None:
direction = self.direction
else:
direction = constants.EnforcedNull
if self.y is None:
return [x, value, direction]
return [x, value, direction, y]
@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),
'marker': as_dict.get('marker', None),
'x': as_dict.get('x', None),
'y': as_dict.get('y', None),
'direction': as_dict.get('direction', None),
'value': as_dict.get('value', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'direction': self.direction,
'value': self.value,
}
parent_as_dict = super()._to_untrimmed_dict(in_cls = in_cls) or {}
for key in parent_as_dict:
untrimmed[key] = parent_as_dict[key]
return untrimmed
[docs]class WindBarbDataCollection(CartesianDataCollection):
"""A collection of :class:`BarData` objects.
.. note::
When serializing to JS literals, if possible, the collection is serialized to a primitive
array to boost performance within Python *and* JavaScript. However, this may not always be
possible if data points have non-array-compliant properties configured (e.g. adjusting their
style, names, identifiers, etc.). If serializing to a primitive array is not possible, the
results are serialized as JS literal objects.
"""
@classmethod
def _get_data_point_class(cls):
"""The Python class to use as the underlying data point within the Collection.
:rtype: class object
"""
return WindBarbData
[docs]class XRangeData(CartesianData):
"""Variant of :class:`CartesianData` which is used for data points in an X-Range
series."""
def __init__(self, **kwargs):
self._partial_fill = None
self._x2 = None
self.partial_fill = kwargs.get('partial_fill', None)
self.x2 = kwargs.get('x2', None)
super().__init__(**kwargs)
@property
def partial_fill(self) -> Optional[PartialFillOptions]:
"""A partial fill for the data point, typically used to visualize how much of a
task is performed. Defaults to :obj:`None <python:None>`.
:rtype: :class:`PartialFillOptions` or :obj:`None <python:None>`
"""
return self._partial_fill
@partial_fill.setter
@class_sensitive(PartialFillOptions)
def partial_fill(self, value):
self._partial_fill = value
@property
def x(self) -> Optional[str | datetime.date | datetime.datetime | int | float | Decimal]:
"""The starting X-value of the range point. Defaults to :obj:`None <python:None>`.
If :obj:`None <python:None>`, the point's position on the x-axis will be
automatically determined based on its position in the series'
:meth:`data <SeriesBase.data>` array. The first point will be given an ``x`` value
of ``0``, or the series' :meth:`point_start <SeriesBase.point_start>` value.
Each subsequent point will be incremented either by ``1`` or the value of
:meth:`point_interval <SeriesBase.point_interval>`.
:rtype: numeric or :class:`str <python:str>` or
:class:`date <python:datetime.date>` or
:class:`datetime <python:datetime.datetime>` or :obj:`None <python:None>`
"""
return self._x
@x.setter
def x(self, value):
if value is None:
self._x = None
else:
if checkers.is_datetime(value):
value = validators.datetime(value)
elif checkers.is_date(value):
value = validators.date(value)
elif checkers.is_numeric(value):
value = validators.numeric(value)
else:
value = validators.string(value)
self._x = value
@property
def x2(self) -> Optional[str | datetime.date | datetime.datetime | int | float | Decimal]:
"""The ending X-value of the range point. Defaults to :obj:`None <python:None>`.
If :obj:`None <python:None>`, the point's position on the x-axis will be
automatically determined based on its position in the series'
:meth:`data <SeriesBase.data>` array. The first point will be given an ``x2`` value
of ``0``, or the series' :meth:`point_start <SeriesBase.point_start>` value.
Each subsequent point will be incremented either by ``1`` or the value of
:meth:`point_interval <SeriesBase.point_interval>`.
:rtype: numeric or :class:`str <python:str>` or
:class:`date <python:datetime.date>` or
:class:`datetime <python:datetime.datetime>` or :obj:`None <python:None>`
"""
return self._x2
@x2.setter
def x2(self, value):
if value is None:
self._x2 = None
else:
if checkers.is_datetime(value):
value = validators.datetime(value)
elif checkers.is_date(value):
value = validators.date(value)
elif checkers.is_numeric(value):
value = validators.numeric(value)
else:
value = validators.string(value)
self._x2 = value
[docs] @classmethod
def from_list(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, 'XRangeData'):
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 = None
else:
raise errors.HighchartsValueError(f'each data point supplied must either '
f'be an X-Range Data Point or be '
f'coercable to one. Could not coerce: '
f'{item}')
collection.append(as_obj)
return collection
[docs] @classmethod
def from_ndarray(cls, value):
"""Creates a collection of data points from a `NumPy <https://numpy.org>`__
:class:`ndarray <numpy:ndarray>` instance.
:returns: A collection of data point values.
:rtype: :class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`
"""
return XRangeDataCollection.from_ndarray(value)
@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),
'marker': as_dict.get('marker', None),
'x': as_dict.get('x', None),
'y': as_dict.get('y', None),
'partial_fill': as_dict.get('partialFill', None),
'x2': as_dict.get('x2', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'partialFill': self.partial_fill,
'x': self.x,
'x2': self.x2,
}
parent_as_dict = super()._to_untrimmed_dict(in_cls = in_cls) or {}
for key in parent_as_dict:
untrimmed[key] = parent_as_dict[key]
return untrimmed
[docs]class XRangeDataCollection(CartesianDataCollection):
"""A collection of :class:`XRangeData` objects.
.. note::
When serializing to JS literals, if possible, the collection is serialized to a primitive
array to boost performance within Python *and* JavaScript. However, this may not always be
possible if data points have non-array-compliant properties configured (e.g. adjusting their
style, names, identifiers, etc.). If serializing to a primitive array is not possible, the
results are serialized as JS literal objects.
"""
@classmethod
def _get_data_point_class(cls):
"""The Python class to use as the underlying data point within the Collection.
:rtype: class object
"""
return XRangeData