Merge pull request #55 from adafruit/api-v2

V2 Update

Author: brentru

.travis.yml

@@ -0,0 +1,23 @@
+# .travis.yml for Adafruit IO Python Client Library
+language: python
+dist: trusty
+sudo: required
+
+python:
+    - "3.6"
+
+cache:
+    pip: true
+
+
+install:
+  - python setup.py install
+  - pip install pylint Sphinx sphinx-rtd-theme
+  - pip install .
+
+script:
+  - cd docs && sphinx-build -E -W -b html . _build/html
+  - cd ..
+  - cd tests/
+  - git checkout api-v2
+  - python -m unittest discover

Adafruit_IO/__init__.py

@@ -20,5 +20,6 @@
 # SOFTWARE.
 from .client import Client
 from .mqtt_client import MQTTClient
-from .errors import AdafruitIOError, RequestError, ThrottlingError
-from .model import Data, Stream, Feed, Group
+from .errors import AdafruitIOError, RequestError, ThrottlingError, MQTTError
+from .model import Data, Feed, Group
+from ._version import __version__

Adafruit_IO/_version.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

Adafruit_IO/client.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2014 Adafruit Industries
+# Copyright (c) 2018 Adafruit Industries
 # Authors: Justin Cooper & Tony DiCola
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -21,6 +21,7 @@
 import json
 import pkg_resources
 import platform
+# import logging
 
 import requests
 
@@ -41,23 +42,30 @@ class Client(object):
     REST API.  Use this client class to send, receive, and enumerate feed data.
     """
 
-    def __init__(self, key, proxies=None, base_url='https://io.adafruit.com', api_version='v1'):
+    def __init__(self, username, key, proxies=None, base_url='https://io.adafruit.com', api_version = 'v2'):
         """Create an instance of the Adafruit IO REST API client.  Key must be
         provided and set to your Adafruit IO access key value.  Optionaly
         provide a proxies dict in the format used by the requests library, a
         base_url to point at a different Adafruit IO service (the default is
         the production Adafruit IO service over SSL), and a api_version to
         add support for future API versions.
         """
+        self.username = username
         self.key = key
         self.proxies = proxies
         self.api_version = api_version
+        # self.logger = logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
+
         # Save URL without trailing slash as it will be added later when
         # constructing the path.
         self.base_url = base_url.rstrip('/')
 
-    def _compose_url(self, path):
-        return '{0}/api/{1}/{2}'.format(self.base_url, self.api_version, path)
+    def _compose_url(self, path, is_time=None):
+        if not is_time:
+            return '{0}/api/{1}/{2}/{3}'.format(self.base_url, self.api_version, self.username, path)
+        else: # return a call to https://io.adafruit.com/api/v2/time/{unit}
+            return '{0}/api/{1}/{2}'.format(self.base_url, self.api_version, path)
+
 
     def _handle_error(self, response):
         # Handle explicit errors.
@@ -73,12 +81,15 @@ def _headers(self, given):
         headers.update(given)
         return headers
 
-    def _get(self, path):
-        response = requests.get(self._compose_url(path),
+    def _get(self, path, is_time=None):
+        response = requests.get(self._compose_url(path, is_time),
                                 headers=self._headers({'X-AIO-Key': self.key}),
                                 proxies=self.proxies)
         self._handle_error(response)
-        return response.json()
+        if not is_time:
+            return response.json()
+        else: # time doesn't need to serialize into json, just return text
+            return response.text
 
     def _post(self, path, data):
         response = requests.post(self._compose_url(path),
@@ -97,14 +108,25 @@ def _delete(self, path):
         self._handle_error(response)
 
     # Data functionality.
-    def send(self, feed_name, value):
-        """Helper function to simplify adding a value to a feed.  Will find the
-        specified feed by name or create a new feed if it doesn't exist, then
-        will append the provided value to the feed.  Returns a Data instance
-        with details about the newly appended row of data.
+    def send_data(self, feed, value):
+        """Helper function to simplify adding a value to a feed.  Will append the
+        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.
         """
-        path = "feeds/{0}/data/send".format(feed_name)
-        return Data.from_dict(self._post(path, {'value': value}))
+        return self.create_data(feed, Data(value=value))
+
+    send = send_data
+
+    def send_batch_data(self, feed, data_list):
+        """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.
+        """
+        path = "feeds/{0}/data/batch".format(feed)
+        data_dict = type(data_list)((data._asdict() for data in data_list))
+        self._post(path, {"data": data_dict})
 
     def append(self, feed, value):
         """Helper function to simplify adding a value to a feed.  Will append the
@@ -114,6 +136,26 @@ def append(self, feed, value):
         """
         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
+        """
+        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
+        """
+        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
@@ -185,7 +227,7 @@ def create_feed(self, feed):
         type with at least the name property set.
         """
         path = "feeds/"
-        return Feed.from_dict(self._post(path, feed._asdict()))
+        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
@@ -194,25 +236,6 @@ def delete_feed(self, feed):
         path = "feeds/{0}".format(feed)
         self._delete(path)
 
-    # Group functionality.
-    def send_group(self, group_name, data):
-        """Update all feeds in a group with one call.  Group_name should be the
-        name of a group to update.  Data should be a dict with an item for each
-        feed in the group, where the key is the feed name and value is the new
-        data row value.  For example a group 'TestGroup' with feeds 'FeedOne'
-        and 'FeedTwo' could be updated by calling:
-
-        send_group('TestGroup', {'FeedOne': 'value1', 'FeedTwo': 10})
-
-        This would add the value 'value1' to the feed 'FeedOne' and add the
-        value 10 to the feed 'FeedTwo'.
-
-        After a successful update an instance of Group will be returned with
-        metadata about the updated group.
-        """
-        path = "groups/{0}/send".format(group_name)
-        return Group.from_dict(self._post(path, {'value': data}))
-
     def receive_group(self, group):
         """Retrieve the most recent value for the specified group.  Group can be
         a group ID, group key, or group name.  Returns a Group instance whose

Adafruit_IO/errors.py

@@ -18,6 +18,17 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
+
+import json
+
+# MQTT RC Error Types
+MQTT_ERRORS   = [ 'Connection successful',
+                  'Incorrect protocol version',
+                  'Invalid Client ID',
+                  'Server unavailable ',
+                  'Bad username or password',
+                  'Not authorized' ]
+
 class AdafruitIOError(Exception):
     """Base class for all Adafruit IO request failures."""
     pass
@@ -26,8 +37,16 @@ class AdafruitIOError(Exception):
 class RequestError(Exception):
     """General error for a failed Adafruit IO request."""
     def __init__(self, response):
-        super(RequestError, self).__init__("Adafruit IO request failed: {0} {1}".format(
-            response.status_code, response.reason))
+        error_message = self._parse_error(response)
+        super(RequestError, self).__init__("Adafruit IO request failed: {0} {1} - {2}".format(
+            response.status_code, response.reason, error_message))
+
+    def _parse_error(self, response):
+        try:
+            content = json.loads(response.content)
+            return ' - '.join(content['error'])
+        except ValueError:
+            return ""
 
 
 class ThrottlingError(AdafruitIOError):
@@ -38,3 +57,12 @@ def __init__(self):
         super(ThrottlingError, self).__init__("Exceeded the limit of Adafruit IO "  \
             "requests in a short period of time. Please reduce the rate of requests " \
             "and try again later.")
+
+
+class MQTTError(Exception):
+    """Handles connection attempt failed errors.
+    """
+    def __init__(self, response):
+        error = MQTT_ERRORS[response]
+        super(MQTTError, self).__init__(error)
+    pass

Adafruit_IO/model.py

@@ -28,33 +28,29 @@
 
 
 # List of fields/properties that are present on a data object from IO.
-DATA_FIELDS   = [ 'created_epoch', 
+DATA_FIELDS   = [ 'created_epoch',
                   'created_at',
                   'updated_at',
                   'value',
                   'completed_at',
                   'feed_id',
                   'expiration',
                   'position',
-                  'id' ]
-
-STREAM_FIELDS = [ 'completed_at',
-                  'created_at',
                   'id',
-                  'value' ]
+                  'lat',
+                  'lon',
+                  'ele']
 
-FEED_FIELDS   = [ 'last_value_at',
-                  'name',
-                  'stream',
-                  'created_at',
-                  'updated_at',
-                  'unit_type',
-                  'mode',
+FEED_FIELDS   = [ 'name',
                   'key',
+                  'description',
+                  'unit_type',
                   'unit_symbol',
-                  'fixed',
-                  'last_value',
-                  'id' ]
+                  'history',
+                  'visibility',
+                  'license',
+                  'status_notify',
+                  'status_timeout']
 
 GROUP_FIELDS  = [ 'description',
                   'source_keys',
@@ -73,18 +69,17 @@
 # client it might be prudent to revisit this decision and consider making these
 # full fledged classes that are mutable.
 Data   = namedtuple('Data', DATA_FIELDS)
-Stream = namedtuple('Stream', STREAM_FIELDS)
 Feed   = namedtuple('Feed', FEED_FIELDS)
 Group  = namedtuple('Group', GROUP_FIELDS)
 
 
 # Magic incantation to make all parameters to the initializers optional with a
 # default value of None.
-Data.__new__.__defaults__   = tuple(None for x in DATA_FIELDS)
-Stream.__new__.__defaults__ = tuple(None for x in STREAM_FIELDS)
-Feed.__new__.__defaults__   = tuple(None for x in FEED_FIELDS)
 Group.__new__.__defaults__  = tuple(None for x in GROUP_FIELDS)
+Data.__new__.__defaults__   = tuple(None for x in DATA_FIELDS)
 
+# explicitly set feed values
+Feed.__new__.__defaults__ = (None, None, None, None, None, 'ON', 'Private', None, None, None)
 
 # Define methods to convert from dicts to the data types.
 def _from_dict(cls, data):
@@ -98,8 +93,6 @@ def _from_dict(cls, data):
 
 def _feed_from_dict(cls, data):
     params = {x: data.get(x, None) for x in cls._fields}
-    # Parse the stream if provided and generate a stream instance.
-    params['stream'] = Stream.from_dict(data.get('stream', {}))
     return cls(**params)
 
 
@@ -112,6 +105,5 @@ def _group_from_dict(cls, data):
 
 # Now add the from_dict class methods defined above to the data types.
 Data.from_dict   = classmethod(_from_dict)
-Stream.from_dict = classmethod(_from_dict)
 Feed.from_dict   = classmethod(_feed_from_dict)
 Group.from_dict  = classmethod(_group_from_dict)