Create organized api modules 🎉!

This was driving me nuts. We basically manually handle creating and
validating *each* api response inside each calling function. Even worse,
we *sometimes* raise a `PlotlyRequestError` and *sometimes* just bubble
up the `requests.exceptions.HTTPError` ;__;.

This does the following:

* Define an `api.v1` module that only includes `clientresp` (the only old
api method we still *need* to cling to)
* Define an `api.v2` module that includes all the new functionality of
our v2 api.
* Both `v1` and `v2` raise the same `PlotlyRequestError`, so that users
only need to catch *one* exception class in scripts.

Author: theengineear

plotly/api/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import absolute_import
+
+from plotly.api.v1.clientresp import clientresp

plotly/api/v1/__init__.py

@@ -0,0 +1,42 @@
+"""Interface to deprecated /clientresp API. Subject to deletion."""
+from __future__ import absolute_import
+
+import json
+import warnings
+
+from plotly import config, utils, version
+from plotly.api.v1.utils import request
+
+
+def clientresp(data, **kwargs):
+    """
+    Deprecated endpoint, still used because it can parse data out of a plot.
+
+    When we get around to forcing users to create grids and then create plots,
+    we can finally get rid of this.
+
+    :param (list) data: The data array from a figure.
+
+    """
+    creds = config.get_credentials()
+    cfg = config.get_config()
+
+    payload = {
+        'platform': 'python', 'version': version.__version__,
+        'args': json.dumps(data, cls=utils.PlotlyJSONEncoder),
+        'un': creds['username'], 'key': creds['api_key'], 'origin': 'plot',
+        'kwargs': json.dumps(kwargs, cls=utils.PlotlyJSONEncoder)
+    }
+
+    url = '{plotly_domain}/clientresp'.format(**cfg)
+    response = request('post', url, data=payload,
+                       verify=cfg['plotly_ssl_verification'])
+
+    # Old functionality, just keeping it around.
+    parsed_content = response.json()
+    if parsed_content.get('warning'):
+        warnings.warn(parsed_content['warning'])
+    if parsed_content.get('message'):
+        print(parsed_content['message'])
+
+    return response

plotly/api/v1/clientresp.py

@@ -0,0 +1,51 @@
+from __future__ import absolute_import
+
+import requests
+
+from plotly import exceptions
+
+
+def validate_response(response):
+    """
+    Raise a helpful PlotlyRequestError for failed requests.
+
+    :param (requests.Response) response: A Response object from an api request.
+    :raises: (PlotlyRequestError) If the request failed for any reason.
+    :returns: (None)
+
+    """
+    if response.ok:
+        return
+
+    content = response.content
+    status_code = response.status_code
+    try:
+        parsed_content = response.json()
+    except ValueError:
+        message = content if content else 'No Content'
+        raise exceptions.PlotlyRequestError(message, status_code, content)
+
+    message = ''
+    if isinstance(parsed_content, dict):
+        error = parsed_content.get('error')
+        if error:
+            message = error
+    if not message:
+        message = content if content else 'No Content'
+
+    raise exceptions.PlotlyRequestError(message, status_code, content)
+
+
+def request(method, url, **kwargs):
+    """
+    Central place to make any api request.
+
+    :param (str) method: The request method ('get', 'put', 'delete', ...).
+    :param (str) url: The full api url to make the request to.
+    :param kwargs: These are passed along to requests.
+    :return: (requests.Response) The response directly from requests.
+
+    """
+    response = requests.request(method, url, **kwargs)
+    validate_response(response)
+    return response

plotly/api/v1/utils.py

@@ -0,0 +1,3 @@
+from __future__ import absolute_import
+
+from plotly.api.v2 import files, folders, grids, images, plots

plotly/api/v2/__init__.py

@@ -0,0 +1,85 @@
+"""Interface to Plotly's /v2/files endpoints."""
+from __future__ import absolute_import
+
+from plotly.api.v2.utils import build_url, make_params, request
+
+RESOURCE = 'files'
+
+
+def retrieve(fid, share_key=None):
+    """
+    Retrieve a general file from Plotly.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :param (str) share_key: The secret key granting 'read' access if private.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid)
+    params = make_params(share_key=share_key)
+    return request('get', url, params=params)
+
+
+def update(fid, body):
+    """
+    Update a general file from Plotly.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :param (dict) body: A mapping of body param names to values.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid)
+    return request('put', url, json=body)
+
+
+def trash(fid):
+    """
+    Soft-delete a general file from Plotly. (Can be undone with 'restore').
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid, route='trash')
+    return request('post', url)
+
+
+def restore(fid):
+    """
+    Restore a trashed, general file from Plotly. See 'trash'.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid, route='restore')
+    return request('post', url)
+
+
+def permanent_delete(fid):
+    """
+    Permanently delete a trashed, general file from Plotly. See 'trash'.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid, route='permanent_delete')
+    return request('delete', url)
+
+
+def lookup(path, parent=None, user=None, exists=None):
+    """
+    Retrieve a general file from Plotly without needing a fid.
+
+    :param (str) path: The '/'-delimited path specifying the file location.
+    :param (int) parent: Parent id, an integer, which the path is relative to.
+    :param (str) user: The username to target files for. Defaults to requestor.
+    :param (bool) exists: If True, don't return the full file, just a flag.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, route='lookup')
+    params = make_params(path=path, parent=parent, user=user, exists=exists)
+    return request('get', url, params=params)

plotly/api/v2/files.py

@@ -0,0 +1,87 @@
+"""Interface to Plotly's /v2/folders endpoints."""
+from __future__ import absolute_import
+
+from plotly.api.v2.utils import build_url, make_params, request
+
+RESOURCE = 'folders'
+
+
+def create(body):
+    """
+    Create a new folder.
+
+    :param (dict) body: A mapping of body param names to values.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE)
+    return request('post', url, json=body)
+
+
+def retrieve(fid, share_key=None):
+    """
+    Retrieve a folder from Plotly.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :param (str) share_key: The secret key granting 'read' access if private.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid)
+    params = make_params(share_key=share_key)
+    return request('get', url, params=params)
+
+
+def update(fid, body):
+    """
+    Update a folder from Plotly.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :param (dict) body: A mapping of body param names to values.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid)
+    return request('put', url, json=body)
+
+
+def trash(fid):
+    """
+    Soft-delete a folder from Plotly. (Can be undone with 'restore').
+
+    This action is recursively done on files inside the folder.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid, route='trash')
+    return request('post', url)
+
+
+def restore(fid):
+    """
+    Restore a trashed folder from Plotly. See 'trash'.
+
+    This action is recursively done on files inside the folder.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid, route='restore')
+    return request('post', url)
+
+
+def permanent_delete(fid):
+    """
+    Permanently delete a trashed folder file from Plotly. See 'trash'.
+
+    This action is recursively done on files inside the folder.
+
+    :param (str) fid: The `{username}:{idlocal}` identifier. E.g. `foo:88`.
+    :returns: (requests.Response) Returns response directly from requests.
+
+    """
+    url = build_url(RESOURCE, id=fid, route='permanent_delete')
+    return request('delete', url)