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/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)