Added boto/ to depot_tools/third_party

third_party/boto/ses/connection.py

+# Copyright (c) 2010 Mitch Garnaat http://garnaat.org/
+# Copyright (c) 2011 Harry Marr http://hmarr.com/
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish, dis-
+# tribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the fol-
+# lowing conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
+# ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+# SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+import re
+import urllib
+import base64
+
+from boto.connection import AWSAuthConnection
+from boto.exception import BotoServerError
+from boto.regioninfo import RegionInfo
+import boto
+import boto.jsonresponse
+from boto.ses import exceptions as ses_exceptions
+
+
+class SESConnection(AWSAuthConnection):
+
+    ResponseError = BotoServerError
+    DefaultRegionName = 'us-east-1'
+    DefaultRegionEndpoint = 'email.us-east-1.amazonaws.com'
+    APIVersion = '2010-12-01'
+
+    def __init__(self, aws_access_key_id=None, aws_secret_access_key=None,
+                 is_secure=True, port=None, proxy=None, proxy_port=None,
+                 proxy_user=None, proxy_pass=None, debug=0,
+                 https_connection_factory=None, region=None, path='/',
+                 security_token=None, validate_certs=True):
+        if not region:
+            region = RegionInfo(self, self.DefaultRegionName,
+                                self.DefaultRegionEndpoint)
+        self.region = region
+        AWSAuthConnection.__init__(self, self.region.endpoint,
+                                   aws_access_key_id, aws_secret_access_key,
+                                   is_secure, port, proxy, proxy_port,
+                                   proxy_user, proxy_pass, debug,
+                                   https_connection_factory, path,
+                                   security_token=security_token,
+                                   validate_certs=validate_certs)
+
+    def _required_auth_capability(self):
+        return ['ses']
+
+    def _build_list_params(self, params, items, label):
+        """Add an AWS API-compatible parameter list to a dictionary.
+
+        :type params: dict
+        :param params: The parameter dictionary
+
+        :type items: list
+        :param items: Items to be included in the list
+
+        :type label: string
+        :param label: The parameter list's name
+        """
+        if isinstance(items, basestring):
+            items = [items]
+        for i in range(1, len(items) + 1):
+            params['%s.%d' % (label, i)] = items[i - 1]
+
+    def _make_request(self, action, params=None):
+        """Make a call to the SES API.
+
+        :type action: string
+        :param action: The API method to use (e.g. SendRawEmail)
+
+        :type params: dict
+        :param params: Parameters that will be sent as POST data with the API
+            call.
+        """
+        ct = 'application/x-www-form-urlencoded; charset=UTF-8'
+        headers = {'Content-Type': ct}
+        params = params or {}
+        params['Action'] = action
+
+        for k, v in params.items():
+            if isinstance(v, unicode):  # UTF-8 encode only if it's Unicode
+                params[k] = v.encode('utf-8')
+
+        response = super(SESConnection, self).make_request(
+            'POST',
+            '/',
+            headers=headers,
+            data=urllib.urlencode(params)
+        )
+        body = response.read()
+        if response.status == 200:
+            list_markers = ('VerifiedEmailAddresses', 'Identities',
+                            'VerificationAttributes', 'SendDataPoints')
+            item_markers = ('member', 'item', 'entry')
+
+            e = boto.jsonresponse.Element(list_marker=list_markers,
+                                          item_marker=item_markers)
+            h = boto.jsonresponse.XmlHandler(e, None)
+            h.parse(body)
+            return e
+        else:
+            # HTTP codes other than 200 are considered errors. Go through
+            # some error handling to determine which exception gets raised,
+            self._handle_error(response, body)
+
+    def _handle_error(self, response, body):
+        """
+        Handle raising the correct exception, depending on the error. Many
+        errors share the same HTTP response code, meaning we have to get really
+        kludgey and do string searches to figure out what went wrong.
+        """
+        boto.log.error('%s %s' % (response.status, response.reason))
+        boto.log.error('%s' % body)
+
+        if "Address blacklisted." in body:
+            # Delivery failures happened frequently enough with the recipient's
+            # email address for Amazon to blacklist it. After a day or three,
+            # they'll be automatically removed, and delivery can be attempted
+            # again (if you write the code to do so in your application).
+            ExceptionToRaise = ses_exceptions.SESAddressBlacklistedError
+            exc_reason = "Address blacklisted."
+        elif "Email address is not verified." in body:
+            # This error happens when the "Reply-To" value passed to
+            # send_email() hasn't been verified yet.
+            ExceptionToRaise = ses_exceptions.SESAddressNotVerifiedError
+            exc_reason = "Email address is not verified."
+        elif "Daily message quota exceeded." in body:
+            # Encountered when your account exceeds the maximum total number
+            # of emails per 24 hours.
+            ExceptionToRaise = ses_exceptions.SESDailyQuotaExceededError
+            exc_reason = "Daily message quota exceeded."
+        elif "Maximum sending rate exceeded." in body:
+            # Your account has sent above its allowed requests a second rate.
+            ExceptionToRaise = ses_exceptions.SESMaxSendingRateExceededError
+            exc_reason = "Maximum sending rate exceeded."
+        elif "Domain ends with dot." in body:
+            # Recipient address ends with a dot/period. This is invalid.
+            ExceptionToRaise = ses_exceptions.SESDomainEndsWithDotError
+            exc_reason = "Domain ends with dot."
+        elif "Local address contains control or whitespace" in body:
+            # I think this pertains to the recipient address.
+            ExceptionToRaise = ses_exceptions.SESLocalAddressCharacterError
+            exc_reason = "Local address contains control or whitespace."
+        elif "Illegal address" in body:
+            # A clearly mal-formed address.
+            ExceptionToRaise = ses_exceptions.SESIllegalAddressError
+            exc_reason = "Illegal address"
+        # The re.search is to distinguish from the
+        # SESAddressNotVerifiedError error above.
+        elif re.search('Identity.*is not verified', body):
+            ExceptionToRaise = ses_exceptions.SESIdentityNotVerifiedError
+            exc_reason = "Identity is not verified."
+        elif "ownership not confirmed" in body:
+            ExceptionToRaise = ses_exceptions.SESDomainNotConfirmedError
+            exc_reason = "Domain ownership is not confirmed."
+        else:
+            # This is either a common AWS error, or one that we don't devote
+            # its own exception to.
+            ExceptionToRaise = self.ResponseError
+            exc_reason = response.reason
+
+        raise ExceptionToRaise(response.status, exc_reason, body)
+
+    def send_email(self, source, subject, body, to_addresses,
+                   cc_addresses=None, bcc_addresses=None,
+                   format='text', reply_addresses=None,
+                   return_path=None, text_body=None, html_body=None):
+        """Composes an email message based on input data, and then immediately
+        queues the message for sending.
+
+        :type source: string
+        :param source: The sender's email address.
+
+        :type subject: string
+        :param subject: The subject of the message: A short summary of the
+                        content, which will appear in the recipient's inbox.
+
+        :type body: string
+        :param body: The message body.
+
+        :type to_addresses: list of strings or string
+        :param to_addresses: The To: field(s) of the message.
+
+        :type cc_addresses: list of strings or string
+        :param cc_addresses: The CC: field(s) of the message.
+
+        :type bcc_addresses: list of strings or string
+        :param bcc_addresses: The BCC: field(s) of the message.
+
+        :type format: string
+        :param format: The format of the message's body, must be either "text"
+                       or "html".
+
+        :type reply_addresses: list of strings or string
+        :param reply_addresses: The reply-to email address(es) for the
+                                message. If the recipient replies to the
+                                message, each reply-to address will
+                                receive the reply.
+
+        :type return_path: string
+        :param return_path: The email address to which bounce notifications are
+                            to be forwarded. If the message cannot be delivered
+                            to the recipient, then an error message will be
+                            returned from the recipient's ISP; this message
+                            will then be forwarded to the email address
+                            specified by the ReturnPath parameter.
+
+        :type text_body: string
+        :param text_body: The text body to send with this email.
+
+        :type html_body: string
+        :param html_body: The html body to send with this email.
+
+        """
+        format = format.lower().strip()
+        if body is not None:
+            if format == "text":
+                if text_body is not None:
+                    raise Warning("You've passed in both a body and a "
+                                  "text_body; please choose one or the other.")
+                text_body = body
+            else:
+                if html_body is not None:
+                    raise Warning("You've passed in both a body and an "
+                                  "html_body; please choose one or the other.")
+                html_body = body
+
+        params = {
+            'Source': source,
+            'Message.Subject.Data': subject,
+        }
+
+        if return_path:
+            params['ReturnPath'] = return_path
+
+        if html_body is not None:
+            params['Message.Body.Html.Data'] = html_body
+        if text_body is not None:
+            params['Message.Body.Text.Data'] = text_body
+
+        if(format not in ("text", "html")):
+            raise ValueError("'format' argument must be 'text' or 'html'")
+
+        if(not (html_body or text_body)):
+            raise ValueError("No text or html body found for mail")
+
+        self._build_list_params(params, to_addresses,
+                               'Destination.ToAddresses.member')
+        if cc_addresses:
+            self._build_list_params(params, cc_addresses,
+                                   'Destination.CcAddresses.member')
+
+        if bcc_addresses:
+            self._build_list_params(params, bcc_addresses,
+                                   'Destination.BccAddresses.member')
+
+        if reply_addresses:
+            self._build_list_params(params, reply_addresses,
+                                   'ReplyToAddresses.member')
+
+        return self._make_request('SendEmail', params)
+
+    def send_raw_email(self, raw_message, source=None, destinations=None):
+        """Sends an email message, with header and content specified by the
+        client. The SendRawEmail action is useful for sending multipart MIME
+        emails, with attachments or inline content. The raw text of the message
+        must comply with Internet email standards; otherwise, the message
+        cannot be sent.
+
+        :type source: string
+        :param source: The sender's email address. Amazon's docs say:
+
+          If you specify the Source parameter, then bounce notifications and
+          complaints will be sent to this email address. This takes precedence
+          over any Return-Path header that you might include in the raw text of
+          the message.
+
+        :type raw_message: string
+        :param raw_message: The raw text of the message. The client is
+          responsible for ensuring the following:
+
+          - Message must contain a header and a body, separated by a blank line.
+          - All required header fields must be present.
+          - Each part of a multipart MIME message must be formatted properly.
+          - MIME content types must be among those supported by Amazon SES.
+            Refer to the Amazon SES Developer Guide for more details.
+          - Content must be base64-encoded, if MIME requires it.
+
+        :type destinations: list of strings or string
+        :param destinations: A list of destinations for the message.
+
+        """
+
+        if isinstance(raw_message, unicode):
+            raw_message = raw_message.encode('utf-8')
+
+        params = {
+            'RawMessage.Data': base64.b64encode(raw_message),
+        }
+
+        if source:
+            params['Source'] = source
+
+        if destinations:
+            self._build_list_params(params, destinations,
+                                   'Destinations.member')
+
+        return self._make_request('SendRawEmail', params)
+
+    def list_verified_email_addresses(self):
+        """Fetch a list of the email addresses that have been verified.
+
+        :rtype: dict
+        :returns: A ListVerifiedEmailAddressesResponse structure. Note that
+                  keys must be unicode strings.
+        """
+        return self._make_request('ListVerifiedEmailAddresses')
+
+    def get_send_quota(self):
+        """Fetches the user's current activity limits.
+
+        :rtype: dict
+        :returns: A GetSendQuotaResponse structure. Note that keys must be
+                  unicode strings.
+        """
+        return self._make_request('GetSendQuota')
+
+    def get_send_statistics(self):
+        """Fetches the user's sending statistics. The result is a list of data
+        points, representing the last two weeks of sending activity.
+
+        Each data point in the list contains statistics for a 15-minute
+        interval.
+
+        :rtype: dict
+        :returns: A GetSendStatisticsResponse structure. Note that keys must be
+                  unicode strings.
+        """
+        return self._make_request('GetSendStatistics')
+
+    def delete_verified_email_address(self, email_address):
+        """Deletes the specified email address from the list of verified
+        addresses.
+
+        :type email_adddress: string
+        :param email_address: The email address to be removed from the list of
+                              verified addreses.
+
+        :rtype: dict
+        :returns: A DeleteVerifiedEmailAddressResponse structure. Note that
+                  keys must be unicode strings.
+        """
+        return self._make_request('DeleteVerifiedEmailAddress', {
+            'EmailAddress': email_address,
+        })
+
+    def verify_email_address(self, email_address):
+        """Verifies an email address. This action causes a confirmation email
+        message to be sent to the specified address.
+
+        :type email_adddress: string
+        :param email_address: The email address to be verified.
+
+        :rtype: dict
+        :returns: A VerifyEmailAddressResponse structure. Note that keys must
+                  be unicode strings.
+        """
+        return self._make_request('VerifyEmailAddress', {
+            'EmailAddress': email_address,
+        })
+
+    def verify_domain_dkim(self, domain):
+        """
+        Returns a set of DNS records, or tokens, that must be published in the
+        domain name's DNS to complete the DKIM verification process. These
+        tokens are DNS ``CNAME`` records that point to DKIM public keys hosted
+        by Amazon SES. To complete the DKIM verification process, these tokens
+        must be published in the domain's DNS.  The tokens must remain
+        published in order for Easy DKIM signing to function correctly.
+
+        After the tokens are added to the domain's DNS, Amazon SES will be able
+        to DKIM-sign email originating from that domain.  To enable or disable
+        Easy DKIM signing for a domain, use the ``SetIdentityDkimEnabled``
+        action.  For more information about Easy DKIM, go to the `Amazon SES
+        Developer Guide
+        <http://docs.amazonwebservices.com/ses/latest/DeveloperGuide>`_.
+
+        :type domain: string
+        :param domain: The domain name.
+
+        """
+        return self._make_request('VerifyDomainDkim', {
+            'Domain': domain,
+        })
+
+    def set_identity_dkim_enabled(self, identity, dkim_enabled):
+        """Enables or disables DKIM signing of email sent from an identity.
+
+        * If Easy DKIM signing is enabled for a domain name identity (e.g.,
+        * ``example.com``),
+          then Amazon SES will DKIM-sign all email sent by addresses under that
+          domain name (e.g., ``user@example.com``)
+        * If Easy DKIM signing is enabled for an email address, then Amazon SES
+          will DKIM-sign all email sent by that email address.
+
+        For email addresses (e.g., ``user@example.com``), you can only enable
+        Easy DKIM signing  if the corresponding domain (e.g., ``example.com``)
+        has been set up for Easy DKIM using the AWS Console or the
+        ``VerifyDomainDkim`` action.
+
+        :type identity: string
+        :param identity: An email address or domain name.
+
+        :type dkim_enabled: bool
+        :param dkim_enabled: Specifies whether or not to enable DKIM signing.
+
+        """
+        return self._make_request('SetIdentityDkimEnabled', {
+            'Identity': identity,
+            'DkimEnabled': 'true' if dkim_enabled else 'false'
+        })
+
+    def get_identity_dkim_attributes(self, identities):
+        """Get attributes associated with a list of verified identities.
+
+        Given a list of verified identities (email addresses and/or domains),
+        returns a structure describing identity notification attributes.
+
+        :type identities: list
+        :param identities: A list of verified identities (email addresses
+            and/or domains).
+
+        """
+        params = {}
+        self._build_list_params(params, identities, 'Identities.member')
+        return self._make_request('GetIdentityDkimAttributes', params)
+
+    def list_identities(self):
+        """Returns a list containing all of the identities (email addresses
+        and domains) for a specific AWS Account, regardless of
+        verification status.
+
+        :rtype: dict
+        :returns: A ListIdentitiesResponse structure. Note that
+                  keys must be unicode strings.
+        """
+        return self._make_request('ListIdentities')
+
+    def get_identity_verification_attributes(self, identities):
+        """Given a list of identities (email addresses and/or domains),
+        returns the verification status and (for domain identities)
+        the verification token for each identity.
+
+        :type identities: list of strings or string
+        :param identities: List of identities.
+
+        :rtype: dict
+        :returns: A GetIdentityVerificationAttributesResponse structure.
+                  Note that keys must be unicode strings.
+        """
+        params = {}
+        self._build_list_params(params, identities,
+                               'Identities.member')
+        return self._make_request('GetIdentityVerificationAttributes', params)
+
+    def verify_domain_identity(self, domain):
+        """Verifies a domain.
+
+        :type domain: string
+        :param domain: The domain to be verified.
+
+        :rtype: dict
+        :returns: A VerifyDomainIdentityResponse structure. Note that
+                  keys must be unicode strings.
+        """
+        return self._make_request('VerifyDomainIdentity', {
+            'Domain': domain,
+        })
+
+    def verify_email_identity(self, email_address):
+        """Verifies an email address. This action causes a confirmation
+        email message to be sent to the specified address.
+
+        :type email_adddress: string
+        :param email_address: The email address to be verified.
+
+        :rtype: dict
+        :returns: A VerifyEmailIdentityResponse structure. Note that keys must
+                  be unicode strings.
+        """
+        return self._make_request('VerifyEmailIdentity', {
+            'EmailAddress': email_address,
+        })
+
+    def delete_identity(self, identity):
+        """Deletes the specified identity (email address or domain) from
+        the list of verified identities.
+
+        :type identity: string
+        :param identity: The identity to be deleted.
+
+        :rtype: dict
+        :returns: A DeleteIdentityResponse structure. Note that keys must
+                  be unicode strings.
+        """
+        return self._make_request('DeleteIdentity', {
+            'Identity': identity,
+        })