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

PR for v.1.3.0

Author: hcpchris

CHANGES.rst

@@ -1,3 +1,17 @@
+Release 1.3.0
+=========================================
+
+* **ENHANCEMENT:** Modified the way that data points are serialized to JavaScript literal objects. Now, they are serialized to a JavaScript array if their configured properties are those that Highcharts (JS) supports in JavaScript array notation. Otherwise, the code falls back to serialize the data point as a JavaScript object literal. This change is intended to improve performance and reduce the size of the serialized data. (#25)
+* **ENHANCEMENT:** Added ``__repr__()`` method for Highcharts Core for Python classes.
+* **ENHANCEMENT:** Added ``__str__()`` method with special handling for difficult-to-read classes.
+* **ENHANCEMENT:** Added ``Chart.get_script_tags()`` to retrieve Javascript ``<script>`` tags.
+* **ENHANCEMENT:** Added ``utility_functions.to_snake_case()`` function.
+* **BUGFIX:** Fixed incorrect serialization of datetime and Pandas ``Timestamp`` objects in ``.to_dict()`` and ``.to_json()``.
+* **BUGFIX:** Fixed incorrect serialization of ``EnforcedNull`` in ``.to_dict()`` and ``.to_json()``.
+
+
+---------------------
+
 Release 1.2.0
 =========================================
 

README.rst

@@ -85,7 +85,7 @@ Before you install, please be aware of the following "hard" dependencies:
   * Python 3.10 or higher
   * Highcharts Maps (JS) v.10.2 or higher (not technically a Python dependency, but 
     it won't work with earlier versions of Highcharts)
-  * `Highcharts Core for Python <https://core-docs.highchartspython.com/en/latest/>`__ v.1.0 or higher
+  * `Highcharts Core for Python <https://core-docs.highchartspython.com/en/latest/>`__ v.1.3 or higher
   * `esprima-python <https://github.com/Kronuz/esprima-python>`__ v.4.0 or higher
   * `requests <https://requests.readthedocs.io/en/latest/>`__ v.2.31 or higher
   * `validator-collection <https://validator-collection.readthedocs.io/en/latest/>`__

docs/_dependencies.rst

@@ -32,7 +32,7 @@
         Not technically a Python dependency, but obviously **Highcharts Maps for Python**
         will not work properly if your rendering layer does not leverage Highcharts Maps.
 
-    * `highcharts-core <https://core-docs.highchartspython.com>`_ v.1.0.0 or higher
+    * `highcharts-core <https://core-docs.highchartspython.com>`_ v.1.3.0 or higher
     * `esprima-python <https://github.com/Kronuz/esprima-python>`_ v.4.0 or higher
     * `requests <https://requests.readthedocs.io/en/latest/>`_ v.2.31 or higher
     * `validator-collection <https://validator-collection.readthedocs.io/en/latest/>`_

highcharts_maps/__version__.py

@@ -1 +1 @@
-__version__ = '1.2.0'
+__version__ = '1.3.0'

highcharts_maps/options/series/data/connections.py

@@ -322,6 +322,17 @@ def from_array(cls, value):
 
         return collection
 
+    def _get_props_from_array(self) -> 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.
+        
+        :rtype: :class:`list <python:list>` of :class:`str <python:str>`
+        """
+        return ['from_',
+                'to',
+                'weight']
+
     @classmethod
     def _get_kwargs_from_dict(cls, as_dict):
         """Convenience method which returns the keyword arguments used to initialize the

highcharts_maps/options/series/data/geometric.py

@@ -1,4 +1,4 @@
-from typing import Optional, List
+from typing import Optional, List, Dict
 from decimal import Decimal
 
 from validator_collection import validators, checkers
@@ -305,6 +305,62 @@ def from_array(cls, value):
 
         return collection
 
+    def _get_props_from_array(self) -> List[str]:
+        """Returns a list of the property names that can be set using the
+        :meth:`.from_array() <highcharts_maps.options.series.data.geometric.GeometricData.from_array>`
+        method.
+        
+        :rtype: :class:`list <python:list>` of :class:`str <python:str>`
+        """
+        return ['name', 'value']
+
+    @property
+    def requires_js_object(self) -> bool:
+        """Indicates whether or not the data point *must* be serialized to a JS literal 
+        object or whether it can be serialized to a primitive array.
+        
+        :returns: ``True`` if the data point *must* be serialized to a JS literal object.
+          ``False`` if it can be serialized to an array.
+        :rtype: :class:`bool <python:bool>`
+        """
+        from_array_props = [utility_functions.to_camelCase(x)
+                            for x in self._get_props_from_array()]
+        
+        as_dict = self.to_dict()
+        trimmed_dict = self.trim_dict(as_dict)
+        for prop in from_array_props:
+            if prop in trimmed_dict:
+                del trimmed_dict[prop]
+
+        if trimmed_dict:
+            return True
+        
+        return False
+
+    def to_array(self, force_object = False) -> List | Dict:
+        """Generate the array representation of the data point (the inversion 
+        of 
+        :meth:`.from_array() <highcharts_maps.options.series.data.geometric.GeometricData.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()
+
+        return [getattr(self, x, constants.EnforcedNull)
+                for x in self._get_props_from_array()]
+
     @classmethod
     def _get_kwargs_from_dict(cls, as_dict):
         """Convenience method which returns the keyword arguments used to initialize the
@@ -437,6 +493,15 @@ def from_array(cls, value):
 
         return collection
 
+    def _get_props_from_array(self) -> List[str]:
+        """Returns a list of the property names that can be set using the
+        :meth:`.from_array() <highcharts_maps.options.series.data.geometric.GeometricData.from_array>`
+        method.
+        
+        :rtype: :class:`list <python:list>` of :class:`str <python:str>`
+        """
+        return ['z']
+
     @classmethod
     def _get_kwargs_from_dict(cls, as_dict):
         """Convenience method which returns the keyword arguments used to initialize the
@@ -631,6 +696,15 @@ def from_array(cls, value):
 
         return collection
 
+    def _get_props_from_array(self) -> List[str]:
+        """Returns a list of the property names that can be set using the
+        :meth:`.from_array() <highcharts_maps.options.series.data.geometric.GeometricData.from_array>`
+        method.
+        
+        :rtype: :class:`list <python:list>` of :class:`str <python:str>`
+        """
+        return ['name', 'y']
+
     @classmethod
     def _get_kwargs_from_dict(cls, as_dict):
         """Convenience method which returns the keyword arguments used to initialize the

highcharts_maps/options/series/data/map_data.py

@@ -36,6 +36,42 @@ def __init__(self, **kwargs):
         self.force_geojson = kwargs.get('force_geojsons', None)
         self.topology = kwargs.get('topology', None)
 
+    def __str__(self):
+        """Return a human-readable :class:`str <python:str>` representation of the map 
+        data.
+
+        .. warning::
+        
+          To ensure that the result is human-readable, the result will be rendered
+          *without* its 
+          :meth:`.topology <highcharts_maps.options.series.data.map_data.MapData.topology>`
+          property.
+        
+          .. tip::
+        
+            If you would like a *complete* and *unambiguous* :class:`str <python:str>` 
+            representation, then you can:
+            
+            * use the 
+              :meth:`__repr__() <highcharts_maps.options.series.data.map_data.MapData.__repr__>` method,
+            * call ``repr(my_map_data)``, or
+            * serialize the chart to TopoJSON using 
+              :meth:`.to_topojson() <highcharts_maps.options.series.data.map_data.MapData.to_topojson>`
+            * serialize the chart to GeoJSON using 
+              :meth:`.to_geojson() <highcharts_maps.options.series.data.map_data.MapData.to_geojson>`
+            
+        :returns: A :class:`str <python:str>` representation of the map data.
+        :rtype: :class:`str <python:str>`
+        """
+        as_dict = self.to_dict()
+
+        kwargs = {utility_functions.to_snake_case(key): as_dict[key]
+                  for key in as_dict if key not in ['topology']}
+        kwargs_as_str = ', '.join([f'{key} = {repr(kwargs[key])}'
+                                   for key in kwargs])
+
+        return f'{self.__class__.__name__}({kwargs_as_str})'
+
     @property
     def force_geojson(self) -> Optional[bool]:
         """If ``True``, will serialize as :term:`GeoJSON`. If ``False``, will serialize

pyproject.toml

@@ -58,7 +58,7 @@ classifiers = [
 
 requires-python = ">= 3.10"
 dependencies = [
-    "highcharts-core>=1.0.0-rc1",
+    "highcharts-core>=1.3.0",
     "esprima>=4.0.1",
     "validator-collection>=1.5.0",
     "requests>=2.31.0",

requirements.dev.txt

@@ -18,4 +18,4 @@ requests==2.31.0
 tox==4.0.0
 urllib3==1.26.9
 validator-collection==1.5.0
-highcharts-core>=1.0.0-rc1
+highcharts-core>=1.3.0

requirements.travis.txt

@@ -18,4 +18,4 @@ requests==2.31.0
 tox==4.0.0
 urllib3==1.26.9
 validator-collection==1.5.0
-highcharts-core>=1.0.0-rc1
+highcharts-core>=1.3.0