fetch arsenovics mpl offline function pr to edit and merge master

Author: cldougl

CHANGELOG.md

@@ -4,6 +4,35 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [1.9.4] - 2015-01-11
+### Added
+- Offline plotting now works outside of the IPython/Juypter notebook. Here's an example:
+```
+from plotly.offline import plot
+from plotly.graph_objs import Scatter
+
+plot([Scatter(x=[1, 2, 3], y=[3, 1, 6])])
+```
+
+This command works entirely locally. It writes to a local HTML file with the necessary [plotly.js](https://plot.ly/javascript) code to render the graph. Your browser will open the file after you make the call.
+
+The call signature is very similar to `plotly.offline.iplot` and `plotly.plotly.plot` and `plotly.plotly.iplot`, so you can basically use these commands interchangeably.
+
+If you want to publish your graphs to the web, use `plotly.plotly.plot`, as in:
+
+```
+import plotly.plotly as py
+from plotly.graph_objs import Scatter
+
+py.plot([Scatter(x=[1, 2, 3], y=[5, 1, 6])])
+```
+
+This will upload the graph to your online plotly account.
+
+## [1.9.3] - 2015-12-08
+### Added
+- Check for `no_proxy` when determining if the streaming request should pass through a proxy in the chunked_requests submodule. Example: `no_proxy='my_stream_url'` and `http_proxy=my.proxy.ip:1234`, then `my_stream_url` will not get proxied. Previously it would.   
+
 ## [1.9.2] - 2015-11-30
 **Bug Fix**: Previously, the "Export to plot.ly" link on
 offline charts would export your figures to the

plotly/graph_reference/default-schema.json

@@ -7,6 +7,7 @@
     download_plotlyjs,
     init_notebook_mode,
     iplot,
+    plot,
     iplot_mpl,
-    plotly_takeover,
+    plotly_takeover
 )

plotly/offline/__init__.py

@@ -10,6 +10,7 @@
 import uuid
 import warnings
 from pkg_resources import resource_string
+import webbrowser
 
 import plotly
 from plotly import tools, utils
@@ -70,6 +71,72 @@ def init_notebook_mode():
                  '</script>'))
 
 
+def _plot_html(figure_or_data, show_link, link_text,
+               validate, default_width, default_height):
+
+    figure = tools.return_figure_from_figure_or_data(figure_or_data, validate)
+
+    width = figure.get('layout', {}).get('width', default_width)
+    height = figure.get('layout', {}).get('height', default_height)
+
+    try:
+        float(width)
+    except (ValueError, TypeError):
+        pass
+    else:
+        width = str(width) + 'px'
+
+    try:
+        float(width)
+    except (ValueError, TypeError):
+        pass
+    else:
+        width = str(width) + 'px'
+
+    plotdivid = uuid.uuid4()
+    jdata = json.dumps(figure.get('data', []), cls=utils.PlotlyJSONEncoder)
+    jlayout = json.dumps(figure.get('layout', {}), cls=utils.PlotlyJSONEncoder)
+
+    config = {}
+    config['showLink'] = show_link
+    config['linkText'] = link_text
+    jconfig = json.dumps(config)
+
+    # TODO: The get_config 'source of truth' should
+    # really be somewhere other than plotly.plotly
+    plotly_platform_url = plotly.plotly.get_config().get('plotly_domain',
+                                                         'https://plot.ly')
+    if (plotly_platform_url != 'https://plot.ly' and
+            link_text == 'Export to plot.ly'):
+
+        link_domain = plotly_platform_url\
+            .replace('https://', '')\
+            .replace('http://', '')
+        link_text = link_text.replace('plot.ly', link_domain)
+
+    script = 'Plotly.newPlot("{id}", {data}, {layout}, {config})'.format(
+        id=plotdivid,
+        data=jdata,
+        layout=jlayout,
+        config=jconfig)
+
+    plotly_html_div = (
+        ''
+        '<div id="{id}" style="height: {height}; width: {width};" '
+        'class="plotly-graph-div">'
+        '</div>'
+        '<script type="text/javascript">'
+        'window.PLOTLYENV=window.PLOTLYENV || {{}};'
+        'window.PLOTLYENV.BASE_URL="' + plotly_platform_url + '";'
+        '{script}'
+        '</script>'
+        '').format(
+        id=plotdivid, script=script,
+        height=height, width=width)
+
+    return plotly_html_div, plotdivid, width, height
+
+
 def iplot(figure_or_data, show_link=True, link_text='Export to plot.ly',
           validate=True):
     """
@@ -116,82 +183,145 @@ def iplot(figure_or_data, show_link=True, link_text='Export to plot.ly',
         raise ImportError('`iplot` can only run inside an IPython Notebook.')
 
     from IPython.display import HTML, display
-    figure = tools.return_figure_from_figure_or_data(figure_or_data, validate)
 
-    width = figure.get('layout', {}).get('width', '100%')
-    height = figure.get('layout', {}).get('height', 525)
-    try:
-        float(width)
-    except (ValueError, TypeError):
-        pass
-    else:
-        width = str(width) + 'px'
+    plot_html, plotdivid, width, height = _plot_html(
+        figure_or_data, show_link, link_text, validate,
+        '100%', 525)
 
-    try:
-        float(width)
-    except (ValueError, TypeError):
-        pass
-    else:
-        width = str(width) + 'px'
+    display(HTML(plot_html))
 
-    plotdivid = uuid.uuid4()
-    jdata = json.dumps(figure.get('data', []), cls=utils.PlotlyJSONEncoder)
-    jlayout = json.dumps(figure.get('layout', {}), cls=utils.PlotlyJSONEncoder)
 
-    config = {}
-    config['showLink'] = show_link
-    config['linkText'] = link_text
-    jconfig = json.dumps(config)
+def plot(figure_or_data,
+         show_link=True, link_text='Export to plot.ly',
+         validate=True, output_type='file',
+         include_plotlyjs=True,
+         filename='temp-plot.html',
+         auto_open=True):
+    """ Create a plotly graph locally as an HTML document or string.
 
-    # TODO: The get_config 'source of truth' should
-    # really be somewhere other than plotly.plotly
-    plotly_platform_url = plotly.plotly.get_config().get('plotly_domain',
-                                                         'https://plot.ly')
-    if (plotly_platform_url != 'https://plot.ly' and
-            link_text == 'Export to plot.ly'):
+    Example:
+    ```
+    from plotly.offline import plot
+    import plotly.graph_objs as go
 
-        link_domain = plotly_platform_url\
-            .replace('https://', '')\
-            .replace('http://', '')
-        link_text = link_text.replace('plot.ly', link_domain)
+    plot([
+        go.Scatter(x=[1, 2, 3], y=[3, 2 6])
+    ], filename='my-graph.html')
+    ```
+    More examples below.
 
-    display(HTML(
-        '<script type="text/javascript">'
-        'window.PLOTLYENV=window.PLOTLYENV || {};'
-        'window.PLOTLYENV.BASE_URL="' + plotly_platform_url + '";'
-        '</script>'
-    ))
-
-    script = '\n'.join([
-        'Plotly.plot("{id}", {data}, {layout}, {config}).then(function() {{',
-        '    $(".{id}.loading").remove();',
-        '}})'
-    ]).format(id=plotdivid,
-              data=jdata,
-              layout=jlayout,
-              config=jconfig)
-
-    display(HTML(''
-                 '<div class="{id} loading" style="color: rgb(50,50,50);">'
-                 'Drawing...</div>'
-                 '<div id="{id}" style="height: {height}; width: {width};" '
-                 'class="plotly-graph-div">'
-                 '</div>'
-                 '<script type="text/javascript">'
-                 '{script}'
-                 '</script>'
-                 ''.format(id=plotdivid, script=script,
-                           height=height, width=width)))
+    figure_or_data -- a plotly.graph_objs.Figure or plotly.graph_objs.Data or
+                      dict or list that describes a Plotly graph.
+                      See https://plot.ly/python/ for examples of
+                      graph descriptions.
+
+    Keyword arguments:
+    show_link (default=True) -- display a link in the bottom-right corner of
+        of the chart that will export the chart to Plotly Cloud or
+        Plotly Enterprise
+    link_text (default='Export to plot.ly') -- the text of export link
+    validate (default=True) -- validate that all of the keys in the figure
+        are valid? omit if your version of plotly.js has become outdated
+        with your version of graph_reference.json or if you need to include
+        extra, unnecessary keys in your figure.
+    output_type ('file' | 'div' - default 'file') -- if 'file', then
+        the graph is saved as a standalone HTML file and `plot`
+        returns None.
+        If 'div', then `plot` returns a string that just contains the
+        HTML <div> that contains the graph and the script to generate the
+        graph.
+        Use 'file' if you want to save and view a single graph at a time
+        in a standalone HTML file.
+        Use 'div' if you are embedding these graphs in an HTML file with
+        other graphs or HTML markup, like a HTML report or an website.
+    include_plotlyjs (default=True) -- If True, include the plotly.js
+        source code in the output file or string.
+        Set as False if your HTML file already contains a copy of the plotly.js
+        library.
+    filename (default='temp-plot.html') -- The local filename to save the
+        outputted chart to. If the filename already exists, it will be
+        overwritten. This argument only applies if `output_type` is 'file'.
+    auto_open (default=True) -- If True, open the saved file in a
+        web browser after saving.
+        This argument only applies if `output_type` is 'file'.
+    """
+    if output_type not in ['div', 'file']:
+        raise ValueError(
+            "`output_type` argument must be 'div' or 'file'. "
+            "You supplied `" + output_type + "``")
+    if not filename.endswith('.html') and output_type == 'file':
+        warnings.warn(
+            "Your filename `" + filename + "` didn't end with .html. "
+            "Adding .html to the end of your file.")
+        filename += '.html'
+
+    plot_html, plotdivid, width, height = _plot_html(
+        figure_or_data, show_link, link_text, validate,
+        '100%', '100%')
+
+    figure = tools.return_figure_from_figure_or_data(figure_or_data, validate)
+
+    resize_script = ''
+    if width == '100%' or height == '100%':
+        resize_script = (
+            ''
+            '<script type="text/javascript">'
+            'window.removeEventListener("resize");'
+            'window.addEventListener("resize", function(){{'
+            'Plotly.Plots.resize(document.getElementById("{id}"));}});'
+            '</script>'
+        ).format(id=plotdivid)
+
+    if output_type == 'file':
+        with open(filename, 'w') as f:
+            if include_plotlyjs:
+                plotly_js_script = ''.join([
+                    '<script type="text/javascript">',
+                    get_plotlyjs(),
+                    '</script>',
+                ])
+            else:
+                plotly_js_script = ''
+
+            f.write(''.join([
+                '<html>',
+                '<head><meta charset="utf-8" /></head>',
+                '<body>',
+                plotly_js_script,
+                plot_html,
+                resize_script,
+                '</body>',
+                '</html>']))
+
+        url = 'file://' + os.path.abspath(filename)
+        if auto_open:
+            webbrowser.open(url)
+
+        return url
+
+    elif output_type == 'div':
+        if include_plotlyjs:
+            return ''.join([
+                '<div>',
+                '<script type="text/javascript">',
+                get_plotlyjs(),
+                '</script>',
+                plot_html,
+                '</div>'
+            ])
+        else:
+            return plot_html
 
 
 def iplot_mpl(mpl_fig,mpl_to_plotly_kw={},iplot_kw={}):
     '''
-    Convert a matplotlib figure to plotly dictionary  plot inside an 
+    Convert a matplotlib figure to plotly dictionary  plot inside an
     IPython notebook without connecting to an external server.
     '''
     plotly_plot = tools.mpl_to_plotly(mpl_fig,**mpl_to_plotly_kw)
     return iplot(plotly_plot,**iplot_kw)
 
+
 def plotly_takeover(**kwargs):
     '''
     Enable the automatic display of figures in the IPython Notebook.
@@ -200,7 +330,7 @@ def plotly_takeover(**kwargs):
     or `%matplotlib inline`. This works by adding an HTML formatter
     for Figure objects; the existing SVG/PNG formatters will remain
     enabled.
-    
+
     (idea taken from `mpld3._display.enable_notebook`)
     '''
     if __PLOTLY_OFFLINE_INITIALIZED != True:
@@ -210,10 +340,3 @@ def plotly_takeover(**kwargs):
     formatter.for_type(matplotlib.figure.Figure,
                        lambda fig, kwds=kwargs: iplot_mpl(fig, **kwds))
 
-    
-
-def plot():
-    """ Configured to work with localhost Plotly graph viewer
-    """
-    raise NotImplementedError
-