Merge pull request #739 from plotly/presentations-wrapper

Presentations wrapper

Author: Kully

CHANGELOG.md

@@ -2,6 +2,10 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.2.0] - 2017-10-20
+### Added
+- NEW Presentations API for Python! Run `help(plotly.presentation_objs.Presentations)` for help or check out the new [documentation](https://plot.ly/python/presentations-api/)
+
 ## [2.1.0] - 2017-10-10
 ### Updated
 - Updated `plotly.min.js` to version 1.31.0.

plotly/api/v2/__init__.py

@@ -1,4 +1,5 @@
 from __future__ import absolute_import
 
 from plotly.api.v2 import (dash_apps, dashboards, files, folders, grids,
-                           images, plot_schema, plots, users)
+                           images, plot_schema, plots, spectacle_presentations,
+                           users)

plotly/api/v2/spectacle_presentations.py

@@ -0,0 +1,32 @@
+"""
+Interface to Plotly's /v2/spectacle-presentations endpoint.
+"""
+from __future__ import absolute_import
+
+from plotly.api.v2.utils import build_url, request
+
+RESOURCE = 'spectacle-presentations'
+
+
+def create(body):
+    """Create a presentation."""
+    url = build_url(RESOURCE)
+    return request('post', url, json=body)
+
+
+def list():
+    """Returns the list of all users' presentations."""
+    url = build_url(RESOURCE)
+    return request('get', url)
+
+
+def retrieve(fid):
+    """Retrieve a presentation from Plotly."""
+    url = build_url(RESOURCE, id=fid)
+    return request('get', url)
+
+
+def update(fid, content):
+    """Completely update the writable."""
+    url = build_url(RESOURCE, id=fid)
+    return request('put', url, json=content)

plotly/figure_factory/_scatterplot.py

@@ -1,6 +1,6 @@
 from __future__ import absolute_import
 
-from plotly import exceptions, optional_imports
+from plotly import colors, exceptions, optional_imports
 from plotly.figure_factory import utils
 from plotly.graph_objs import graph_objs
 from plotly.tools import make_subplots
@@ -386,9 +386,9 @@ def scatterplot_theme(dataframe, headers, diag, size, height, width, title,
 
         # Convert colormap to list of n RGB tuples
         if colormap_type == 'seq':
-            foo = utils.color_parser(colormap, utils.unlabel_rgb)
+            foo = colors.color_parser(colormap, colors.unlabel_rgb)
             foo = utils.n_colors(foo[0], foo[1], n_colors_len)
-            theme = utils.color_parser(foo, utils.label_rgb)
+            theme = colors.color_parser(foo, colors.label_rgb)
 
         if colormap_type == 'cat':
             # leave list of colors the same way
@@ -556,9 +556,9 @@ def scatterplot_theme(dataframe, headers, diag, size, height, width, title,
 
             # Convert colormap to list of n RGB tuples
             if colormap_type == 'seq':
-                foo = utils.color_parser(colormap, utils.unlabel_rgb)
+                foo = colors.color_parser(colormap, colors.unlabel_rgb)
                 foo = utils.n_colors(foo[0], foo[1], len(intervals))
-                theme = utils.color_parser(foo, utils.label_rgb)
+                theme = colors.color_parser(foo, colors.label_rgb)
 
             if colormap_type == 'cat':
                 # leave list of colors the same way

plotly/package_data/default-schema.json

@@ -35081,6 +35081,7 @@
                             "role": "info",
                             "valType": "string"
                         },
+                        "description": "",
                         "editType": "calc",
                         "family": {
                             "arrayOk": true,
@@ -35101,6 +35102,7 @@
                         "size": {
                             "arrayOk": true,
                             "editType": "calc",
+                            "min": 1,
                             "role": "style",
                             "valType": "number"
                         },
@@ -35134,6 +35136,7 @@
                     "line": {
                         "color": {
                             "arrayOk": true,
+                            "dflt": "grey",
                             "editType": "calc",
                             "role": "style",
                             "valType": "color"
@@ -35148,6 +35151,7 @@
                         "role": "object",
                         "width": {
                             "arrayOk": true,
+                            "dflt": 1,
                             "editType": "calc",
                             "role": "style",
                             "valType": "number"
@@ -35216,7 +35220,7 @@
                 },
                 "columnwidth": {
                     "arrayOk": true,
-                    "description": "The width of cells.",
+                    "description": "The width of columns expressed as a ratio. Columns fill the available width in proportion of their specified column widths.",
                     "dflt": null,
                     "editType": "calc",
                     "role": "style",
@@ -35345,6 +35349,7 @@
                             "role": "info",
                             "valType": "string"
                         },
+                        "description": "",
                         "editType": "calc",
                         "family": {
                             "arrayOk": true,
@@ -35365,6 +35370,7 @@
                         "size": {
                             "arrayOk": true,
                             "editType": "calc",
+                            "min": 1,
                             "role": "style",
                             "valType": "number"
                         },
@@ -35398,6 +35404,7 @@
                     "line": {
                         "color": {
                             "arrayOk": true,
+                            "dflt": "grey",
                             "editType": "calc",
                             "role": "style",
                             "valType": "color"
@@ -35412,6 +35419,7 @@
                         "role": "object",
                         "width": {
                             "arrayOk": true,
+                            "dflt": 1,
                             "editType": "calc",
                             "role": "style",
                             "valType": "number"

plotly/plotly/__init__.py

@@ -24,6 +24,7 @@
     get_config,
     get_grid,
     dashboard_ops,
+    presentation_ops,
     create_animations,
     icreate_animations
 )

plotly/plotly/plotly.py

@@ -47,6 +47,11 @@
     'sharing': files.FILE_CONTENT[files.CONFIG_FILE]['sharing']
 }
 
+SHARING_ERROR_MSG = (
+    "Whoops, sharing can only be set to either 'public', 'private', or "
+    "'secret'."
+)
+
 # test file permissions and make sure nothing is corrupted
 tools.ensure_local_plotly_files()
 
@@ -1520,6 +1525,81 @@ def get_dashboard_names(cls):
         return [str(dboard['filename']) for dboard in dashboards]
 
 
+class presentation_ops:
+    """
+    Interface to Plotly's Spectacle-Presentations API.
+    """
+    @classmethod
+    def upload(cls, presentation, filename, sharing='public', auto_open=True):
+        """
+        Function for uploading presentations to Plotly.
+
+        :param (dict) presentation: the JSON presentation to be uploaded. Use
+            plotly.presentation_objs.Presentation to create presentations
+            from a Markdown-like string.
+        :param (str) filename: the name of the presentation to be saved in
+            your Plotly account. Will overwrite a presentation of the same
+            name if it already exists in your files.
+        :param (str) sharing: can be set to either 'public', 'private'
+            or 'secret'. If 'public', your presentation will be viewable by
+            all other users. If 'private' only you can see your presentation.
+            If it is set to 'secret', the url will be returned with a string
+            of random characters appended to the url which is called a
+            sharekey. The point of a sharekey is that it makes the url very
+            hard to guess, but anyone with the url can view the presentation.
+        :param (bool) auto_open: automatically opens the presentation in the
+            browser.
+
+        See the documentation online for examples.
+        """
+        if sharing == 'public':
+            world_readable = True
+        elif sharing in ['private', 'secret']:
+            world_readable = False
+        else:
+            raise exceptions.PlotlyError(
+                SHARING_ERROR_MSG
+            )
+        data = {
+            'content': json.dumps(presentation),
+            'filename': filename,
+            'world_readable': world_readable
+        }
+
+        # lookup if pre-existing filename already exists
+        try:
+            lookup_res = v2.files.lookup(filename)
+            lookup_res.raise_for_status()
+            matching_file = json.loads(lookup_res.content)
+
+            if matching_file['filetype'] != 'spectacle_presentation':
+                raise exceptions.PlotlyError(
+                    "'{filename}' is already a {filetype} in your account. "
+                    "You can't overwrite a file that is not a spectacle_"
+                    "presentation. Please pick another filename.".format(
+                        filename=filename,
+                        filetype=matching_file['filetype']
+                    )
+                )
+            else:
+                old_fid = matching_file['fid']
+                res = v2.spectacle_presentations.update(old_fid, data)
+
+        except exceptions.PlotlyRequestError:
+            res = v2.spectacle_presentations.create(data)
+        res.raise_for_status()
+
+        url = res.json()['web_url']
+
+        if sharing == 'secret':
+            url = add_share_key_to_url(url)
+
+        if auto_open:
+            webbrowser.open_new(res.json()['web_url'])
+
+        return url
+
+
 def create_animations(figure, filename=None, sharing='public', auto_open=True):
     """
     BETA function that creates plots with animations via `frames`.
@@ -1712,8 +1792,7 @@ def create_animations(figure, filename=None, sharing='public', auto_open=True):
         body['share_key_enabled'] = True
     else:
         raise exceptions.PlotlyError(
-            "Whoops, sharing can only be set to either 'public', 'private', "
-            "or 'secret'."
+            SHARING_ERROR_MSG
         )
 
     response = v2.plots.create(body)

plotly/presentation_objs/__init__.py

@@ -0,0 +1,8 @@
+"""
+presentation_objs
+
+A wrapper for the spectacle-presentations endpoint.
+===========
+
+"""
+from . presentation_objs import Presentation