highcharts-for-python · hcpchris · Oct 10, 2023 · Jul 27, 2023 · Aug 14, 2023 · Aug 14, 2023
diff --git a/.gitignore b/.gitignore
@@ -109,7 +109,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
-.py310/
+.py31*/
 
 # Spyder project settings
 .spyderproject

diff --git a/.travis.yml b/.travis.yml
@@ -1,10 +1,6 @@
 language: python
 job:
   include:
-    #- python: "3.8"
-    #  env: TOXENV=py38
-    #- python: "3.9"
-    #  env: TOXENV=py39
     - python: "3.10"
       dist: focal
       env: TOXENV=py310

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,4 +1,29 @@
 
+Release 1.4.0
+=========================================
+
+* **MAJOR** performance gains in the ``.to_js_literal()`` method. Implementation seems to
+  improve performance by 50 - 90%. (#51)
+* *SIGNIFICANT* performance gains in the ``.to_json()`` method. Implementation seems to 
+  improve performance by 30 - 90%.
+* **ENHANCEMENT:** Significantly simplified use of the ``.from_pandas()`` method to support:
+
+  * creation of multiple series from one DataFrame in one method call
+  * creation of series without needing to specify a full property map
+  * support for creating series by DataFrame row, rather than just by DataFrame column
+
+* **ENHANCEMENT:** Added the ``.from_pandas_in_rows()`` method to support creation of
+  charts and series from simple two-dimensional DataFrames laid out in rows.
+* **ENHANCEMENT:** Added one-shot chart creation and rendering from Series objects (#89).
+* **ENHANCEMENT:** Added one-shot chart creation using ``series`` and ``data``/``series_type`` keywords. (#90).
+* **ENHANCEMENT:** Added ``.convert_to()`` convenience method to Series objects (#107).
+* **ENHANCEMENT:** Added ``CallbackFunction.from_python()`` method which converts a Python function
+  to its JavaScript equivalent using generative AI, with support for both OpenAI and Anthropic (#109).
+* **BUGFIX:** Fixed instability issues in Jupyter Notebooks, both when operating as a Notebook (outside of 
+  Jupyter Lab) and when saved to a static HTML file (#66).
+
+--------------------
+
 Release 1.3.7
 =========================================
 

diff --git a/README.rst b/README.rst
@@ -212,49 +212,53 @@ Hello World, and Basic Usage
 
   .. code-block:: python
 
+    # from a primitive array, using keyword arguments
+    my_chart = Chart(data = [[1, 23], [2, 34], [3, 45]], 
+                     series_type = 'line')
+
+    # from a primitive array, using the .from_array() method
+    my_chart = Chart.from_array([[1, 23], [2, 34], [3, 45]], 
+                                series_type = 'line')
+
+    # from a Numpy ndarray, using keyword arguments
+    my_chart = Chart(data = numpy_array, series_type = 'line')
+
+    # from a Numpy ndarray, using the .from_array() method
+    my_chart = Chart.from_array(data = numpy_array, series_type = 'line')
+
     # from a JavaScript file
-    my_chart = highcharts.Chart.from_js_literal('my_js_literal.js')
+    my_chart = Chart.from_js_literal('my_js_literal.js')
 
     # from a JSON file
-    my_chart = highcharts.Chart.from_json('my_json.json')
+    my_chart = Chart.from_json('my_json.json')
 
     # from a Python dict
-    my_chart = highcharts.Chart.from_dict(my_dict_obj)
+    my_chart = Chart.from_dict(my_dict_obj)
 
     # from a Pandas dataframe
-    my_chart = highcharts.Chart.from_pandas(df,
-                                            property_map = {
-                                                'x': 'transactionDate',
-                                                'y': 'invoiceAmt',
-                                                'id': 'id'
-                                            },
-                                            series_type = 'line')
+    my_chart = Chart.from_pandas(df)
 
     # from a PySpark dataframe
-    my_chart = highcharts.Chart.from_pyspark(df,
-                                             property_map = {
-                                                 'x': 'transactionDate',
-                                                 'y': 'invoiceAmt',
-                                                 'id': 'id'
-                                             },
-                                             series_type = 'line')
+    my_chart = Chart.from_pyspark(df,
+                                  property_map = {
+                                      'x': 'transactionDate',
+                                      'y': 'invoiceAmt',
+                                      'id': 'id'
+                                  },
+                                  series_type = 'line')
 
     # from a CSV
-    my_chart = highcharts.Chart.from_csv('/some_file_location/filename.csv'
-                                         column_property_map = {
-                                            'x': 0,
-                                            'y': 4,
-                                            'id': 14
-                                         },
-                                         series_type = 'line')
+    my_chart = Chart.from_csv('/some_file_location/filename.csv')
 
     # from a HighchartsOptions configuration object
-    my_chart = highcharts.Chart.from_options(my_options)
-
-    # from a Series configuration
-    my_chart = highcharts.Chart.from_series(my_series)
+    my_chart = Chart.from_options(my_options)
 
+    # from a Series configuration, using keyword arguments
+    my_chart = Chart(series = my_series)
 
+    # from a Series configuration, using .from_series()
+    my_chart = Chart.from_series(my_series)
+
 3. Configure Global Settings (optional)
 =============================================
 
@@ -284,6 +288,7 @@ Hello World, and Basic Usage
     from highcharts_core.options.title import Title
     from highcharts_core.options.credits import Credits
 
+    # EXAMPLE 1.
     # Using dicts
     my_chart.title = {
         'align': 'center'
@@ -294,7 +299,7 @@ Hello World, and Basic Usage
 
     my_chart.credits = {
         'enabled': True,
-        'href': 'https://www.highcharts.com/',
+        'href': 'https://www.highchartspython.com/',
         'position': {
             'align': 'center',
             'vertical_align': 'bottom',
@@ -309,17 +314,21 @@ Hello World, and Basic Usage
         'text': 'Chris Modzelewski'
     }
 
+    # EXAMPLE 2.
     # Using direct objects
     from highcharts_core.options.title import Title
     from highcharts_core.options.credits import Credits
 
-    my_title = Title(text = 'The Title for My Chart', floating = True, align = 'center')
+    my_title = Title(text = 'The Title for My Chart',
+                     floating = True, 
+                     align = 'center')
     my_chart.options.title = my_title
 
-    my_credits = Credits(text = 'Chris Modzelewski', enabled = True, href = 'https://www.highcharts.com')
+    my_credits = Credits(text = 'Chris Modzelewski', 
+                         enabled = True, 
+                         href = 'https://www.highchartspython.com')
     my_chart.options.credits = my_credits
 
-
 5. Generate the JavaScript Code for Your Chart
 =================================================
 
@@ -328,9 +337,11 @@ that will render the chart wherever it is you want it to go:
 
   .. code-block:: python
 
+    # EXAMPLE 1.
     # as a string
     js_as_str = my_chart.to_js_literal()
 
+    # EXAMPLE 2.
     # to a file (and as a string)
     js_as_str = my_chart.to_js_literal(filename = 'my_target_file.js')
 
@@ -359,6 +370,14 @@ that will render the chart wherever it is you want it to go:
     my_image_bytes = my_chart.download_chart(filename = 'my_target_file.png',
                                              format = 'png')
 
+
+8. Render Your Chart in a Jupyter Notebook
+===============================================
+
+  .. code-block:: python
+
+    my_chart.display()
+
 --------------
 
 ***********************

diff --git a/docs/_dependencies.rst b/docs/_dependencies.rst
@@ -56,11 +56,14 @@
         $ pip install highcharts-core[soft]
 
     * `IPython <https://ipython.org/>`__ v. 8.10 or higher
+    * `Jupyter Notebook <https://jupyter.org/>`__ v.6.4 or higher
     * `orjson <https://github.com/ijl/orjson>`__ v.3.7.7 or higher
+    * `NumPy <https://numpy.org>`__ v.1.19.3 or higher
     * `pandas <https://pandas.pydata.org/>`_ v. 1.3 or higher
     * `pyspark <https://spark.apache.org/docs/latest/api/python/index.html>`_ v.3.3 or
       higher
 
+
   .. tab:: Developer
 
     .. warning::

diff --git a/docs/_static/census-time-series.png b/docs/_static/census-time-series.png
diff --git a/docs/_static/highcharts-chart-anatomy.png b/docs/_static/highcharts-chart-anatomy.png
diff --git a/docs/_static/tutorials/census-time-series-01.png b/docs/_static/tutorials/census-time-series-01.png
diff --git a/docs/_static/tutorials/census-time-series-02.png b/docs/_static/tutorials/census-time-series-02.png
diff --git a/docs/_static/tutorials/census-time-series-03.png b/docs/_static/tutorials/census-time-series-03.png
diff --git a/docs/_static/tutorials/census-time-series-04.png b/docs/_static/tutorials/census-time-series-04.png
diff --git a/docs/_static/tutorials/census-time-series-05.png b/docs/_static/tutorials/census-time-series-05.png
diff --git a/docs/_static/tutorials/census-time-series-06.png b/docs/_static/tutorials/census-time-series-06.png
diff --git a/docs/_static/tutorials/census-time-series-07.png b/docs/_static/tutorials/census-time-series-07.png
diff --git a/docs/_static/tutorials/census-time-series-08.png b/docs/_static/tutorials/census-time-series-08.png
diff --git a/docs/_static/tutorials/census-time-series-09.png b/docs/_static/tutorials/census-time-series-09.png
diff --git a/docs/_static/tutorials/census-time-series-10.png b/docs/_static/tutorials/census-time-series-10.png
diff --git a/docs/_static/tutorials/census-time-series-csv-01.png b/docs/_static/tutorials/census-time-series-csv-01.png
diff --git a/docs/_static/tutorials/raw-data-as-numpy.png b/docs/_static/tutorials/raw-data-as-numpy.png
diff --git a/docs/api.rst b/docs/api.rst
@@ -449,51 +449,81 @@ Core Components
     - :class:`DataPointAccessibility <highcharts_core.options.series.data.accessibility.DataPointAccessibility>`
   * - :mod:`.options.series.data.arcdiagram <highcharts_core.options.series.data.arcdiagram>`
     - :class:`ArcDiagramData <highcharts_core.options.series.data.arcdiagram.ArcDiagramData>`
+      :class:`ArcDiagramDataCollection <highcharts_core.options.series.data.arcidagram.ArcDiagramDataCollection>`
   * - :mod:`.options.series.data.bar <highcharts_core.options.series.data.bar>`
     - :class:`BarData <highcharts_core.options.series.data.bar.BarData>`
+      :class:`BarDataCollection <highcharts_core.options.series.data.bar.BarDataCollection>`
       :class:`WaterfallData <highcharts_core.options.series.data.bar.WaterfallData>`
+      :class:`WaterfallDataCollection <highcharts_core.options.series.data.bar.WaterfallDataCollection>`
       :class:`WindBarbData <highcharts_core.options.series.data.bar.WindBarbData>`
+      :class:`WindBarbDataCollection <highcharts_core.options.series.data.bar.WindBarbDataCollection>`
       :class:`XRangeData <highcharts_core.options.series.data.bar.XRangeData>`
+      :class:`XRangeDataCollection <highcharts_core.options.series.data.bar.XRangeDataCollection>`
   * - :mod:`.options.series.data.base <highcharts_core.options.series.data.base>`
     - :class:`DataBase <highcharts_core.options.series.data.base.DataBase>`
   * - :mod:`.options.series.data.boxplot <highcharts_core.options.series.data.boxplot>`
     - :class:`BoxPlotData <highcharts_core.options.series.data.boxplot.BoxPlotData>`
+      :class:`BoxPlotDataCollection <highcharts_core.options.series.data.boxplot.BoxPlotDataCollection>`
   * - :mod:`.options.series.data.bullet <highcharts_core.options.series.data.bullet>`
     - :class:`BulletData <highcharts_core.options.series.data.bullet.BulletData>`
+      :class:`BulletDataCollection <highcharts_core.options.series.data.bullet.BulletDataCollection>`
   * - :mod:`.options.series.data.cartesian <highcharts_core.options.series.data.cartesian>`
     - :class:`CartesianData <highcharts_core.options.series.data.cartesian.CartesianData>`
+      :class:`CartesianDataCollection <highcharts_core.options.series.data.cartesian.CartesianDataCollection>`
       :class:`Cartesian3DData <highcharts_core.options.series.data.cartesian.Cartesian3DData>`
+      :class:`Cartesian3DDataCollection <highcharts_core.options.series.data.cartesian.Cartesian3DDataCollection>`
       :class:`CartesianValueData <highcharts_core.options.series.data.cartesian.CartesianValueData>`
+      :class:`CartesianValueDataCollection <highcharts_core.options.series.data.cartesian.CartesianValueDataCollection>`
+  * - :mod:`.options.series.data.collections <highcharts_core.options.series.data.collections>`
+    - :class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`
   * - :mod:`.options.series.data.connections <highcharts_core.options.series.data.connections>`
     - :class:`ConnectionData <highcharts_core.options.series.data.connections.ConnectionData>`
+      :class:`ConnectionDataCollection <highcharts_core.options.series.data.connections.ConnectionDataCollection>`
       :class:`WeightedConnectionData <highcharts_core.options.series.data.connections.WeightedConnectionData>`
+      :class:`WeightedConnectionDataCollection <highcharts_core.options.series.data.connections.WeightedConnectionDataCollection>`
       :class:`OutgoingWeightedConnectionData <highcharts_core.options.series.data.connections.OutgoingWeightedConnectionData>`
+      :class:`OutgoingWeightedConnectionDataCollection <highcharts_core.options.series.data.connections.OutgoingWeightedConnectionDataCollection>`
       :class:`ConnectionBase <highcharts_core.options.series.data.connections.ConnectionBase>`
   * - :mod:`.options.series.data.pie <highcharts_core.options.series.data.pie>`
     - :class:`PieData <highcharts_core.options.series.data.pie.PieData>`
+      :class:`PieDataCollection <highcharts_core.options.series.data.pie.PieDataCollection>`
       :class:`VariablePieData <highcharts_core.options.series.data.pie.VariablePieData>`
+      :class:`VariablePieDataCollection <highcharts_core.options.series.data.pie.VariablePieDataCollection>`
   * - :mod:`.options.series.data.range <highcharts_core.options.series.data.range>`
     - :class:`RangeData <highcharts_core.options.series.data.range.RangeData>`
+      :class:`RangeDataCollection <highcharts_core.options.series.data.range.RangeDataCollection>`
       :class:`ConnectedRangeData <highcharts_core.options.series.data.range.ConnectedRangeData>`
+      :class:`ConnectedRangeDataCollection <highcharts_core.options.series.data.range.ConnectedRangeDataCollection>`
   * - :mod:`.options.series.data.single_point <highcharts_core.options.series.data.single_point>`
     - :class:`SinglePointData <highcharts_core.options.series.data.single_point.SinglePointData>`
+      :class:`SinglePointDataCollection <highcharts_core.options.series.data.single_point.SinglePointDataCollection>`
       :class:`SingleValueData <highcharts_core.options.series.data.single_point.SingleValueData>`
+      :class:`SingleValueDataCollection <highcharts_core.options.series.data.single_point.SingleValueDataCollection>`
       :class:`SingleXData <highcharts_core.options.series.data.single_point.SingleXData>`
+      :class:`SingleXDataCollection <highcharts_core.options.series.data.single_point.SingleXDataCollection>`
       :class:`LabeledSingleXData <highcharts_core.options.series.data.single_point.LabeledSingleXData>`
+      :class:`LabeledSingleXDataCollection <highcharts_core.options.series.data.single_point.LabeledSingleXDataCollection>`
       :class:`ConnectedSingleXData <highcharts_core.options.series.data.single_point.ConnectedSingleXData>`
+      :class:`ConnectedSingleXDataCollection <highcharts_core.options.series.data.single_point.ConnectedSingleXDataCollection>`
       :class:`SinglePointBase <highcharts_core.options.series.data.single_point.SinglePointBase>`
   * - :mod:`.options.series.data.sunburst <highcharts_core.options.series.data.sunburst>`
     - :class:`SunburstData <highcharts_core.options.series.data.sunburst.SunburstData>`
+      :class:`SunburstDataCollection <highcharts_core.options.series.data.sunburst.SunburstDataCollection>`
   * - :mod:`.options.series.data.treegraph <highcharts_core.options.series.data.treegraph>`
     - :class:`TreegraphData <highcharts_core.options.series.data.treegraph.TreegraphData>`
+      :class:`TreegraphDataCollection <highcharts_core.options.series.data.treegraph.TreegraphDataCollection>`
   * - :mod:`.options.series.data.treemap <highcharts_core.options.series.data.treemap>`
     - :class:`TreemapData <highcharts_core.options.series.data.treemap.TreemapData>`
+      :class:`TreemapDataCollection <highcharts_core.options.series.data.treemap.TreemapDataCollection>`
   * - :mod:`.options.series.data.vector <highcharts_core.options.series.data.vector>`
     - :class:`VectorData <highcharts_core.options.series.data.vector.VectorData>`
+      :class:`VectorDataCollection <highcharts_core.options.series.data.vector.VectorDataCollection>`
   * - :mod:`.options.series.data.venn <highcharts_core.options.series.data.venn>`
     - :class:`VennData <highcharts_core.options.series.data.venn.VennData>`
+      :class:`VennDataCollection <highcharts_core.options.series.data.venn.VennDataCollection>`
   * - :mod:`.options.series.data.wordcloud <highcharts_core.options.series.data.wordcloud>`
     - :class:`WordcloudData <highcharts_core.options.series.data.wordcloud.WordcloudData>`
+      :class:`WordcloudDataCollection <highcharts_core.options.series.data.wordcloud.WordcloudDataCollection>`
   * - :mod:`.options.series.dependencywheel <highcharts_core.options.series.dependencywheel>`
     - :class:`DependencyWheelSeries <highcharts_core.options.series.dependencywheel.DependencyWheelSeries>`
   * - :mod:`.options.series.dumbbell <highcharts_core.options.series.dumbbell>`
@@ -563,10 +593,10 @@ Core Components
     - :class:`PointGrouping <highcharts_core.options.sonification.grouping.SonificationGrouping>`
   * - :mod:`.options.sonification.mapping <highcharts_core.options.sonification.mapping>`
     - :class:`SonificationMapping <highcharts_core.options.sonification.mapping.SonificationMapping>`
-      :class:`AudioParameter <highcahrts_core.options.sonification.mapping.AudioParameter>`
+      :class:`AudioParameter <highcharts_core.options.sonification.mapping.AudioParameter>`
       :class:`AudioFilter <highcharts_core.options.sonification.mapping.AudioFilter>`
       :class:`PitchParameter <highcharts_core.options.sonification.mapping.PitchParameter>`
-      :class:`TremoloEffect <highcahrts_core.options.sonification.mapping.TremoloEffect>`
+      :class:`TremoloEffect <highcharts_core.options.sonification.mapping.TremoloEffect>`
   * - :mod:`.options.sonification.track_configurations <highcharts_core.options.sonification.track_configurations>`
     - :class:`InstrumentTrackConfiguration <highcharts_core.options.sonification.track_configurations.InstrumentTrackConfiguration>`
       :class:`SpeechTrackConfiguration <highcharts_core.options.sonification.track_configurations.SpeechTrackConfiguration>`
@@ -715,6 +745,12 @@ familiarize yourself with these internals.
       :func:`to_camelCase() <highcharts_core.utility_functions.to_camelCase>`
       :func:`to_snake_case() <highcharts_core.utility_functions.to_snake_case>`
       :func:`parse_csv() <highcharts_core.utility_functions.parse_csv>`
+  * - :mod:`.ai <highcharts_core.ai>`
+    - :func:`convert_to_js() <highcharts_core.ai.convert_to_js>`
+      :func:`openai_moderate() <highcharts_core.ai.openai_moderate>`
+      :func:`openai_conversion() <highcharts_core.ai.openai_conversion>`
+      :func:`anthropic_conversion() <highcharts_core.ai.anthropic_conversion>`
+      :func:`get_source() <highcharts_core.ai.get_source>`
 
 .. target-notes::
 

diff --git a/docs/api/internals.rst b/docs/api/internals.rst
@@ -174,3 +174,42 @@ function:: :func:`parse_csv() <highcharts_core.utility_functions.parse_csv>`
 =====================================================================================================
 
 .. autofunction:: parse_csv
+
+--------------
+
+.. module:: highcharts_core.ai
+
+******************************************************************************
+module: :mod:`.ai <highcharts_core.ai>`
+******************************************************************************
+
+The :mod:`.ai <highcharts_core.ai>` module contains - as one might
+expect - functions that enable Highcharts for Python to communicate with
+supported generative AI platforms. These functions are used to convert
+Python callables to their JavaScript equivalents in the 
+:meth:`CallbackFunction.from_python() <highcharts_core.utility_classes.javascript_functions.CallbackFunction.from_python>` method.
+
+function:: :func:`convert_to_js() <highcharts_core.ai.convert_to_js>`
+=====================================================================================================
+
+.. autofunction:: convert_to_js
+
+function:: :func:`openai_moderate() <highcharts_core.ai.openai_moderate>`
+=====================================================================================================
+
+.. autofunction:: openai_moderate
+
+function:: :func:`openai_conversion() <highcharts_core.ai.openai_conversion>`
+=====================================================================================================
+
+.. autofunction:: openai_conversion
+
+function:: :func:`anthropic_conversion() <highcharts_core.ai.anthropic_conversion>`
+=====================================================================================================
+
+.. autofunction:: anthropic_conversion
+
+function:: :func:`get_source() <highcharts_core.ai.get_source>`
+=====================================================================================================
+
+.. autofunction:: get_source