Improve and document JSON serialization for Mandrill API

* Add some context to exceptions on unserializable
  values (addresses #89).
* Document need to format merge data
  (into something JSON-serializable).
* Add RemovedInDjrill2 DeprecationWarning.
* Deprecate blanket date/datetime serialization.

djrill/tests/mock_backend.py

@@ -5,12 +5,12 @@ import six
 
 from django.test import TestCase
 
-from .utils import override_settings
+from .utils import BackportedAssertions, override_settings
 
 
 @override_settings(MANDRILL_API_KEY="FAKE_API_KEY_FOR_TESTING",
                    EMAIL_BACKEND="djrill.mail.backends.djrill.DjrillBackend")
-class DjrillBackendMockAPITestCase(TestCase):
+class DjrillBackendMockAPITestCase(TestCase, BackportedAssertions):
     """TestCase that uses Djrill EmailBackend with a mocked Mandrill API"""
 
     class MockResponse(requests.Response):

djrill/tests/test_legacy.py

@@ -1,10 +1,56 @@
 # Tests deprecated Djrill features
 
+from datetime import date, datetime
+import warnings
+
+from django.core import mail
 from django.test import TestCase
 
 from djrill.mail import DjrillMessage
 from djrill import MandrillAPIError, NotSupportedByMandrillError
 
+from .mock_backend import DjrillBackendMockAPITestCase
+
+
+class DjrillBackendDeprecationTests(DjrillBackendMockAPITestCase):
+
+    def test_deprecated_json_date_encoding(self):
+        """Djrill 2.0+ avoids a blanket JSONDateUTCEncoder"""
+        # Djrill allows dates for send_at, so shouldn't warn:
+        message = mail.EmailMessage('Subject', 'Body', 'from@example.com', ['to@example.com'])
+        message.send_at = datetime(2022, 10, 11, 12, 13, 14, 567)
+        self.assertNotWarns(DeprecationWarning, message.send)
+
+        # merge_vars need to be json-serializable, so should generate a warning:
+        message = mail.EmailMessage('Subject', 'Body', 'from@example.com', ['to@example.com'])
+        message.global_merge_vars = {'DATE': date(2022, 10, 11)}
+        self.assertWarnsMessage(DeprecationWarning,
+                                "Djrill 2.0 will require you to explicitly convert this date to a string",
+                                message.send)
+        # ... but should still encode the date (for now):
+        data = self.get_api_call_data()
+        self.assertEqual(data['message']['global_merge_vars'],
+                         [{'name': 'DATE', 'content': "2022-10-11 00:00:00"}])
+
+    def assertWarnsMessage(self, warning, message, callable, *args, **kwds):
+        """Checks that `callable` issues a warning of category `warning` containing `message`"""
+        with warnings.catch_warnings(record=True) as warned:
+            warnings.simplefilter("always")
+            callable(*args, **kwds)
+        self.assertGreater(len(warned), 0, msg="No warnings issued")
+        self.assertTrue(
+            any(issubclass(w.category, warning) and message in str(w.message) for w in warned),
+            msg="%r(%r) not found in %r" % (warning, message, [str(w) for w in warned]))
+
+    def assertNotWarns(self, warning, callable, *args, **kwds):
+        """Checks that `callable` does not issue any warnings of category `warning`"""
+        with warnings.catch_warnings(record=True) as warned:
+            warnings.simplefilter("always")
+            callable(*args, **kwds)
+        relevant_warnings = [w for w in warned if issubclass(w.category, warning)]
+        self.assertEqual(len(relevant_warnings), 0,
+                         msg="Unexpected warnings %r" % [str(w) for w in relevant_warnings])
+
 
 class DjrillMessageTests(TestCase):
     """Test the DjrillMessage class (deprecated as of Djrill v0.2.0)

djrill/tests/test_mandrill_send.py

@@ -4,6 +4,7 @@ from __future__ import unicode_literals
 
 from base64 import b64decode
 from datetime import date, datetime, timedelta, tzinfo
+from decimal import Decimal
 from email.mime.base import MIMEBase
 from email.mime.image import MIMEImage
 import json
@@ -507,6 +508,16 @@ class DjrillMandrillFeatureTests(DjrillBackendMockAPITestCase):
         self.assertEqual(sent, 0)
         self.assertIsNone(msg.mandrill_response)
 
+    def test_json_serialization_warnings(self):
+        """Try to provide more information about non-json-serializable data"""
+        self.message.global_merge_vars = {'PRICE': Decimal('19.99')}
+        with self.assertRaisesMessage(
+                TypeError,
+                "Decimal('19.99') is not JSON serializable in a Djrill message (perhaps "
+                "it's a merge var?). Try converting it to a string or number first."
+        ):
+            self.message.send()
+
 
 @override_settings(EMAIL_BACKEND="djrill.mail.backends.djrill.DjrillBackend")
 class DjrillImproperlyConfiguredTests(TestCase):

djrill/tests/utils.py

@@ -1,4 +1,8 @@
+import re
+import six
+
 __all__ = (
+    'BackportedAssertions',
     'override_settings',
 )
 
@@ -66,3 +70,19 @@ except ImportError:
             #     new_value = getattr(settings, key, None)
             #     setting_changed.send(sender=settings._wrapped.__class__,
             #                          setting=key, value=new_value)
+
+
+class BackportedAssertions(object):
+    """Handful of useful TestCase assertions backported to Python 2.6/Django 1.3"""
+
+    # Backport from Python 2.7/3.1
+    def assertIn(self, member, container, msg=None):
+        """Just like self.assertTrue(a in b), but with a nicer default message."""
+        if member not in container:
+            self.fail(msg or '%r not found in %r' % (member, container))
+
+    # Backport from Django 1.4
+    def assertRaisesMessage(self, expected_exception, expected_message,
+                            callable_obj=None, *args, **kwargs):
+        return six.assertRaisesRegex(self, expected_exception, re.escape(expected_message),
+                                     callable_obj, *args, **kwargs)