diff options
Diffstat (limited to 'src/mailman/docs/users.txt')
| -rw-r--r-- | src/mailman/docs/users.txt | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/src/mailman/docs/users.txt b/src/mailman/docs/users.txt new file mode 100644 index 000000000..ff7b9ca84 --- /dev/null +++ b/src/mailman/docs/users.txt @@ -0,0 +1,195 @@ +Users +===== + +Users are entities that represent people. A user has a real name and a +password. Optionally a user may have some preferences and a set of addresses +they control. A user also knows which mailing lists they are subscribed to. + +See usermanager.txt for examples of how to create, delete, and find users. + + >>> usermgr = config.db.user_manager + + +User data +--------- + +Users may have a real name and a password. + + >>> user_1 = usermgr.create_user() + >>> user_1.password = u'my password' + >>> user_1.real_name = u'Zoe Person' + >>> sorted(user.real_name for user in usermgr.users) + [u'Zoe Person'] + >>> sorted(user.password for user in usermgr.users) + [u'my password'] + +The password and real name can be changed at any time. + + >>> user_1.real_name = u'Zoe X. Person' + >>> user_1.password = u'another password' + >>> sorted(user.real_name for user in usermgr.users) + [u'Zoe X. Person'] + >>> sorted(user.password for user in usermgr.users) + [u'another password'] + + +Users addresses +--------------- + +One of the pieces of information that a user links to is a set of email +addresses they control, in the form of IAddress objects. A user can control +many addresses, but addresses may be controlled by only one user. + +The easiest way to link a user to an address is to just register the new +address on a user object. + + >>> user_1.register(u'zperson@example.com', u'Zoe Person') + <Address: Zoe Person <zperson@example.com> [not verified] at 0x...> + >>> user_1.register(u'zperson@example.org') + <Address: zperson@example.org [not verified] at 0x...> + >>> sorted(address.address for address in user_1.addresses) + [u'zperson@example.com', u'zperson@example.org'] + >>> sorted(address.real_name for address in user_1.addresses) + [u'', u'Zoe Person'] + +You can also create the address separately and then link it to the user. + + >>> address_1 = usermgr.create_address(u'zperson@example.net') + >>> user_1.link(address_1) + >>> sorted(address.address for address in user_1.addresses) + [u'zperson@example.com', u'zperson@example.net', u'zperson@example.org'] + >>> sorted(address.real_name for address in user_1.addresses) + [u'', u'', u'Zoe Person'] + +But don't try to link an address to more than one user. + + >>> another_user = usermgr.create_user() + >>> another_user.link(address_1) + Traceback (most recent call last): + ... + AddressAlreadyLinkedError: zperson@example.net + +You can also ask whether a given user controls a given address. + + >>> user_1.controls(address_1.address) + True + >>> user_1.controls(u'bperson@example.com') + False + +Given a text email address, the user manager can find the user that controls +that address. + + >>> usermgr.get_user(u'zperson@example.com') is user_1 + True + >>> usermgr.get_user(u'zperson@example.net') is user_1 + True + >>> usermgr.get_user(u'zperson@example.org') is user_1 + True + >>> print usermgr.get_user(u'bperson@example.com') + None + +Addresses can also be unlinked from a user. + + >>> user_1.unlink(address_1) + >>> user_1.controls(u'zperson@example.net') + False + >>> print usermgr.get_user(u'aperson@example.net') + None + +But don't try to unlink the address from a user it's not linked to. + + >>> user_1.unlink(address_1) + Traceback (most recent call last): + ... + AddressNotLinkedError: zperson@example.net + >>> another_user.unlink(address_1) + Traceback (most recent call last): + ... + AddressNotLinkedError: zperson@example.net + + +Users and preferences +--------------------- + +This is a helper function for the following section. + + >>> def show_prefs(prefs): + ... print 'acknowledge_posts :', prefs.acknowledge_posts + ... print 'preferred_language :', prefs.preferred_language + ... print 'receive_list_copy :', prefs.receive_list_copy + ... print 'receive_own_postings :', prefs.receive_own_postings + ... print 'delivery_mode :', prefs.delivery_mode + +Users have preferences, but these preferences have no default settings. + + >>> from mailman.interfaces.preferences import IPreferences + >>> show_prefs(user_1.preferences) + acknowledge_posts : None + preferred_language : None + receive_list_copy : None + receive_own_postings : None + delivery_mode : None + +Some of these preferences are booleans and they can be set to True or False. + + >>> from mailman.constants import DeliveryMode + >>> prefs = user_1.preferences + >>> prefs.acknowledge_posts = True + >>> prefs.preferred_language = u'it' + >>> prefs.receive_list_copy = False + >>> prefs.receive_own_postings = False + >>> prefs.delivery_mode = DeliveryMode.regular + >>> show_prefs(user_1.preferences) + acknowledge_posts : True + preferred_language : it + receive_list_copy : False + receive_own_postings : False + delivery_mode : DeliveryMode.regular + + +Subscriptions +------------- + +Users know which mailing lists they are subscribed to, regardless of +membership role. + + >>> user_1.link(address_1) + >>> sorted(address.address for address in user_1.addresses) + [u'zperson@example.com', u'zperson@example.net', u'zperson@example.org'] + >>> com = usermgr.get_address(u'zperson@example.com') + >>> org = usermgr.get_address(u'zperson@example.org') + >>> net = usermgr.get_address(u'zperson@example.net') + + >>> from mailman.app.lifecycle import create_list + >>> mlist_1 = create_list(u'xtest_1@example.com') + >>> mlist_2 = create_list(u'xtest_2@example.com') + >>> mlist_3 = create_list(u'xtest_3@example.com') + >>> from mailman.interfaces.member import MemberRole + + >>> com.subscribe(mlist_1, MemberRole.member) + <Member: Zoe Person <zperson@example.com> on xtest_1@example.com as + MemberRole.member> + >>> org.subscribe(mlist_2, MemberRole.member) + <Member: zperson@example.org on xtest_2@example.com as MemberRole.member> + >>> org.subscribe(mlist_2, MemberRole.owner) + <Member: zperson@example.org on xtest_2@example.com as MemberRole.owner> + >>> net.subscribe(mlist_3, MemberRole.moderator) + <Member: zperson@example.net on xtest_3@example.com as + MemberRole.moderator> + + >>> memberships = user_1.memberships + >>> from mailman.interfaces.roster import IRoster + >>> from zope.interface.verify import verifyObject + >>> verifyObject(IRoster, memberships) + True + >>> members = sorted(memberships.members) + >>> len(members) + 4 + >>> def sortkey(member): + ... return member.address.address, member.mailing_list, int(member.role) + >>> for member in sorted(members, key=sortkey): + ... print member.address.address, member.mailing_list, member.role + zperson@example.com xtest_1@example.com MemberRole.member + zperson@example.net xtest_3@example.com MemberRole.moderator + zperson@example.org xtest_2@example.com MemberRole.member + zperson@example.org xtest_2@example.com MemberRole.owner |