Chris' comments sans tests

Author: Kully

plotly/plotly/__init__.py

@@ -23,5 +23,6 @@
     file_ops,
     get_config,
     get_grid,
-    create_animations
+    create_animations,
+    icreate_animations
 )

plotly/plotly/plotly.py

@@ -1493,40 +1493,153 @@ def get_grid(grid_url, raw=False):
         return json_res
 
 
-def create_animations(figure, filename=None, sharing='public'):
+def create_animations(figure, filename=None, sharing='public', auto_open=True):
     """
-    Put description here.
+    BETA function that creates plots with animations via `frames`.
+
+    Creates an animated plot using 'frames' alongside 'data' and 'layout'.
+    This BETA endpoint is subject to deprecation in the future. In relation
+    to `plotly.plotly.plot`, folder-creation and overwriting are not supported
+    but creating a plot with or without animations via frames is supported.
+
+    :param (str) filename: if set to 'None', an automatically generated plot
+        name will be created. Does not support folder creation, meaning that
+        a folder of the form 'folder/name' will NOT create a the folder and
+        place the plot in it.
+    :param (str) sharing: see `plotly.plotly.plot()` doc string.
+    :param (bool) auto_open: if True, opens plot in the browser. If False,
+        returns the url for the plot instead.
+
+    Example 1: Simple Animation
+    ```
+    import plotly.plotly as py
+    from plotly.grid_objs import Grid, Column
+
+    column_1 = Column([1, 2, 3], 'x')
+    column_2 = Column([1, 3, 6], 'y')
+    column_3 = Column([2, 4, 6], 'new x')
+    column_4 = Column([1, 1, 5], 'new y')
+    grid = Grid([column_1, column_2, column_3, column_4])
+    py.grid_ops.upload(grid, 'animations_grid', auto_open=False)
+
+    # create figure
+    figure = {
+        'data': [
+            {
+                'xsrc': grid.get_fid_uid('x'),
+                'ysrc': grid.get_fid_uid('y')
+            }
+        ],
+        'layout': {'title': 'First Title'},
+        'frames': [
+            {
+                'data': [
+                    {
+                        'xsrc': grid.get_fid_uid('new x'),
+                        'ysrc': grid.get_fid_uid('new y')
+                    }
+                ],
+                'layout': {'title': 'Second Title'}
+            }
+        ]
+    }
 
-    For parameter descriptions, see the doc string for `py.plot()`.
-    `private` is not supported currently for param 'sharing'. Returns the
-    url for the plot if response is ok.
+    py.create_animations(figure, 'new_plot_with_animations')
+    ```
     """
     credentials = get_credentials()
     validate_credentials(credentials)
     username, api_key = credentials['username'], credentials['api_key']
     auth = HTTPBasicAuth(str(username), str(api_key))
-    headers = {'Plotly-Client-Platform': 'python'}
+    headers = {'Plotly-Client-Platform': 'python',
+               'content-type': 'application/json'}
 
     json = {
         'figure': figure,
-        'world_readable': 'true'
+        'world_readable': True
     }
 
     # set filename if specified
     if filename:
+        # warn user that creating folders isn't support in this version
+        if '/' in filename:
+            warnings.warn(
+                "This BETA version of 'create_animations' does not support "
+                "automatic folder creation. This means a filename of the form "
+                "'name1/name2' will just create the plot with that name only."
+            )
         json['filename'] = filename
 
     # set sharing
     if sharing == 'public':
-        json['world_readable'] = 'true'
+        json['world_readable'] = True
     elif sharing == 'private':
-        json['world_readable'] = 'false'
+        json['world_readable'] = False
+    elif sharing == 'secret':
+        json['world_readable'] = False
+        json['share_key_enabled'] = True
+    else:
+        raise exceptions.PlotlyError(
+            "Whoops, sharing can only be set to either 'public', 'private', "
+            "or 'secret'."
+        )
 
     api_url = _api_v2.api_url('plots')
     r = requests.post(api_url, auth=auth, headers=headers, json=json)
+    r.raise_for_status()
+
+    try:
+        parsed_response = r.json()
+    except:
+        parsed_response = r.content
+
+    if 'error' in r and r['error'] != '':
+        raise exceptions.PlotlyError(r['message'])
 
-    json_r = json.loads(r.text)
-    return json_r['file']['web_url']
+    if sharing == 'secret':
+        web_url = (parsed_response['file']['web_url'][:-1] +
+                   '?share_key=' + parsed_response['file']['share_key'])
+    else:
+        web_url = parsed_response['file']['web_url']
+
+    if auto_open:
+        _open_url(web_url)
+
+    return web_url
+
+
+def icreate_animations(figure, filename=None, sharing='public', auto_open=False):
+    """
+    Create a unique url for this animated plot in Plotly and open in IPython.
+
+    This function is based off `plotly.plotly.iplot`. See `plotly.plotly.
+    create_animations` Doc String for param descriptions.
+    """
+    url = create_animations(figure, filename, sharing, auto_open)
+
+    if isinstance(figure, dict):
+        layout = figure.get('layout', {})
+    else:
+        layout = {}
+
+    embed_options = dict()
+    embed_options['width'] = layout.get('width', '100%')
+    embed_options['height'] = layout.get('height', 525)
+    try:
+        float(embed_options['width'])
+    except (ValueError, TypeError):
+        pass
+    else:
+        embed_options['width'] = str(embed_options['width']) + 'px'
+
+    try:
+        float(embed_options['height'])
+    except (ValueError, TypeError):
+        pass
+    else:
+        embed_options['height'] = str(embed_options['height']) + 'px'
+
+    return tools.embed(url, **embed_options)
 
 
 def _open_url(url):