Download and cache plot schema (or always download if no file permissions).

make_instructions.txt

@@ -18,6 +18,8 @@ Available targets (i.e. $ make target):
 
     readme -> `less` this file
 
+    update_default_schema -> download the latest plot schema from plot.ly
+
     setup_subs -> delete old submodule locations, init, update, and sync new
 
     install -> 1. sync submodules 2. install plotly with setup.py

makefile

@@ -17,6 +17,15 @@ setup_subs :
 	git submodule update
 	make sync_subs
 
+update_default_schema :
+	@echo "Making sure the default-schema.json file is up to date"
+	python -c "import json;\
+               from plotly.graph_reference import GRAPH_REFERENCE;\
+               f = open('plotly/graph_reference/default-schema.json', 'w');\
+               json.dump(GRAPH_REFERENCE, f, indent=4, sort_keys=True,\
+                   separators=(',', ': '));\
+               f.close()"
+
 install : sync_subs
 	@echo ""
 	@echo "Installing Python API with make"

plotly/files.py

@@ -0,0 +1,39 @@
+import os
+
+# file structure
+PLOTLY_DIR = os.path.join(os.path.expanduser("~"), ".plotly")
+CREDENTIALS_FILE = os.path.join(PLOTLY_DIR, ".credentials")
+CONFIG_FILE = os.path.join(PLOTLY_DIR, ".config")
+GRAPH_REFERENCE_FILE = os.path.join(PLOTLY_DIR, ".graph_reference")
+TEST_DIR = os.path.join(os.path.expanduser("~"), ".test")
+TEST_FILE = os.path.join(PLOTLY_DIR, ".permission_test")
+
+# this sets both the DEFAULTS and the TYPES for these files
+FILE_CONTENT = {CREDENTIALS_FILE: {'username': '',
+                                   'api_key': '',
+                                   'proxy_username': '',
+                                   'proxy_password': '',
+                                   'stream_ids': []},
+                CONFIG_FILE: {'plotly_domain': 'https://plot.ly',
+                              'plotly_streaming_domain': 'stream.plot.ly',
+                              'plotly_api_domain': 'https://api.plot.ly',
+                              'plotly_ssl_verification': True,
+                              'plotly_proxy_authorization': False,
+                              'world_readable': True}}
+
+try:
+    os.mkdir(TEST_DIR)
+    os.rmdir(TEST_DIR)
+    if not os.path.exists(PLOTLY_DIR):
+        os.mkdir(PLOTLY_DIR)
+    f = open(TEST_FILE, 'w')
+    f.write('testing\n')
+    f.close()
+    os.remove(TEST_FILE)
+    _file_permissions = True
+except:
+    _file_permissions = False
+
+
+def check_file_permissions():
+    return _file_permissions

plotly/graph_reference.py

@@ -0,0 +1,66 @@
+"""
+This module handles accessing, storing, and managing the graph reference.
+
+"""
+from __future__ import absolute_import
+
+import hashlib
+import json
+import os
+import requests
+from pkg_resources import resource_string
+
+import six
+
+from plotly import exceptions, files, utils
+
+GRAPH_REFERENCE_PATH = '/v2/plot-schema'
+GRAPH_REFERENCE_DOWNLOAD_TIMEOUT = 5  # seconds
+
+
+def get_graph_reference():
+    """
+    Attempts to load local copy of graph reference or makes GET request if DNE.
+
+    :return: (dict) The graph reference.
+    :raises: (PlotlyError) When graph reference DNE and GET request fails.
+
+    """
+    default_config = files.FILE_CONTENT[files.CONFIG_FILE]
+    if files.check_file_permissions():
+        graph_reference = utils.load_json_dict(files.GRAPH_REFERENCE_FILE)
+        config = utils.load_json_dict(files.CONFIG_FILE)
+
+        # TODO: https://github.com/plotly/python-api/issues/293
+        plotly_api_domain = config.get('plotly_api_domain',
+                                       default_config['plotly_api_domain'])
+    else:
+        graph_reference = {}
+        plotly_api_domain = default_config['plotly_api_domain']
+
+    sha1 = hashlib.sha1(six.b(str(graph_reference))).hexdigest()
+
+    graph_reference_url = '{}{}?sha1={}'.format(plotly_api_domain,
+                                                GRAPH_REFERENCE_PATH, sha1)
+
+    try:
+        response = requests.get(graph_reference_url,
+                                timeout=GRAPH_REFERENCE_DOWNLOAD_TIMEOUT)
+        response.raise_for_status()
+    except requests.exceptions.RequestException:
+        if not graph_reference:
+            path = os.path.join('graph_reference', 'default-schema.json')
+            s = resource_string('plotly', path).decode('utf-8')
+            graph_reference = json.loads(s)
+    else:
+        if six.PY3:
+            content = str(response.content, encoding='utf-8')
+        else:
+            content = response.content
+        data = json.loads(content)
+        if data['modified']:
+            graph_reference = data['schema']
+
+    return utils.decode_unicode(graph_reference)
+
+GRAPH_REFERENCE = get_graph_reference()