Support converting a Chart to a Vega editor URL (#3252)

* Add to_url method to convert chart to Vega editor URL * Add to_url documentation * Add changelog * Move to local import * ruff format * update url test * typing Co-authored-by: Stefan Binder <[email protected]> * reword Co-authored-by: Stefan Binder <[email protected]> * make fullscreen a keyword-only argument --------- Co-authored-by: Stefan Binder <[email protected]>
vega · Nov 6, 2023 · b03d071 · b03d071
1 parent e5fb1f0
commit b03d071
Show file tree

Hide file tree

Showing 4 changed files with 65 additions and 0 deletions.
diff --git a/altair/vegalite/v5/api.py b/altair/vegalite/v5/api.py
@@ -1055,6 +1055,25 @@ def to_html(
             requirejs=requirejs,
         )
 
+    def to_url(self, *, fullscreen: bool = False) -> str:
+        """Convert a chart to a URL that opens the chart specification in the Vega chart editor
+        The chart specification (including any inline data) is encoded in the URL.
+
+        This method requires that the vl-convert-python package is installed.
+
+        Parameters
+        ----------
+        fullscreen : bool
+            If True, editor will open chart in fullscreen mode. Default False
+        """
+        from ...utils._importers import import_vl_convert
+
+        vlc = import_vl_convert()
+        if _using_vegafusion():
+            return vlc.vega_to_url(self.to_dict(format="vega"), fullscreen=fullscreen)
+        else:
+            return vlc.vegalite_to_url(self.to_dict(), fullscreen=fullscreen)
+
     def save(
         self,
         fp: Union[str, IO],

diff --git a/doc/releases/changes.rst b/doc/releases/changes.rst
@@ -8,6 +8,8 @@ Version 5.2.0 (unreleased month date, year)
 
 Enhancements
 ~~~~~~~~~~~~
+- Support saving charts as PDF files using the vl-convert export engine (#3244)
+- Support converting charts to sharable Vega editor URLs with ``chart.to_url()`` (#3252)
 
 Bug Fixes
 ~~~~~~~~~

diff --git a/doc/user_guide/saving_charts.rst b/doc/user_guide/saving_charts.rst
@@ -224,6 +224,26 @@ size at the default resolution of 72 ppi::
 
     chart.save('chart.png', scale_factor=2)
 
+Sharable URL
+~~~~~~~~~~~~
+The :meth:`Chart.to_url` method can be used to build a sharable URL that opens the chart
+specification in the online Vega editor_.
+
+.. altair-plot::
+    :output: repr
+
+    import altair as alt
+    from vega_datasets import data
+
+    chart = alt.Chart(data.cars.url).mark_point().encode(
+        x='Horsepower:Q',
+        y='Miles_per_Gallon:Q',
+        color='Origin:N'
+    )
+
+    chart.to_url()
+
 .. _vl-convert: https://github.com/vega/vl-convert
 .. _altair_saver: http://github.com/altair-viz/altair_saver/
 .. _vegaEmbed: https://github.com/vega/vega-embed
+.. _editor: https://vega.github.io/editor/
diff --git a/tests/vegalite/v5/test_api.py b/tests/vegalite/v5/test_api.py
@@ -380,6 +380,30 @@ def test_save_html(basic_chart, inline):
         assert 'src="https://cdn.jsdelivr.net/npm/vega-embed@6' in content
 
 
+def test_to_url(basic_chart):
+    share_url = basic_chart.to_url()
+    expected_vegalite_encoding = (
+        "N4Igxg9gdgZglgcxALlANzgUwO4tJKAFzigFcJSBnAdTgBNCALFAZgAY2AacaYsiygAlMiRoVYcAvpO50AhoTl4QU"
+        "OQFtMKEPMUBaMACY5LTAA4AnACM55ugFY6ARgBspgOz2zh03Wfs5bCwsIDIganIATgDWyoQAngAOmsgg1hEh3JhQk"
+        "HQkSKggAB7K8JgANnRaStzxSVpQEGokcmUZIHElWBValiA1ickgAI6kckRwisRomtLcACSUYIyY4VpihAmUyAD029"
+        "MIcgB0CBOMpJaHcBDbi8vhe5gHumUTmHt2h44fjocAVpTQPraBRySiYQiUZQ6OT6IwmCzWWwOFzuTymby+fyBYLIA"
+        "DaoCUKQAgkDesgDKYZAStAAhUkoOx2KkgQkgADC9OQABYWMzWQARTnmRx8rQAUU5phFnGpKQAYpy7LyZSytABxTmO"
+        "cyilKCSVuHUgACSioMkgAutIgA"
+    )
+
+    assert (
+        share_url
+        == f"https://vega.github.io/editor/#/url/vega-lite/{expected_vegalite_encoding}"
+    )
+
+    # Check fullscreen
+    fullscreen_share_url = basic_chart.to_url(fullscreen=True)
+    assert (
+        fullscreen_share_url
+        == f"https://vega.github.io/editor/#/url/vega-lite/{expected_vegalite_encoding}/view"
+    )
+
+
 def test_facet_basic():
     # wrapped facet
     chart1 = (