Refactors Personalizations logic to simplify flow (#93)

EmailMessage.personalizations can now accept a Sendgrid API object or python dict

Author: sklarsa

sendgrid_backend/mail.py

@@ -8,7 +8,7 @@
 import uuid
 import warnings
 from email.mime.base import MIMEBase
-from typing import TYPE_CHECKING, Dict, Iterable, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Tuple, Union
 
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
@@ -34,7 +34,12 @@
 )
 
 from sendgrid_backend.signals import sendgrid_email_sent
-from sendgrid_backend.util import SENDGRID_5, SENDGRID_6, get_django_setting
+from sendgrid_backend.util import (
+    SENDGRID_5,
+    SENDGRID_6,
+    dict_to_personalization,
+    get_django_setting,
+)
 
 DjangoAttachment = Union[Tuple[str, Union[bytes, str], str], MIMEBase]
 
@@ -242,10 +247,10 @@ def _parse_email_address(self, address: str) -> Tuple[str, Optional[str]]:
 
     def _build_sg_personalization(
         self,
-        to: Iterable[str],
+        to: List[Any],
         msg: EmailMessage,
         extra_headers: Iterable[Header],
-        personalizations: Dict = None,
+        existing_personalizations: Optional[Personalization] = None,
     ) -> Personalization:
         """
         Constructs a Sendgrid Personalization instance / row for the given recipients.
@@ -257,41 +262,44 @@ def _build_sg_personalization(
             to: The email addresses for the given personalization.
             msg: The base Django Email message object - used to fill (missing) personalization data
             extra_headers: The non "reply-to" headers for the personalization.
-            personalizations: Personalization data, eg. dynamic_template_data or substitutions.
+            existing_personalizations: Personalization data, eg. dynamic_template_data or substitutions.
                 A given value should have key equivalent to corresponding msg attr
 
 
         Returns:
             A sendgrid personalization instance
         """
+        personalization = existing_personalizations or Personalization()
 
-        personalizations = personalizations or {}
-        personalization = Personalization()
-
-        for addr in msg.to:
-            personalization.add_to(Email(*self._parse_email_address(addr)))
+        if to:
+            if type(to[0]) == str:
+                for addr in to:
+                    personalization.add_to(Email(*self._parse_email_address(addr)))
+            else:
+                personalization.tos = to
 
-        for addr in personalizations.get("cc") or msg.cc:
-            personalization.add_cc(Email(*self._parse_email_address(addr)))
+        if not personalization.ccs:
+            for addr in msg.cc:
+                personalization.add_cc(Email(*self._parse_email_address(addr)))
 
-        for addr in personalizations.get("bcc") or msg.bcc:
-            personalization.add_bcc(Email(*self._parse_email_address(addr)))
+        if not personalization.bccs:
+            for addr in msg.bcc:
+                personalization.add_bcc(Email(*self._parse_email_address(addr)))
 
-        for k, v in personalizations.get(
-            "custom_args",
-            getattr(msg, "custom_args", {}),
-        ).items():
-            personalization.add_custom_arg(CustomArg(k, v))
+        if not personalization.custom_args:
+            for k, v in getattr(msg, "custom_args", {}).items():
+                personalization.add_custom_arg(CustomArg(k, v))
 
         if self._is_transaction_template(msg):
-            if msg.subject:
+            if personalization.subject or msg.subject:
                 logger.warning(
                     "Message subject is ignored in transactional template, "
                     "please add it as template variable (e.g. {{ subject }}"
                 )
                 # See https://github.com/sendgrid/sendgrid-nodejs/issues/843
-        else:
-            personalization.subject = personalizations.get("subject") or msg.subject
+
+        if not personalization.subject:
+            personalization.subject = msg.subject
 
         for header in extra_headers:
             personalization.add_header(header)
@@ -308,15 +316,12 @@ def _build_sg_personalization(
             personalization.send_at = msg.send_at
 
         if hasattr(msg, "template_id"):
-            for k, v in personalizations.get(
-                "substitutions",
-                getattr(msg, "substitutions", {}),
-            ).items():
-                personalization.add_substitution(Substitution(k, v))
-
-            dtd = personalizations.get(
-                "dynamic_template_data",
-                getattr(msg, "dynamic_template_data", None),
+            if not personalization.substitutions:
+                for k, v in getattr(msg, "substitutions", {}).items():
+                    personalization.add_substitution(Substitution(k, v))
+
+            dtd = personalization.dynamic_template_data or getattr(
+                msg, "dynamic_template_data", None
             )
             if dtd:
                 if SENDGRID_5:
@@ -420,13 +425,17 @@ def _build_sg_mail(self, msg: EmailMessage) -> Dict:
 
         if hasattr(msg, "personalizations"):
             for personalization in msg.personalizations:
-                to = personalization.pop("to")
+                if type(personalization) == Dict:
+                    personalization = dict_to_personalization(personalization)
+
+                assert type(personalization) == Personalization
+
                 mail.add_personalization(
                     self._build_sg_personalization(
-                        to,
+                        personalization.tos or msg.to,
                         msg,
                         personalization_headers,
-                        personalizations=personalization,
+                        existing_personalizations=personalization,
                     )
                 )
         elif getattr(msg, "make_private", False):

sendgrid_backend/util.py

@@ -1,5 +1,8 @@
+from typing import Any, Dict
+
 import sendgrid
 from django.conf import settings
+from sendgrid.helpers.mail import Personalization
 
 SENDGRID_VERSION = sendgrid.__version__
 
@@ -14,3 +17,30 @@ def get_django_setting(setting_str, default=None):
     if hasattr(settings, setting_str):
         return getattr(settings, setting_str, default)
     return default
+
+
+def dict_to_personalization(data: Dict[Any, Any]) -> Personalization:
+    """
+    Reverses Sendgrid's Personalization.get() method to create a Personalization
+    object from its emitted data structure (in the form of a Dict)
+    """
+    personalization = Personalization()
+
+    properties = [
+        p
+        for p in dir(Personalization)
+        if isinstance(getattr(Personalization, p), property)
+    ]
+    for attr in properties:
+        if attr in ["tos", "ccs", "bccs"]:
+            key = attr[:-1]
+        else:
+            key = attr
+
+        value = data.get(key, None)
+
+        if value:
+            setattr(personalization, attr, value)
+            getattr(personalization, attr)
+
+    return personalization

test/test_echo_to_stream.py

@@ -1,5 +1,3 @@
-import os
-import sys
 import warnings
 from unittest.mock import MagicMock
 

test/test_mail.py

@@ -1,13 +1,22 @@
 import base64
-import sys
 from email.mime.image import MIMEImage
 
 from django.core.mail import EmailMessage, EmailMultiAlternatives
 from django.test import override_settings
 from django.test.testcases import SimpleTestCase
+from sendgrid.helpers.mail import (
+    CustomArg,
+    Email,
+    Header,
+    Personalization,
+    Substitution,
+)
 
 from sendgrid_backend.mail import SendgridBackend
-from sendgrid_backend.util import SENDGRID_5
+from sendgrid_backend.util import SENDGRID_5, SENDGRID_6, dict_to_personalization
+
+if SENDGRID_6:
+    from sendgrid.helpers.mail import Bcc, Cc, To
 
 
 class TestMailGeneration(SimpleTestCase):
@@ -480,12 +489,109 @@ def test_EmailMessage_custom_args(self):
 
         self.assertDictEqual(result, expected)
 
-    """
-    todo: Implement these
-    def test_attachments(self):
-        pass
+    def test_personalizations_resolution(self):
+        """
+        Tests that adding a Personalization() object directly to an EmailMessage object
+        works as expected.
+
+        Written to test functionality introduced in the PR:
+        https://github.com/sklarsa/django-sendgrid-v5/pull/90
+        """
+        msg = EmailMessage(
+            subject="Hello, World!",
+            body="Hello, World!",
+            from_email="Sam Smith <sam.smith@example.com>",
+            to=["John Doe <john.doe@example.com>", "jane.doe@example.com"],
+            cc=["Stephanie Smith <stephanie.smith@example.com>"],
+            bcc=["Sarah Smith <sarah.smith@example.com>"],
+            reply_to=["Sam Smith <sam.smith@example.com>"],
+        )
+
+        # Tests that personalizations take priority
+        test_str = "admin@my-test-domain.com"
+        test_key_str = "my key"
+        test_val_str = "my val"
+        personalization = Personalization()
+
+        if SENDGRID_5:
+            personalization.add_to(Email(test_str))
+            personalization.add_cc(Email(test_str))
+            personalization.add_bcc(Email(test_str))
+        else:
+            personalization.add_to(To(test_str))
+            personalization.add_cc(Cc(test_str))
+            personalization.add_bcc(Bcc(test_str))
+
+        personalization.add_custom_arg(CustomArg(test_key_str, test_val_str))
+        personalization.add_header(Header(test_key_str, test_val_str))
+        personalization.add_substitution(Substitution(test_key_str, test_val_str))
+
+        msg.personalizations = [personalization]
+
+        result = self.backend._build_sg_mail(msg)
+
+        personalization = result["personalizations"][0]
+
+        for field in ("to", "cc", "bcc"):
+            data = personalization[field]
+            self.assertEquals(len(data), 1)
+            self.assertEquals(data[0]["email"], test_str)
+
+        for field in ("custom_args", "headers", "substitutions"):
+            data = personalization[field]
+            self.assertEquals(len(data), 1)
+            self.assertIn(test_key_str, data)
+            self.assertEquals(test_val_str, data[test_key_str])
+
+    def test_dict_to_personalization(self):
+        """
+        Tests that dict_to_personalization works
+        """
+        data = {
+            "to": [
+                {"email": "john.doe@example.com", "name": "John Doe"},
+                {
+                    "email": "jane.doe@example.com",
+                },
+            ],
+            "cc": [
+                {
+                    "email": "stephanie.smith@example.com",
+                    "name": "Stephanie Smith",
+                }
+            ],
+            "bcc": [{"email": "sarah.smith@example.com", "name": "Sarah Smith"}],
+            "subject": "Hello, World!",
+            "custom_args": {"arg_1": "Foo", "arg_2": "bar"},
+            "headers": {"header_1": "Foo", "header_2": "Bar"},
+            "substitutions": {"sub_a": "foo", "sub_b": "bar"},
+            "send_at": 1518108670,
+            "dynamic_template_data": {
+                "subject": "Hello, World!",
+                "content": "Hello, World!",
+                "link": "http://hello.com",
+            },
+        }
 
-    def test_headers(self):
-        pass
+        p = dict_to_personalization(data)
+
+        fields_to_test = (
+            ("tos", "to"),
+            ("ccs", "cc"),
+            ("bccs", "bcc"),
+            ("subject", "subject"),
+            ("custom_args", "custom_args"),
+            ("headers", "headers"),
+            ("substitutions", "substitutions"),
+            ("send_at", "send_at"),
+            ("dynamic_template_data", "dynamic_template_data"),
+        )
 
-    """
+        for arg, key in fields_to_test:
+            val = getattr(p, arg)
+            if type(val) == list:
+                self.assertListEqual(val, data[key])
+            elif type(val) == dict:
+                self.assertDictEqual(val, data[key])
+            else:
+                self.assertEquals(val, data[key])