src/mailman/interfaces/roster.py

   1 # Copyright (C) 2007-2023 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
  20 from public import public
  21 from zope.interface import Attribute, Interface
  22
  23
  24 @public
  25 class 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         Likewise, an email can be a member of the administrators roster,
  61         both as an owner and as a moderator.  In this case, this API will
  62         return the owner.
  63
  64         :param email: The email address to search for.
  65         :type email: string
  66         :return: The member if found, otherwise None
  67         :rtype: `IMember` or None
  68         """
  69
  70     def get_memberships(email):
  71         """Get the memberships for the given address.
  72
  73         :param email: The email address to search for.
  74         :type email: string
  75         :return: All the memberships associated with this email address.
  76         :rtype: sequence of length 0, 1, or 2 of ``IMember``
  77         """