Initial WIP commit - no testing plan yet

Dan · Dan · commit a836a4c440d0 · 2018-07-26T17:04:27.000+01:00
diff --git a/examples/helpers/mail/mail_example.py b/examples/helpers/mail/mail_example.py
@@ -35,8 +35,8 @@ def build_personalization(personalization):
     for header in personalization['headers']:
         mock_personalization.add_header(header)
 
-    for substitution in personalization['substitutions']:
-        mock_personalization.add_substitution(substitution)
+    for dynamic_template_data in personalization['dynamic_template_data']:
+        mock_personalization.add_dynamic_template_data(dynamic_template_data)
 
     for arg in personalization['custom_args']:
         mock_personalization.add_custom_arg(arg)
@@ -69,8 +69,8 @@ def get_mock_personalization_dict():
     mock_pers['headers'] = [Header("X-Test", "test"),
                             Header("X-Mock", "true")]
 
-    mock_pers['substitutions'] = [Substitution("%name%", "Example User"),
-                                  Substitution("%city%", "Denver")]
+    mock_pers['dynamic_template_data'] = [DynamicData("name", "Example User"),
+                                          DynamicData("city", "Denver")]
 
     mock_pers['custom_args'] = [CustomArg("user_id", "343"),
                                 CustomArg("type", "marketing")]
diff --git a/sendgrid/helpers/mail/dynamic_template_data.py b/sendgrid/helpers/mail/dynamic_template_data.py
@@ -0,0 +1,44 @@
+class DynamicData(object):
+    """Handlebars compatible dynamic data to be applied to the text and HTML
+    contents of the body of your email, as well as in the Subject and Reply-To
+    parameters.
+    """
+
+    def __init__(self, key=None, value=None):
+        """Create DynamicData with the given key and value.
+
+        :param key: Text to be replaced with "value" param
+        :type key: string, optional
+        :param value: Value to substitute into email
+        :type value: string or array of objects, optional
+        """
+        self.key = key
+        self.value = value
+
+    @property
+    def key(self):
+        return self._key
+
+    @key.setter
+    def key(self, value):
+        self._key = value
+
+    @property
+    def value(self):
+        return self._value
+
+    @value.setter
+    def value(self, value):
+        self._value = value
+
+    def get(self):
+        """
+        Get a JSON-ready representation of this DynamicData.
+
+        :returns: This DynamicData, ready for use in a request body.
+        :rtype: dict
+        """
+        dynamic_data = {}
+        if self.key is not None and self.value is not None:
+            dynamic_data[self.key] = self.value
+        return dynamic_data
diff --git a/sendgrid/helpers/mail/personalization.py b/sendgrid/helpers/mail/personalization.py
@@ -1,3 +1,6 @@
+import warnings
+
+
 class Personalization(object):
     """A Personalization defines who should receive an individual message and
     how that message should be handled.
@@ -10,6 +13,7 @@ def __init__(self):
         self._bccs = []
         self._subject = None
         self._headers = []
+        self._dynamic_template_data = []
         self._substitutions = []
         self._custom_args = []
         self._send_at = None
@@ -106,6 +110,31 @@ def add_header(self, header):
         """
         self._headers.append(header.get())
 
+    @property
+    def dynamic_template_data(self):
+        """Dynamic Template Data to be applied within this Personalization.
+        :rtype: list(dict)
+        """
+        return self._dynamic_template_data
+
+    @dynamic_template_data.setter
+    def dynamic_template_data(self, value):
+        if len(self.substitutions) > 0:
+            warnings.warn(
+                "Dynamic template data should not be used in conjunction with "
+                "substitutions")
+        self._dynamic_template_data = value
+
+    def add_dynamic_template_data(self, dynamic_template_data):
+        """Add a new Substitution to this Personalization.
+        :type substitution: Substitution
+        """
+        if len(self.substitutions) > 0:
+            warnings.warn(
+                "Dynamic template data should not be used in conjunction with "
+                "substitutions")
+        self._dynamic_template_data.append(dynamic_template_data.get())
+
     @property
     def substitutions(self):
         """Substitutions to be applied within this Personalization.
@@ -116,13 +145,21 @@ def substitutions(self):
 
     @substitutions.setter
     def substitutions(self, value):
+        if len(self.dynamic_template_data) > 0:
+            warnings.warn(
+                "Substitutions should not be used in conjunction with "
+                "dynamic template data")
         self._substitutions = value
 
     def add_substitution(self, substitution):
         """Add a new Substitution to this Personalization.
 
         :type substitution: Substitution
         """
+        if len(self.dynamic_template_data) > 0:
+            warnings.warn(
+                "Substitutions should not be used in conjunction with "
+                "dynamic template data")
         self._substitutions.append(substitution.get())
 
     @property
@@ -184,6 +221,12 @@ def get(self):
                 headers.update(key)
             personalization["headers"] = headers
 
+        if self.dynamic_template_data:
+            dynamic_template_data = {}
+            for key in self.dynamic_template_data:
+                dynamic_template_data.update(key)
+            personalization["dynamic_template_data"] = dynamic_template_data
+
         if self.substitutions:
             substitutions = {}
             for key in self.substitutions:
diff --git a/use_cases/README.md b/use_cases/README.md
@@ -14,7 +14,8 @@ This directory provides examples for specific use cases of this library. Please
 ### Working with Mail
 * [Asynchronous Mail Send](asynchronous_mail_send.md)
 * [Attachment](attachment.md)
-* [Transactional Templates](transational_templates.md)
+* [Dynamic Transactional Templates](dynamic_transational_templates.md)
+* [Legacy Transactional Templates](legacy_transational_templates.md)
 
 ### Library Features
 * [Error Handling](error_handling.md)
diff --git a/use_cases/dynamic_transactional_templates.md b/use_cases/dynamic_transactional_templates.md
@@ -0,0 +1,114 @@
+# Transactional Templates
+
+For this example, we assume you have created a [dynamic transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/how_to_send_an_email_with_transactional_templates.html). Following is the template content we used for testing.
+
+Template ID (replace with your own):
+
+```text
+d-5b08559ac97289da39defbb521bc62da
+```
+
+Email Subject:
+
+```text
+{{subject}}
+```
+
+Template Body:
+
+```html
+<html>
+<head>
+    <title></title>
+</head>
+<body>
+Hello {{name}},
+<br /><br/>
+I'm glad you are trying out the template feature!
+{{#if city}}
+<br /><br/>
+I hope you are having a great day in {{city.name}}, {{city.country}} :)
+{{/if}}
+<br /><br/>
+</body>
+</html>
+```
+
+## With Mail Helper Class
+
+```python
+import sendgrid
+import os
+from sendgrid.helpers.mail import Email, DynamicData, Mail, Personalization
+try:
+    # Python 3
+    import urllib.request as urllib
+except ImportError:
+    # Python 2
+    import urllib2 as urllib
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+from_email = Email("test@example.com")
+to_email = Email("test@example.com")
+mail = Mail(from_email, to_email)
+personalization = Personalization()
+personalization.add_dynamic_template_data(DynamicData("subject", "Dynamic Templating"))
+personalization.add_dynamic_template_data(DynamicData("name", "Example User"))
+personalization.add_dynamic_template_data(DynamicData("city", { "name": "Denver", "country": "USA" }))
+mail.template_id = "d-5b08559ac97289da39defbb521bc62da"
+
+try:
+    response = sg.client.mail.send.post(request_body=mail.get())
+except urllib.HTTPError as e:
+    print (e.read())
+    exit()
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
+
+## Without Mail Helper Class
+
+```python
+import sendgrid
+import os
+try:
+    # Python 3
+    import urllib.request as urllib
+except ImportError:
+    # Python 2
+    import urllib2 as urllib
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+data = {
+  "personalizations": [
+    {
+      "to": [
+        {
+          "email": "test@example.com"
+        }
+      ],
+      "dynamic_template_data": {
+        "subject": "Dynamic Templating",
+        "name": "Example User",
+        "city": {
+            "name": "Denver",
+            "country": "USA"
+        }
+      },
+    },
+  ],
+  "from": {
+    "email": "test@example.com"
+  },
+  "template_id": "d-5b08559ac97289da39defbb521bc62da"
+}
+try:
+    response = sg.client.mail.send.post(request_body=data)
+except urllib.HTTPError as e:
+    print (e.read())
+    exit()
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
diff --git a/use_cases/legacy_transational_templates.md b/use_cases/legacy_transational_templates.md
@@ -1,6 +1,6 @@
 # Transactional Templates
 
-For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing.
+For this example, we assume you have created a [legacy transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing.
 
 Template ID (replace with your own):
 
