variable domain in docstring

chriddyp · chriddyp · commit 223a0b72a9ef · 2014-05-29T18:14:44.000-04:00
diff --git a/plotly/__init__.py b/plotly/__init__.py
@@ -1,4 +1,5 @@
 from . version import __version__
 import graph_objs
 import plotly
-import tools
+import tools
+import utils
diff --git a/plotly/plotly/plotly.py b/plotly/plotly/plotly.py
@@ -316,11 +316,12 @@ def get_figure(file_owner, file_id, raw=False):
                 "There was an error retrieving this file")
 
 
+@utils.template_doc(plotly_domain=tools._get_plotly_urls(forgiving=True)[0])
 class Stream:
     """ Interface to Plotly's real-time graphing API.
 
     Initialize a Stream object with a stream_id
-    found in https://plot.ly/settings.
+    found in {plotly_domain}/settings.
     Real-time graphs are initialized with a call to `plot` that embeds
     your unique `stream_id`s in each of the graph's traces. The `Stream`
     interface plots data to these traces, as identified with the unique
@@ -333,7 +334,7 @@ class Stream:
     Stream example:
     # Initialize a streaming graph
     # by embedding stream_id's in the graph's traces
-    >>> stream_id = "your_stream_id" # See https://plot.ly/settings
+    >>> stream_id = "your_stream_id" # See {plotly_domain}/settings
     >>> py.plot(Data([Scatter(x=[],
                               y=[],
                               stream=dict(token=stream_id, maxpoints=100))])
@@ -343,9 +344,10 @@ class Stream:
     >>> stream.write(dict(x=1, y=1)) # Plot (1, 1) in your graph
     """
 
+    @utils.template_doc(plotly_domain=tools._get_plotly_urls(forgiving=True)[0])
     def __init__(self, stream_id):
         """ Initialize a Stream object with your unique stream_id.
-        Find your stream_id at https://plot.ly/settings.
+        Find your stream_id at {plotly_domain}/settings.
 
         For more help, see: `help(plotly.plotly.Stream)`
         or see examples and tutorials here:
@@ -362,7 +364,7 @@ def open(self):
         http://nbviewer.ipython.org/github/plotly/python-user-guide/blob/master/s7_streaming/s7_streaming.ipynb
         """
 
-        plotly_streaming_url = tools._get_plotly_urls()[1]
+        plotly_streaming_url = tools._get_plotly_urls(forgiving=True)[1]
         self._stream = chunked_requests.Stream(plotly_streaming_url,
                                                80,
                                                {'Host': plotly_streaming_url,
diff --git a/plotly/tools.py b/plotly/tools.py
@@ -186,8 +186,38 @@ def embed(username, plot_id, width="100%", height=525):
         pass
 
 
-### mpl-related tools ###
+def _get_plotly_urls(forgiving=False):
+    ''' Return url endpoints for Plotly services.
+        These endpoints are configurable, and are
+        retrieved from ~/.plotly/.credentials as:
+        {
+            'plotly_rest_url': '...',
+            'plotly_streaming_url': '...'
+        }
+    '''
+    if forgiving:
+        try:
+            config_on_file = get_credentials_file()
+        except:
+            config_on_file = {}
+    else:
+        config_on_file = get_credentials_file()
+
+    if 'plotly_rest_url' in config_on_file:
+        plotly_rest_url = config_on_file['plotly_rest_url']
+    else:
+        plotly_rest_url = 'https://plot.ly'
+
+    if 'plotly_streaming_url' in config_on_file:
+        plotly_streaming_url = config_on_file['plotly_streaming_url']
+    else:
+        plotly_streaming_url = 'stream.plot.ly'
+
+    return (plotly_rest_url, plotly_streaming_url)
 
+
+### mpl-related tools ###
+@utils.template_doc(plotly_domain=_get_plotly_urls(forgiving=True)[0])
 def mpl_to_plotly(fig, resize=False, strip_style=False, verbose=False):
     """Convert a matplotlib figure to plotly dictionary and send.
 
@@ -230,10 +260,10 @@ def mpl_to_plotly(fig, resize=False, strip_style=False, verbose=False):
     notebook -- an option for use with an IPython notebook
 
     ** Don't have a username/api_key? Try looking here:
-    https://plot.ly/plot
+    {plotly_domain}/plot
 
     ** Forgot your api_key? Try signing in and looking here:
-    https://plot.ly/api/python/getting-started
+    {plotly_domain}/api/python/getting-started
 
     """
     if _matplotlylib_imported:
@@ -401,26 +431,3 @@ def validate_stream(obj, obj_type):
             validate_stream(val, sub_obj_type)
         except KeyError:
             pass
-
-def _get_plotly_urls():
-    ''' Return url endpoints for Plotly services.
-        These endpoints are configurable, and are
-        retrieved from ~/.plotly/.credentials as:
-        {
-            'plotly_rest_url': '...',
-            'plotly_streaming_url': '...'
-        }
-    '''
-    config_on_file = get_credentials_file()
-
-    if 'plotly_rest_url' in config_on_file:
-        plotly_rest_url = config_on_file['plotly_rest_url']
-    else:
-        plotly_rest_url = 'https://plot.ly'
-
-    if 'plotly_streaming_url' in config_on_file:
-        plotly_streaming_url = config_on_file['plotly_streaming_url']
-    else:
-        plotly_streaming_url = 'stream.plot.ly'
-
-    return (plotly_rest_url, plotly_streaming_url)
diff --git a/plotly/utils.py b/plotly/utils.py
@@ -103,7 +103,6 @@ def default(self, obj):
 
 
 ### unicode stuff ###
-
 def decode_unicode(coll):
     if isinstance(coll, list):
         for no, entry in enumerate(coll):
@@ -126,4 +125,13 @@ def decode_unicode(coll):
                 except UnicodeEncodeError:
                     pass
             coll[str(key)] = coll.pop(key)
-    return coll
+    return coll
+
+
+### docstring templating ###
+def template_doc(**kwargs):
+    def _decorator(func):
+        if func.__doc__ is not None:
+            func.__doc__ = func.__doc__.format(**kwargs)
+        return func
+    return _decorator
