<commit_before>"""
:mod:`django-email-from-template` --- send emails generated entirely from Django templates
===========================================================================================

``email_from_template`` generates and sends mail defined in Django templates to
avoid presentation layer violations. It has the following features:

 * HTML email support
 * Context processor system
 * Support for non-Django template rendering systems

Whilst Django provides a comprehensive mail framework that simplifies the
sending mechanics of email, the typical use of it is often ugly and results in
unnecessary and complicated string formatting inside views or forms::

    from django.core.mail import send_mail
    from django.core.urlresolvers import reverse
    from django.contrib.sites.models import Site

    # XXX: Bad! Shouldn't be in views.py
    send_mail(
        'Hi %s, %d %s written on your wall' % (
            user.username,
            num_posts > 1 and 'people have' or 'person has',
        ),
        'Hi %s\\n\\nCheck out what they wrote here:\\n\\n %s%s\\n\\n' % (
            user.username,
            Site.objects.get_current(),url,
            reverse('profile:view', args=(user.username,)),
        ),
        '<EMAIL>',
        [user.email],
        fail_silently=False,
    )

With :mod:`django-email-from-template`, you can relegate all this formatting to
the presentation layer as well as leverage any existing templatetags and
filters. First we define our template::

    {% extends email_from_template %}

    {% block subject %}
    Hi {{ user.username }}, {{ num_posts }} {{ num_posts|pluralize:"person has,people have" }} written on your wall
    {% endblock %}

    {% block body %}
    Hi {{ user.username }}.

    Check out what they wrote here:

      {{ settings.SITE_URL }}{% url profile:view user.username %}
    {% endblock %}

We then simply call our template-aware version of ``send_mail`` with the
appropriate context::

    from email_from_template import send_mail

    send_mail([user.email], 'path/to/my_email.email', {
        'user': user,
        'num_posts': num_posts,
    })

Now your views or forms are not cluttered with unnecessary presentation logic.

For HTML-enabled mail readers, we can optionally include suitable content
within a "html" block::

    {% block html %}
    <p>Hi <strong>{{ user.username }}</strong></p>
    <p>Check out what they wrote here:</p>
    <a href="{{ setings.SITE_URL }}{% url profile:view user.username %}">
        {{ settings.SITE_URL }}{% url profile:view user.username %}
    </a>
    {% endblock %}

:mod:`django-email-from-template` also has the ability to only send the email
when the current transaction commits. Pass ``on_commit=True`` to ``send_mail``
to enable this functionality - for backwards compatability and predictability
it is not enabled by default. Note that the rendering still occurs during the
transaction, it is only the sending that is deferred - this is desirable as it
means that failing to render a template will still result in a transaction
rolling back.::

    from email_from_template import send_mail

    send_mail([user.email], 'path/to/my_email.email', {
        'user': user,
        'num_posts': num_posts,
    }, on_commit=True)


Installation
------------

Add ``email_from_template`` to your ``INSTALLED_APPS``::

    INSTALLED_APPS = (
        ...
        'email_from_template',
        ...
    )

Context processors
------------------<commit_msg>Document the change in return type<commit_after>"""
:mod:`django-email-from-template` --- send emails generated entirely from Django templates
===========================================================================================

``email_from_template`` generates and sends mail defined in Django templates to
avoid presentation layer violations. It has the following features:

 * HTML email support
 * Context processor system
 * Support for non-Django template rendering systems

Whilst Django provides a comprehensive mail framework that simplifies the
sending mechanics of email, the typical use of it is often ugly and results in
unnecessary and complicated string formatting inside views or forms::

    from django.core.mail import send_mail
    from django.core.urlresolvers import reverse
    from django.contrib.sites.models import Site

    # XXX: Bad! Shouldn't be in views.py
    send_mail(
        'Hi %s, %d %s written on your wall' % (
            user.username,
            num_posts > 1 and 'people have' or 'person has',
        ),
        'Hi %s\\n\\nCheck out what they wrote here:\\n\\n %s%s\\n\\n' % (
            user.username,
            Site.objects.get_current(),url,
            reverse('profile:view', args=(user.username,)),
        ),
        '<EMAIL>',
        [user.email],
        fail_silently=False,
    )

With :mod:`django-email-from-template`, you can relegate all this formatting to
the presentation layer as well as leverage any existing templatetags and
filters. First we define our template::

    {% extends email_from_template %}

    {% block subject %}
    Hi {{ user.username }}, {{ num_posts }} {{ num_posts|pluralize:"person has,people have" }} written on your wall
    {% endblock %}

    {% block body %}
    Hi {{ user.username }}.

    Check out what they wrote here:

      {{ settings.SITE_URL }}{% url profile:view user.username %}
    {% endblock %}

We then simply call our template-aware version of ``send_mail`` with the
appropriate context::

    from email_from_template import send_mail

    send_mail([user.email], 'path/to/my_email.email', {
        'user': user,
        'num_posts': num_posts,
    })

Now your views or forms are not cluttered with unnecessary presentation logic.

For HTML-enabled mail readers, we can optionally include suitable content
within a "html" block::

    {% block html %}
    <p>Hi <strong>{{ user.username }}</strong></p>
    <p>Check out what they wrote here:</p>
    <a href="{{ setings.SITE_URL }}{% url profile:view user.username %}">
        {{ settings.SITE_URL }}{% url profile:view user.username %}
    </a>
    {% endblock %}

:mod:`django-email-from-template` also has the ability to only send the email
when the current transaction commits. Pass ``on_commit=True`` to ``send_mail``
to enable this functionality - for backwards compatability and predictability
it is not enabled by default. Note that the rendering still occurs during the
transaction, it is only the sending that is deferred - this is desirable as it
means that failing to render a template will still result in a transaction
rolling back.::

    from email_from_template import send_mail

    send_mail([user.email], 'path/to/my_email.email', {
        'user': user,
        'num_posts': num_posts,
    }, on_commit=True)

The return value of ``send_mail`` is, by default, the number of messages sent.
When passed ``on_commit=True``, we cannot know the number of messages that send
successfully until after the transaction commits, so we return ``None``. We
don't return 0 as this could indicate an explicit error (which has not
occurred), however care should be taken when checking this return code, to
ensure that 0 is checked for explicitly, as ``None`` is falsy.


Installation
------------

Add ``email_from_template`` to your ``INSTALLED_APPS``::

    INSTALLED_APPS = (
        ...
        'email_from_template',
        ...
    )

Context processors
------------------
{'fraction_non_alphanumeric': 0.12956008583690987, 'fraction_numerical': 0.000536480686695279, 'mean_word_length': 3.2562785388127855, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5979532', 'n_tokens_mistral': 2067, 'n_tokens_neox': 1945, 'n_words': 770}