Merge pull request #78 from brentru/rtd-comments

Documentation for Client.py (API Client)

Author: brentru

Adafruit_IO/_version.py

@@ -1 +1 @@
-__version__ = "2.0.17"
+__version__ = "2.0.18"

Adafruit_IO/client.py

@@ -116,6 +116,8 @@ def send_data(self, feed, value):
         specified value to the feed identified by either name, key, or ID.
         Returns a Data instance with details about the newly appended row of data.
         Note that send_data now operates the same as append.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
+        :param string value: Value to send.
         """
         return self.create_data(feed, Data(value=value))
 
@@ -126,6 +128,8 @@ def send_batch_data(self, feed, data_list):
         ID, feed key, or feed name.  Data must be an instance of the Data class
         with at least a value property set on it.  Returns a Data instance with
         details about the newly appended row of data.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
+        :param Data data_list: Multiple data values.
         """
         path = "feeds/{0}/data/batch".format(feed)
         data_dict = type(data_list)((data._asdict() for data in data_list))
@@ -136,58 +140,57 @@ def append(self, feed, value):
         specified value to the feed identified by either name, key, or ID.
         Returns a Data instance with details about the newly appended row of data.
         Note that unlike send the feed should exist before calling append.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
+        :param string value: Value to append to feed.
         """
         return self.create_data(feed, Data(value=value))
 
-    def send_location_data(self, feed, value, lat, lon, ele):
-        """Sends locational data to a feed
-
-        args:
-            - lat: latitude 
-            - lon: logitude
-            - ele: elevation
-            - (optional) value: value to send to the feed
+    def send_location_data(self, feed, lat, lon, ele, value=None):
+        """Sends locational data to a feed.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
+        :param int lat: Latitude.
+        :param int lon: Longitude.
+        :param int ele: Elevation.
+        :param int value: Optional value to send, defaults to None.
         """
-        return self.create_data(feed, Data(value = value,lat=lat, lon=lon, ele=ele))
+        return self.create_data(feed, Data(value=value,lat=lat, lon=lon, ele=ele))
 
     def receive_time(self, time):
         """Returns the time from the Adafruit IO server.
-
-        args:
-            - time (string): millis, seconds, ISO-8601
+        :param string time: Time to be returned: `millis`, `seconds`, `ISO-8601`.
         """
         timepath = "time/{0}".format(time)
         return self._get(timepath, is_time=True)
 
     def receive(self, feed):
-        """Retrieve the most recent value for the specified feed.  Feed can be a
-        feed ID, feed key, or feed name.  Returns a Data instance whose value
-        property holds the retrieved value.
+        """Retrieve the most recent value for the specified feed. Returns a Data
+        instance whose value property holds the retrieved value.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
         """
         path = "feeds/{0}/data/last".format(feed)
         return Data.from_dict(self._get(path))
 
     def receive_next(self, feed):
-        """Retrieve the next unread value from the specified feed.  Feed can be
-        a feed ID, feed key, or feed name.  Returns a Data instance whose value
-        property holds the retrieved value.
+        """Retrieve the next unread value from the specified feed. Returns a Data 
+        instance whose value property holds the retrieved value.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
         """
         path = "feeds/{0}/data/next".format(feed)
         return Data.from_dict(self._get(path))
 
     def receive_previous(self, feed):
-        """Retrieve the previous unread value from the specified feed.  Feed can
-        be a feed ID, feed key, or feed name.  Returns a Data instance whose
-        value property holds the retrieved value.
+        """Retrieve the previous unread value from the specified feed. Returns a
+        Data instance whose value property holds the retrieved value.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
         """
         path = "feeds/{0}/data/previous".format(feed)
         return Data.from_dict(self._get(path))
 
     def data(self, feed, data_id=None):
-        """Retrieve data from a feed.  Feed can be a feed ID, feed key, or feed
-        name.  Data_id is an optional id for a single data value to retrieve.
-        If data_id is not specified then all the data for the feed will be
-        returned in an array.
+        """Retrieve data from a feed. If data_id is not specified then all the data
+        for the feed will be returned in an array.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
+        :param string data_id: ID of the piece of data to delete.
         """
         if data_id is None:
             path = "feeds/{0}/data".format(feed)
@@ -197,41 +200,46 @@ def data(self, feed, data_id=None):
             return Data.from_dict(self._get(path))
 
     def create_data(self, feed, data):
-        """Create a new row of data in the specified feed.  Feed can be a feed
-        ID, feed key, or feed name.  Data must be an instance of the Data class
-        with at least a value property set on it.  Returns a Data instance with
-        details about the newly appended row of data.
+        """Create a new row of data in the specified feed.
+        Returns a Data instance with details about the newly 
+        appended row of data.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
+        :param Data data: Instance of the Data class. Must have a value property set. 
         """
         path = "feeds/{0}/data".format(feed)
         return Data.from_dict(self._post(path, data._asdict()))
 
     def delete(self, feed, data_id):
-        """Delete data from a feed.  Feed can be a feed ID, feed key, or feed
-        name.  Data_id must be the ID of the piece of data to delete.
+        """Delete data from a feed.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
+        :param string data_id: ID of the piece of data to delete.
         """
         path = "feeds/{0}/data/{1}".format(feed, data_id)
         self._delete(path)
 
     def toRed(self, data):
-        """Hex color feed to red channel. 
+        """Hex color feed to red channel.
+        :param int data: Color value, in hexadecimal.
         """
         return ((int(data[1], 16))*16) + int(data[2], 16)
 
     def toGreen(self, data):
         """Hex color feed to green channel. 
+        :param int data: Color value, in hexadecimal.
         """
         return (int(data[3], 16) * 16) + int(data[4], 16)
 
     def toBlue(self, data):
-        """Hex color feed to blue channel. 
+        """Hex color feed to blue channel.
+        :param int data: Color value, in hexadecimal.
         """
         return (int(data[5], 16) * 16) + int(data[6], 16)
 
-    # Feed functionality.
+    # feed functionality.
     def feeds(self, feed=None):
         """Retrieve a list of all feeds, or the specified feed.  If feed is not
-        specified a list of all feeds will be returned.  If feed is specified it
-        can be a feed name, key, or ID and the requested feed will be returned.
+        specified a list of all feeds will be returned.
+        :param string feed: Name/Key/ID of Adafruit IO feed, defaults to None.
         """
         if feed is None:
             path = "feeds"
@@ -241,25 +249,23 @@ def feeds(self, feed=None):
             return Feed.from_dict(self._get(path))
 
     def create_feed(self, feed):
-        """Create the specified feed.  Feed should be an instance of the Feed
-        type with at least the name property set.
+        """Create the specified feed.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
         """
         path = "feeds/"
         return Feed.from_dict(self._post(path, {"feed": feed._asdict()}))
 
     def delete_feed(self, feed):
-        """Delete the specified feed.  Feed can be a feed ID, feed key, or feed
-        name.
+        """Delete the specified feed.
+        :param string feed: Name/Key/ID of Adafruit IO feed.
         """
         path = "feeds/{0}".format(feed)
         self._delete(path)
 
     # Group functionality.
     def groups(self, group=None):
-        """Retrieve a list of all groups, or the specified group.  If group is
-        not specified a list of all groups will be returned.  If group is
-        specified it can be a group name, key, or ID and the requested group
-        will be returned.
+        """Retrieve a list of all groups, or the specified group.
+        :param string group: Name/Key/ID of Adafruit IO Group. Defaults to None.
         """
         if group is None:
             path = "groups/"
@@ -269,15 +275,15 @@ def groups(self, group=None):
             return Group.from_dict(self._get(path))
 
     def create_group(self, group):
-        """Create the specified group.  Group should be an instance of the Group
-        type with at least the name and feeds property set.
+        """Create the specified group.
+        :param string group: Name/Key/ID of Adafruit IO Group.
         """
         path = "groups/"
         return Group.from_dict(self._post(path, group._asdict()))
 
     def delete_group(self, group):
-        """Delete the specified group.  Group can be a group ID, group key, or
-        group name.
+        """Delete the specified group.
+        :param string group: Name/Key/ID of Adafruit IO Group.
         """
         path = "groups/{0}".format(group)
         self._delete(path)

examples/api/location.py

@@ -33,4 +33,4 @@
 ele = 6 # elevation above sea level (meters)
 
 # Send location data to Adafruit IO
-aio.send_location_data(location.key, value, lat, lon, ele)
+aio.send_location_data(location.key, lat, lon, ele, value)

examples/basics/location.py

@@ -49,7 +49,7 @@
     print('\tLon: ', lon)
     print('\tEle: ', ele)
     # Send location data to Adafruit IO
-    aio.send_location_data(location.key, value, lat, lon, ele)
+    aio.send_location_data(location.key, lat, lon, ele, value)
     # shift all values (for test/demo purposes)
     value += 1
     lat -= 0.01

tests/test_client.py

@@ -23,7 +23,7 @@ class TestClient(base.IOTestCase):
     # If your IP isn't put on the list of non-throttled IPs, uncomment the
     # function below to waste time between tests to prevent throttling.
     #def tearDown(self):
-    #    time.sleep(30.0)
+    time.sleep(30.0)
 
     # Helper Methods
     def get_client(self):
@@ -132,15 +132,14 @@ def test_create_data(self):
     def test_location_data(self):
         aio = self.get_client()
         self.ensure_feed_deleted(aio, 'testlocfeed')
-        test_feed = aio.create_feed(Feed(name="testlocfeed"))
-        aio.send_location_data(test_feed.key, 0, 40, -74, 6)
+        test_feed = aio.create_feed(Feed(name='testlocfeed'))
+        aio.send_location_data(test_feed.key, 40, -74, 6, 0)
         data = aio.receive(test_feed.key)
-        self.assertEqual(int(data.value), 0)
+        self.assertEqual(int(data.value), 0.0)
         self.assertEqual(float(data.lat), 40.0)
         self.assertEqual(float(data.lon), -74.0)
         self.assertEqual(float(data.ele), 6.0)
 
-
     # Test Feed Functionality
     def test_append_by_feed_name(self):
         io = self.get_client()