← Back to branch summary

~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to lib/lp/services/mail/interfaces.py

  • Committer: Launchpad Patch Queue Manager
  • Date: 2011-12-20 17:18:38 UTC
  • mfrom: (14557.1.20 login-token-apocalyse)
  • Revision ID: launchpad@pqm.canonical.com-20111220171838-t5bzp4y0hjmxxqze
[rs=sinzui][no-qa] migrate logintoken, launchpad statistics,
        and feeds.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/lp/services/mail/interfaces.py
1
 
# Copyright 2009 Canonical Ltd.  This software is licensed under the
 
1
# Copyright 2009-2011 Canonical Ltd.  This software is licensed under the
2
2
# GNU Affero General Public License version 3 (see the file LICENSE).
3
3
 
4
4
# pylint: disable-msg=E0211,E0213
6
6
"""Interfaces specific to mail handling."""
7
7
 
8
8
__metaclass__ = type
9
 
__all__ = ['IWeaklyAuthenticatedPrincipal',
10
 
           'ISignedMessage',
11
 
           'IMailHandler',
12
 
           'EmailProcessingError',
13
 
           'BugTargetNotFound',
14
 
           'IEmailCommand',
15
 
           'IBugEmailCommand',
16
 
           'IBugTaskEmailCommand',
17
 
           'IBugEditEmailCommand',
18
 
           'IBugTaskEditEmailCommand']
 
9
__all__ = [
 
10
    'BugTargetNotFound',
 
11
    'EmailProcessingError',
 
12
    'IBugEditEmailCommand',
 
13
    'IBugEmailCommand',
 
14
    'IBugTaskEditEmailCommand',
 
15
    'IBugTaskEmailCommand',
 
16
    'IEmailCommand',
 
17
    'IMailHandler',
 
18
    'INotificationRecipientSet',
 
19
    'ISignedMessage',
 
20
    'IWeaklyAuthenticatedPrincipal',
 
21
    'UnknownRecipientError',
 
22
    ]
19
23
 
20
24
from zope.interface import (
21
25
    Attribute,
103
107
        self.stop_processing = stop_processing
104
108
 
105
109
 
 
110
class UnknownRecipientError(KeyError):
 
111
    """Error raised when an email or person isn't part of the recipient set.
 
112
    """
 
113
 
 
114
 
 
115
class INotificationRecipientSet(Interface):
 
116
    """Represents a set of notification recipients and rationales.
 
117
 
 
118
    All Launchpad emails should include a footer explaining why the user
 
119
    is receiving the email. An INotificationRecipientSet encapsulates a
 
120
    list of recipients along the rationale for being on the recipients list.
 
121
 
 
122
    The pattern for using this are as follows: email addresses in an
 
123
    INotificationRecipientSet are being notified because of a specific
 
124
    event (for instance, because a bug changed). The rationales describe
 
125
    why that email addresses is included in the recipient list,
 
126
    detailing subscription types, membership in teams and/or other
 
127
    possible reasons.
 
128
 
 
129
    The set maintains the list of `IPerson` that will be contacted as well
 
130
    as the email address to use to contact them.
 
131
    """
 
132
 
 
133
    def getEmails():
 
134
        """Return all email addresses registered, sorted alphabetically."""
 
135
 
 
136
    def getRecipients():
 
137
        """Return the set of person who will be notified.
 
138
 
 
139
        :return: An iterator of `IPerson`, sorted by display name.
 
140
        """
 
141
 
 
142
    def getRecipientPersons():
 
143
        """Return the set of individual Persons who will be notified.
 
144
 
 
145
        :return: An iterator of (`email_address`, `IPerson`), unsorted.
 
146
        """
 
147
 
 
148
    def __iter__():
 
149
        """Return an iterator of the recipients."""
 
150
 
 
151
    def __contains__(person_or_email):
 
152
        """Is person_or_email in the notification recipients list?
 
153
 
 
154
        Return true if person or email is in the notification recipients list.
 
155
        """
 
156
 
 
157
    def __nonzero__():
 
158
        """Return False when the set is empty, True when it's not."""
 
159
 
 
160
    def getReason(person_or_email):
 
161
        """Return a reason tuple containing (text, header) for an address.
 
162
 
 
163
        The text is meant to appear in the notification footer. The header
 
164
        should be a short code that will appear in an
 
165
        X-Launchpad-Message-Rationale header for automatic filtering.
 
166
 
 
167
        :param person_or_email: An `IPerson` or email address that is in the
 
168
            recipients list.
 
169
 
 
170
        :raises UnknownRecipientError: if the person or email isn't in the
 
171
            recipients list.
 
172
        """
 
173
 
 
174
    def add(person, reason, header):
 
175
        """Add a person or a sequence of persons to the recipients list.
 
176
 
 
177
        When the added person is a team without an email address, all its
 
178
        members emails will be added. If the person is already in the
 
179
        recipients list, the reson for contacting him is not changed.
 
180
 
 
181
        :param person: The `IPerson` or a sequence of `IPerson`
 
182
            that will be notified.
 
183
        :param reason: The rationale message that should appear in the
 
184
            notification footer.
 
185
        :param header: The code that will appear in the
 
186
            X-Launchpad-Message-Rationale header.
 
187
        """
 
188
 
 
189
    def remove(person):
 
190
        """Remove a person or a list of persons from the recipients list.
 
191
 
 
192
        :param person: The `IPerson` or a sequence of `IPerson`
 
193
            that will removed from the recipients list.
 
194
        """
 
195
 
 
196
    def update(recipient_set):
 
197
        """Updates this instance's reasons with reasons from another set.
 
198
 
 
199
        The rationale for recipient already in this set will not be updated.
 
200
 
 
201
        :param recipient_set: An `INotificationRecipientSet`.
 
202
        """
 
203
 
 
204
 
106
205
class BugTargetNotFound(Exception):
107
206
    """A bug target couldn't be found."""
108
207