[TOOLSLIBS-407] Email updates (#173)

* adds opt_in_mode to email

* fixes opt_in_mode setter

* fixes email uninstall test

* adds properties to registration

* adds email lookup

* fixes tag set test

* adds attachment url

* wires up EmailAttachment

* adds isort config

* moves tag imports to prevent circular import

* corrects config

* adds email attachment class

* adds logo image for testing

* changes local test file path

* adds return to rst

* adds attachments to email override

* adds email override test

* adds more email overrides

* formatting

* adds full payload test

* url safe encoding

Author: aschuman0

isort.cfg

@@ -0,0 +1,2 @@
+[ settings ]
+extend_skip=__init__.py

tests/data/logo.png

@@ -1,10 +1,10 @@
+import base64
 import json
-import mock
 import unittest
 import uuid
 
+import mock
 import requests
-
 import urbanairship as ua
 from tests import TEST_KEY, TEST_SECRET
 
@@ -17,6 +17,7 @@ def setUp(self):
         self.locale_language = "en"
         self.timezone = "America/Los_Angeles"
         self.channel_id = str(uuid.uuid4())
+        self.opt_in_mode = "double"
 
     def test_email_reg(self):
         with mock.patch.object(ua.Airship, "_request") as mock_request:
@@ -89,11 +90,13 @@ def test_email_reg_w_opts(self):
                 locale_country=self.locale_country,
                 locale_language=self.locale_language,
                 timezone=self.timezone,
+                opt_in_mode=self.opt_in_mode,
             )
 
             r = email_obj.register()
 
             self.assertEqual(self.channel_id, email_obj.channel_id)
+            self.assertEqual(self.opt_in_mode, email_obj.opt_in_mode)
             self.assertEqual(201, r.status_code)
 
     def test_email_uninstall(self):
@@ -107,11 +110,29 @@ def test_email_uninstall(self):
 
             email_obj = ua.Email(airship=self.airship, address=self.address)
 
-            r = email_obj.register()
+            r = email_obj.uninstall()
 
-            self.assertEqual(self.channel_id, email_obj.channel_id)
             self.assertEqual(200, r.status_code)
 
+    def test_email_lookup(self):
+        with mock.patch.object(ua.Airship, "_request") as mock_request:
+            response = requests.Response()
+            response._content = json.dumps(
+                {
+                    "ok": True,
+                    "channel": {"channel_id": self.channel_id, "device_type": "email"},
+                }
+            )
+            response.status_code = 200
+            mock_request.return_value = response
+
+            lookup = ua.Email.lookup(airship=self.airship, address=self.address)
+
+            self.assertEqual(200, lookup.status_code)
+            self.assertEqual(
+                "email", json.loads(lookup.content)["channel"]["device_type"]
+            )
+
 
 class TestEmailTags(unittest.TestCase):
     def setUp(self):
@@ -154,7 +175,7 @@ def testTagSet(self):
             mock_request.return_value = response
 
             email_tags = ua.EmailTags(airship=self.airship, address=self.address)
-            email_tags.remove(group=self.test_group, tags=self.test_tags)
+            email_tags.set(group=self.test_group, tags=self.test_tags)
             response = email_tags.send()
 
             self.assertEqual(200, response.status_code)
@@ -172,3 +193,28 @@ def testSetWithAddAndRemove(self):
 
             with self.assertRaises(ValueError):
                 email_tags.send()
+
+
+class TestEmailAttachment(unittest.TestCase):
+    def setUp(self):
+        self.attachment = ua.EmailAttachment(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            filename="test_file.png",
+            content_type='image/png; charset="UTF-8"',
+            filepath="tests/data/logo.png",
+        )
+        file = open("tests/data/logo.png", "rb").read()
+        self.encoded = str(base64.urlsafe_b64encode(file))
+
+    def test_encoding(self):
+        self.assertEqual(self.encoded, self.attachment.req_payload.get("data"))
+
+    def test_payload(self):
+        self.assertDictEqual(
+            self.attachment.req_payload,
+            {
+                "filename": "test_file.png",
+                "content_type": 'image/png; charset="UTF-8"',
+                "data": self.encoded,
+            },
+        )

tests/devices/test_email.py

@@ -31,7 +31,7 @@ def test_upload(self):
             "alias,marianb".split(","),
             "named_user,billg".split(","),
         ]
-        self.path = "test_data.csv"
+        self.path = "tests/data/test_data.csv"
 
         with open(self.path, "wt") as csv_file:
             writer = csv.writer(csv_file, delimiter=",")
@@ -188,7 +188,7 @@ def test_next_page(self):
                         "last_updated": "2015-05-30 23:42:39",
                         "channel_count": 23,
                         "status": "processing",
-                    },
+                    }
                 ]
             }
         ).encode("utf-8")

tests/devices/test_static_lists.py

@@ -380,6 +380,7 @@ def test_email_overrides(self):
                 sender_name="test_name",
                 subject="hi",
                 html_body="<html>so rich!</html>",
+                attachments=["16d7442e-5ad4-4ab2-b65a-99c63e39a1d6"],
             )
         )
         p.device_types = ua.device_types("email")
@@ -398,6 +399,7 @@ def test_email_overrides(self):
                         "sender_name": "test_name",
                         "subject": "hi",
                         "html_body": "<html>so rich!</html>",
+                        "attachments": [{"id": "16d7442e-5ad4-4ab2-b65a-99c63e39a1d6"}],
                     }
                 },
             },

tests/push/test_push.py

@@ -15,6 +15,7 @@
     DeviceInfo,
     DeviceTokenList,
     Email,
+    EmailAttachment,
     EmailTags,
     LocationFinder,
     ModifyAttributes,
@@ -187,6 +188,7 @@
     Pipeline,
     Email,
     EmailTags,
+    EmailAttachment,
     CreateAndSendPush,
     date_attribute,
     text_attribute,

urbanairship/__init__.py

@@ -59,6 +59,8 @@ def __init__(self, location=None):
         self.experiments_schedule_url = self.experiments_url + "scheduled/"
         self.experiments_validate = self.experiments_url + "validate/"
 
+        self.attachment_url = self.base_url + "attachments/"
+
     def get(self, endpoint):
         url = getattr(self, endpoint, None)
 

urbanairship/core.py

@@ -1,30 +1,11 @@
-from .devicelist import (
-    ChannelList,
-    ChannelInfo,
-    DeviceTokenList,
-    APIDList,
-    DeviceInfo,
-)
-
 from .tag import ChannelTags, OpenChannelTags
-
-from .segment import Segment, SegmentList
-
+from .attributes import Attribute, AttributeResponse, ModifyAttributes
 from .channel_uninstall import ChannelUninstall
-
-from .open_channel import OpenChannel
-
-from .named_users import NamedUser, NamedUserList, NamedUserTags
-
-from .static_lists import (
-    StaticList,
-    StaticLists,
-)
-
+from .devicelist import APIDList, ChannelInfo, ChannelList, DeviceInfo, DeviceTokenList
+from .email import Email, EmailAttachment, EmailTags
 from .locationfinder import LocationFinder
-
+from .named_users import NamedUser, NamedUserList, NamedUserTags
+from .open_channel import OpenChannel
+from .segment import Segment, SegmentList
 from .sms import Sms
-
-from .email import Email, EmailTags
-
-from .attributes import Attribute, ModifyAttributes, AttributeResponse
+from .static_lists import StaticList, StaticLists

urbanairship/devices/__init__.py

@@ -1,3 +1,4 @@
+import base64
 import json
 import logging
 import re
@@ -16,7 +17,7 @@ class Email(object):
 
     Please see the email documentation for important information about
     opt-in times and email types.
-    https://docs.urbanairship.com/api/ua/#operation/api/channels/email
+    hhttps://docs.airship.com/api/ua/#tag-email
 
     :param address: Required. The email address the object represents.
     :param commercial_opted_in: Optional. A string in ISO 8601 format that
@@ -34,6 +35,12 @@ class Email(object):
         to locale country setting.
     :param locale_language: Optional. The device property tag related
         to locale language setting.
+    :param opt_in_mode: Optional. The opt-in mode for registering the channel. `classic`
+        is the default when unspecified, `double` creates a `double_opt_in` event.
+    :param properties: Optional. An object containing event properties. You can use
+        these properties to filter the double opt-in event and reference them in your
+        message content by using handlebars. Items in the `properties` object are
+        limited to a 255-character maximum string length.
     :param timezone: Optional. The deice property tag related to
         timezone setting.
     :param template_fields: For use with CreateAndSend with inline templates.
@@ -50,6 +57,8 @@ def __init__(
         transactional_opted_out=None,
         locale_country=None,
         locale_language=None,
+        opt_in_mode=None,
+        properties=None,
         timezone=None,
         template_fields=None,
     ):
@@ -61,6 +70,8 @@ def __init__(
         self.transactional_opted_out = transactional_opted_out
         self.locale_country = locale_country
         self.locale_language = locale_language
+        self.opt_in_mode = opt_in_mode
+        self.properties = properties
         self.timezone = timezone
         self.template_fields = template_fields
         self._email_type = "email"  # only acceptable value at this time
@@ -77,6 +88,17 @@ def template_fields(self, value):
 
         self._template_fields = value
 
+    @property
+    def opt_in_mode(self):
+        return self._opt_in_mode
+
+    @opt_in_mode.setter
+    def opt_in_mode(self, value):
+        if value not in ["classic", "double"] and value is not None:
+            raise ValueError("opt_in_mode must be one of: 'classic' or 'double'")
+
+        self._opt_in_mode = value
+
     @property
     def address(self):
         return self._address
@@ -129,9 +151,7 @@ def transactional_opted_out(self, value):
 
     @property
     def create_and_send_audience(self):
-        audience = {
-            "ua_address": self.address,
-        }
+        audience = {"ua_address": self.address}
         if self.commercial_opted_in:
             audience["ua_commercial_opted_in"] = self.commercial_opted_in
         if self.transactional_opted_in:
@@ -150,12 +170,7 @@ def register(self):
         :return: The response object from the API.
         """
         url = self.airship.urls.get("email_url")
-        reg_payload = {
-            "channel": {
-                "type": self._email_type,
-                "address": self.address,
-            }
-        }
+        reg_payload = {"channel": {"type": self._email_type, "address": self.address}}
 
         if self.commercial_opted_in:
             reg_payload["channel"]["commercial_opted_in"] = self.commercial_opted_in
@@ -176,6 +191,10 @@ def register(self):
             reg_payload["channel"]["locale_country"] = self.locale_country
         if self.timezone is not None:
             reg_payload["channel"]["timezone"] = self.timezone
+        if self.opt_in_mode is not None:
+            reg_payload["channel"]["opt_in_mode"] = self.opt_in_mode
+        if self.properties is not None:
+            reg_payload["channel"]["properties"] = self.properties
 
         body = json.dumps(reg_payload).encode("utf-8")
 
@@ -215,6 +234,17 @@ def uninstall(self):
 
         return response
 
+    @classmethod
+    def lookup(cls, airship, address):
+        if not VALID_EMAIL.match(address) and address is not None:
+            raise ValueError("Invalid email address format")
+
+        url = airship.urls.get("email_url") + address
+
+        response = airship.request(method="GET", url=url, version=3, body=None)
+
+        return response
+
 
 class EmailTags(object):
     """Add, remove or set tags for a list of email addresses
@@ -303,3 +333,54 @@ def send(self):
         )
 
         return response
+
+
+class EmailAttachment(object):
+    """
+    Create an email attachment from a file.
+    Please see https://docs.airship.com/api/ua/#operation/api/attachments/post
+    for important information about file size, content type, and send type limitations.
+
+    :param filename: Required. The name of the uploaded file (max 255 UTF-8 bytes).
+        Multiple files with the same name are allowed in separate requests.
+    :param content_type: Required: The mimetype of the uploaded file including the
+        charset parameter, if needed.
+    :param filepath: Required. A path to the file to be uploaded and attached. File must
+        have permissions set to be opened in 'rb' (binary) mode.
+
+    :return: the response object from the API including the 'attachment_ids' uuid to
+        be used in the email override object.
+    """
+
+    def __init__(self, airship, filename, content_type, filepath):
+        self.airship = airship
+        self.filename = filename
+        self.content_type = content_type
+        self.filepath = filepath
+
+    def _encode_attachment(self, filepath):
+        file = open(filepath, "rb").read()
+        enc = base64.urlsafe_b64encode(file)
+
+        return str(enc)
+
+    @property
+    def req_payload(self):
+        attachment_payload = {
+            "filename": self.filename,
+            "content_type": self.content_type,
+            "data": self._encode_attachment(self.filepath),
+        }
+
+        return attachment_payload
+
+    def post(self):
+        response = self.airship.request(
+            method="POST",
+            body=json.dumps(self.req_payload),
+            url=self.airship.urls.get("attachment_url"),
+            content_type="application/json",
+            version=3,
+        )
+
+        return response.json()