diff options
Diffstat (limited to 'Mailman/docs')
| -rw-r--r-- | Mailman/docs/usermanager.txt | 9 | ||||
| -rw-r--r-- | Mailman/docs/users.txt | 145 |
2 files changed, 90 insertions, 64 deletions
diff --git a/Mailman/docs/usermanager.txt b/Mailman/docs/usermanager.txt index 389c68956..1f863b606 100644 --- a/Mailman/docs/usermanager.txt +++ b/Mailman/docs/usermanager.txt @@ -20,7 +20,7 @@ Creating users There are several ways you can create a user object. The simplest is to create a 'blank' user by not providing an address or real name at creation time. This user will have an empty string as their real name, but will not -have a password or preferences. +have a password. >>> from Mailman.interfaces import IUser >>> user = mgr.create_user() @@ -31,11 +31,14 @@ have a password or preferences. [] >>> user.real_name '' - >>> print user.preferences - None >>> print user.password None +The user has preferences, but none of them will be specified. + + >>> print user.preferences + <Preferences ...> + A user can be assigned a real name. >>> user.real_name = 'Anne Person' diff --git a/Mailman/docs/users.txt b/Mailman/docs/users.txt index a65527eff..2b60ed0bc 100644 --- a/Mailman/docs/users.txt +++ b/Mailman/docs/users.txt @@ -17,9 +17,9 @@ User data Users may have a real name and a password. - >>> user = mgr.create_user() - >>> user.password = 'my password' - >>> user.real_name = 'Zoe Person' + >>> user_1 = mgr.create_user() + >>> user_1.password = 'my password' + >>> user_1.real_name = 'Zoe Person' >>> flush() >>> sorted(user.real_name for user in mgr.users) ['Zoe Person'] @@ -28,8 +28,8 @@ Users may have a real name and a password. The password and real name can be changed at any time. - >>> user.real_name = 'Zoe X. Person' - >>> user.password = 'another password' + >>> user_1.real_name = 'Zoe X. Person' + >>> user_1.password = 'another password' >>> flush() >>> sorted(user.real_name for user in mgr.users) ['Zoe X. Person'] @@ -41,101 +41,124 @@ Users addresses --------------- One of the pieces of information that a user links to is a set of email -addresses, in the form of IAddress objects. A user can control many -addresses, but addresses may be control by only one user. +addresses they control, in the form of IAddress objects. A user can control +many addresses, but addresses may be controlled by only one user. -Given a user and an address, you can link the two together. +The easiest way to link a user to an address is to just register the new +address on a user object. - >>> roster = mgr.get_roster('') - >>> address = roster.create('aperson@example.com', 'Anne Person') - >>> user.link(address) + >>> user_1.register('zperson@example.com', 'Zoe Person') + <Address: Zoe Person <zperson@example.com> [not verified]> + >>> user_1.register('zperson@example.org') + <Address: zperson@example.org [not verified]> >>> flush() - >>> sorted(address.address for address in user.addresses) - ['aperson@example.com'] + >>> sorted(address.address for address in user_1.addresses) + ['zperson@example.com', 'zperson@example.org'] + >>> sorted(address.real_name for address in user_1.addresses) + ['', 'Zoe Person'] + +You can also create the address separately and then link it to the user. + + >>> address_1 = mgr.create_address('zperson@example.net') + >>> user_1.link(address_1) + >>> flush() + >>> sorted(address.address for address in user_1.addresses) + ['zperson@example.com', 'zperson@example.net', 'zperson@example.org'] + >>> sorted(address.real_name for address in user_1.addresses) + ['', '', 'Zoe Person'] But don't try to link an address to more than one user. >>> another_user = mgr.create_user() - >>> another_user.link(address) + >>> another_user.link(address_1) Traceback (most recent call last): ... - AddressAlreadyLinkedError: Anne Person <aperson@example.com> + AddressAlreadyLinkedError: zperson@example.net You can also ask whether a given user controls a given address. - >>> user.controls(address) + >>> user_1.controls(address_1.address) True - >>> not_my_address = roster.create('bperson@example.com', 'Ben Person') - >>> user.controls(not_my_address) + >>> user_1.controls('bperson@example.com') False Given a text email address, the user manager can find the user that controls that address. - >>> mgr.get_user('aperson@example.com') is user + >>> mgr.get_user('zperson@example.com') is user_1 True - >>> mgr.get_user('bperson@example.com') is None + >>> mgr.get_user('zperson@example.net') is user_1 True + >>> mgr.get_user('zperson@example.org') is user_1 + True + >>> print mgr.get_user('bperson@example.com') + None Addresses can also be unlinked from a user. - >>> user.unlink(address) - >>> user.controls(address) + >>> user_1.unlink(address_1) + >>> user_1.controls('zperson@example.net') False - >>> mgr.get_user('aperson@example.com') is None - True + >>> print mgr.get_user('aperson@example.net') + None But don't try to unlink the address from a user it's not linked to. - >>> user.unlink(address) + >>> user_1.unlink(address_1) Traceback (most recent call last): ... - AddressNotLinkedError: Anne Person <aperson@example.com> - >>> another_user.unlink(address) + AddressNotLinkedError: zperson@example.net + >>> another_user.unlink(address_1) Traceback (most recent call last): ... - AddressNotLinkedError: Anne Person <aperson@example.com> - >>> mgr.delete_user(another_user) + AddressNotLinkedError: zperson@example.net -Users and profiles ------------------- +Users and preferences +--------------------- -Users always have a default profile. +This is a helper function for the following section. - >>> from Mailman.interfaces import IProfile - >>> IProfile.providedBy(user.profile) - True - -A profile is a set of preferences such as whether the user wants to receive an -acknowledgment of all of their posts to a mailing list... + >>> 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 - >>> user.profile.acknowledge_posts - False +Users have preferences, but these preferences have no default settings. -...whether the user wants to hide their email addresses on web pages and in -postings to the list... + >>> from Mailman.interfaces import IPreferences + >>> show_prefs(user_1.preferences) + acknowledge_posts : None + preferred_language : None + receive_list_copy : None + receive_own_postings : None + delivery_mode : None - >>> user.profile.hide_address - True +Some of these preferences are booleans and they can be set to True or False. -...the language code for the user's preferred language... - - >>> user.profile.preferred_language - 'en' - -...whether the user wants to receive the list's copy of a message if they are -explicitly named in one of the recipient headers... - - >>> user.profile.receive_list_copy - True - -...whether the user wants to receive a copy of their own postings... + >>> from Mailman.constants import DeliveryMode + >>> prefs = user_1.preferences + >>> prefs.acknowledge_posts = True + >>> prefs.preferred_language = 'it' + >>> prefs.receive_list_copy = False + >>> prefs.receive_own_postings = False + >>> prefs.delivery_mode = DeliveryMode.regular + >>> flush() + >>> show_prefs(user_1.preferences) + acknowledge_posts : True + preferred_language : it + receive_list_copy : False + receive_own_postings : False + delivery_mode : DeliveryMode.regular - >>> user.profile.receive_own_postings - True -...and the preferred delivery method. +Clean up +-------- - >>> print user.profile.delivery_mode - DeliveryMode.regular + >>> for user in mgr.users: + ... mgr.delete_user(user) + >>> flush() + >>> sorted(mgr.users) + [] |