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

PR for v.1.0.0-rc6

Author: hcpchris

CHANGES.rst

@@ -1,3 +1,16 @@
+Release 1.0.0-rc6
+=========================================
+
+* Fixed bug in deserialization of ``options.plot_options.base.MapBaseOptions.join_by``.
+* Fixed Heatmap and Highcharts Maps JavaScript import conflict.
+* Fixed bug in utility_classes.projections.ProjectionOptions.custom property.
+* Fixed serialization bugs in options.series.data.map_data.MapData.
+* Added ``properties`` support to data point classes in ``options.series.data.geometric``.
+* Updated Jupyter display logic to align with **Highcharts Core for Python** signatures.
+* Added demos to documentation.
+
+---------------
+
 Release 1.0.0-rc5
 =========================================
 

docs/demos.rst

@@ -0,0 +1,125 @@
+################################
+Demos
+################################
+
+.. contents::
+  :depth: 2
+  :backlinks: entry
+
+-------------------
+
+***********************************************
+Trying the Highcharts for Python Toolkit
+***********************************************
+
+You are welcome to try the **Highcharts for Python** toolkit at your convenience and at no cost.
+You can do so by installing the libraries you need very simple:
+
+.. tabs::
+
+  .. tab:: Highcharts Core for Python
+
+    To install **Highcharts Core for Python**, just execute:
+
+    .. code-block:: bash
+
+      $ pip install highcharts-core
+
+  .. tab:: Highcharts Stock for Python
+
+    To install **Highcharts Stock for Python**, just execute:
+
+    .. code-block:: bash
+
+      $ pip install highcharts-stock
+
+  .. tab:: Highcharts Maps for Python
+
+    To install **Highcharts Maps for Python**, just execute:
+
+    .. code-block:: bash
+
+      $ pip install highcharts-maps
+
+  .. tab:: Highcharts Gantt for Python
+
+    To install **Highcharts Gantt for Python**, just execute:
+
+    .. code-block:: bash
+
+      $ pip install highcharts-gantt
+
+If you are evaluating the **Highcharts for Python Toolkit**, you are welcome 
+to install this library and use it free of charge. 
+
+However, if you are using it for professional purposes - either to use 
+Highcharts for your work, or to build an application that integrates the library - 
+then you have to pay for both Highcharts Core (JS) itself *and* for your right 
+to use the **Highcharts for Python Toolkit**. 
+
+You can purchase licenses for both from Highsoft A/S at: 
+`https://shop.highcharts.com/ <https://shop.highcharts.com>`__.
+
+---------------
+
+********************************************************
+Demonstrating the Highcharts for Python Toolkit
+********************************************************
+
+We have prepared an extensive set of demos showcasing much of the code and
+functionality of the **Highcharts for Python** toolkit. To see the demos in action,
+we recommend that you click the following badge:
+
+  .. image:: https://mybinder.org/badge_logo.svg
+    :target: https://mybinder.org/v2/gh/highcharts-for-python/highcharts-for-python-demos/HEAD
+    :alt: Binder: Highcharts for Python Demos
+
+This will clone the `Highcharts for Python Demos <https://github.com/highcharts-for-python-demos>`__
+source repository within a Docker image, and launch `Jupyter Lab <https://jupyter.org>`__ within that
+Docker container. This will then let you browse, edit, and run any of the Jupyter Notebooks contained
+within the `Highcharts for Python Demos <https://github.com/highcharts-for-python-demos>`__ repo.
+
+How the Demos are Organized
+==============================
+
+.. sidebar::
+
+  You should be aware that the demos use a variety of Highcharts for Python features, including various
+  ways of de-serializing chart configurations. Some might load data from files, others might load them
+  from ``snake_case`` :class:`dict <python:dict>`, others from ``camelCase`` Javascript Object Literal 
+  Notation :class:`str <python:str>` values, and more.
+
+  To see the full flexibility that the toolkit provides, we recommend reviewing several of the demos.
+
+Once you have launched the Binder, you can browse the folders and Notebooks in the Jupyter Lab 
+environment. You'll notice that the Jupyter Lab environment has one folder for each of the core
+Highcharts for Python libraries, respectively: ``highcharts-core``, ``highcharts-stock``, 
+``highcharts-maps``, and ``highcharts-gantt``. Within each of these folders, you will find sub-folders
+labeled in a way to describe their contents. 
+
+For example:
+
+  * the sub-folder ``line-charts`` would contain various Notebooks that demonstrate the 
+    generation of various Line Charts using the **Highcharts for Python** toolkit
+  * the sub-folder ``python-features`` would contain various Notebooks that demonstrate
+    the use of Python-specific features like the ``.from_pandas()`` convenience methods
+  * etc.
+
+Navigating the demos should be fairly intuitive - just pay attention to the folder names and the filenames of the Jupyter Notebooks.
+
+Executing a Demo
+===================
+
+Once you are reviewing the demos, you can run a demo either by stepping through the cells in the Notebook, or 
+by running all the cells in sequence.
+
+------------------
+
+*******************************
+Running Demos Locally
+*******************************
+
+.. info::
+  
+  You can run the demos locally by following instructions in the 
+  `Highcharts for Python Demos <https://github.com/highcharts-for-python-demos>`__ Github repo's README.

docs/index.rst

@@ -22,6 +22,7 @@ Highcharts Maps for Python
 
   Home <self>
   Quickstart: Patterns and Best Practices <quickstart>
+  Demos <demos>
   Supported Visualizations <visualizations>
   FAQ <faq>
   Toolkit Components and Roadmap <toolkit>

highcharts_maps/__version__.py

@@ -1 +1 @@
-__version__ = '1.0.0-rc5'
+__version__ = '1.0.0-rc6'

highcharts_maps/chart.py

@@ -62,6 +62,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.
@@ -76,6 +77,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>`
@@ -87,7 +92,11 @@ 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,
@@ -101,6 +110,7 @@ def _jupyter_javascript(self,
 
         js_str += utility_functions.prep_js_for_jupyter(self.to_js_literal(),
                                                         container = self.container,
+                                                        random_slug = random_slug,
                                                         retries = retries,
                                                         interval = interval)
 
@@ -254,7 +264,12 @@ def to_js_literal(self,
         options_as_str = ''
         if self.options:
             options_as_str = self.options.to_js_literal(encoding = encoding)
-            if self.options.chart and self.options.chart.map and self.options.chart.is_async:
+            if (
+                self.is_maps_chart and 
+                hasattr(self.options.chart, 'map') and 
+                self.options.chart.map and 
+                self.options.chart.is_async
+            ):
                 chart_map_str = self.options.chart.map.to_js_literal(encoding = encoding)
                 chart_map_str = f"""'{chart_map_str}'"""
                 fetch_counter = self.options.chart.map.fetch_counter
@@ -455,38 +470,6 @@ def from_series(cls, *series, kwargs = None):
 
         instance.add_series(series)
 
-    def display(self, global_options = None):
-        """Display the chart in `Jupyter Labs <https://jupyter.org/>`_ or
-        `Jupyter Notebooks <https://jupyter.org/>`_.
-
-        :raises HighchartsDependencyError: if
-          `ipython <https://ipython.readthedocs.io/en/stable/>`_ is not available in the
-          runtime environment
-        """
-        try:
-            from IPython import display
-        except ImportError:
-            raise errors.HighchartsDependencyError('Unable to import IPython.display. '
-                                                   'Make sure that it is available in '
-                                                   'your runtime environment. To install,'
-                                                   'use: pip install ipython')
-
-        if global_options is not None:
-            global_options = validate_types(global_options,
-                                            types = SharedMapsOptions)
-
-        if self.is_maps_chart:
-            include_str = constants.MAPS_INCLUDE_STR
-        else:
-            include_str = constants.INCLUDE_STR
-
-        html_str = include_str + '\n'
-        if global_options:
-            html_str += global_options._repr_html_() + '\n'
-        html_str += self._repr_html_()
-
-        display.display_html(html_str, raw = True)
-
     @staticmethod
     def _get_options_obj(series_type, options_kwargs):
         """Return an :class:`Options` descendent based on the series type.
@@ -1053,7 +1036,7 @@ def is_async(self) -> bool:
         if not self.options or not self.options.series:
             return False
 
-        if self.options.chart and self.options.chart.is_async:
+        if self.options.chart and hasattr(self.options.chart, 'is_async') and self.options.chart.is_async:
             return True
 
         for series in self.options.series:

highcharts_maps/constants.py

@@ -1,10 +1,10 @@
 """Defines a set of constants that are used throughout the library."""
 from highcharts_core.constants import *
 
-
-MAPS_INCLUDE_LIBS = INCLUDE_LIBS + [
+MAPS_INCLUDE_LIBS = [x for x in INCLUDE_LIBS if x != 'https://code.highcharts.com/modules/heatmap.js']
+MAPS_INCLUDE_LIBS.extend([
     'https://code.highcharts.com/maps/modules/map.js'
-]
+])
 
 MAPS_INCLUDE_STR = INCLUDE_STR + """
     <script src="https://code.highcharts.com/maps/modules/map.js"/>

highcharts_maps/options/chart/__init__.py

@@ -10,7 +10,7 @@
 from highcharts_maps.options.series.data.map_data import MapData, AsyncMapData
 
 from highcharts_core.options.chart import (PanningOptions,
-                                             ChartOptions as ChartOptionsBase)
+                                           ChartOptions as ChartOptionsBase)
 
 
 class ChartOptions(ChartOptionsBase):

highcharts_maps/options/plot_options/base.py

@@ -1,4 +1,5 @@
 from typing import Optional, List
+from collections import UserDict
 
 from validator_collection import validators, checkers
 
@@ -79,15 +80,18 @@ def join_by(self, value):
             self._join_by = None
         elif isinstance(value, constants.EnforcedNullType):
             self._join_by = constants.EnforcedNull
-        elif checkers.is_iterable(value):
+        elif checkers.is_iterable(value, forbid_literals = (str, bytes, dict, UserDict)):
             if len(value) > 2:
                 raise errors.HighchartsValueError(f'join_by expects a 2-member iterable.'
                                                   f'Received a {len(value)}-member '
                                                   f'iterable.')
             elif len(value) == 2:
-                self._join_by = validators.string(value[0])
+                self._join_by = [
+                    validators.string(value[0]),
+                    validators.string(value[1])
+                ]
             else:
-                self._join_by = [validators.string(x) for x in value]
+                self._join_by = validators.string(value)
         else:
             self._join_by = validators.string(value)