Merge pull request #47 from aydrian/ISSUE-16

richleland · richleland · commit 731eae348511 · 2015-09-01T09:07:21.000-04:00
Added Suppression List resource lib
diff --git a/docs/api/suppression_list.rst b/docs/api/suppression_list.rst
@@ -0,0 +1,7 @@
+.. module:: sparkpost.suppression_list
+
+:mod:`sparkpost.suppression_list`
+=================================
+
+.. autoclass:: SuppressionList
+   :members:
diff --git a/docs/resources/suppression_list.rst b/docs/resources/suppression_list.rst
@@ -0,0 +1,68 @@
+Suppression List
+================
+
+Let's use the underlying `suppression_list API`_ to create a suppression entry:
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    response = sp.suppression_list.create({
+      "email": "test@test.com"
+      "transactional": False,
+      "non_transactional": True,
+      "description": "User requested to not receive any non-transactional emails."
+    })
+
+    print response
+    # outputs {u'message': u'Recipient successfully created'}
+
+.. _suppression_list API: https://www.sparkpost.com/api#/reference/suppression-list
+
+
+Get a suppression entry
+-----------------------
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    sp.suppression_list.get('test@test.com')
+
+
+List suppression entries
+------------------------
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    sp.suppression_list.list()
+
+
+API reference
+-------------
+
+:doc:`/api/suppression_list`
+
+
+Further examples
+----------------
+
+See the `python-sparkpost suppression_list examples`_.
+
+.. _python-sparkpost suppression_list examples: https://github.com/SparkPost/python-sparkpost/tree/master/examples/suppression_list
+
+
+Additional documentation
+------------------------
+
+See the `SparkPost Suppression List API Reference`_.
+
+.. _SparkPost Suppression List API Reference: https://www.sparkpost.com/api#/reference/suppression-list
diff --git a/examples/suppression_list/create_suppression_entries_bulk.py b/examples/suppression_list/create_suppression_entries_bulk.py
@@ -0,0 +1,25 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+recipients = [
+    {
+        'email': 'test1@test.com',
+        'transactional': False,
+        'non_transactional': True,
+        'description': 'Test description 1'
+    },
+    {
+        'email': 'test2@test.com',
+        'transactional': True,
+        'non_transactional': True,
+        'description': 'Test description 2'
+    },
+    {
+        'email': 'test3@test.com',
+        'transactional': True,
+        'non_transactional': False,
+        'description': 'Test description 3'
+    }
+]
+result = sp.suppression_list.create(recipients)
+print result
diff --git a/examples/suppression_list/create_suppression_entry.py b/examples/suppression_list/create_suppression_entry.py
@@ -0,0 +1,10 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+result = sp.suppression_list.create({
+    'email': 'test@test.com',
+    'transactional': False,
+    'non_transactional': True,
+    'description': 'Test description'
+})
+print result
diff --git a/examples/suppression_list/delete_suppression_entry.py b/examples/suppression_list/delete_suppression_entry.py
@@ -0,0 +1,5 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+result = sp.suppression_list.delete('test@test.com')
+print result
diff --git a/examples/suppression_list/get_suppression_entry.py b/examples/suppression_list/get_suppression_entry.py
@@ -0,0 +1,5 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+entry = sp.suppression_list.get('test@test.com')
+print entry
diff --git a/examples/suppression_list/list_suppression_entries.py b/examples/suppression_list/list_suppression_entries.py
@@ -0,0 +1,9 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+results = sp.suppression_list.list(
+    from_date='2015-05-07T00:00:00+0000',
+    to_date='2015-05-07T23:59:59+0000',
+    limit=5
+)
+print results
diff --git a/examples/suppression_list/update_suppression_entries_bulk.py b/examples/suppression_list/update_suppression_entries_bulk.py
@@ -0,0 +1,25 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+recipients = [
+    {
+        'email': 'test1@test.com',
+        'transactional': False,
+        'non_transactional': True,
+        'description': 'Test description 1'
+    },
+    {
+        'email': 'test2@test.com',
+        'transactional': True,
+        'non_transactional': True,
+        'description': 'Test description 2'
+    },
+    {
+        'email': 'test3@test.com',
+        'transactional': True,
+        'non_transactional': False,
+        'description': 'Test description 3'
+    }
+]
+result = sp.suppression_list.update(recipients)
+print result
diff --git a/examples/suppression_list/update_suppression_enty.py b/examples/suppression_list/update_suppression_enty.py
@@ -0,0 +1,10 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+result = sp.suppression_list.update({
+    'email': 'test@test.com',
+    'transactional': False,
+    'non_transactional': True,
+    'description': 'Test description'
+})
+print result
diff --git a/sparkpost/__init__.py b/sparkpost/__init__.py
@@ -3,6 +3,7 @@
 from .exceptions import SparkPostException
 from .metrics import Metrics
 from .recipient_lists import RecipientLists
+from .suppression_list import SuppressionList
 from .templates import Templates
 from .transmissions import Transmissions
 
@@ -29,6 +30,7 @@ def __init__(self, api_key=None, base_uri='https://api.sparkpost.com',
 
         self.metrics = Metrics(self.base_uri, self.api_key)
         self.recipient_lists = RecipientLists(self.base_uri, self.api_key)
+        self.suppression_list = SuppressionList(self.base_uri, self.api_key)
         self.templates = Templates(self.base_uri, self.api_key)
         self.transmissions = Transmissions(self.base_uri, self.api_key)
         # Keeping self.transmission for backwards compatibility.
diff --git a/sparkpost/base.py b/sparkpost/base.py
@@ -20,9 +20,13 @@ def request(self, method, uri, **kwargs):
             'Authorization': self.api_key
         }
         response = requests.request(method, uri, headers=headers, **kwargs)
+        if response.status_code == 204:
+            return True
         if not response.ok:
             raise SparkPostAPIException(response)
-        return response.json()['results']
+        if 'results' in response.json():
+            return response.json()['results']
+        return response.json()
 
     def get(self):
         raise NotImplementedError
diff --git a/sparkpost/suppression_list.py b/sparkpost/suppression_list.py
@@ -0,0 +1,109 @@
+import json
+
+from .base import Resource
+
+
+class SuppressionList(Resource):
+    """
+    SuppressionList class used to search, get and modify suppression status.
+    For detailed request and response formats, see the `Suppresion List API
+    documentation
+    <https://www.sparkpost.com/api#/reference/suppression-list>`_.
+    """
+
+    key = 'suppression-list'
+
+    def list(self, **kwargs):
+        """
+        List supression list entries based on the supplied parameters
+
+        :param datetime from_date: DateTime to start listing
+        :param datetime to_date: DateTime to end listing
+        :param list types: Types of entries to return
+        :param int limit: Maximum number of entries to return
+
+        :returns: a ``list`` of entries
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        key_map = {
+            'from_date': 'from',
+            'to_date': 'to',
+            'types': 'types',
+            'limit': 'limit'
+        }
+        params = dict([(key_map[i], kwargs[i]) for i in list(key_map.keys())
+                       if i in kwargs])
+        results = self.request('GET', self.uri, params=params)
+        return results
+
+    def get(self, email):
+        """
+        Retrieve a suppression list entry for a specific recipient by email
+
+        :param str email: Email of the recipient whose status you want to
+            check_status
+
+        :returns: a suppression list entry
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        uri = "%s/%s" % (self.uri, email)
+        results = self.request('GET', uri)
+        return results
+
+    def _upsert(self, status):
+        uri = self.uri
+        if isinstance(status, dict):
+            # single upsert, update uri and remove email property
+            uri = "%s/%s" % (self.uri, status.pop("email", None))
+        else:
+            status = {"recipients": status}
+        results = self.request('PUT', uri, data=json.dumps(status))
+        return results
+
+    def create(self, entry):
+        """
+        Create a suppression list entry.
+
+        :param dict|list status: If dict it is a single entry to create
+            ``{
+            'email': 'test@test.com',
+            'transactional': True,
+            'non_transactional': True,
+            'description': 'Test description'
+            }``, if list it is multiple entries to create
+
+        :returns: a ``dict`` with a message
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        return self._upsert(entry)
+
+    def update(self, entry):
+        """
+        Update a suppression list entry.
+
+        :param dict|list status: If dict it is a single entry to update
+            ``{
+            'email': 'test@test.com',
+            'transactional': True,
+            'non_transactional': True,
+            'description': 'Test description'
+            }``, if list it is multiple entries to update
+
+        :returns: a ``dict`` with a message
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        return self._upsert(entry)
+
+    def delete(self, email):
+        """
+        Delete the suppression status for a specific recipient by email
+
+        :param str email: Email of the recipient whose status you want to
+            remove
+
+        :returns: TODO
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        uri = "%s/%s" % (self.uri, email)
+        results = self.request('DELETE', uri)
+        return results
diff --git a/test/test_base.py b/test/test_base.py
@@ -24,6 +24,20 @@ def test_uri():
 
 @responses.activate
 def test_success_request():
+    responses.add(
+        responses.GET,
+        fake_uri,
+        status=200,
+        content_type='application/json',
+        body='{}'
+    )
+    resource = create_resource()
+    results = resource.request('GET', resource.uri)
+    assert results == {}
+
+
+@responses.activate
+def test_success_request_with_results():
     responses.add(
         responses.GET,
         fake_uri,
diff --git a/test/test_suppression_list.py b/test/test_suppression_list.py

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +from sparkpost import SparkPost
++
 +sp = SparkPost('YOUR API KEY')
 +result = sp.suppression_list.delete('[email protected]')
 +print result