SeriesHelper documentation improvements

aviau · aviau · commit c2492ebc0f56 · 2015-01-23T11:37:33.000-05:00
diff --git a/docs/source/api-documentation.rst b/docs/source/api-documentation.rst
@@ -54,3 +54,13 @@ These clients are initiated in the same way as the
 .. autoclass:: influxdb.DataFrameClient
     :members:
     :undoc-members:
+
+-----------------------
+:class:`SeriesHelper`
+-----------------------
+
+
+.. currentmodule:: influxdb.SeriesHelper
+.. autoclass:: influxdb.SeriesHelper
+    :members:
+    :undoc-members:
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -19,4 +19,9 @@ Tutorials - pandas
 
 .. literalinclude:: ../../examples/tutorial_pandas.py
    :language: python
-   :linenos:
+
+Tutorials - SeriesHelper
+========================
+
+.. literalinclude:: ../../examples/tutorial_serieshelper.py
+   :language: python
diff --git a/examples/tutorial_serieshelper.py b/examples/tutorial_serieshelper.py
@@ -0,0 +1,30 @@
+from influxdb import InfluxDBClient
+from influxdb import SeriesHelper
+
+
+class MySeriesHelper(SeriesHelper):
+    class Meta:
+        # Meta class stores time series helper configuration.
+        client = InfluxDBClient()
+        # The client should be an instance of InfluxDBClient.
+        series_name = 'events.stats.{server_name}'
+        # The series name must be a string. Add dependent field names in curly brackets.
+        fields = ['time', 'server_name']
+        # Defines all the fields in this time series.
+        bulk_size = 5
+        # Defines the number of data points to store prior to writing on the wire.
+
+# The following will create *five* (immutable) data points.
+# Since bulk_size is set to 5, upon the fifth construction call, *all* data
+# points will be written on the wire via MySeriesHelper.Meta.client.
+MySeriesHelper(server_name='us.east-1', time=159)
+MySeriesHelper(server_name='us.east-1', time=158)
+MySeriesHelper(server_name='us.east-1', time=157)
+MySeriesHelper(server_name='us.east-1', time=156)
+MySeriesHelper(server_name='us.east-1', time=155)
+
+# To manually submit data points which are not yet written, call commit:
+MySeriesHelper.commit()
+
+# To inspect the JSON which will be written, call _json_body_():
+MySeriesHelper._json_body_()
diff --git a/influxdb/helper.py b/influxdb/helper.py
@@ -10,56 +10,41 @@
 
 class SeriesHelper(object):
 
-    '''
+    """
     Subclassing this helper eases writing data points in bulk.
     All data points are immutable, insuring they do not get overwritten.
     Each subclass can write to its own database.
     The time series names can also be based on one or more defined fields.
 
-    Annotated example:
-    ```
-    class MySeriesHelper(SeriesHelper):
-        class Meta:
-            # Meta class stores time series helper configuration.
-            series_name = 'events.stats.{server_name}'
-            # Series name must be a string, curly brackets for dynamic use.
-            fields = ['time', 'server_name']
-            # Defines all the fields in this time series.
-            ### Following attributes are optional. ###
-            client = TestSeriesHelper.client
-            # Client should be an instance of InfluxDBClient.
-            :warning: Only used if autocommit is True.
-            bulk_size = 5
-            # Defines the number of data points to write simultaneously.
-            :warning: Only applicable if autocommit is True.
-            autocommit = True
-            # If True and no bulk_size, then will set bulk_size to 1.
-
-    # The following will create *five* (immutable) data points.
-    # Since bulk_size is set to 5, upon the fifth construction call, all data
-    # points will be written on the wire via MySeriesHelper.Meta.client.
-    MySeriesHelper(server_name='us.east-1', time=159)
-    MySeriesHelper(server_name='us.east-1', time=158)
-    MySeriesHelper(server_name='us.east-1', time=157)
-    MySeriesHelper(server_name='us.east-1', time=156)
-    MySeriesHelper(server_name='us.east-1', time=155)
-
-    # If autocommit None or False, one must call commit to write datapoints.
-    # To manually submit data points which are not yet written, call commit:
-    MySeriesHelper.commit()
-
-    # To inspect the JSON which will be written, call _json_body_():
-    MySeriesHelper._json_body_()
-    ```
-    '''
+    Annotated example::
+
+        class MySeriesHelper(SeriesHelper):
+            class Meta:
+                # Meta class stores time series helper configuration.
+                series_name = 'events.stats.{server_name}'
+                # Series name must be a string, curly brackets for dynamic use.
+                fields = ['time', 'server_name']
+                # Defines all the fields in this time series.
+                ### Following attributes are optional. ###
+                client = TestSeriesHelper.client
+                # Client should be an instance of InfluxDBClient.
+                :warning: Only used if autocommit is True.
+                bulk_size = 5
+                # Defines the number of data points to write simultaneously.
+                # Only applicable if autocommit is True.
+                autocommit = True
+                # If True and no bulk_size, then will set bulk_size to 1.
+
+    """
     __initialized__ = False
 
     def __new__(cls, *args, **kwargs):
-        '''
+        """
         Initializes class attributes for subsequent constructor calls.
+
         :note: *args and **kwargs are not explicitly used in this function,
         but needed for Python 2 compatibility.
-        '''
+        """
         if not cls.__initialized__:
             cls.__initialized__ = True
             try:
@@ -107,11 +92,12 @@ def __new__(cls, *args, **kwargs):
         return super(SeriesHelper, cls).__new__(cls)
 
     def __init__(self, **kw):
-        '''
+        """
         Constructor call creates a new data point. All fields must be present.
+
         :note: Data points written when `bulk_size` is reached per Helper.
         :warning: Data points are *immutable* (`namedtuples`).
-        '''
+        """
         cls = self.__class__
 
         if sorted(cls._fields) != sorted(kw.keys()):
@@ -127,12 +113,13 @@ def __init__(self, **kw):
 
     @classmethod
     def commit(cls, client=None):
-        '''
+        """
         Commit everything from datapoints via the client.
+
         :param client: InfluxDBClient instance for writing points to InfluxDB.
         :attention: any provided client will supersede the class client.
-        :return result of client.write_points.
-        '''
+        :return: result of client.write_points.
+        """
         if not client:
             client = cls._client
         rtn = client.write_points(cls._json_body_())
@@ -141,9 +128,9 @@ def commit(cls, client=None):
 
     @classmethod
     def _json_body_(cls):
-        '''
+        """
         :return: JSON body of these datapoints.
-        '''
+        """
         json = []
         for series_name, data in six.iteritems(cls._datapoints):
             json.append({'name': series_name,
@@ -155,7 +142,7 @@ def _json_body_(cls):
 
     @classmethod
     def _reset_(cls):
-        '''
+        """
         Reset data storage.
-        '''
+        """
         cls._datapoints = defaultdict(list)
