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

"""

import email

from email import MIMEBase

from email import MIMEMultipart

from email import MIMEText

import logging

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 = {

    mail_service_pb.MailServiceError.BAD_REQUEST:

      BadRequestError,

    mail_service_pb.MailServiceError.UNAUTHORIZED_SENDER:

      InvalidSenderError,

    mail_service_pb.MailServiceError.INVALID_ATTACHMENT_TYPE:

      InvalidAttachmentTypeError,

}

EXTENSION_MIME_MAP = {

    'asc': 'text/plain',

    'bmp': 'image/x-ms-bmp',

    'css': 'text/css',

    'csv': 'text/csv',

    'diff': 'text/plain',

    'gif': 'image/gif',

    'htm': 'text/html',

    'html': 'text/html',

    'ics': 'text/calendar',

    'jpe': 'image/jpeg',

    'jpeg': 'image/jpeg',

    'jpg': 'image/jpeg',

    'pdf': 'application/pdf',

    'png': 'image/png',

    'pot': 'text/plain',

    'rss': 'text/rss+xml',

    'text': 'text/plain',

    'tif': 'image/tiff',

    'tiff': 'image/tiff',

    'txt': 'text/plain',

    'vcf': 'text/directory',

    'wbmp': 'image/vnd.wap.wbmp',

    }

EXTENSION_WHITELIST = frozenset(EXTENSION_MIME_MAP.iterkeys())

def invalid_email_reason(email_address, field):

  """Determine reason why email is invalid.

  Args:

    email_address: Email to check.

    field: Field that is invalid.

  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()

  if not isinstance(email_address, basestring):

    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):

  """Check that email is valid.

  Args:

    email_address: Email to check.

    field: Field 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.

  """

  if isinstance(emails, basestring):

    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.

  """

  if len(attachments) == 2 and isinstance(attachments[0], basestring):

    return attachments,

  return attachments

def _parse_mime_message(mime_message):

  """Helper function converts a mime_message in to email.Message.Message.

  Args:

    mime_message: MIME Message, string or file containing mime message.

  Returns:

    Instance of email.Message.Message.  Will return mime_message if already

    an instance.

  """

  if isinstance(mime_message, email.Message.Message):

    return mime_message

  elif isinstance(mime_message, basestring):

    return email.message_from_string(mime_message)

  else:

    return email.message_from_file(mime_message)

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:

    protocol_message: Message PB to convert to MIMEMultitype.

  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):

  """Helper function to make sure unicode values converted to utf-8.

  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 EncodedPayload(object):

  """Wrapper for a payload that contains encoding information.

  When an email is recieved, it is usually encoded using a certain

  character set, and then possibly further encoded using a transfer

  encoding in that character set.  Most of the times, it is possible

  to decode the encoded payload as is, however, in the case where it

  is not, the encoded payload and the original encoding information

  must be preserved.

  Attributes:

    payload: The original encoded payload.

    charset: The character set of the encoded payload.  None means use

      default character set.

    encoding: The transfer encoding of the encoded payload.  None means

      content not encoded.

  """

  def __init__(self, payload, charset=None, encoding=None):

    """Constructor.

    Args:

      payload: Maps to attribute of the same name.

      charset: Maps to attribute of the same name.

      encoding: Maps to attribute of the same name.

    """

    self.payload = payload

    self.charset = charset

    self.encoding = encoding

  def decode(self):

    """Attempt to decode the encoded data.

    Attempt to use pythons codec library to decode the payload.  All

    exceptions are passed back to the caller.

    Returns:

      Binary or unicode version of payload content.

    """

    payload = self.payload

    if self.encoding and self.encoding.lower() != '7bit':

      try:

        payload = payload.decode(self.encoding).lower()

      except LookupError:

        raise UnknownEncodingError('Unknown decoding %s.' % self.encoding)

      except (Exception, Error), e:

        raise PayloadEncodingError('Could not decode payload: %s' % e)

    if self.charset and str(self.charset).lower() != '7bit':

      try:

        payload = payload.decode(str(self.charset)).lower()

      except LookupError:

        raise UnknownCharsetError('Unknown charset %s.' % self.charset)

      except (Exception, Error), e:

        raise PayloadEncodingError('Could read characters: %s' % e)

    return payload

  def __eq__(self, other):

    """Equality operator.

    Args:

      other: The other EncodedPayload object to compare with.  Comparison

        with other object types are not implemented.

    Returns:

      True of payload and encodings are equal, else false.

    """

    if isinstance(other, EncodedPayload):

      return (self.payload == other.payload and

              self.charset == other.charset and

              self.encoding == other.encoding)

    else:

      return NotImplemented

  def copy_to(self, mime_message):

    """Copy contents to MIME message payload.

    If no content transfer encoding is specified, and the character set does

    not equal the over-all message encoding, the payload will be base64

    encoded.

    Args:

      mime_message: Message instance to receive new payload.

    """

    if self.encoding:

      mime_message['content-transfer-encoding'] = self.encoding

    mime_message.set_payload(self.payload, self.charset)

  def to_mime_message(self):

    """Convert to MIME message.

    Returns:

      MIME message instance of payload.

    """

    mime_message = email.Message.Message()

    self.copy_to(mime_message)

    return mime_message

  def __str__(self):

    """String representation of encoded message.

    Returns:

      MIME encoded representation of encoded payload as an independent message.

    """

    return str(self.to_mime_message())

  def __repr__(self):

    """Basic representation of encoded payload.

    Returns:

      Payload itself is represented by its hash value.

    """

    result = '<EncodedPayload payload=#%d' % hash(self.payload)

    if self.charset:

      result += ' charset=%s' % self.charset

    if self.encoding:

      result += ' encoding=%s' % self.encoding

    return result + '>'

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([

      'sender',

      'reply_to',

      'subject',

      'body',

      'html',

      'attachments',

  ])