app/soc/logic/mail_dispatcher.py

# Copyright 2008 the Melange authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Functions used to send email messages.

The following are the possible fields of an email message:

  sender: The email address of the sender, the From address. This must be the
    email address of a registered administrator for the application, or the
    address of the current signed-in user. Administrators can be added to
    an application using the Administration Console. The current user's email
    address can be determined with the Users API.
  to: A recipient's email address (a string) or a list of email addresses to
    appear on the To: line in the message header.
  cc: A recipient's email address (a string) or a list of email addresses to
    appear on the Cc: line in the message header.
  bcc: A recipient's email address (a string) or a list of email addresses to
    receive the message, but not appear in the message header ("blind carbon
    copy").
  reply_to: An email address to which a recipient should reply instead of the
    sender address, the Reply-To: field.
  subject: The subject of the message, the Subject: line.
  body: The plaintext body content of the message.
  html: An HTML version of the body content, for recipients that
    prefer HTML email.
  attachments: The file attachments for the message, as a list of two-value
    tuples, one tuple for each attachment. Each tuple contains a filename as
    the first element, and the file contents as the second element.
    An attachment file must be one of the allowed file types, and the
    filename must end with an extension that corresponds with the type.
    For a list of allowed types and filename extensions, see Allowed
    Attachment Types.

Usage:

  context = { 'sender': 'melange-noreply@example.com',
              'to': 'test@example.com',
              'subject': 'You have been invited to become a Host',
              'sender_name': 'Alice',
              'to_name': 'Melange Team',
              'role': 'Host',
              'group': 'Google Summer of Code 2009',
              'invitation_url': 'http://invitation-url'}

  sendMailFromTemplate('soc/mail/invitation.html', context)
"""


from django.template import Context
from django.template import loader

from google.appengine.api import mail
from google.appengine.ext import db

from soc.logic import dicts
from soc.logic import system
from soc.tasks import mailer


def sendMailFromTemplate(template, context):
  """Sends out an email using a Django template.

  If 'html' is present in context dictionary it is overwritten with
  template HTML output.

  Args:
    template: the template (or search list of templates) to use
    context: The context supplied to the template and email (dictionary)

  Raises:
    Error that corresponds with the first problem it finds iff the message
    is not properly initialized.

    List of all possible errors:
      http://code.google.com/appengine/docs/mail/exceptions.html
  """

  # render the template and put in context with 'html' as key
  context['html'] = loader.render_to_string(template, dictionary=context)

  # filter out the unneeded values in context to keep sendMail happy
  sendMail(dicts.filter(context, mail.EmailMessage.PROPERTIES))


def getSendMailFromTemplateNameTxn(template_name, context, parent=None,
    transactional=True):
  """Returns a method that is safe to be run in a transaction to sent out an
     email using a Django template_name.

  See sendMailFromTemplate() for more information.

  Args:
    parent: The parent entity to use for the transaction.
    context: The context passed on to sendMail.
    parent: An optional parent entity of the to be created mail entity.
    transactional: Whether the task should be created transactionally.
  """
  # render the template and put in context with 'html' as key
  context['html'] = loader.render_to_string(template_name, dictionary=context)

  # filter out the unneeded values in context to keep sendMail happy
  return sendMail(dicts.filter(context, mail.EmailMessage.PROPERTIES),
                  parent=parent, run=False, transactional=transactional)


def getSendMailFromTemplateStringTxn(template_string, context, parent=None,
    transactional=True):
  """Returns a method that is safe to be run in a transaction to sent out an
     email using a Django template which is represented by the specified
     string instance.

  See sendMailFromTemplate() for more information.

  Args:
    parent: The parent entity to use for the transaction.
    context: The context passed on to sendMail.
    parent: An optional parent entity of the to be created mail entity.
    transactional: Whether the task should be created transactionally.
  """
  # create Template instance based on the string representation
  template = loader.get_template_from_string(template_string)

  return getSendMailFromTemplateTxn(template, context, parent=parent,
      transactional=transactional)


def getSendMailFromTemplateTxn(template, context, parent=None,
    transactional=True):
  """Returns a method that is safe to be run in a transaction to sent out an
     email using a Django Template instance.

  See sendMailFromTemplate() for more information.

  Args:
    parent: The parent entity to use for the transaction.
    context: The context passed on to sendMail.
    parent: An optional parent entity of the to be created mail entity.
    transactional: Whether the task should be created transactionally.
  """

  context_instance = Context(context)
  context['html'] = template.render(context_instance)

  # filter out the unneeded values in context to keep sendMail happy
  return sendMail(dicts.filter(context, mail.EmailMessage.PROPERTIES),
                  parent=parent, run=False, transactional=transactional)


def sendMail(context, parent=None, run=True, transactional=True):
  """Sends out an email using context to supply the needed information.

  Args:
    context: The context supplied to the email message (dictionary)
    parent: The parent entity to use for when this mail is to be sent in a
            transaction.
    run: If true the mail will be sent otherwise the function that can sent
         the mail will be returned.
    transactional: Whether the task should be created transactionally.

  Raises:
    Error that corresponds with the first problem it finds iff the message
    is not properly initialized.

    List of all possible errors:
      http://code.google.com/appengine/docs/mail/exceptions.html
  """
  # construct the EmailMessage from the given context
  message = mail.EmailMessage(**context)
  message.check_initialized()

  # don't send out emails in non-local debug mode
  if not system.isLocal() and system.isDebug():
    return

  txn = mailer.getSpawnMailTaskTxn(
      context=context, parent=parent, transactional=transactional)
  if run:
    return db.RunInTransaction(txn)
  else:
    return txn


def getDefaultMailSender(data=None):
  """Returns the sender that currently can be used to send emails.

  Args:
    data: an option RequestData object

  Returns:
    - A tuple containing (sender_name, sender_address)
    Consisting of:
  """
  from soc.logic import site

  # check if there is a noreply email address set

  if data:
    site_entity = data.site
  else:
    site_entity = site.singleton()

  no_reply_email = system.getApplicationNoReplyEmail()

  return (site_entity.site_name, no_reply_email)