src/mailman/model/docs/subscriptions.rst

   1 =====================
   2 Subscription services
   3 =====================
   4
   5 The ``ISubscriptionService`` utility provides higher level convenience methods
   6 useful for searching, retrieving, iterating, and removing memberships across
   7 all mailing lists on th esystem.  Adding new users is handled by the
   8 ``IRegistrar`` interface.
   9
  10     >>> from mailman.interfaces.subscriptions import ISubscriptionService
  11     >>> from zope.component import getUtility
  12     >>> service = getUtility(ISubscriptionService)
  13
  14 You can use the service to get all members of all mailing lists, for any
  15 membership role.  At first, there are no memberships.
  16
  17     >>> service.get_members()
  18     []
  19     >>> sum(1 for member in service)
  20     0
  21     >>> from uuid import UUID
  22     >>> print(service.get_member(UUID(int=801)))
  23     None
  24
  25
  26 Listing members
  27 ===============
  28
  29 When there are some members, of any role on any mailing list, they can be
  30 retrieved through the subscription service.
  31
  32     >>> from mailman.app.lifecycle import create_list
  33     >>> ant = create_list('ant@example.com')
  34     >>> bee = create_list('bee@example.com')
  35     >>> cat = create_list('cat@example.com')
  36
  37 Some people become members.
  38
  39     >>> from mailman.interfaces.member import MemberRole
  40     >>> from mailman.testing.helpers import subscribe
  41     >>> anne_1 = subscribe(ant, 'Anne')
  42     >>> anne_2 = subscribe(ant, 'Anne', MemberRole.owner)
  43     >>> bart_1 = subscribe(ant, 'Bart', MemberRole.moderator)
  44     >>> bart_2 = subscribe(bee, 'Bart', MemberRole.owner)
  45     >>> anne_3 = subscribe(cat, 'Anne', email='anne@example.com')
  46     >>> cris_1 = subscribe(cat, 'Cris')
  47
  48 The service can be used to iterate over them.
  49
  50     >>> for member in service.get_members():
  51     ...     print(member)
  52     <Member: Anne Person <aperson@example.com>
  53         on ant@example.com as MemberRole.owner>
  54     <Member: Bart Person <bperson@example.com>
  55         on ant@example.com as MemberRole.moderator>
  56     <Member: Anne Person <aperson@example.com>
  57         on ant@example.com as MemberRole.member>
  58     <Member: Bart Person <bperson@example.com>
  59         on bee@example.com as MemberRole.owner>
  60     <Member: Anne Person <anne@example.com>
  61         on cat@example.com as MemberRole.member>
  62     <Member: Cris Person <cperson@example.com>
  63         on cat@example.com as MemberRole.member>
  64
  65 The service can also be used to get the information about a single member.
  66
  67     >>> print(service.get_member(bart_2.member_id))
  68     <Member: Bart Person <bperson@example.com>
  69         on bee@example.com as MemberRole.owner>
  70
  71 There is an iteration shorthand for getting all the members.
  72
  73     >>> for member in service:
  74     ...     print(member)
  75     <Member: Anne Person <aperson@example.com>
  76         on ant@example.com as MemberRole.owner>
  77     <Member: Bart Person <bperson@example.com>
  78         on ant@example.com as MemberRole.moderator>
  79     <Member: Anne Person <aperson@example.com>
  80         on ant@example.com as MemberRole.member>
  81     <Member: Bart Person <bperson@example.com>
  82         on bee@example.com as MemberRole.owner>
  83     <Member: Anne Person <anne@example.com>
  84         on cat@example.com as MemberRole.member>
  85     <Member: Cris Person <cperson@example.com>
  86         on cat@example.com as MemberRole.member>
  87
  88
  89 Searching for members
  90 =====================
  91
  92 The subscription service can be used to find memberships based on specific
  93 search criteria.  For example, we can find all the mailing lists that Anne is
  94 a member of with her ``aperson@example.com`` address.
  95
  96     >>> for member in service.find_members('aperson@example.com'):
  97     ...     print(member)
  98     <Member: Anne Person <aperson@example.com>
  99         on ant@example.com as MemberRole.member>
 100     <Member: Anne Person <aperson@example.com>
 101         on ant@example.com as MemberRole.owner>
 102
 103 There may be no matching memberships.
 104
 105     >>> list(service.find_members('dave@example.com'))
 106     []
 107
 108 The address may contain asterisks, which will be interpreted as a wildcard in
 109 the search pattern.
 110
 111     >>> for member in service.find_members('*person*'):
 112     ...     print(member)
 113     <Member: Anne Person <aperson@example.com>
 114         on ant@example.com as MemberRole.member>
 115     <Member: Anne Person <aperson@example.com>
 116         on ant@example.com as MemberRole.owner>
 117     <Member: Bart Person <bperson@example.com>
 118         on ant@example.com as MemberRole.moderator>
 119     <Member: Bart Person <bperson@example.com>
 120         on bee@example.com as MemberRole.owner>
 121     <Member: Cris Person <cperson@example.com>
 122         on cat@example.com as MemberRole.member>
 123
 124 Memberships can also be searched for by user id.
 125
 126     >>> for member in service.find_members(anne_1.user.user_id):
 127     ...     print(member)
 128     <Member: Anne Person <aperson@example.com>
 129         on ant@example.com as MemberRole.member>
 130     <Member: Anne Person <aperson@example.com>
 131         on ant@example.com as MemberRole.owner>
 132
 133 You can find all the memberships for a specific mailing list.
 134
 135     >>> for member in service.find_members(list_id='ant.example.com'):
 136     ...     print(member)
 137     <Member: Anne Person <aperson@example.com>
 138         on ant@example.com as MemberRole.member>
 139     <Member: Anne Person <aperson@example.com>
 140         on ant@example.com as MemberRole.owner>
 141     <Member: Bart Person <bperson@example.com>
 142         on ant@example.com as MemberRole.moderator>
 143
 144 You can find all the memberships for an address on a specific mailing list,
 145 but you have to give it the list id, not the fqdn listname since the former is
 146 stable but the latter could change if the list is moved.
 147
 148     >>> for member in service.find_members(
 149     ...         'bperson@example.com', 'ant.example.com'):
 150     ...     print(member)
 151     <Member: Bart Person <bperson@example.com>
 152         on ant@example.com as MemberRole.moderator>
 153
 154 You can find all the memberships for an address with a specific role.
 155
 156     >>> for member in service.find_members(
 157     ...         list_id='ant.example.com', role=MemberRole.owner):
 158     ...     print(member)
 159     <Member: Anne Person <aperson@example.com>
 160         on ant@example.com as MemberRole.owner>
 161
 162 You can also find a specific membership by all three criteria.
 163
 164     >>> for member in service.find_members(
 165     ...         'bperson@example.com', 'bee.example.com', MemberRole.owner):
 166     ...     print(member)
 167     <Member: Bart Person <bperson@example.com>
 168         on bee@example.com as MemberRole.owner>
 169
 170
 171 Finding a single member
 172 =======================
 173
 174 If you expect only zero or one member to match your criteria, you can use a
 175 the more efficient ``find_member()`` method.  This takes exactly the same
 176 criteria as ``find_members()``.
 177
 178 There may be no matching members.
 179
 180     >>> print(service.find_member('dave@example.com'))
 181     None
 182
 183 But if there is exactly one membership, it is returned.
 184
 185     >>> service.find_member('bperson@example.com', 'ant.example.com')
 186     <Member: Bart Person <bperson@example.com>
 187         on ant@example.com as MemberRole.moderator>
 188
 189
 190 Removing members
 191 ================
 192
 193 Members can be removed via this service.
 194
 195     >>> len(service.get_members())
 196     6
 197     >>> service.leave('cat.example.com', 'cperson@example.com')
 198     >>> len(service.get_members())
 199     5
 200     >>> for member in service:
 201     ...     print(member)
 202     <Member: Anne Person <aperson@example.com>
 203         on ant@example.com as MemberRole.owner>
 204     <Member: Bart Person <bperson@example.com>
 205         on ant@example.com as MemberRole.moderator>
 206     <Member: Anne Person <aperson@example.com>
 207         on ant@example.com as MemberRole.member>
 208     <Member: Bart Person <bperson@example.com>
 209         on bee@example.com as MemberRole.owner>
 210     <Member: Anne Person <anne@example.com>
 211         on cat@example.com as MemberRole.member>