src/mailman/docs/users.txt

   1 =====
   2 Users
   3 =====
   4
   5 Users are entities that represent people.  A user has a real name and a
   6 password.  Optionally a user may have some preferences and a set of addresses
   7 they control.  A user also knows which mailing lists they are subscribed to.
   8
   9 See `usermanager.txt`_ for examples of how to create, delete, and find users.
  10
  11     >>> from mailman.interfaces.usermanager import IUserManager
  12     >>> from zope.component import getUtility
  13     >>> user_manager = getUtility(IUserManager)
  14
  15
  16 User data
  17 =========
  18
  19 Users may have a real name and a password.
  20
  21     >>> user_1 = user_manager.create_user()
  22     >>> user_1.password = 'my password'
  23     >>> user_1.real_name = 'Zoe Person'
  24     >>> sorted(user.real_name for user in user_manager.users)
  25     [u'Zoe Person']
  26     >>> sorted(user.password for user in user_manager.users)
  27     [u'my password']
  28
  29 The password and real name can be changed at any time.
  30
  31     >>> user_1.real_name = 'Zoe X. Person'
  32     >>> user_1.password = 'another password'
  33     >>> sorted(user.real_name for user in user_manager.users)
  34     [u'Zoe X. Person']
  35     >>> sorted(user.password for user in user_manager.users)
  36     [u'another password']
  37
  38
  39 Users addresses
  40 ===============
  41
  42 One of the pieces of information that a user links to is a set of email
  43 addresses they control, in the form of IAddress objects.  A user can control
  44 many addresses, but addresses may be controlled by only one user.
  45
  46 The easiest way to link a user to an address is to just register the new
  47 address on a user object.
  48
  49     >>> user_1.register('zperson@example.com', 'Zoe Person')
  50     <Address: Zoe Person <zperson@example.com> [not verified] at 0x...>
  51     >>> user_1.register('zperson@example.org')
  52     <Address: zperson@example.org [not verified] at 0x...>
  53     >>> sorted(address.address for address in user_1.addresses)
  54     [u'zperson@example.com', u'zperson@example.org']
  55     >>> sorted(address.real_name for address in user_1.addresses)
  56     [u'', u'Zoe Person']
  57
  58 You can also create the address separately and then link it to the user.
  59
  60     >>> address_1 = user_manager.create_address('zperson@example.net')
  61     >>> user_1.link(address_1)
  62     >>> sorted(address.address for address in user_1.addresses)
  63     [u'zperson@example.com', u'zperson@example.net', u'zperson@example.org']
  64     >>> sorted(address.real_name for address in user_1.addresses)
  65     [u'', u'', u'Zoe Person']
  66
  67 But don't try to link an address to more than one user.
  68
  69     >>> another_user = user_manager.create_user()
  70     >>> another_user.link(address_1)
  71     Traceback (most recent call last):
  72     ...
  73     AddressAlreadyLinkedError: zperson@example.net
  74
  75 You can also ask whether a given user controls a given address.
  76
  77     >>> user_1.controls(address_1.address)
  78     True
  79     >>> user_1.controls('bperson@example.com')
  80     False
  81
  82 Given a text email address, the user manager can find the user that controls
  83 that address.
  84
  85     >>> user_manager.get_user('zperson@example.com') is user_1
  86     True
  87     >>> user_manager.get_user('zperson@example.net') is user_1
  88     True
  89     >>> user_manager.get_user('zperson@example.org') is user_1
  90     True
  91     >>> print user_manager.get_user('bperson@example.com')
  92     None
  93
  94 Addresses can also be unlinked from a user.
  95
  96     >>> user_1.unlink(address_1)
  97     >>> user_1.controls('zperson@example.net')
  98     False
  99     >>> print user_manager.get_user('aperson@example.net')
 100     None
 101
 102 But don't try to unlink the address from a user it's not linked to.
 103
 104     >>> user_1.unlink(address_1)
 105     Traceback (most recent call last):
 106     ...
 107     AddressNotLinkedError: zperson@example.net
 108     >>> another_user.unlink(address_1)
 109     Traceback (most recent call last):
 110     ...
 111     AddressNotLinkedError: zperson@example.net
 112
 113
 114 Users and preferences
 115 =====================
 116
 117 This is a helper function for the following section.
 118
 119     >>> def show_prefs(prefs):
 120     ...     print 'acknowledge_posts    :', prefs.acknowledge_posts
 121     ...     print 'preferred_language   :', prefs.preferred_language
 122     ...     print 'receive_list_copy    :', prefs.receive_list_copy
 123     ...     print 'receive_own_postings :', prefs.receive_own_postings
 124     ...     print 'delivery_mode        :', prefs.delivery_mode
 125
 126 Users have preferences, but these preferences have no default settings.
 127
 128     >>> from mailman.interfaces.preferences import IPreferences
 129     >>> show_prefs(user_1.preferences)
 130     acknowledge_posts    : None
 131     preferred_language   : None
 132     receive_list_copy    : None
 133     receive_own_postings : None
 134     delivery_mode        : None
 135
 136 Some of these preferences are booleans and they can be set to True or False.
 137
 138     >>> config.languages.add('it', 'iso-8859-1', 'Italian')
 139
 140     >>> from mailman.core.constants import DeliveryMode
 141     >>> prefs = user_1.preferences
 142     >>> prefs.acknowledge_posts = True
 143     >>> prefs.preferred_language = 'it'
 144     >>> prefs.receive_list_copy = False
 145     >>> prefs.receive_own_postings = False
 146     >>> prefs.delivery_mode = DeliveryMode.regular
 147     >>> show_prefs(user_1.preferences)
 148     acknowledge_posts    : True
 149     preferred_language   : <Language [it] Italian>
 150     receive_list_copy    : False
 151     receive_own_postings : False
 152     delivery_mode        : DeliveryMode.regular
 153
 154
 155 Subscriptions
 156 =============
 157
 158 Users know which mailing lists they are subscribed to, regardless of
 159 membership role.
 160
 161     >>> user_1.link(address_1)
 162     >>> sorted(address.address for address in user_1.addresses)
 163     [u'zperson@example.com', u'zperson@example.net', u'zperson@example.org']
 164     >>> com = user_manager.get_address('zperson@example.com')
 165     >>> org = user_manager.get_address('zperson@example.org')
 166     >>> net = user_manager.get_address('zperson@example.net')
 167
 168     >>> mlist_1 = create_list('xtest_1@example.com')
 169     >>> mlist_2 = create_list('xtest_2@example.com')
 170     >>> mlist_3 = create_list('xtest_3@example.com')
 171     >>> from mailman.interfaces.member import MemberRole
 172
 173     >>> com.subscribe(mlist_1, MemberRole.member)
 174     <Member: Zoe Person <zperson@example.com> on xtest_1@example.com as
 175         MemberRole.member>
 176     >>> org.subscribe(mlist_2, MemberRole.member)
 177     <Member: zperson@example.org on xtest_2@example.com as MemberRole.member>
 178     >>> org.subscribe(mlist_2, MemberRole.owner)
 179     <Member: zperson@example.org on xtest_2@example.com as MemberRole.owner>
 180     >>> net.subscribe(mlist_3, MemberRole.moderator)
 181     <Member: zperson@example.net on xtest_3@example.com as
 182         MemberRole.moderator>
 183
 184     >>> memberships = user_1.memberships
 185     >>> from mailman.interfaces.roster import IRoster
 186     >>> from zope.interface.verify import verifyObject
 187     >>> verifyObject(IRoster, memberships)
 188     True
 189     >>> members = sorted(memberships.members)
 190     >>> len(members)
 191     4
 192     >>> def sortkey(member):
 193     ...     return (member.address.address, member.mailing_list,
 194     ...             int(member.role))
 195     >>> for member in sorted(members, key=sortkey):
 196     ...     print member.address.address, member.mailing_list, member.role
 197     zperson@example.com xtest_1@example.com MemberRole.member
 198     zperson@example.net xtest_3@example.com MemberRole.moderator
 199     zperson@example.org xtest_2@example.com MemberRole.member
 200     zperson@example.org xtest_2@example.com MemberRole.owner
 201
 202
 203 Cross references
 204 ================
 205
 206 .. _`usermanager.txt`: usermanager.html
 207