- 🔪 *kwargs* -update docstring with keyword arguments

cldougl · cldougl · commit 6dd6ed8057e6 · 2016-01-15T19:04:36.000-05:00
diff --git a/plotly/graph_reference/default-schema.json b/plotly/graph_reference/default-schema.json
@@ -426,12 +426,14 @@
                 ]
             },
             "dragmode": {
-                "description": "Determines the mode of drag interactions.",
+                "description": "Determines the mode of drag interactions. *select* and *lasso* apply only to scatter traces with markers or text. *orbit* and *turntable* apply only to 3D scenes.",
                 "role": "info",
                 "valType": "enumerated",
                 "values": [
                     "zoom",
                     "pan",
+                    "select",
+                    "lasso",
                     "orbit",
                     "turntable"
                 ]
diff --git a/plotly/offline/__init__.py b/plotly/offline/__init__.py
@@ -5,10 +5,10 @@
 """
 from . offline import (
     download_plotlyjs,
+    enable_mpl_offline,
     init_notebook_mode,
     iplot,
     iplot_mpl,
     plot,
-    plot_mpl,
-    plotly_takeover
+    plot_mpl
 )
diff --git a/plotly/offline/offline.py b/plotly/offline/offline.py
@@ -312,30 +312,52 @@ def plot(figure_or_data,
 
 
 def plot_mpl(mpl_fig, resize=False, strip_style=False,
-             verbose=False, **kwargs):
-    '''
-    Convert a matplotlib figure to a plotly graph locally as an HTML document
-    or string
+             verbose=False, show_link=True, link_text='Export to plot.ly',
+             validate=True, output_type='file', include_plotlyjs=True,
+             filename='temp-plot.html', auto_open=True):
+    """
+    Convert a matplotlib figure to a Plotly graph stored locally as HTML.
 
     For more information on converting matplotlib visualizations to plotly
-    graphs, call help(plotly.tools.mpl_to_plotly)
+    graphs, call help(plotly.plot_mpl)
 
     For more information on creating plotly charts locally as an HTML document
     or string, call help(plotly.offline.plot)
 
-    :param (matplotlib figure) mpl_fig: matplotlib figure to convert to a
-        plotly graph
-    :param (bool) resize: Default = False
-    :param (bool) strip_style: Default = False
-    :param (bool) verbose: Default = False
-    :param kwargs: kwargs passed through `plotly.offline.plot`.
-        For more information on valid kwargs call `help(plotly.offline.plot)`
-    :return (None|string): if `output_type` is 'file' (default), then the graph
-        is saved as a standalone HTML file and `plot_mpl` returns None.
-        If `output_type` is 'div', then `plot` returns a string that contains
-        the HTML <div> that contains the graph and the script to generate the
-        graph. For more information about `output_type` call
-        `help(plotly.offline.plot)`
+    mpl_fig -- a matplotlib figure object to convert to a plotly graph
+
+    Keyword arguments:
+    resize (default=False) -- allow plotly to choose the figure size.
+    strip_style (default=False) -- allow plotly to choose style options.
+    verbose (default=False) -- print message.
+    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'.
 
     Example:
     ```
@@ -351,14 +373,16 @@ def plot_mpl(mpl_fig, resize=False, strip_style=False,
 
     plot_mpl(fig)
     ```
-    '''
+    """
     plotly_plot = tools.mpl_to_plotly(mpl_fig, resize, strip_style, verbose)
-    return plot(plotly_plot, **kwargs)
+    return plot(plotly_plot, show_link, link_text, validate, output_type,
+                include_plotlyjs, filename, auto_open)
 
 
 def iplot_mpl(mpl_fig, resize=False, strip_style=False,
-              verbose=False, **kwargs):
-    '''
+              verbose=False, show_link=True,
+              link_text='Export to plot.ly', validate=True):
+    """
     Convert a matplotlib figure to a plotly graph and plot inside an IPython
     notebook without connecting to an external server.
 
@@ -371,14 +395,24 @@ def iplot_mpl(mpl_fig, resize=False, strip_style=False,
     For more information on plotting plotly charts offline in an Ipython
     notebook call `help(plotly.offline.iplot)`
 
-    :param (matplotlib figure) mpl_fig: matplotlib figure to convert to a
-        plotly graph
-    :param (bool) resize: Default = False
-    :param (bool) strip_style: Default = False
-    :param (bool) verbose: Default = False
-    :param kwargs: kwargs passed through `plotly.offline.iplot`.
-        For more information on valid kwargs call `help(plotly.offline.iplot)`
-    :return: draws converted plotly figure in Ipython notebook
+    mpl_fig -- a matplotlib.figure to convert to a plotly graph
+
+    Keyword arguments:
+    resize (default=False) -- allow plotly to choose the figure size.
+    strip_style (default=False) -- allow plotly to choose style options.
+    verbose (default=False) -- print message.
+    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
+    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.
 
     Example:
     ```
@@ -394,17 +428,18 @@ def iplot_mpl(mpl_fig, resize=False, strip_style=False,
 
     iplot_mpl(fig)
     ```
-    '''
+    """
     plotly_plot = tools.mpl_to_plotly(mpl_fig, resize, strip_style, verbose)
-    return iplot(plotly_plot, **kwargs)
+    return iplot(plotly_plot, show_link, link_text, validate)
 
 
-def plotly_takeover(**kwargs):
-    '''
-    Enable the automatic matplotlib to plotly conversion and display
-    of figures in an IPython Notebook.
+def enable_mpl_offline(resize=False, strip_style=False,
+                       verbose=False, show_link=True,
+                       link_text='Export to plot.ly', validate=True):
+    """
+    Convert mpl plots to locally hosted HTML documents.
 
-    This function should be used with the inline Matplotlib backend
+    This function should be used with the inline matplotlib backend
     that ships with IPython that can be enabled with `%pylab inline`
     or `%matplotlib inline`. This works by adding an HTML formatter
     for Figure objects; the existing SVG/PNG formatters will remain
@@ -417,7 +452,7 @@ def plotly_takeover(**kwargs):
     from plotly.offline import init_notebook_mode, plotly_takeover
     import matplotlib.pyplot as plt
 
-    init_notebook_mode
+    init_notebook_mode()
     plotly_takeover()
 
     fig = plt.figure()
@@ -426,11 +461,12 @@ def plotly_takeover(**kwargs):
     plt.plot(x, y, "o")
     fig
     ```
-    '''
+    """
     if not __PLOTLY_OFFLINE_INITIALIZED:
         init_notebook_mode()
     ip = IPython.core.getipython.get_ipython()
     formatter = ip.display_formatter.formatters['text/html']
     formatter.for_type(matplotlib.figure.Figure,
-                       lambda fig, kwds=kwargs: iplot_mpl(fig, **kwds))
+                       lambda fig: iplot_mpl(fig, resize, strip_style, verbose,
+                                             show_link, link_text, validate))
 
