← Back to branch summary

~barry/mailman/lp1423756

« back to all changes in this revision

Viewing changes to src/mailman/model/docs/users.rst

  • Committer: Barry Warsaw
  • Date: 2015-01-05 01:20:33 UTC
  • mfrom: (7264.4.66 py3)
  • Revision ID: barry@list.org-20150105012033-zdrw9c2odhpf22fz
Merge the Python 3 branch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/mailman/model/docs/users.rst
20
20
Users may have a real name and a password.
21
21
 
22
22
    >>> user_1 = user_manager.create_user()
23
 
    >>> user_1.password = b'my password'
 
23
    >>> user_1.password = 'my password'
24
24
    >>> user_1.display_name = 'Zoe Person'
25
25
    >>> dump_list(user.display_name for user in user_manager.users)
26
26
    Zoe Person
30
30
The password and real name can be changed at any time.
31
31
 
32
32
    >>> user_1.display_name = 'Zoe X. Person'
33
 
    >>> user_1.password = b'another password'
 
33
    >>> user_1.password = 'another password'
34
34
    >>> dump_list(user.display_name for user in user_manager.users)
35
35
    Zoe X. Person
36
36
    >>> dump_list(user.password for user in user_manager.users)
44
44
    ...     saved_event = event
45
45
    >>> from mailman.testing.helpers import event_subscribers
46
46
    >>> with event_subscribers(save_event):
47
 
    ...     user_1.password = b'changed again'
 
47
    ...     user_1.password = 'changed again'
48
48
    >>> print(saved_event)
49
49
    <PasswordChangeEvent Zoe X. Person>
50
50
 
59
59
Basic user identification
60
60
=========================
61
61
 
62
 
Although rarely visible to users, every user has a unique ID in Mailman, which
63
 
never changes.  This ID is generated randomly at the time the user is created,
64
 
and is represented by a UUID.
 
62
Although rarely visible to users, every user has a unique immutable ID.  This
 
63
ID is generated randomly at the time the user is created, and is represented
 
64
by a UUID.
65
65
 
66
66
    >>> print(user_1.user_id)
67
67
    00000000-0000-0000-0000-000000000001
68
68
 
69
 
The user id cannot change.
70
 
 
71
 
    >>> user_1.user_id = 'foo'
72
 
    Traceback (most recent call last):
73
 
    ...
74
 
    AttributeError: can't set attribute
75
 
 
76
69
User records also have a date on which they where created.
77
70
 
78
71
    # The test suite uses a predictable timestamp.
84
77
===============
85
78
 
86
79
One of the pieces of information that a user links to is a set of email
87
 
addresses they control, in the form of IAddress objects.  A user can control
88
 
many addresses, but addresses may be controlled by only one user.
 
80
addresses they control, in the form of ``IAddress`` objects.  A user can
 
81
control many addresses, but addresses may be linked to only one user.
89
82
 
90
83
The easiest way to link a user to an address is to just register the new
91
84
address on a user object.
114
107
    <BLANKLINE>
115
108
    Zoe Person
116
109
 
117
 
But don't try to link an address to more than one user.
118
 
 
119
 
    >>> another_user = user_manager.create_user()
120
 
    >>> another_user.link(address_1)
121
 
    Traceback (most recent call last):
122
 
    ...
123
 
    AddressAlreadyLinkedError: zperson@example.net
124
 
 
125
110
You can also ask whether a given user controls a given address.
126
111
 
127
112
    >>> user_1.controls(address_1.email)
149
134
    >>> print(user_manager.get_user('aperson@example.net'))
150
135
    None
151
136
 
152
 
But don't try to unlink the address from a user it's not linked to.
153
 
 
154
 
    >>> user_1.unlink(address_1)
155
 
    Traceback (most recent call last):
156
 
    ...
157
 
    AddressNotLinkedError: zperson@example.net
158
 
    >>> another_user.unlink(address_1)
159
 
    Traceback (most recent call last):
160
 
    ...
161
 
    AddressNotLinkedError: zperson@example.net
162
 
 
163
137
 
164
138
Preferred address
165
139
=================
183
157
    >>> print(user_2.preferred_address)
184
158
    None
185
159
 
186
 
The preferred address must be explicitly registered, however only verified
187
 
address may be registered as preferred.
188
 
 
189
 
    >>> anne
190
 
    <Address: Anne Person <anne@example.com> [not verified] at ...>
191
 
    >>> user_2.preferred_address = anne
192
 
    Traceback (most recent call last):
193
 
    ...
194
 
    UnverifiedAddressError: Anne Person <anne@example.com>
195
 
 
196
 
Once the address has been verified though, it can be set as the preferred
197
 
address, but only if the address is either controlled by the user or
198
 
uncontrolled.  In the latter case, setting it as the preferred address makes
199
 
it controlled by the user.
 
160
Once the address has been verified, it can be set as the preferred address,
 
161
but only if the address is either controlled by the user or uncontrolled.  In
 
162
the latter case, setting it as the preferred address makes it controlled by
 
163
the user.
200
164
::
201
165
 
202
166
    >>> from mailman.utilities.datetime import now
217
181
    >>> user_2.controls(aperson.email)
218
182
    True
219
183
 
220
 
    >>> zperson = user_manager.get_address('zperson@example.com')
221
 
    >>> zperson.verified_on = now()
222
 
    >>> user_2.controls(zperson.email)
223
 
    False
224
 
    >>> user_1.controls(zperson.email)
225
 
    True
226
 
    >>> user_2.preferred_address = zperson
227
 
    Traceback (most recent call last):
228
 
    ...
229
 
    AddressAlreadyLinkedError: Zoe Person <zperson@example.com>
230
 
 
231
184
A user can disavow their preferred address.
232
185
 
233
186
    >>> user_2.preferred_address
328
281
    >>> from zope.interface.verify import verifyObject
329
282
    >>> verifyObject(IRoster, memberships)
330
283
    True
331
 
    >>> members = sorted(memberships.members)
 
284
    >>> def sortkey(member):
 
285
    ...     return member.address.email, member.mailing_list, member.role.value
 
286
    >>> members = sorted(memberships.members, key=sortkey)
332
287
    >>> len(members)
333
288
    4
334
 
    >>> def sortkey(member):
335
 
    ...     return member.address.email, member.mailing_list, member.role.value
336
289
    >>> for member in sorted(members, key=sortkey):
337
290
    ...     print(member.address.email, member.mailing_list.list_id,
338
291
    ...           member.role)