Merge pull request plotly#128 from plotly/grid_api

grid api

Author: chriddyp

gridspec.md

@@ -0,0 +1,255 @@
+### Creating a grid with `grid_objs`
+
+```python
+from plotly.grid_objs import Column, Grid
+
+column_1 = Column([1, 2, 3], 'column 1')
+
+column_2 = Column(['a', 'b', datetime.datetime.now()], 'column 2')
+
+grid = Grid(column_1, column_2)
+
+unique_url = py.grid_ops.upload(grid, filename, world_readable=True)
+```
+
+### Updating grids
+
+Grids are identified with either `grid` or `grid_url`, or `filename`
+`filename` will be unsupported in this version
+```python
+
+rows = [[1, 'a'], [2, 'b']]
+
+grid = Grid(c1, c2)
+
+py.grid_ops.upload(grid, 'my file')
+
+# We recommend this call signature, since `row` gets appended to the grid
+py.grid_ops.append_rows(rows, grid=grid)
+
+# But, these all do the same thing
+py.grid_ops.append_rows(rows, grid_url="https://plot.ly/~chris/3") #shortcut
+py.grid_ops.append_rows(rows, filename='my file') # currently unsupported.
+                                            # will do a get request behind
+                                            # the scenes to get the grid_id
+```
+
+Similarly for appending columns:
+```python
+from plotly.grid_objs import Column
+
+new_col = Column([1,2,3], 'new col name')
+
+# these are equivalent
+py.grid_ops.append_columns([new_col], grid_url='https://plot.ly/~chris/3')
+py.grid_ops.append_columns([new_col], filename='my file') # Currently unsupported
+
+# this, too:
+grid = Grid(Column([1,2,3], 'first column name'))
+py.grid_ops.upload(grid, 'my file')
+
+py.grid_ops.append_columns([new_col], grid=grid) # also implicitly adds new_col to grid
+
+grid[0].name # 'first column name'
+grid[1].name # 'new col name'
+```
+
+
+### On overwriting and duplicate file names and deletion
+
+Overwriting currently isn't possible. For now,
+```python
+>> py.grid_ops.upload(grid, 'my grid')
+"PlotlyFileException: Yikes, a file already exists with this filename."
+"You can delete that file with:"
+"> py.grid_ops.delete('my grid')"
+"Warning: If any graphs were made from this grid, the data in those graphs"
+"will also be lost. If you make a new grid after you delete with the same filename, "
+"the new grid's URL will also be different."
+"That's confusing and you're probably not having a good time.""
+"Questions? [email protected]"
+```
+
+In the near future:
+```python
+# Updates the data, but not the column ids, of the grid. Referenced plots don't break.
+# Behind the scenes, this:
+# 1 - Makes a `GET` request to retrieve a {column_name: column_id} hash
+# 2 - Makes a `PUT` request to update the data of the columns
+>> py.grid_ops.upload('my grid') # overwrite defaults to True
+
+# Or, recieve an exception with:
+>> py.grid_ops.upload(grid, 'my grid', overwrite=False)
+"PLotlyFileException: Yikes! ..."
+```
+
+Deleting:
+
+```
+# throw good errors if none or more than 1 were specified
+py.grid_ops.delete(filename=None, grid_url=None, grid=None, grid_id=None)
+```
+
+In the future, once we can delete Plots and Folders
+
+```
+py.file_ops.delete(file_path=None, fid=None, url=None)
+```
+
+
+### Appearance and Access
+
+```python
+>> print Column([1,2,3], 'column 1')
+<Column "column 1": [1, 2, 3]>
+```
+
+```python
+>> print Grid(col1, col2)
+<Grid: [<Column "column 1": [1, 2, 3]>, <Column "column 2": ["a", "b", "c"]>]>
+```
+
+```python
+>> grid = Grid(col1, col2)
+>> print grid[0]
+<Column "column 1": [1, 2, 3]>
+```
+
+```python
+>> grid = Grid(col1, col2)
+>> print grid.get_column('column 1')
+<Column "column 1": [1, 2, 3]>
+```
+
+### Creating a graph from a grid
+
+If you have the grid
+```python
+>> from plotly.grid_objs import Grid
+>> grid = Grid(column_1, column_2)
+>> grid.upload(grid, 'experimental data')
+
+>> fig_data = [Scatter(xsrc=grid[0], ysrc=grid[0])]
+>> print Scatter(xsrc=grid[0], ysrc=grid[1])
+[{"xsrc": "chris/8:3dkb", "ysrc": "chris/8:cbk8", "type": "scatter"}]
+>> py.plot(fig_data)
+
+>> Scatter(x=[1,2,3], y=[2,1,2])
+"High five!"
+>> Scatter(xsrc=[1,2,3], ysrc=[2,1,2])
+"PlotlyTypeException: xrc and ysrc must be type string or plotly.grid_obj.Column"
+>> Scatter(xsrc=Column('myCol', [1,2,3]), ysrc=Column('otherCol', [2,1,2]))
+"PlotlyFileException: you must upload a grid before you can reference it in plots"
+>> Scatter(xsrc=localGrid[0], ysrc=localGrid[1])
+"PlotlyFileException: you must upload a grid before you can reference it in plots"
+>>  Scatter(x=grid[0], y=grid[1])
+"PlotlyTypeException: Yikes, column objects aren't currently supported here."
+"x must be an array of strings, numbers, or datetimes."
+>> print Scatter(xsrc=grid[0], yscr=grid[1])
+{"xsrc": "chris/3:3dfbk", "ysrc": "chris/3:dk3c"}
+```
+
+Otherwise, download the grid (Not currently supported)
+```
+>> grid = grid_ops.get(filename=None, grid_id=None, grid_url=None)
+```
+
+(Download should use same endpoint as `grid_url.json`, e.g. [https://plot.ly/~chris/142.json](https://plot.ly/~chris/142.json))
+
+### Errors
+```python
+>> grid = Grid(column_1, column_2)
+>> trace = Scatter(x=grid[0], y=grid[1])
+"PlotlyGridException: Grid must be uploaded to Plotly before figures can be created."
+"Call `py.grid_ops.upload(grid)`"
+```
+
+```python
+>> col1 = Column([], 'my column name')
+>> col2 = Column([], 'my column name')
+>> Grid(col1, col2)
+"PlotlyGridException: Grid can't have duplicate column names"
+```
+
+```python
+>> py.grid_ops.append_row(Row({'column 1': 1}), grid=grid)
+"PlotlyGridException: Missing column entries, partial row update is not supported."
+"Supply data for 'column 2' and try again."
+```
+
+Type checking boiler plate
+```python
+>> Column({'a': 'b'}, 'col1')
+"PlotlyColumnException: Data argument must be an array of numbers, strings, Nones, or datetimes"
+```
+
+```python
+>> Column([{'a': 'b'}], 'col1')
+"PlotlyColumnException: Data values must be an array string, a number, Nones, or a datetime"
+```
+
+### Exceptions from Requests
+A `PlotlyRequestError` that prints a useful error message from the server:
+1. Print `response.detail` if provided (Plotly error message)
+2. Otherwise, print `response.body` if the response is plain-text
+3. Otherwise, print the original `requests.expceptions.HTTPError` error message.
+
+Also, store the status code.
+
+
+### Adding metadata to grids
+
+```python
+c1 = Column('first column', [1, 2, 3, 4])
+grid = Grid([c1])
+meta = {"settings":{"scope1":{"model":"Unicorn Finder","voltage":4}}}
+py.grid_ops.upload(
+    grid,
+    unique_filename,
+    meta=meta,
+    auto_open=False)
+```
+
+```python
+# First, create a grid
+c1 = Column('first column', [1, 2, 3, 4])
+grid = Grid([c1])
+grid_url = py.grid_ops.upload(grid, unique_filename, auto_open=False)
+
+# Add some meta data to that grid
+meta = {"settings": {"scope1": {"model": "Unicorn Finder", "voltage": 4}}}
+meta_url = py.meta_ops.upload(
+    meta,
+    grid_url=grid_url)
+```
+
+### Plotly File system
+
+```python
+
+>> py.file_ops.mkdirs('new folder in root')
+
+>> py.file_ops.mkdirs('make/each/of/these/folders')
+```
+
+Note that this is like `mkdir -p`. `mkdirs` is a Java convention.
+We could also use our own, like:
+
+- `py.file_ops.create_folders('new/folders')`
+- `py.file_ops.new_folders('new/folders')`
+
+These commands will:
+- return status codes: `200` if nothing created, `201` if created
+- raise exception if a file or folder already exists with that path
+
+
+In the future, once we can delete Plots and Folders
+
+```
+py.file_ops.delete(file_path=None, fid=None, url=None)
+```
+
+Or, if we want to keep unix convention (do we?)
+```
+py.file_ops.rm(file_path=None, fid=None, url=None)
+```

plotly/__init__.py

@@ -28,5 +28,5 @@
 
 from __future__ import absolute_import
 
-from plotly import plotly, graph_objs, tools, utils
+from plotly import plotly, graph_objs, grid_objs, tools, utils
 from plotly.version import __version__

plotly/exceptions.py

@@ -15,14 +15,59 @@
 
 
 """
-
+import json
 
 ## Base Plotly Error ##
 
 class PlotlyError(Exception):
     pass
 
 
+
+class InputError(PlotlyError):
+    pass
+
+
+class PlotlyRequestError(PlotlyError):
+    def __init__(self, requests_exception):
+        self.status_code = requests_exception.response.status_code
+        self.HTTPError = requests_exception
+        content_type = requests_exception.response.headers['content-type']
+        if 'json' in content_type:
+            content = requests_exception.response.content
+            if content != '':
+                res_payload = json.loads(requests_exception.response.content)
+                if 'detail' in res_payload:
+                    self.message = res_payload['detail']
+                else:
+                    self.message = ''
+            else:
+                self.message = ''
+        elif content_type == 'text/plain':
+            self.message = requests_exception.response.content
+        else:
+            self.message = requests_exception.message
+
+    def __str__(self):
+        return self.message
+
+
+## Grid Errors ##
+
+COLUMN_NOT_YET_UPLOADED_MESSAGE = (
+    "Hm... it looks like your column '{column_name}' hasn't "
+    "been uploaded to Plotly yet. You need to upload your "
+    "column to Plotly before you can assign it to '{reference}'.\n"
+    "To upload, try `plotly.plotly.grid_objs.upload` or "
+    "`plotly.plotly.grid_objs.append_column`.\n"
+    "Questions? [email protected]"
+)
+
+NON_UNIQUE_COLUMN_MESSAGE = (
+    "Yikes, plotly grids currently "
+    "can't have duplicate column names. Rename "
+    "the column \"{}\" and try again."
+)
 ## Would Cause Server Errors ##
 
 class PlotlyEmptyDataError(PlotlyError):

plotly/graph_objs/graph_objs.py

@@ -30,8 +30,11 @@
 from plotly.graph_objs.graph_objs_tools import (
     INFO, OBJ_MAP, NAME_TO_KEY, KEY_TO_NAME
 )
-import copy
+
 from plotly import exceptions
+from plotly import utils
+
+import copy
 import sys
 if sys.version[:3] == '2.6':
     from ordereddict import OrderedDict
@@ -297,6 +300,11 @@ class PlotlyDict(dict):
 
     def __init__(self, *args, **kwargs):
         class_name = self.__class__.__name__
+
+        for key in kwargs:
+            if utils.is_source_key(key):
+                kwargs[key] = self._assign_id_to_src(key, kwargs[key])
+
         super(PlotlyDict, self).__init__(*args, **kwargs)
         if issubclass(NAME_TO_CLASS[class_name], PlotlyTrace):
             if (class_name != 'PlotlyTrace') and (class_name != 'Trace'):
@@ -307,6 +315,37 @@ def __init__(self, *args, **kwargs):
                           "dictionary-like graph_objs.\nIt is not meant to be "
                           "a user interface.")
 
+    def __setitem__(self, key, value):
+
+        if key in ('xsrc', 'ysrc'):
+            value = self._assign_id_to_src(key, value)
+
+        return super(PlotlyDict, self).__setitem__(key, value)
+
+    def _assign_id_to_src(self, src_name, src_value):
+        if isinstance(src_value, basestring):
+            src_id = src_value
+        else:
+            try:
+                src_id = src_value.id
+            except:
+                err = ("{} does not have an `id` property. "
+                       "{} needs to be assigned to either an "
+                       "object with an `id` (like a "
+                       "plotly.grid_objs.Column) or a string. "
+                       "The `id` is a unique identifier "
+                       "assigned by the Plotly webserver "
+                       "to this grid column.")
+                src_value_str = str(src_value)
+                err = err.format(src_name, src_value_str)
+                raise exceptions.InputError(err)
+
+        if src_id == '':
+            err = exceptions.COLUMN_NOT_YET_UPLOADED_MESSAGE
+            err.format(column_name=src_value.name, reference=src_name)
+            raise exceptions.InputError(err)
+        return src_id
+
     def update(self, dict1=None, **dict2):
         """Update current dict with dict1 and then dict2.
 

plotly/grid_objs/__init__.py

@@ -0,0 +1,8 @@
+""""
+grid_objs
+=========
+
+"""
+
+
+from . grid_objs import Grid, Column