Added personalization and i18n features

Author: zefciu

.gitignore

@@ -7,6 +7,7 @@
 # Distribution
 build/
 dist/
+django_templated_mail.egg-info
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -36,4 +37,7 @@ ENV/
 *.DS_Store
 
 # logs
-*.log
+*.log
+
+# vim
+*.swp

docs/source/index.rst

@@ -13,6 +13,7 @@ Welcome to django-templated-mail documentation!
    settings
    templates_syntax
    sample_usage
+   personalization
 
 Indices and tables
 ==================

docs/source/personalization.rst

@@ -0,0 +1,34 @@
+Personalizing e-mails
+========================
+
+
+
+Interpolating user data
+------------------------------
+
+If you want to put some personal data of your user in the e-mail, you may use
+the ``user`` variable in your context. To use this variable you either need to
+pass the ``request`` object when creating the ``BaseEmailMessage``:
+
+.. code-block:: python
+    email_message = BaseEmailMessage(
+        request=request,
+        template_name='personalized_mail.html'
+    )
+
+or you need to specify actual user objects in the `to` field:
+
+.. code-block:: python
+    email_message.send(to=[user1, user2], single_email=False)
+
+i18n
+------
+
+Django features some pretty nice i18n mechanism, but it can be insufficient
+when emailing your users. Your e-mails will ofter be sent from inside a celery
+task, where the ``request`` object is not accessible. If you still want to
+translate the e-mail for your userbase, you need to specify the `locale_field`
+value in your settings. This value should point to a field (or a property)
+on your user models that contains their locale (it is up to you,
+how do you populate this field). If you then send personalized emails, as
+described above, they will be translated to your users' locales.

docs/source/settings.rst

@@ -5,8 +5,12 @@ You may optionally provide following settings:
 
 .. code-block:: python
 
-    'DOMAIN': 'example.com'
-    'SITE_NAME': 'Foo Website'
+'TEMPLATED_MAIL': {
+    'DOMAIN': 'example.com',
+    'SITE_NAME': 'Foo Website',
+    LOCALE_FIELD: 'locale',
+}
+
 
 DOMAIN
 ------
@@ -25,4 +29,12 @@ Used in email template context. Usually it will contain the desired title of you
 app. If not provided the current site's name will be used.
 
 
-**Default**: ``False``
+**Required**: ``False``
+
+LOCALE_FIELD
+------------------
+
+The field on a user model that contains the locale name to be used. If not
+specified, the per-user i18n is disabled.
+
+**Required**: ``False``

manage.py

@@ -0,0 +1,8 @@
+import os
+import sys
+
+if __name__ == "__main__":
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "tests.settings")
+    from django.core.management import execute_from_command_line
+    args = sys.argv
+    execute_from_command_line(args)

requirements/base

@@ -1 +1,2 @@
 django>=1.8
+six==1.12.0

requirements/test

@@ -3,4 +3,5 @@ flake8==3.4.1
 pytest==3.2.2
 pytest-cov==2.5.1
 pytest-django==3.1.2
-pytest-pythonpath==0.7.1
+pytest-pythonpath==0.7.1
+six==1.12.0

templated_mail/mail.py

@@ -1,12 +1,38 @@
+import copy
+import contextlib
+import six
+
 from django.conf import settings
+from django.contrib.auth.models import AbstractBaseUser
 from django.contrib.sites.shortcuts import get_current_site
 from django.core import mail
+from django.utils import translation
 from django.template.context import make_context
 from django.template.loader import get_template
 from django.template.loader_tags import BlockNode, ExtendsNode
 from django.views.generic.base import ContextMixin
 
 
+LOCALE_FIELD = getattr(
+    settings, 'TEMPLATED_MAIL', {}
+).get('locale_field', None)
+
+
+@contextlib.contextmanager
+def translation_context(language):
+    prev_language = translation.get_language()
+    try:
+        translation.activate(language)
+        yield
+    finally:
+        translation.activate(prev_language)
+
+
+@contextlib.contextmanager
+def nullcontext():
+    yield
+
+
 class BaseEmailMessage(mail.EmailMultiAlternatives, ContextMixin):
     _node_map = {
         'subject': 'subject',
@@ -25,8 +51,9 @@ def __init__(self, request=None, context=None, template_name=None,
 
         if template_name is not None:
             self.template_name = template_name
+        self.is_rendered = False
 
-    def get_context_data(self, **kwargs):
+    def get_context_data(self, user=None, **kwargs):
         ctx = super(BaseEmailMessage, self).get_context_data(**kwargs)
         context = dict(ctx, **self.context)
         if self.request:
@@ -40,14 +67,14 @@ def get_context_data(self, **kwargs):
             site_name = context.get('site_name') or (
                 getattr(settings, 'SITE_NAME', '') or site.name
             )
-            user = context.get('user') or self.request.user
+            user = user or context.get('user') or self.request.user
         else:
             domain = context.get('domain') or getattr(settings, 'DOMAIN', '')
             protocol = context.get('protocol') or 'http'
             site_name = context.get('site_name') or getattr(
                 settings, 'SITE_NAME', ''
             )
-            user = context.get('user')
+            user = user or context.get('user')
 
         context.update({
             'domain': domain,
@@ -57,27 +84,62 @@ def get_context_data(self, **kwargs):
         })
         return context
 
-    def render(self):
-        context = make_context(self.get_context_data(), request=self.request)
+    def render(self, user=None):
+        if self.is_rendered:
+            return
+        context = make_context(
+            self.get_context_data(user),
+            request=self.request,
+        )
+        if user is None or LOCALE_FIELD is None:
+            language_context = nullcontext()
+        else:
+            language_context = translation_context(
+                getattr(user, LOCALE_FIELD)
+            )
         template = get_template(self.template_name)
-        with context.bind_template(template.template):
+        with language_context, context.bind_template(template.template):
             blocks = self._get_blocks(template.template.nodelist, context)
             for block_node in blocks.values():
                 self._process_block(block_node, context)
         self._attach_body()
+        self.is_rendered = True
 
-    def send(self, to, *args, **kwargs):
-        self.render()
-
-        self.to = to
-        self.cc = kwargs.pop('cc', [])
-        self.bcc = kwargs.pop('bcc', [])
-        self.reply_to = kwargs.pop('reply_to', [])
-        self.from_email = kwargs.pop(
-            'from_email', settings.DEFAULT_FROM_EMAIL
-        )
-
-        super(BaseEmailMessage, self).send(*args, **kwargs)
+    def send(self, to, single_email=True, *args, **kwargs):
+        if single_email:
+            self.render()
+            to_emails = []
+            for recipient in to:
+                if isinstance(recipient, AbstractBaseUser):
+                    to_emails.append(recipient.email)
+                elif isinstance(recipient, six.string_types):
+                    to_emails.append(recipient)
+                else:
+                    raise TypeError(
+                        'The `to` argument should contain strings or users'
+                    )
+            self.to = to_emails
+            self.cc = kwargs.pop('cc', [])
+            self.bcc = kwargs.pop('bcc', [])
+            self.reply_to = kwargs.pop('reply_to', [])
+            self.from_email = kwargs.pop(
+                'from_email', settings.DEFAULT_FROM_EMAIL
+            )
+            super(BaseEmailMessage, self).send(*args, **kwargs)
+        else:
+            for recipient in to:
+                email = copy.copy(self)
+                if isinstance(recipient, AbstractBaseUser):
+                    email_to = [recipient.email]
+                    email.render(user=recipient)
+                elif isinstance(recipient, six.string_types):
+                    email_to = [recipient]
+                    email.render()
+                else:
+                    raise TypeError(
+                        'The `to` argument should contain strings or users'
+                    )
+                email.send(to=email_to, *args, **kwargs)
 
     def _process_block(self, block_node, context):
         attr = self._node_map.get(block_node.name)

tests/locale/ka_GE/LC_MESSAGES/django.po

@@ -0,0 +1,23 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2019-03-08 15:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <[email protected]>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#: tests/templates/personalized_mail.html:4
+#: tests/templates/personalized_mail.html:5
+msgid "Hello"
+msgstr "გამარჯობა"

tests/locale/pl_PL/LC_MESSAGES/django.po

@@ -0,0 +1,23 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2019-04-01 09:54+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <[email protected]>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#: tests/templates/personalized_mail.html:4
+#: tests/templates/personalized_mail.html:5
+msgid "Hello"
+msgstr "Cześć"