From 43a519dc1c367203c29499cf0a16d1b1f8d0fe52 Mon Sep 17 00:00:00 2001
From: etpinard <etienne.t.pinard@gmail.com>
Date: Thu, 26 Jun 2014 12:02:00 -0400
Subject: [PATCH 1/2] URL support fot get_embed()

I added URL support for plotly.tools.get_embed() and plotly.tools.embed()
so that

plotly.tools.get_embed('https://plot.ly/~etpinard/270/')

and

plotly.tools.get_embed('etpinard','270')

are both accepted.

I also corrected a few typos in docstring for plotly.plotly.get_figure()
---
 plotly/plotly/plotly.py |  4 +-
 plotly/tools.py         | 87 +++++++++++++++++++++++++++++++++++++----
 2 files changed, 82 insertions(+), 9 deletions(-)

diff --git a/plotly/plotly/plotly.py b/plotly/plotly/plotly.py
index eb4a56a30e..bc98f14497 100644
--- a/plotly/plotly/plotly.py
+++ b/plotly/plotly/plotly.py
@@ -279,7 +279,7 @@ def get_figure(file_owner_or_url, file_id=None, raw=False):
     pass a valid plotly url as the first argument.
 
     Note, if you're using a file_owner string as the first argument, you MUST
-    specity a `file_id` keyword argument. Else, if you're using a url string
+    specify a `file_id` keyword argument. Else, if you're using a url string
     as the first argument, you MUST NOT specify a `file_id` keyword argument, or
     file_id must be set to Python's None value.
 
@@ -287,7 +287,7 @@ def get_figure(file_owner_or_url, file_id=None, raw=False):
     file_owner_or_url (string) -- a valid plotly username OR a valid plotly url
 
     Keyword arguments:
-    file_id (defualt=None) -- an int or string that can be converted to int
+    file_id (default=None) -- an int or string that can be converted to int
                               if you're using a url, don't fill this in!
     raw (default=False) -- if true, return unicode JSON string verbatim**
 
diff --git a/plotly/tools.py b/plotly/tools.py
index 8de8aafe52..5ad87427e1 100644
--- a/plotly/tools.py
+++ b/plotly/tools.py
@@ -33,6 +33,8 @@
                  CONFIG_FILE: {'plotly_domain': u'https://plot.ly',
                                'plotly_streaming_domain': u'stream.plot.ly'}}
 
+_credentials = dict()
+
 try:
     os.mkdir(TEST_DIR)
     os.rmdir(TEST_DIR)
@@ -180,36 +182,107 @@ def reset_config_file():
 
 ### embed tools ###
 
-def get_embed(username, plot_id, width="100%", height=525):
+def get_embed(file_owner_or_url, file_id=None, width="100%", height=525):
+    """Returns HTML code to embed figure on a webpage as an <iframe>
+    
+    Plotly uniquely identifies figures with a 'file_owner'/'file_id' pair.
+    Since each file is given a corresponding unique url, you may also simply
+    pass a valid plotly url as the first argument.
+
+    Note, if you're using a file_owner string as the first argument, you MUST
+    specify a `file_id` keyword argument. Else, if you're using a url string
+    as the first argument, you MUST NOT specify a `file_id` keyword argument, or
+    file_id must be set to Python's None value.
+
+    Positional arguments:
+    file_owner_or_url (string) -- a valid plotly username OR a valid plotly url
+
+    Keyword arguments:
+    file_id (default=None) -- an int or string that can be converted to int
+                              if you're using a url, don't fill this in!
+    width (default="100%") -- an int or string corresp. to width of the figure
+    height (default="525") -- same as width but corresp. to the height of the figure
+
+    """
     padding = 25
     plotly_rest_url = get_config_file()['plotly_domain']
+    if file_id is None:  # assume we're using a url
+        url = file_owner_or_url
+        if url[:len(plotly_rest_url)] != plotly_rest_url:
+            raise exceptions.PlotlyError(
+                "Because you didn't supply a 'file_id' in the call, "
+                "we're assuming you're trying to snag a figure from a url. "
+                "You supplied the url, '{}', we expected it to start with '{}'."
+                "\nRun help on this function for more information."
+                "".format(url, plotly_rest_url))
+        head = plotly_rest_url + "/~"
+        file_owner = url.replace(head, "").split('/')[0]
+        file_id = url.replace(head, "").split('/')[1]
+    else:
+        file_owner = file_owner_or_url
+    resource = "/apigetfile/{file_owner}/{file_id}".format(file_owner=file_owner,
+                                                           file_id=file_id)
+    try:
+        test_if_int = int(file_id)
+    except ValueError:
+        raise exceptions.PlotlyError(
+            "The 'file_id' argument was not able to be converted into an "
+            "integer number. Make sure that the positional 'file_id' argument "
+            "is a number that can be converted into an integer or a string "
+            "that can be converted into an integer."
+        )
+    if int(file_id) < 0:
+        raise exceptions.PlotlyError(
+            "The 'file_id' argument must be a non-negative number."
+        )
     if isinstance(width, (int, long)):
         s = ("<iframe id=\"igraph\" scrolling=\"no\" style=\"border:none;\""
              "seamless=\"seamless\" "
              "src=\"{plotly_rest_url}/"
-             "~{username}/{plot_id}/{plot_width}/{plot_height}\" "
+             "~{file_owner}/{file_id}/{plot_width}/{plot_height}\" "
              "height=\"{iframe_height}\" width=\"{iframe_width}\">"
              "</iframe>").format(
             plotly_rest_url=plotly_rest_url,
-            username=username, plot_id=plot_id,
+            file_owner=file_owner, file_id=file_id,
             plot_width=width-padding, plot_height=height-padding,
             iframe_height=height, iframe_width=width)
     else:
         s = ("<iframe id=\"igraph\" scrolling=\"no\" style=\"border:none;\""
              "seamless=\"seamless\" "
              "src=\"{plotly_rest_url}/"
-             "~{username}/{plot_id}\" "
+             "~{file_owner}/{file_id}\" "
              "height=\"{iframe_height}\" width=\"{iframe_width}\">"
              "</iframe>").format(
             plotly_rest_url=plotly_rest_url,
-            username=username, plot_id=plot_id,
+            file_owner=file_owner, file_id=file_id,
             iframe_height=height, iframe_width=width)
 
     return s
 
 
-def embed(username, plot_id, width="100%", height=525):
-    s = get_embed(username, plot_id, width, height)
+def embed(file_owner_or_url, file_id=None, width="100%", height=525):
+    """Embeds existing Plotly figure in IPython Notebook
+    
+    Plotly uniquely identifies figures with a 'file_owner'/'file_id' pair.
+    Since each file is given a corresponding unique url, you may also simply
+    pass a valid plotly url as the first argument.
+
+    Note, if you're using a file_owner string as the first argument, you MUST
+    specify a `file_id` keyword argument. Else, if you're using a url string
+    as the first argument, you MUST NOT specify a `file_id` keyword argument, or
+    file_id must be set to Python's None value.
+
+    Positional arguments:
+    file_owner_or_url (string) -- a valid plotly username OR a valid plotly url
+
+    Keyword arguments:
+    file_id (default=None) -- an int or string that can be converted to int
+                              if you're using a url, don't fill this in!
+    width (default="100%") -- an int or string corresp. to width of the figure
+    height (default="525") -- same as width but corresp. to the height of the figure
+
+    """
+    s = get_embed(file_owner_or_url, file_id, width, height)
     try:
         # see if we are in the SageMath Cloud
         from sage_salvus import html

From 126e62c9f1dac5532b9033679714eed98813ac29 Mon Sep 17 00:00:00 2001
From: etpinard <etienne.t.pinard@gmail.com>
Date: Thu, 26 Jun 2014 12:16:12 -0400
Subject: [PATCH 2/2] useless line in tools.py removed

---
 plotly/tools.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/plotly/tools.py b/plotly/tools.py
index 5ad87427e1..4f51abc3bf 100644
--- a/plotly/tools.py
+++ b/plotly/tools.py
@@ -33,8 +33,6 @@
                  CONFIG_FILE: {'plotly_domain': u'https://plot.ly',
                                'plotly_streaming_domain': u'stream.plot.ly'}}
 
-_credentials = dict()
-
 try:
     os.mkdir(TEST_DIR)
     os.rmdir(TEST_DIR)