1# Copyright (C) 2007-2020 by the Free Software Foundation, Inc.
2#
3# This file is part of GNU Mailman.
4#
5# GNU Mailman is free software: you can redistribute it and/or modify it under
6# the terms of the GNU General Public License as published by the Free
7# Software Foundation, either version 3 of the License, or (at your option)
8# any later version.
9#
10# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
11# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
13# more details.
14#
15# You should have received a copy of the GNU General Public License along with
16# GNU Mailman.  If not, see <https://www.gnu.org/licenses/>.
17
18"""Interface for a roster of members."""
19
20from public import public
21from zope.interface import Attribute, Interface
22
23
24@public
25class IRoster(Interface):
26    """A roster is a collection of `IMembers`."""
27
28    name = Attribute(
29        """The name for this roster.
30
31        Rosters are considered equal if they have the same name.""")
32
33    members = Attribute(
34        """An iterator over all the IMembers managed by this roster.""")
35
36    member_count = Attribute(
37        """The number of members managed by this roster.""")
38
39    users = Attribute(
40        """An iterator over all the IUsers reachable by this roster.
41
42        This returns all the users for all the members managed by this roster.
43        """)
44
45    addresses = Attribute(
46        """An iterator over all the IAddresses reachable by this roster.
47
48        This returns all the addresses for all the users for all the members
49        managed by this roster.
50        """)
51
52    def get_member(email):
53        """Get the member for the given address.
54
55        *Note* that it is possible for an email to be subscribed to a
56        mailing list twice, once through its explicit address and once
57        indirectly through a user's preferred address.  In this case,
58        this API always returns the explicit address.  Use
59        ``get_memberships()`` to return them all.
60
61        :param email: The email address to search for.
62        :type email: string
63        :return: The member if found, otherwise None
64        :rtype: `IMember` or None
65        """
66
67    def get_memberships(email):
68        """Get the memberships for the given address.
69
70        :param email: The email address to search for.
71        :type email: string
72        :return: All the memberships associated with this email address.
73        :rtype: sequence of length 0, 1, or 2 of ``IMember``
74        """
75