Add a get_plot_url_by_path beta function.

User request that’s pretty easy to shoot a tracer bullet out for.

We’ll probably want to make a full-on wrapper for the api, but this is
useful now and it’s being asked for.

Author: theengineear

plotly/plotly/__init__.py

@@ -21,5 +21,6 @@
     grid_ops,
     meta_ops,
     file_ops,
-    get_config
+    get_config,
+    get_plot_url_by_path
 )

plotly/plotly/plotly.py

@@ -1421,3 +1421,28 @@ def _open_url(url):
         wbopen(url)
     except:  # TODO: what should we except here? this is dangerous
         pass
+
+
+def get_plot_url_by_path(path, user=None, parent=None):
+    """
+    Get the share url of a plot based on the path of the file.
+
+    THIS FUNCTION IS IN BETA! It may change or move without warning.
+
+    :param (str) path: Partial file path (can just be the filename)
+    :param (str) user: The username of the plotly user who owns the file.
+    :param (int) parent: The id of the parent folder. E.g, home folder is `-1`.
+    :raises: (PlotlyError) If underlying api request fails.
+    :return: (str) The url for the plot. This can be passed to get_figure()
+
+    """
+    url = _api_v2.api_url('plots/lookup')
+    query_string = '?path={}'.format(path)
+    if user is not None:
+        query_string += '&user={}'.format(user)
+    if parent is not None:
+        query_string == '&parent={}'.format(parent)
+    headers = _api_v2.headers()
+    response = requests.get('{}{}'.format(url, query_string), headers=headers)
+    response_dict = _api_v2.response_handler(response)
+    return response_dict['web_url']