1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
# Copyright (C) 2009-2014 by the Free Software Foundation, Inc.
#
# This file is part of GNU Mailman.
#
# GNU Mailman is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option)
# any later version.
#
# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along with
# GNU Mailman. If not, see <http://www.gnu.org/licenses/>.
"""Membership interface for REST."""
from __future__ import absolute_import, print_function, unicode_literals
__metaclass__ = type
__all__ = [
'ISubscriptionService',
]
from zope.interface import Interface
from mailman.interfaces.errors import MailmanError
from mailman.interfaces.member import DeliveryMode, MemberRole
class MissingUserError(MailmanError):
"""A an invalid user id was given."""
def __init__(self, user_id):
super(MissingUserError, self).__init__()
self.user_id = user_id
def __str__(self):
return self.user_id
class ISubscriptionService(Interface):
"""General Subscription services."""
def get_members():
"""Return a sequence of all members of all mailing lists.
The members are sorted first by fully-qualified mailing list name,
then by subscribed email address, then by role. Because the user may
be a member of the list under multiple roles (e.g. as an owner and as
a digest member), the member can appear multiple times in this list.
Roles are sorted by: owner, moderator, member.
:return: The list of all members.
:rtype: list of `IMember`
"""
def get_member(member_id):
"""Return a member record matching the member id.
:param member_id: A member id.
:type member_id: int
:return: The matching member, or None if no matching member is found.
:rtype: `IMember`
"""
def find_members(subscriber=None, list_id=None, role=None):
"""Search for and return a specific member.
The members are sorted first by fully-qualified mailing list name,
then by subscribed email address, then by role. Because the user may
be a member of the list under multiple roles (e.g. as an owner and as
a digest member), the member can appear multiple times in this list.
:param subscriber: The email address or user id of the user getting
subscribed.
:type subscriber: string or int
:param list_id: The list id of the mailing list to search for the
subscriber's memberships on.
:type list_id: string
:param role: The member role.
:type role: `MemberRole`
:return: The list of all memberships, which may be empty.
:rtype: list of `IMember`
"""
def __iter__():
"""See `get_members()`."""
def join(list_id, subscriber, display_name=None,
delivery_mode=DeliveryMode.regular,
role=MemberRole.member):
"""Subscribe to a mailing list.
A user for the address is created if it is not yet known to Mailman,
however newly registered addresses will not yet be validated. No
confirmation message will be sent to the address, and the approval of
the subscription request is still dependent on the policy of the
mailing list.
:param list_id: The list id of the mailing list the user is
subscribing to.
:type list_id: string
:param subscriber: The email address or user id of the user getting
subscribed.
:type subscriber: string or int
:param display_name: The name of the user. This is only used if a new
user is created, and it defaults to the local part of the email
address if not given.
:type display_name: string
:param delivery_mode: The delivery mode for this subscription. This
can be one of the enum values of `DeliveryMode`. If not given,
regular delivery is assumed.
:type delivery_mode: string
:param role: The membership role for this subscription.
:type role: `MemberRole`
:return: The just created member.
:rtype: `IMember`
:raises AlreadySubscribedError: if the user is already subscribed to
the mailing list.
:raises InvalidEmailAddressError: if the email address is not valid.
:raises MembershipIsBannedError: if the membership is not allowed.
:raises MissingUserError: when a bogus user id is given.
:raises NoSuchListError: if the named mailing list does not exist.
:raises ValueError: when `delivery_mode` is invalid.
"""
def leave(list_id, email):
"""Unsubscribe from a mailing list.
:param list_id: The list id of the mailing list the user is
unsubscribing from.
:type list_id: string
:param email: The email address of the user getting unsubscribed.
:type email: string
:raises InvalidEmailAddressError: if the email address is not valid.
:raises NoSuchListError: if the named mailing list does not exist.
:raises NotAMemberError: if the given address is not a member of the
mailing list.
"""
|
