Merge pull request #29 from highcharts-for-python/develop

PR for v.1.0.0-rc8

Author: hcpchris

CHANGES.rst

@@ -1,3 +1,17 @@
+Release 1.0.0-rc8
+=========================================
+
+* **BUG:** #25. Fixed the edge case where if multiple notebooks are open in Jupyter Labs and
+  different notebooks use the same container, the charts get rendered in *one* container.
+* **BUG:** Fixed bug when serializing a string value equal to ``'Date'``.
+* **BUG:** Fixed boolean handling in ``options.legend.LegendOptions.shadow``.
+* **Enhancement:** Added ``.from_array()`` support to the ``decorators.validate_types()`` function.
+* **BUG:** Fixed data valization in ``options.plot_options.pie.PieOptions.end_angle`` and ``.start_angle``.
+* Added ``date`` and ``datetime`` support to axis min and max.
+* Added iterable support to ``.from_dict()`` method.
+
+---------------
+
 Release 1.0.0-rc7
 =========================================
 

docs/api/options/series/heatmap.rst

@@ -1,5 +1,5 @@
 ##########################################################################################
-:mod:`.Heatmap <highcharts_core.options.series.heatmap>`
+:mod:`.heatmap <highcharts_core.options.series.heatmap>`
 ##########################################################################################
 
 .. contents:: Module Contents

highcharts_core/__version__.py

@@ -1 +1 @@
-__version__ = '1.0.0-rc7'
+__version__ = '1.0.0-rc8'

highcharts_core/chart.py

@@ -23,6 +23,8 @@ def __init__(self, **kwargs):
         self._options = None
         self._variable_name = None
 
+        self._random_slug = {}
+
         self.callback = kwargs.get('callback', None)
         self.container = kwargs.get('container', None)
         self.options = kwargs.get('options', None)
@@ -54,6 +56,7 @@ def _jupyter_include_scripts(self):
     def _jupyter_javascript(self, 
                             global_options = None, 
                             container = None,
+                            random_slug = None,
                             retries = 3,
                             interval = 1000):
         """Return the JavaScript code which Jupyter Labs will need to render the chart.
@@ -68,6 +71,10 @@ def _jupyter_javascript(self,
           property if set, and ``'highcharts_target_div'`` if not set.
         :type container: :class:`str <python:str>` or :obj:`None <python:None>`
         
+        :param random_slug: The random sequence of characters to append to the container name to ensure uniqueness.
+          Defaults to :obj:`None <python:None>`
+        :type random_slug: :class:`str <python:str>` or :obj:`None <python:None>`
+        
         :param retries: The number of times to retry rendering the chart. Used to avoid race conditions with the 
           Highcharts script. Defaults to 3.
         :type retries: :class:`int <python:int>`
@@ -79,35 +86,46 @@ def _jupyter_javascript(self,
         :rtype: :class:`str <python:str>`
         """
         original_container = self.container
-        self.container = container or self.container or 'highcharts_target_div'
+        new_container = container or self.container or 'highcharts_target_div'
+        if not random_slug:
+            self.container = new_container
+        else:
+            self.container = f'{new_container}_{random_slug}'
 
         if global_options is not None:
             global_options = validate_types(global_options,
                                             types = SharedOptions)
 
         js_str = ''
         js_str += utility_functions.get_retryHighcharts()
-
+        
         if global_options:
             js_str += '\n' + utility_functions.prep_js_for_jupyter(global_options.to_js_literal()) + '\n'
 
         js_str += utility_functions.prep_js_for_jupyter(self.to_js_literal(),
                                                         container = self.container,
+                                                        random_slug = random_slug,
                                                         retries = retries,
                                                         interval = interval)
 
         self.container = original_container
 
         return js_str
 
-    def _jupyter_container_html(self, container = None):
+    def _jupyter_container_html(self,
+                                container = None,
+                                random_slug = None):
         """Returns the Jupyter Labs HTML container for rendering the chart in Jupyter Labs context.
 
         :param container: The ID to apply to the HTML container when rendered in Jupyter Labs. Defaults to
           :obj:`None <python:None>`, which applies the :meth:`.container <highcharts_core.chart.Chart.container>` 
           property if set, and ``'highcharts_target_div'`` if not set.
         :type container: :class:`str <python:str>` or :obj:`None <python:None>`
 
+        :param random_slug: The random sequence of characters to append to the container/function name to ensure 
+          uniqueness. Defaults to :obj:`None <python:None>`
+        :type random_slug: :class:`str <python:str>` or :obj:`None <python:None>`
+
         :rtype: :class:`str <python:str>`
         """
         if self.options.chart:
@@ -116,6 +134,8 @@ def _jupyter_container_html(self, container = None):
             height = 400
 
         container = container or self.container or 'highcharts_target_div'
+        if random_slug:
+            container = f'{container}_{random_slug}'
 
         container_str = f"""<div id=\"{container}\" style=\"width:100%; height:{height};\"></div>\n"""
 
@@ -426,6 +446,9 @@ def _copy_dict_key(cls,
         preserve_data = kwargs.get('preserve_data', True)
 
         original_value = original[key]
+        if other is None:
+            other = {}
+
         other_value = other.get(key, None)
 
         if key == 'data' and preserve_data:
@@ -525,9 +548,9 @@ def copy(self,
         :returns: A mutated version of ``other`` with new property values
 
         """
-        super().copy(other = other,
-                     overwrite = overwrite,
-                     **kwargs)
+        return super().copy(other = other,
+                            overwrite = overwrite,
+                            **kwargs)
 
     def add_series(self, *series):
         """Adds ``series`` to the
@@ -666,6 +689,18 @@ def display(self,
         :param container: The ID to apply to the HTML container when rendered in Jupyter Labs. Defaults to
           :obj:`None <python:None>`, which applies the :meth:`.container <highcharts_core.chart.Chart.container>` 
           property if set, and ``'highcharts_target_div'`` if not set.
+          
+          .. note::
+          
+            Highcharts for Python will append a 6-character random string to the value of ``container``
+            to ensure uniqueness of the chart's container when rendering in a Jupyter Notebook/Labs context. The
+            :class:`Chart <highcharts_core.chart.Chart>` instance will retain the mapping between container and the 
+            random string so long as the instance exists, thus allowing you to easily update the rendered chart by
+            calling the :meth:`.display() <highcharts_core.chart.Chart.display>` method again.
+            
+            If you wish to create a new chart from the instance that does not update the existing chart, then you can do
+            so by specifying a new ``container`` value.
+            
         :type container: :class:`str <python:str>` or :obj:`None <python:None>`
 
         :param retries: The number of times to retry rendering the chart. Used to avoid race conditions with the 
@@ -693,11 +728,21 @@ def display(self,
         include_display = display_mod.Javascript(data = include_js_str)
 
         container = container or self.container or 'highcharts_target_div'
-        html_str = self._jupyter_container_html(container)
+        if not self._random_slug:
+            self._random_slug = {}
+        
+        random_slug = self._random_slug.get(container, None)
+            
+        if not random_slug:
+            random_slug = utility_functions.get_random_string()
+            self._random_slug[container] = random_slug
+
+        html_str = self._jupyter_container_html(container, random_slug)
         html_display = display_mod.HTML(data = html_str)
 
         chart_js_str = self._jupyter_javascript(global_options = global_options, 
                                                 container = container,
+                                                random_slug = random_slug,
                                                 retries = retries,
                                                 interval = interval)
         javascript_display = display_mod.Javascript(data = chart_js_str)

highcharts_core/decorators.py

@@ -1,6 +1,7 @@
 """Implements decorators used throughout the library."""
 import json
 from functools import wraps
+from collections import UserDict
 
 from validator_collection import checkers
 
@@ -113,7 +114,13 @@ def validate_types(value,
         except ValueError:
             pass
 
-    if allow_json and isinstance(value, (str, bytes)):
+    if (
+        force_iterable and
+        checkers.is_iterable(value, forbid_literals = (str, dict, bytes, UserDict)) and
+        hasattr(primary_type, 'from_array')
+    ):
+        value = primary_type.from_array(value)
+    elif allow_json and isinstance(value, (str, bytes)):
         try:
             value = primary_type.from_json(value)
         except AttributeError:

highcharts_core/js_literal_functions.py

@@ -205,14 +205,16 @@ def get_js_literal(item) -> str:
                 as_str += ',\n'
         as_str += ']'
     elif checkers.is_string(item):
-        if item.startswith('[') or item.startswith('Date'):
+        if (item.startswith('[') or item.startswith('Date')) and item != 'Date':
             as_str += f"""{item}"""
         elif item.startswith('{') and item.endswith('}'):
             if is_js_object(item):
                 as_str += f"""{item}"""
             elif "'" in item:
                 item = item.replace("'", "\\'")
                 as_str += f'"{item}"'
+            else:
+                as_str += f"'{item}'"
         elif item in string.whitespace:
             as_str += f"""`{item}`"""
         elif item.startswith == 'HCP: REPLACE-WITH-':

highcharts_core/metaclasses.py

@@ -235,6 +235,10 @@ def from_json(cls,
 
         as_dict = json.loads(as_str)
 
+        if checkers.is_iterable(as_dict, forbid_literals = (str, bytes, dict, UserDict)):
+            return [cls.from_dict(x, allow_snake_case = allow_snake_case)
+                    for x in as_dict]
+
         return cls.from_dict(as_dict,
                              allow_snake_case = allow_snake_case)
 

highcharts_core/options/axes/generic.py

@@ -1,7 +1,8 @@
 from typing import Optional, List
 from decimal import Decimal
+import datetime
 
-from validator_collection import validators
+from validator_collection import validators, checkers
 
 from highcharts_core import constants, errors
 from highcharts_core.decorators import class_sensitive
@@ -395,7 +396,7 @@ def margin(self, value):
         self._margin = validators.numeric(value, allow_empty = True)
 
     @property
-    def max(self) -> Optional[int | float | Decimal]:
+    def max(self) -> Optional[int | float | Decimal | datetime.date | datetime.datetime]:
         """The maximum value of the axis. If :obj:`None <python:None>`, the ``max`` value
         is automatically calculated. Defaults to :obj:`None <python:None>`.
 
@@ -417,7 +418,14 @@ def max(self) -> Optional[int | float | Decimal]:
 
     @max.setter
     def max(self, value):
-        self._max = validators.numeric(value, allow_empty = True)
+        if value is None:
+            self._max = None
+        elif checkers.is_date(value):
+            self._max = validators.date(value)
+        elif checkers.is_datetime(value):
+            self._max = validators.datetime(value)
+        else:
+            self._max = validators.numeric(value, allow_empty = True)
 
     @property
     def max_padding(self) -> Optional[int | float | Decimal]:
@@ -447,7 +455,7 @@ def max_padding(self, value):
                                                minimum = 0)
 
     @property
-    def min(self) -> Optional[int | float | Decimal]:
+    def min(self) -> Optional[int | float | Decimal | datetime.date | datetime.datetime]:
         """The minimum value of the axis. If :obj:`None <python:None>`, the ``min`` value
         is automatically calculated. Defaults to :obj:`None <python:None>`.
 
@@ -473,7 +481,14 @@ def min(self) -> Optional[int | float | Decimal]:
 
     @min.setter
     def min(self, value):
-        self._min = validators.numeric(value, allow_empty = True)
+        if value is None:
+            self._min = None
+        elif checkers.is_date(value):
+            self._min = validators.date(value)
+        elif checkers.is_datetime(value):
+            self._min = validators.datetime(value)
+        else:
+            self._min = validators.numeric(value, allow_empty = True)
 
     @property
     def minor_grid_line_color(self) -> Optional[str | Gradient | Pattern]:

highcharts_core/options/drilldown.py

@@ -8,7 +8,7 @@
 from highcharts_core.utility_classes.animation import AnimationOptions
 from highcharts_core.utility_classes.breadcrumbs import BreadcrumbOptions
 from highcharts_core.options.series.base import SeriesBase
-
+from highcharts_core.options.series.series_generator import create_series_obj
 
 class Drilldown(HighchartsMeta):
     """Options to configure :term:`drilldown` functionality in the chart, which
@@ -169,9 +169,14 @@ def series(self) -> Optional[List[SeriesBase]]:
         return self._series
 
     @series.setter
-    @class_sensitive(SeriesBase, force_iterable = True)
     def series(self, value):
-        self._series = value
+        value = validators.iterable(value, allow_empty = True)
+        if not value:
+            self._series = None
+        else:
+            self._series = [create_series_obj(x,
+                                              default_type = None)
+                            for x in value]
 
     @classmethod
     def _get_kwargs_from_dict(cls, as_dict):

highcharts_core/options/legend/__init__.py

@@ -645,9 +645,12 @@ def shadow(self, value):
         elif value is False:
             self._shadow = False
         else:
-            value = validate_types(value,
-                                   types = ShadowOptions,
-                                   allow_none = False)
+            if value is True:
+                value = ShadowOptions(enabled = True)
+            else:
+                value = validate_types(value,
+                                       types = ShadowOptions,
+                                       allow_none = False)
             self._shadow = value
 
     @property