Added Chart.from_array() support.

Author: hcpchris

highcharts_maps/chart.py

@@ -452,6 +452,111 @@ def add_series(self, *series):
 
         self.options.series = updated_series
 
+    @classmethod
+    def from_array(cls,
+                   value,
+                   series_type = 'line',
+                   series_kwargs = None,
+                   options_kwargs = None,
+                   chart_kwargs = None,
+                   is_maps_chart = False):
+        """Create a :class:`Chart <highcharts_core.chart.Chart>` instance with
+        one series populated from the array contained in ``value``.
+        
+        .. seealso::
+
+          The specific structure of the expected array is highly dependent on the type of data
+          point that the series needs, which itself is dependent on the series type itself.
+
+          Please review the detailed :ref:`series documentation <series_documentation>` for
+          series type-specific details of relevant array structures.
+
+        :param value: The array to use to populate the series data.
+        :type value: iterable
+        
+        :param series_type: Indicates the series type that should be created from the array
+          data. Defaults to ``'line'``.
+        :type series_type: :class:`str <python:str>`
+        
+        :param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
+          arguments that should be used when instantiating the series instance. Defaults
+          to :obj:`None <python:None>`.
+
+          .. warning::
+
+            If ``series_kwargs`` contains a ``data`` key, its value will be *overwritten*.
+            The ``data`` value will be created from ``df`` instead.
+
+        :type series_kwargs: :class:`dict <python:dict>`
+
+        :param options_kwargs: An optional :class:`dict <python:dict>` containing keyword
+          arguments that should be used when instantiating the :class:`HighchartsOptions`
+          instance. Defaults to :obj:`None <python:None>`.
+
+          .. warning::
+
+            If ``options_kwargs`` contains a ``series`` key, the ``series`` value will be
+            *overwritten*. The ``series`` value will be created from the data in ``df``.
+
+        :type options_kwargs: :class:`dict <python:dict>` or :obj:`None <python:None>`
+
+        :param chart_kwargs: An optional :class:`dict <python:dict>` containing keyword
+          arguments that should be used when instantiating the :class:`Chart` instance.
+          Defaults to :obj:`None <python:None>`.
+
+          .. warning::
+
+            If ``chart_kwargs`` contains an ``options`` key, ``options`` will be
+            *overwritten*. The ``options`` value will be created from the
+            ``options_kwargs`` and the data in ``df`` instead.
+
+        :type chart_kwargs: :class:`dict <python:dict>` or :obj:`None <python:None>`
+
+        :param is_maps_chart: if ``True``, enforces the use of 
+          :class:`HighchartsStockOptions <highcharts_stock.options.HighchartsStockOptions>`.
+          If ``False``, applies 
+          :class:`HighchartsOptions <highcharts_stock.options.HighchartsOptions>`.
+          Defaults to ``False``.
+
+          .. note::
+
+            The value given to this argument will override any values specified in
+            ``chart_kwargs``.
+
+        :type is_maps_chart: :class:`bool <python:bool>`
+        
+        :returns: A :class:`Chart <highcharts_core.chart.Chart>` instance with its
+          data populated from the data in ``value``.
+        :rtype: :class:`Chart <highcharts_core.chart.Chart>`
+        
+        """
+        series_type = validators.string(series_type, allow_empty = False)
+        series_type = series_type.lower()
+        if series_type not in SERIES_CLASSES:
+            raise errors.HighchartsValueError(f'series_type expects a valid Highcharts '
+                                              f'series type. Received: {series_type}')
+
+        series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
+        options_kwargs = validators.dict(options_kwargs, allow_empty = True) or {}
+        chart_kwargs = validators.dict(chart_kwargs, allow_empty = True) or {}
+
+        series_cls = SERIES_CLASSES.get(series_type, None)
+
+        series = series_cls.from_array(value, series_kwargs = series_kwargs)
+
+        options_kwargs['series'] = [series]
+        chart_kwargs['is_maps_chart'] = is_maps_chart
+
+        if is_maps_chart:
+            options = HighchartsMapsOptions(**options_kwargs)
+        else:
+            options = HighchartsOptions(**options_kwargs)
+
+        instance = cls(**chart_kwargs)
+        instance.options = options
+
+        return instance
+
     @classmethod
     def from_series(cls, *series, kwargs = None):
         """Creates a new :class:`Chart <highcharts_core.chart.Chart>` instance populated

tests/test_chart.py

@@ -1,6 +1,11 @@
 """Tests for ``highcharts.no_data``."""
 
 import pytest
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
 
 from json.decoder import JSONDecodeError
 
@@ -406,3 +411,65 @@ def test_from_csv(input_files, filename, property_map, kwargs, expected_series,
             result = cls.from_csv(input_file,
                                   property_column_map = property_map,
                                   **kwargs)
+
+
+@pytest.mark.parametrize('value, expected_shape, has_ndarray, has_data_points, error', [
+    (np.asarray([
+        [0.0, 15.0], 
+        [10.0, -50.0], 
+        [20.0, -56.5], 
+        [30.0, -46.5], 
+        [40.0, -22.1],
+        [50.0, -2.5], 
+        [60.0, -27.7], 
+        [70.0, -55.7], 
+        [80.0, -76.5]
+    ]) if HAS_NUMPY else [
+        [0.0, 15.0], 
+        [10.0, -50.0], 
+        [20.0, -56.5], 
+        [30.0, -46.5], 
+        [40.0, -22.1],
+        [50.0, -2.5], 
+        [60.0, -27.7], 
+        [70.0, -55.7], 
+        [80.0, -76.5]
+    ], (9, 2), True, False, None),
+    ([
+        {
+            'id': 'some-value'
+        },
+        {
+            'id': 'some other value'
+        },
+    ], (2, 2), False, True, None),
+    
+    ('Not an Array', None, True, False, ValueError),
+])
+def test_from_array(value, expected_shape, has_ndarray, has_data_points, error):
+    if has_ndarray is False and has_data_points is False:
+        raise AssertionError('Test is invalid. has_ndarray or has_data_points must be '
+                             'True. Both were supplied as False.')
+    if not error:
+        result = cls.from_array(value)
+        assert result is not None
+        assert result.options.series is not None
+        assert len(result.options.series) == 1
+        assert result.options.series[0].data is not None
+
+        if has_ndarray:
+            data = result.options.series[0].data
+            if HAS_NUMPY:
+                assert data.ndarray is not None
+                assert data.ndarray.shape == expected_shape
+            else:
+                assert data.array is not None or data.data_points is not None
+                if data.array:
+                    assert len(data.array) == expected_shape[0]
+                else:
+                    assert len(data.data_points) == expected_shape[0]
+        if has_data_points:
+            assert len(result.options.series[0].data) == expected_shape[0]
+    else:
+        with pytest.raises(error):
+            result = cls.from_array(value)