Added get_plotlyjs and get_plotlyjs_version functions (plotly#1246)

jonmmease · michaelbabyn · commit 54cd796c8c19 · 2018-12-21T19:44:57.000-05:00
* Make get_plotlyjs public and add docstring
* Added plotly.offline.get_plotlyjs_version() function.
  This function returns the plotly.js versions that is bundled with plotly.py.
  The returned version is updated automatically during the updatebundle setup.py command.
diff --git a/plotly/offline/__init__.py b/plotly/offline/__init__.py
@@ -5,6 +5,8 @@
 """
 from . offline import (
     download_plotlyjs,
+    get_plotlyjs_version,
+    get_plotlyjs,
     enable_mpl_offline,
     init_notebook_mode,
     iplot,
diff --git a/plotly/offline/_plotlyjs_version.py b/plotly/offline/_plotlyjs_version.py
@@ -0,0 +1,3 @@
+# DO NOT EDIT
+# This file is generated by the updatebundle setup.py command
+__plotlyjs_version__ = '1.41.3'
diff --git a/plotly/offline/offline.py b/plotly/offline/offline.py
@@ -18,6 +18,7 @@
 import plotly
 from plotly import optional_imports, tools, utils
 from plotly.exceptions import PlotlyError
+from ._plotlyjs_version import __plotlyjs_version__
 
 ipython = optional_imports.get_module('IPython')
 ipython_display = optional_imports.get_module('IPython.display')
@@ -37,11 +38,66 @@ def download_plotlyjs(download_url):
     pass
 
 
+def get_plotlyjs_version():
+    """
+    Returns the version of plotly.js that is bundled with plotly.py.
+
+    Returns
+    -------
+    str
+        Plotly.js version string
+    """
+    return __plotlyjs_version__
+
+
 def get_plotlyjs():
+    """
+    Return the contents of the minified plotly.js library as a string.
+
+    This may be useful when building standalone HTML reports.
+
+    Returns
+    -------
+    str
+        Contents of the minified plotly.js library as a string
+
+    Examples
+    --------
+    Here is an example of creating a standalone HTML report that contains
+    two plotly figures, each in their own div.  The include_plotlyjs argument
+    is set to False when creating the divs so that we don't include multiple
+    copies of the plotly.js library in the output.  Instead, a single copy
+    of plotly.js is included in a script tag in the html head element.
+
+    >>> import plotly.graph_objs as go
+    >>> from plotly.offline import plot, get_plotlyjs
+    >>> fig1 = go.Figure(data=[{'type': 'bar', 'y': [1, 3, 2]}],
+    ...                 layout={'height': 400})
+    >>> fig2 = go.Figure(data=[{'type': 'scatter', 'y': [1, 3, 2]}],
+    ...                  layout={'height': 400})
+    >>> div1 = plot(fig1, output_type='div', include_plotlyjs=False)
+    >>> div2 = plot(fig2, output_type='div', include_plotlyjs=False)
+
+    >>> html = '''
+    ... <html>
+    ...     <head>
+    ...         <script type="text/javascript">{plotlyjs}</script>
+    ...     </head>
+    ...     <body>
+    ...        {div1}
+    ...        {div2}
+    ...     </body>
+    ... </html>
+    ...'''.format(plotlyjs=get_plotlyjs(), div1=div1, div2=div2)
+
+    >>> with open('multi_plot.html', 'w') as f:
+    ...      f.write(html)
+    """
     path = os.path.join('package_data', 'plotly.min.js')
     plotlyjs = pkgutil.get_data('plotly', path).decode('utf-8')
     return plotlyjs
 
+
 def get_image_download_script(caller):
     """
     This function will return a script that will download an image of a Plotly
diff --git a/plotly/tests/test_core/test_offline/test_offline.py b/plotly/tests/test_core/test_offline/test_offline.py
@@ -10,6 +10,7 @@
 from requests.compat import json as _json
 
 import plotly
+import json
 
 
 fig = {
@@ -28,7 +29,7 @@
         ]
 
 
-PLOTLYJS = plotly.offline.offline.get_plotlyjs()
+PLOTLYJS = plotly.offline.get_plotlyjs()
 
 cdn_script = ('<script src="https://cdn.plot.ly/plotly-latest.min.js">'
               '</script>')
@@ -270,3 +271,11 @@ def test_config(self):
         self.assertIn('"linkText": "Plotly rocks!"', html)
         self.assertIn('"showLink": true', html)
         self.assertIn('"editable": true', html)
+
+    def test_plotlyjs_version(self):
+        with open('js/package.json', 'rt') as f:
+            package_json = json.load(f)
+            expected_version = package_json['dependencies']['plotly.js']
+
+        self.assertEqual(expected_version,
+                         plotly.offline.get_plotlyjs_version())
diff --git a/setup.py b/setup.py
@@ -199,6 +199,14 @@ def run(self):
             with open('plotly/package_data/plotly.min.js', 'wb') as f:
                 f.write(response.read())
 
+        # Write plotly.js version file
+        with open('plotly/offline/_plotlyjs_version.py', 'w') as f:
+            f.write("""\
+# DO NOT EDIT
+# This file is generated by the updatebundle setup.py command
+__plotlyjs_version__ = '{plotlyjs_version}'
+""".format(plotlyjs_version=plotly_js_version()))
+
 
 class UpdatePlotlyJsCommand(Command):
     description = 'Update project to a new version of plotly.js'

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# DO NOT EDIT`
	`2`	`+# This file is generated by the updatebundle setup.py command`
	`3`	`+__plotlyjs_version__ = '1.41.3'`