#!/usr/bin/env python

#

# Copyright 2007 Google Inc.

#

# 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.

#

"""Sends email on behalf of application.

Provides functions for application developers to provide email services

for their applications.  Also provides a few utility methods.

"""

from email import MIMEBase

from email import MIMEMultipart

from email import MIMEText

from google.appengine.api import api_base_pb

from google.appengine.api import apiproxy_stub_map

from google.appengine.api import mail_service_pb

from google.appengine.api import users

from google.appengine.api.mail_errors import *

from google.appengine.runtime import apiproxy_errors

ERROR_MAP = {

}

EXTENSION_MIME_MAP = {

EXTENSION_WHITELIST = frozenset(EXTENSION_MIME_MAP.iterkeys())

def invalid_email_reason(email_address, field):

  Args:

    email_address: Email to check.

  Returns:

    String indicating invalid email reason if there is one,

    else None.

  """

  if email_address is None:

    return 'None email address for %s.' % field

  if isinstance(email_address, users.User):

    email_address = email_address.email()

    return 'Invalid email address type for %s.' % field

  stripped_address = email_address.strip()

  if not stripped_address:

    return 'Empty email address for %s.' % field

  return None

InvalidEmailReason = invalid_email_reason

def is_email_valid(email_address):

  """Determine if email is invalid.

  Args:

    email_address: Email to check.

  Returns:

    True if email is valid, else False.

  """

  return invalid_email_reason(email_address, '') is None

IsEmailValid = is_email_valid

def check_email_valid(email_address, field):

  Args:

    email_address: Email to check.

  Raises:

    InvalidEmailError if email_address is invalid.

  """

  reason = invalid_email_reason(email_address, field)

  if reason is not None:

    raise InvalidEmailError(reason)

CheckEmailValid = check_email_valid

def _email_check_and_list(emails, field):

  """Generate a list of emails.

  Args:

    emails: Single email or list of emails.

  Returns:

    Sequence of email addresses.

  Raises:

    InvalidEmailError if any email addresses are invalid.

  """

  if isinstance(emails, types.StringTypes):

    check_email_valid(value)

  else:

    for address in iter(emails):

      check_email_valid(address, field)

def _email_sequence(emails):

  """Forces email to be sequenceable type.

  Iterable values are returned as is.  This function really just wraps the case

  where there is a single email string.

  Args:

    emails: Emails (or email) to coerce to sequence.

  Returns:

    Single tuple with email in it if only one email string provided,

    else returns emails as is.

  """

    return emails,

  return emails

def _attachment_sequence(attachments):

  """Forces attachments to be sequenceable type.

  Iterable values are returned as is.  This function really just wraps the case

  where there is a single attachment.

  Args:

    attachments: Attachments (or attachment) to coerce to sequence.

  Returns:

    Single tuple with attachment tuple in it if only one attachment provided,

    else returns attachments as is.

  """

    return attachments,

  return attachments

def send_mail(sender,

              to,

              subject,

              body,

              make_sync_call=apiproxy_stub_map.MakeSyncCall,

              **kw):

  """Sends mail on behalf of application.

  Args:

    sender: Sender email address as appears in the 'from' email line.

    to: List of 'to' addresses or a single address.

    subject: Message subject string.

    body: Body of type text/plain.

    make_sync_call: Function used to make sync call to API proxy.

    kw: Keyword arguments compatible with EmailMessage keyword based

      constructor.

  Raises:

    InvalidEmailError when invalid email address provided.

  """

  kw['sender'] = sender

  kw['to'] = to

  kw['subject'] = subject

  kw['body'] = body

  message = EmailMessage(**kw)

  message.send(make_sync_call)

SendMail = send_mail

def send_mail_to_admins(sender,

                        subject,

                        body,

                        make_sync_call=apiproxy_stub_map.MakeSyncCall,

                        **kw):

  """Sends mail to admins on behalf of application.

  Args:

    sender: Sender email address as appears in the 'from' email line.

    subject: Message subject string.

    body: Body of type text/plain.

    make_sync_call: Function used to make sync call to API proxy.

    kw: Keyword arguments compatible with EmailMessage keyword based

      constructor.

  Raises:

    InvalidEmailError when invalid email address provided.

  """

  kw['sender'] = sender

  kw['subject'] = subject

  kw['body'] = body

  message = AdminEmailMessage(**kw)

  message.send(make_sync_call)

SendMailToAdmins = send_mail_to_admins

def _GetMimeType(file_name):

  """Determine mime-type from file name.

  Parses file name and determines mime-type based on extension map.

  This method is not part of the public API and should not be used by

  applications.

  Args:

    file_name: File to determine extension for.

  Returns:

    Mime-type associated with file extension.

  Raises:

    InvalidAttachmentTypeError when the file name of an attachment.

  """

  extension_index = file_name.rfind('.')

  if extension_index == -1:

    raise InvalidAttachmentTypeError(

        "File '%s' does not have an extension" % file_name)

  extension = file_name[extension_index + 1:]

  mime_type = EXTENSION_MIME_MAP.get(extension, None)

  if mime_type is None:

    raise InvalidAttachmentTypeError(

        "Extension '%s' is not supported." % extension)

  return mime_type

def mail_message_to_mime_message(protocol_message):

  """Generate a MIMEMultitype message from protocol buffer.

  Generates a complete MIME multi-part email object from a MailMessage

  protocol buffer.  The body fields are sent as individual alternatives

  if they are both present, otherwise, only one body part is sent.

  Multiple entry email fields such as 'To', 'Cc' and 'Bcc' are converted

  to a list of comma separated email addresses.

  Args:

  Returns:

    MIMEMultitype representing the provided MailMessage.

  Raises:

    InvalidAttachmentTypeError when the file name of an attachment

  """

  parts = []

  if protocol_message.has_textbody():

    parts.append(MIMEText.MIMEText(protocol_message.textbody()))

  if protocol_message.has_htmlbody():

    parts.append(MIMEText.MIMEText(protocol_message.htmlbody(),

                                   _subtype='html'))

  if len(parts) == 1:

    payload = parts

  else:

    payload = [MIMEMultipart.MIMEMultipart('alternative', _subparts=parts)]

  result = MIMEMultipart.MIMEMultipart(_subparts=payload)

  for attachment in protocol_message.attachment_list():

    file_name = attachment.filename()

    mime_type = _GetMimeType(file_name)

    maintype, subtype = mime_type.split('/')

    mime_attachment = MIMEBase.MIMEBase(maintype, subtype)

    mime_attachment.add_header('Content-Disposition',

                               'attachment',

                               filename=attachment.filename())

    mime_attachment.set_payload(attachment.data())

    result.attach(mime_attachment)

  if protocol_message.to_size():

    result['To'] = ', '.join(protocol_message.to_list())

  if protocol_message.cc_size():

    result['Cc'] = ', '.join(protocol_message.cc_list())

  if protocol_message.bcc_size():

    result['Bcc'] = ', '.join(protocol_message.bcc_list())

  result['From'] = protocol_message.sender()

  result['Reply-To'] = protocol_message.replyto()

  result['Subject'] = protocol_message.subject()

  return result

MailMessageToMIMEMessage = mail_message_to_mime_message

def _to_str(value):

  Args:

    value: str or unicode to convert to utf-8.

  Returns:

    UTF-8 encoded str of value, otherwise value unchanged.

  """

  if isinstance(value, unicode):

    return value.encode('utf-8')

  return value

class _EmailMessageBase(object):

  """Base class for email API service objects.

  Subclasses must define a class variable called _API_CALL with the name

  of its underlying mail sending API call.

  """

  PROPERTIES = set([

  ])