diff options
Diffstat (limited to 'mailman/docs/users.txt')
| -rw-r--r-- | mailman/docs/users.txt | 195 |
1 files changed, 0 insertions, 195 deletions
diff --git a/mailman/docs/users.txt b/mailman/docs/users.txt deleted file mode 100644 index ff7b9ca84..000000000 --- a/mailman/docs/users.txt +++ /dev/null @@ -1,195 +0,0 @@ -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 |