Merge branch 'master' of https://github.com/plotly/python-api

chrisb2 · chrisb2 · commit edc6f5f1c1c4 · 2014-06-30T18:42:13.000+12:00
diff --git a/.gitmodules b/.gitmodules
@@ -1,9 +1,9 @@
-[submodule "plotly/mplexporter"]
-	path = plotly/mplexporter
+[submodule "submodules/mplexporter"]
+	path = submodules/mplexporter
 	url = git://github.com/mpld3/mplexporter.git
-[submodule "plotly/graph_reference"]
-	path = plotly/graph_reference
+[submodule "submodules/graph_reference"]
+	path = submodules/graph_reference
 	url = git://github.com/plotly/graph_reference.git
-[submodule "plotly/chunked_requests"]
-	path = plotly/chunked_requests
+[submodule "submodules/chunked_requests"]
+	path = submodules/chunked_requests
 	url = git://github.com/chriddyp/chunked_requests.git
diff --git a/README.md b/README.md
@@ -19,6 +19,13 @@ Now you can download, design, and upload Plotly figures--all from Python.
 
 * Official docs: [https://plot.ly/python](https://plot.ly/python)
 
+###Contributing?
+
+This project uses git submodules! After forking and cloning, in your terminal 
+run `make` from inside your local `python-api/` repository. That will spit out 
+the `make_instructions.txt` file. Checkout the *Getting started* section in 
+there for more info.
+
 ###Get in touch
 
 - <feedback@plot.ly>
diff --git a/make_instructions.txt b/make_instructions.txt
@@ -0,0 +1,62 @@
+#################
+MAKE INSTRUCTIONS
+#################
+
+Contents:
+
+    Availble targets
+
+    Getting setup
+
+    Pulling in changes from subprojects
+
+    Why this is worthwhile
+
+################################################################################
+
+Available targets (i.e. $ make target):
+
+    readme -> `less` this file
+
+    setup_subs -> delete old submodule locations, init, update, and sync new
+
+    install -> 1. sync submodules 2. install plotly with setup.py
+
+    sync_subs -> sync all submodules
+
+    sync_mpl -> sync mplexporter submodule ONLY
+
+    sync_chunked -> sync chunked_requests submodule ONLY
+
+    sync_refs -> sync graph_reference submodule ONLY
+
+    pull_subs -> `cd` into *each* submodule and `git pull origin master`
+
+    pull_mpl -> pull in mplexporter *master* branch
+
+    pull_chunked -> pull in chunked_requests *master* branch
+
+    pull_refs -> pull in graph_reference *master* branch
+
+################################################################################
+
+Getting setup:
+
+    1. run `$ make setup_subs`
+    2. if that doesn't work, DELETE your local repo, re-clone, try again.
+
+################################################################################
+
+Pulling in changes from subprojects:
+
+    1. Only pull submodules that you require (e.g., $ make pull_refs)
+    2. Make sure to sync these changes (e.g., $ make sync_refs)
+
+################################################################################
+
+Why this is worthwhile:
+
+    This makefile is mostly to deal with git *submodules*. Since these
+    *subprojects* only copy over their current commits (not the actual content),
+    accepting pull requests is really sloppy! By *syncing* changes, we can
+    more easily track pull new commits from other branches.
diff --git a/makefile b/makefile
@@ -1,38 +1,62 @@
-all : pull_all install
-
-sync_mplexporter : plotly/mplexporter
-	rsync -r plotly/mplexporter/mplexporter plotly/matplotlylib/
-
-sync_chunked_requests : plotly/chunked_requests
-	rsync -r plotly/chunked_requests/chunked_requests plotly/plotly/
-
-install : sync_mplexporter sync_chunked_requests
+all : readme
+
+readme :
+	@echo ""
+	@less make_instructions.txt
+
+setup_subs :
+	@echo "Deleting old submodule locations, if they exist"
+	rm -rf plotly/graph_reference
+	rm -rf plotly/mplexporter
+	rm -rf plotly/chunked_requests
+	rm -rf plotly/plotly/chunked_requests
+	rm -rf plotly/matplotlylib/mplexporter
+	@echo "Initializing submodules listed in project"
+	git submodule init
+	@echo "Updating submodules to their respective commits"
+	git submodule update
+	make sync_subs
+
+install : sync_subs
+	@echo ""
+	@echo "Installing Python API with make"
 	python setup.py install
 
-pull_refs : plotly/graph_reference
-	cd plotly/graph_reference; git pull origin master
-
-pull_mpl : plotly/mplexporter
-	cd plotly/mplexporter; git pull origin master
-
-pull_chunked : plotly/chunked_requests
-	cd plotly/chunked_requests; git pull origin master
-
-pull_all : pull_refs pull_mpl pull_chunked
-
-pull_subs : 
-	echo separated submodule pulls, run pull_refs, pull_chunked, or pull_mpl
-
-show_subs : plotly/graph_reference plotly/chunked_requests plotly/mplexporter
-	git for each ‘git remote -v’
-
-html_nbs : notebooks
-	cd notebooks; \
-		ipython nbconvert 'Plotly and Python.ipynb'; \
-		python add_some_css.py 'Plotly and Python.html'
-	cd notebooks; \
-		ipython nbconvert 'Plotly and matplotlib and mpld3.ipynb'; \
-		python add_some_css.py 'Plotly and matplotlib and mpld3.html'
-	cd notebooks; \
-		ipython nbconvert Quickstart.ipynb; \
-		python add_some_css.py Quickstart.html
+sync_subs : sync_mpl sync_chunked sync_refs
+	@echo ""
+	@echo "Submodules synced"
+
+pull_subs : pull_mpl pull_chunked pull_refs
+	@echo ""
+	@echo "Submodules pulled"
+
+sync_mpl : submodules/mplexporter
+	@echo ""
+	@echo "Syncing mplexporter directories"
+	rsync -r submodules/mplexporter/mplexporter plotly/matplotlylib/
+
+sync_chunked : submodules/chunked_requests
+	@echo ""
+	@echo "Syncing chunked_requests directories"
+	rsync -r submodules/chunked_requests/chunked_requests plotly/plotly/
+
+sync_refs : submodules/graph_reference
+	@echo ""
+	@echo "Syncing graph_reference directories"
+	rsync -r submodules/graph_reference plotly/
+
+pull_refs : submodules/graph_reference
+	@echo ""
+	@echo "Pulling down updates from graph_reference"
+	cd submodules/graph_reference; git pull origin master
+
+pull_mpl : submodules/mplexporter
+	@echo ""
+	@echo "Pulling down updates from mplexporter"
+	cd submodules/mplexporter; git pull origin master
+
+pull_chunked : submodules/chunked_requests
+	@echo ""
+	@echo "Pulling down updates from chunked_requests"
+	cd submodules/chunked_requests; git pull origin master
+	
diff --git a/plotly/exceptions.py b/plotly/exceptions.py
@@ -79,7 +79,8 @@ def __init__(self, obj='', key='', **kwargs):
             "'help(plotly.graph_objs.{obj_name})' for more information."
             "".format(key=key, obj_name=obj.__class__.__name__)
         )
-        plain_message="invalid key, '{}', in dictionary".format(key)
+        plain_message = ("Invalid key, '{key}', found in '{obj}' object"
+                         "".format(key=key, obj=obj.__class__.__name__))
         super(PlotlyDictKeyError, self).__init__(message=message,
                                                  path=[key],
                                                  plain_message=plain_message,
@@ -97,8 +98,8 @@ def __init__(self, obj='', key='', value='', val_types='', **kwargs):
                                            val_types=val_types,
                                            obj_name=obj.__class__.__name__)
         )
-        plain_message = ("invalid value associated with key, '{}', in "
-                         "dictionary".format(key))
+        plain_message = ("Invalid value found in '{obj}' associated with key, "
+                         "'{key}'".format(key=key, obj=obj.__class__.__name__))
         super(PlotlyDictValueError, self).__init__(message=message,
                                                    plain_message=plain_message,
                                                    path=[key],
@@ -112,8 +113,8 @@ def __init__(self, obj='', index='', entry='', **kwargs):
             "".format(index, obj.__class__.__name__)
         )
         plain_message = (
-            "The entry at index, '{}', is invalid."
-            "".format(index)
+            "Invalid entry found in '{obj}' object at index, '{index}'."
+            "".format(obj=obj.__class__.__name__, index=index)
         )
         super(PlotlyListEntryError, self).__init__(message=message,
                                                    plain_message=plain_message,
@@ -129,9 +130,9 @@ def __init__(self, obj='', index='', **kwargs):
                 "'{}' lists.".format(index, obj.__class__.__name__)
         )
         plain_message = (
-                "The entry at index, '{}', is invalid because it does not "
-                "contain a valid 'type' key-value. This is required for "
-                "valid data lists.".format(index))
+                "Invalid entry found in 'data' object at index, '{}'. It does "
+                "not contain a valid 'type' key, required for 'data' lists."
+                "".format(index))
         super(PlotlyDataTypeError, self).__init__(message=message,
                                                   plain_message=plain_message,
                                                   path=[index],
diff --git a/plotly/graph_objs/graph_objs.py b/plotly/graph_objs/graph_objs.py
@@ -237,8 +237,11 @@ def __new__(mcs, name, bases, attrs):
                     descr = str(obj_info[key]['description'])
                 except KeyError:
                     descr = undocumented
-                str_1 = "{} [required={}] (value={}):\n".format(key, required,
-                                                                val_types)
+                str_1 = "{} [required={}] (value={})".format(
+                    key, required, val_types)
+                if "streamable" in obj_info[key] and obj_info[key]["streamable"]:
+                    str_1 += " (streamable)"
+                str_1 += ":\n"
                 str_1 = "\t" + "\n\t".join(textwrap.wrap(str_1,
                                                          width=width1)) + "\n"
                 str_2 = "\t\t" + "\n\t\t".join(textwrap.wrap(descr,
diff --git a/plotly/matplotlylib/mplexporter/utils.py b/plotly/matplotlylib/mplexporter/utils.py
@@ -259,6 +259,8 @@ def get_axes_properties(ax):
              'axesbgalpha': ax.patch.get_alpha(),
              'bounds': ax.get_position().bounds,
              'dynamic': ax.get_navigate(),
+             'axison': ax.axison,
+             'frame_on': ax.get_frame_on(),
              'axes': [get_axis_properties(ax.xaxis),
                       get_axis_properties(ax.yaxis)]}
 
diff --git a/plotly/plotly/plotly.py b/plotly/plotly/plotly.py
@@ -279,15 +279,15 @@ def get_figure(file_owner_or_url, file_id=None, raw=False):
     pass a valid plotly url as the first argument.
 
     Note, if you're using a file_owner string as the first argument, you MUST
-    specity a `file_id` keyword argument. Else, if you're using a url string
+    specify a `file_id` keyword argument. Else, if you're using a url string
     as the first argument, you MUST NOT specify a `file_id` keyword argument, or
     file_id must be set to Python's None value.
 
     Positional arguments:
     file_owner_or_url (string) -- a valid plotly username OR a valid plotly url
 
     Keyword arguments:
-    file_id (defualt=None) -- an int or string that can be converted to int
+    file_id (default=None) -- an int or string that can be converted to int
                               if you're using a url, don't fill this in!
     raw (default=False) -- if true, return unicode JSON string verbatim**
 
@@ -417,21 +417,35 @@ def heartbeat(self, reconnect_on=(200, '', 408)):
                                          "cannot write to a closed connection. "
                                          "Call `open()` on the stream to open the stream.")
 
-    def write(self, data, layout=None, validate=True,
+    def write(self, trace, layout=None, validate=True,
               reconnect_on=(200, '', 408)):
-        """ Write `data` to your stream. This will plot the
-        `data` in your graph in real-time.
+        """Write to an open stream.
 
-        `data` is a plotly formatted dict.
-        Valid keys:
+        Once you've instantiated a 'Stream' object with a 'stream_id',
+        you can 'write' to it in real time.
+
+        positional arguments:
+        trace - A valid plotly trace object (e.g., Scatter, Heatmap, etc.).
+                Not all keys in these are `stremable` run help(Obj) on the type
+                of trace your trying to stream, for each valid key, if the key
+                is streamable, it will say 'streamable = True'. Trace objects
+                must be dictionary-like.
+
+        keyword arguments:
+        layout (default=None) - A valid Layout object
+                                Run help(plotly.graph_objs.Layout)
+        validate (default = True) - Validate this stream before sending?
+                                    This will catch local errors if set to True.
+
+        Some valid keys for trace dictionaries:
             'x', 'y', 'text', 'z', 'marker', 'line'
 
         Examples:
-        >>> write(dict(x = 1, y = 2))
-        >>> write(dict(x = [1, 2, 3], y = [10, 20, 30]))
-        >>> write(dict(x = 1, y = 2, text = 'scatter text'))
-        >>> write(dict(x = 1, y = 3, marker = dict(color = 'blue')))
-        >>> write(dict(z = [[1,2,3], [4,5,6]]))
+        >>> write(dict(x=1, y=2))  # assumes 'scatter' type
+        >>> write(Bar(x=[1, 2, 3], y=[10, 20, 30]))
+        >>> write(Scatter(x=1, y=2, text='scatter text'))
+        >>> write(Scatter(x=1, y=3, marker=Marker(color='blue')))
+        >>> write(Heatmap(z=[[1, 2, 3], [4, 5, 6]]))
 
         The connection to plotly's servers is checked before writing
         and reconnected if disconnected and if the response status code
@@ -442,7 +456,7 @@ def write(self, data, layout=None, validate=True,
         http://nbviewer.ipython.org/github/plotly/python-user-guide/blob/master/s7_streaming/s7_streaming.ipynb
         """
         stream_object = dict()
-        stream_object.update(data)
+        stream_object.update(trace)
         if 'type' not in stream_object:
             stream_object['type'] = 'scatter'
         if validate:
diff --git a/plotly/tools.py b/plotly/tools.py
diff --git a/plotly/version.py b/plotly/version.py
