Add, document SendableEmail.create_message. Fixes #35, #36.

Author: toolness

docs/quickstart.rst

@@ -69,6 +69,9 @@ version of the email will use "Jane Doe".
 The email will also contain a call-to-action (CTA) that directs the
 user to a website.
 
+Registering the email with the gallery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Now we just need to let the email example gallery know about the
 existence of your new template. Do this by adding the following to
 your project's ``settings.py``:
@@ -81,3 +84,17 @@ your project's ``settings.py``:
 Now you're set! Start your app and visit ``/examples/``; you should
 see the email gallery with a single entry, and be able to view your
 example email as HTML and plaintext.
+
+Sending the email
+~~~~~~~~~~~~~~~~~
+
+You can create a Django :py:class:`~django.core.mail.EmailMessage` with your
+email's :py:meth:`~emailpal.SendableEmail.create_message` method like so:
+
+.. literalinclude:: ../emailpal/tests/test_sendable_email.py
+   :language: python
+   :dedent: 4
+   :start-after: Start create_message doc snippet
+   :end-before: End create_message doc snippet
+
+Then you can send the message with ``msg.send()``.

docs/sendable-emails.rst

@@ -6,4 +6,4 @@ Sendable emails
 .. currentmodule:: emailpal
 
 .. autoclass:: SendableEmail
-   :members: subject, template_name, send_messages
+   :members: subject, template_name, create_message

emailpal/sendable_email.py

@@ -2,7 +2,7 @@
 import re
 from typing import Dict, TypeVar, Generic, Dict, Any, cast  # NOQA
 from django.utils.safestring import SafeString
-from django.core.mail import EmailMultiAlternatives
+from django.core.mail import EmailMultiAlternatives, EmailMessage
 from django.template.loader import render_to_string
 from django.utils.html import strip_tags
 
@@ -64,7 +64,7 @@ def subject(self) -> str:
         :py:meth:`str.format` and passed the same context that is
         passed to templates when rendering the email, so you can
         include context variables via brace notation, e.g.
-        ``Hello {full_name}!``.
+        ``"Hello {full_name}!"``.
         '''
 
         pass  # pragma: no cover
@@ -74,7 +74,7 @@ def subject(self) -> str:
     def template_name(self) -> str:
         '''
         The path to the template used to render the email, e.g.
-        ``my_app/my_email.html``.
+        ``"my_app/my_email.html"``.
         '''
 
         pass  # pragma: no cover
@@ -109,14 +109,17 @@ def render_body_as_html(self, ctx: T) -> SafeString:
     def render_subject(self, ctx: T) -> str:
         return self.subject.format(**self._cast_to_dict(ctx))
 
-    def send_messages(self, ctx: T, from_email=None, to=None, bcc=None,
-                      connection=None, attachments=None, headers=None,
-                      alternatives=None, cc=None, reply_to=None) -> int:
+    def create_message(self, ctx: T, from_email=None, to=None, bcc=None,
+                       connection=None, attachments=None, headers=None,
+                       alternatives=None, cc=None,
+                       reply_to=None) -> EmailMessage:
         '''
-        Renders the email using context specified by ``ctx`` and sends it.
+        Creates and returns a :py:class:`django.core.mail.EmailMessage`
+        which contains the plaintext and HTML versions of the email,
+        using the context specified by ``ctx``.
 
         Aside from ``ctx``, arguments to this method are the
-        same as those for :py:class:`django.core.mail.EmailMessage`.
+        same as those for :py:class:`~django.core.mail.EmailMessage`.
         '''
 
         msg = EmailMultiAlternatives(
@@ -133,4 +136,4 @@ def send_messages(self, ctx: T, from_email=None, to=None, bcc=None,
             reply_to=reply_to,
         )
         msg.attach_alternative(self.render_body_as_html(ctx), 'text/html')
-        return msg.send(fail_silently=False)
+        return msg

emailpal/tests/test_sendable_email.py

@@ -47,15 +47,17 @@ def mail_connection():
 
 
 def test_email_sending_works(mail_connection):
-    ctx = MyContext(full_name='boop jones')
-    e = MySendableEmail()
-    num_sent = e.send_messages(
-        ctx,
+    # Start create_message doc snippet
+    msg = MySendableEmail().create_message(
+        {'full_name': 'boop jones'},
         from_email='foo@example.org',
         to=['bar@example.org'],
         headers={'Message-ID': 'blah'},
-        connection=mail_connection
     )
+    # End create_message doc snippet
+
+    msg.connection = mail_connection
+    num_sent = msg.send(fail_silently=False)
     assert num_sent == 1
     assert len(mail.outbox) == 1
     msg = mail.outbox[0]