diff options
Diffstat (limited to 'Mailman/docs/membership.txt')
| -rw-r--r-- | Mailman/docs/membership.txt | 231 |
1 files changed, 0 insertions, 231 deletions
diff --git a/Mailman/docs/membership.txt b/Mailman/docs/membership.txt deleted file mode 100644 index 21084d194..000000000 --- a/Mailman/docs/membership.txt +++ /dev/null @@ -1,231 +0,0 @@ -List memberships -================ - -Users represent people in Mailman. Users control email addresses, and rosters -are collectons of members. A member gives an email address a role, such as -'member', 'administrator', or 'moderator'. Roster sets are collections of -rosters and a mailing list has a single roster set that contains all its -members, regardless of that member's role. - -Mailing lists and roster sets have an indirect relationship, through the -roster set's name. Roster also have names, but are related to roster sets -by a more direct containment relationship. This is because it is possible to -store mailing list data in a different database than user data. - -When we create a mailing list, it starts out with no members... - - >>> from Mailman.configuration import config - >>> mlist = config.db.list_manager.create(u'_xtest@example.com') - >>> mlist - <mailing list "_xtest@example.com" at ...> - >>> sorted(member.address.address for member in mlist.members.members) - [] - >>> sorted(user.real_name for user in mlist.members.users) - [] - >>> sorted(address.address for member in mlist.members.addresses) - [] - -...no owners... - - >>> sorted(member.address.address for member in mlist.owners.members) - [] - >>> sorted(user.real_name for user in mlist.owners.users) - [] - >>> sorted(address.address for member in mlist.owners.addresses) - [] - -...no moderators... - - >>> sorted(member.address.address for member in mlist.moderators.members) - [] - >>> sorted(user.real_name for user in mlist.moderators.users) - [] - >>> sorted(address.address for member in mlist.moderators.addresses) - [] - -...and no administrators. - - >>> sorted(member.address.address - ... for member in mlist.administrators.members) - [] - >>> sorted(user.real_name for user in mlist.administrators.users) - [] - >>> sorted(address.address for member in mlist.administrators.addresses) - [] - - - -Administrators --------------- - -A mailing list's administrators are defined as union of the list's owners and -the list's moderators. We can add new owners or moderators to this list by -assigning roles to users. First we have to create the user, because there are -no users in the user database yet. - - >>> usermgr = config.db.user_manager - >>> user_1 = usermgr.create_user(u'aperson@example.com', u'Anne Person') - >>> user_1.real_name - u'Anne Person' - >>> sorted(address.address for address in user_1.addresses) - [u'aperson@example.com'] - -We can add Anne as an owner of the mailing list, by creating a member role for -her. - - >>> from Mailman.interfaces import MemberRole - >>> address_1 = list(user_1.addresses)[0] - >>> address_1.address - u'aperson@example.com' - >>> address_1.subscribe(mlist, MemberRole.owner) - <Member: Anne Person <aperson@example.com> on - _xtest@example.com as MemberRole.owner> - >>> sorted(member.address.address for member in mlist.owners.members) - [u'aperson@example.com'] - >>> sorted(user.real_name for user in mlist.owners.users) - [u'Anne Person'] - >>> sorted(address.address for address in mlist.owners.addresses) - [u'aperson@example.com'] - -Adding Anne as a list owner also makes her an administrator, but does not make -her a moderator. Nor does it make her a member of the list. - - >>> sorted(user.real_name for user in mlist.administrators.users) - [u'Anne Person'] - >>> sorted(user.real_name for user in mlist.moderators.users) - [] - >>> sorted(user.real_name for user in mlist.members.users) - [] - -We can add Ben as a moderator of the list, by creating a different member role -for him. - - >>> user_2 = usermgr.create_user(u'bperson@example.com', u'Ben Person') - >>> user_2.real_name - u'Ben Person' - >>> address_2 = list(user_2.addresses)[0] - >>> address_2.address - u'bperson@example.com' - >>> address_2.subscribe(mlist, MemberRole.moderator) - <Member: Ben Person <bperson@example.com> - on _xtest@example.com as MemberRole.moderator> - >>> sorted(member.address.address for member in mlist.moderators.members) - [u'bperson@example.com'] - >>> sorted(user.real_name for user in mlist.moderators.users) - [u'Ben Person'] - >>> sorted(address.address for address in mlist.moderators.addresses) - [u'bperson@example.com'] - -Now, both Anne and Ben are list administrators. - - >>> sorted(member.address.address - ... for member in mlist.administrators.members) - [u'aperson@example.com', u'bperson@example.com'] - >>> sorted(user.real_name for user in mlist.administrators.users) - [u'Anne Person', u'Ben Person'] - >>> sorted(address.address for address in mlist.administrators.addresses) - [u'aperson@example.com', u'bperson@example.com'] - - -Members -------- - -Similarly, list members are born of users being given the proper role. It's -more interesting here because these roles should have a preference which can -be used to decide whether the member is to get regular delivery or digest -delivery. Without a preference, Mailman will fall back first to the address's -preference, then the user's preference, then the list's preference. Start -without any member preference to see the system defaults. - - >>> user_3 = usermgr.create_user(u'cperson@example.com', u'Claire Person') - >>> user_3.real_name - u'Claire Person' - >>> address_3 = list(user_3.addresses)[0] - >>> address_3.address - u'cperson@example.com' - >>> address_3.subscribe(mlist, MemberRole.member) - <Member: Claire Person <cperson@example.com> - on _xtest@example.com as MemberRole.member> - -Claire will be a regular delivery member but not a digest member. - - >>> sorted(address.address for address in mlist.members.addresses) - [u'cperson@example.com'] - >>> sorted(address.address for address in mlist.regular_members.addresses) - [u'cperson@example.com'] - >>> sorted(address.address for address in mlist.digest_members.addresses) - [] - -It's easy to make the list administrators members of the mailing list too. - - >>> members = [] - >>> for address in mlist.administrators.addresses: - ... member = address.subscribe(mlist, MemberRole.member) - ... members.append(member) - >>> sorted(members, key=lambda m: m.address.address) - [<Member: Anne Person <aperson@example.com> on - _xtest@example.com as MemberRole.member>, - <Member: Ben Person <bperson@example.com> on - _xtest@example.com as MemberRole.member>] - >>> sorted(address.address for address in mlist.members.addresses) - [u'aperson@example.com', u'bperson@example.com', u'cperson@example.com'] - >>> sorted(address.address for address in mlist.regular_members.addresses) - [u'aperson@example.com', u'bperson@example.com', u'cperson@example.com'] - >>> sorted(address.address for address in mlist.digest_members.addresses) - [] - - -Finding members ---------------- - -You can find the IMember object that is a member of a roster for a given text -email address by using an IRoster's .get_member() method. - - >>> mlist.owners.get_member(u'aperson@example.com') - <Member: Anne Person <aperson@example.com> on - _xtest@example.com as MemberRole.owner> - >>> mlist.administrators.get_member(u'aperson@example.com') - <Member: Anne Person <aperson@example.com> on - _xtest@example.com as MemberRole.owner> - >>> mlist.members.get_member(u'aperson@example.com') - <Member: Anne Person <aperson@example.com> on - _xtest@example.com as MemberRole.member> - -However, if the address is not subscribed with the appropriate role, then None -is returned. - - >>> print mlist.administrators.get_member(u'zperson@example.com') - None - >>> print mlist.moderators.get_member(u'aperson@example.com') - None - >>> print mlist.members.get_member(u'zperson@example.com') - None - - -All subscribers ---------------- - -There is also a roster containing all the subscribers of a mailing list, -regardless of their role. - - >>> def sortkey(member): - ... return (member.address.address, int(member.role)) - >>> [(member.address.address, str(member.role)) - ... for member in sorted(mlist.subscribers.members, key=sortkey)] - [(u'aperson@example.com', 'MemberRole.member'), - (u'aperson@example.com', 'MemberRole.owner'), - (u'bperson@example.com', 'MemberRole.member'), - (u'bperson@example.com', 'MemberRole.moderator'), - (u'cperson@example.com', 'MemberRole.member')] - - -Double subscriptions --------------------- - -It is an error to subscribe someone to a list with the same role twice. - - >>> address_1.subscribe(mlist, MemberRole.owner) - Traceback (most recent call last): - ... - AlreadySubscribedError: aperson@example.com is already a MemberRole.owner - of mailing list _xtest@example.com |