Before users can join a mailing list, they must first register with Mailman. The only thing they must supply is an email address, although there is additional information they may supply. All registered email addresses must be verified before Mailman will send them any list traffic.
The IUserManager manages users, but it does so at a fairly low level. Specifically, it does not handle verifications, email address syntax validity checks, etc. The IRegistrar is the interface to the object handling all this stuff.
>>> from mailman.interfaces.registrar import IRegistrar
>>> from zope.component import getUtility
>>> registrar = getUtility(IRegistrar)
Here is a helper function to check the token strings.
>>> def check_token(token):
... assert isinstance(token, basestring), 'Not a string'
... assert len(token) == 40, 'Unexpected length: %d' % len(token)
... assert token.isalnum(), 'Not alphanumeric'
... print 'ok'
Here is a helper function to extract tokens from confirmation messages.
>>> import re
>>> cre = re.compile('http://lists.example.com/confirm/(.*)')
>>> def extract_token(msg):
... mo = cre.search(msg.get_payload())
... return mo.group(1)
Addresses are registered within the context of a mailing list, mostly so that confirmation emails can come from some place. You also need the email address of the user who is registering.
>>> mlist = create_list('alpha@example.com')
Some amount of sanity checks are performed on the email address, although honestly, not as much as probably should be done. Still, some patently bad addresses are rejected outright.
>>> registrar.register(mlist, '')
Traceback (most recent call last):
...
InvalidEmailAddressError: u''
>>> registrar.register(mlist, 'some name@example.com')
Traceback (most recent call last):
...
InvalidEmailAddressError: u'some name@example.com'
>>> registrar.register(mlist, '<script>@example.com')
Traceback (most recent call last):
...
InvalidEmailAddressError: u'<script>@example.com'
>>> registrar.register(mlist, '\xa0@example.com')
Traceback (most recent call last):
...
InvalidEmailAddressError: u'\xa0@example.com'
>>> registrar.register(mlist, 'noatsign')
Traceback (most recent call last):
...
InvalidEmailAddressError: u'noatsign'
>>> registrar.register(mlist, 'nodom@ain')
Traceback (most recent call last):
...
InvalidEmailAddressError: u'nodom@ain'
Registration of an unknown address creates nothing until the confirmation step is complete. No IUser or IAddress is created at registration time, but a record is added to the pending database, and the token for that record is returned.
>>> token = registrar.register(mlist, 'aperson@example.com', 'Anne Person')
>>> check_token(token)
ok
There should be no records in the user manager for this address yet.
>>> from mailman.interfaces.usermanager import IUserManager
>>> from zope.component import getUtility
>>> user_manager = getUtility(IUserManager)
>>> print user_manager.get_user('aperson@example.com')
None
>>> print user_manager.get_address('aperson@example.com')
None
But this address is waiting for confirmation.
>>> from mailman.interfaces.pending import IPendings
>>> pendingdb = getUtility(IPendings)
>>> dump_msgdata(pendingdb.confirm(token, expunge=False))
address : aperson@example.com
list_name: alpha@example.com
real_name: Anne Person
type : registration
There is also a verification email sitting in the virgin queue now. This message is sent to the user in order to verify the registered address.
>>> from mailman.testing.helpers import get_queue_messages
>>> items = get_queue_messages('virgin')
>>> len(items)
1
>>> print items[0].msg.as_string()
MIME-Version: 1.0
...
Subject: confirm ...
From: alpha-confirm+...@example.com
To: aperson@example.com
...
<BLANKLINE>
Email Address Registration Confirmation
<BLANKLINE>
Hello, this is the GNU Mailman server at example.com.
<BLANKLINE>
We have received a registration request for the email address
<BLANKLINE>
aperson@example.com
<BLANKLINE>
Before you can start using GNU Mailman at this site, you must first
confirm that this is your email address. You can do this by replying to
this message, keeping the Subject header intact. Or you can visit this
web page
<BLANKLINE>
http://lists.example.com/confirm/...
<BLANKLINE>
If you do not wish to register this email address simply disregard this
message. If you think you are being maliciously subscribed to the list,
or have any other questions, you may contact
<BLANKLINE>
postmaster@example.com
<BLANKLINE>
>>> dump_msgdata(items[0].msgdata)
_parsemsg : False
listname : alpha@example.com
nodecorate : True
recipients : [u'aperson@example.com']
reduced_list_headers: True
version : 3
The confirmation token shows up in several places, each of which provides an easy way for the user to complete the confirmation. The token will always appear in a URL in the body of the message.
>>> sent_token = extract_token(items[0].msg)
>>> sent_token == token
True
The same token will appear in the From header.
>>> items[0].msg['from'] == 'alpha-confirm+' + token + '@example.com'
True
It will also appear in the Subject header.
>>> items[0].msg['subject'] == 'confirm ' + token
True
The user would then validate their registered address by clicking on a url or responding to the message. Either way, the confirmation process extracts the token and uses that to confirm the pending registration.
>>> registrar.confirm(token)
True
Now, there is an IAddress in the database matching the address, as well as an IUser linked to this address. The IAddress is verified.
>>> found_address = user_manager.get_address('aperson@example.com')
>>> found_address
<Address: Anne Person <aperson@example.com> [verified] at ...>
>>> found_user = user_manager.get_user('aperson@example.com')
>>> found_user
<User "Anne Person" at ...>
>>> found_user.controls(found_address.address)
True
>>> from datetime import datetime
>>> isinstance(found_address.verified_on, datetime)
True
If you try to confirm a registration token twice, of course only the first one will work. The second one is ignored.
>>> token = registrar.register(mlist, 'bperson@example.com')
>>> check_token(token)
ok
>>> items = get_queue_messages('virgin')
>>> len(items)
1
>>> sent_token = extract_token(items[0].msg)
>>> token == sent_token
True
>>> registrar.confirm(token)
True
>>> registrar.confirm(token)
False
If an address is in the system, but that address is not linked to a user yet and the address is not yet validated, then no user is created until the confirmation step is completed.
>>> user_manager.create_address('cperson@example.com')
<Address: cperson@example.com [not verified] at ...>
>>> token = registrar.register(
... mlist, 'cperson@example.com', 'Claire Person')
>>> print user_manager.get_user('cperson@example.com')
None
>>> items = get_queue_messages('virgin')
>>> len(items)
1
>>> sent_token = extract_token(items[0].msg)
>>> registrar.confirm(sent_token)
True
>>> user_manager.get_user('cperson@example.com')
<User "Claire Person" at ...>
>>> user_manager.get_address('cperson@example.com')
<Address: cperson@example.com [verified] at ...>
Even if the address being registered has already been verified, the registration sends a confirmation.
>>> token = registrar.register(mlist, 'cperson@example.com')
>>> token is not None
True
A confirmation token can also be discarded, say if the user changes his or her mind about registering. When discarded, no IAddress or IUser is created.
>>> token = registrar.register(mlist, 'eperson@example.com', 'Elly Person')
>>> check_token(token)
ok
>>> registrar.discard(token)
>>> print pendingdb.confirm(token)
None
>>> print user_manager.get_address('eperson@example.com')
None
>>> print user_manager.get_user('eperson@example.com')
None
# Clear the virgin queue of all the preceding confirmation messages.
>>> ignore = get_queue_messages('virgin')
When a new address for an existing user is registered, there isn’t too much different except that the new address will still need to be verified before it can be used.
>>> dperson = user_manager.create_user(
... 'dperson@example.com', 'Dave Person')
>>> dperson
<User "Dave Person" at ...>
>>> address = user_manager.get_address('dperson@example.com')
>>> address.verified_on = datetime.now()
>>> from operator import attrgetter
>>> sorted((addr for addr in dperson.addresses), key=attrgetter('address'))
[<Address: Dave Person <dperson@example.com> [verified] at ...>]
>>> dperson.register('david.person@example.com', 'David Person')
<Address: David Person <david.person@example.com> [not verified] at ...>
>>> token = registrar.register(mlist, 'david.person@example.com')
>>> items = get_queue_messages('virgin')
>>> len(items)
1
>>> sent_token = extract_token(items[0].msg)
>>> registrar.confirm(sent_token)
True
>>> user = user_manager.get_user('david.person@example.com')
>>> user is dperson
True
>>> user
<User "Dave Person" at ...>
>>> sorted((addr for addr in user.addresses), key=attrgetter('address'))
[<Address: David Person <david.person@example.com> [verified] at ...>,
<Address: Dave Person <dperson@example.com> [verified] at ...>]
If you try to confirm a token that doesn’t exist in the pending database, the confirm method will just return False.
>>> registrar.confirm(bytes('no token'))
False
Likewise, if you try to confirm, through the IUserRegistrar interface, a token that doesn’t match a registration event, you will get None. However, the pending event matched with that token will still be removed.
>>> from mailman.interfaces.pending import IPendable
>>> from zope.interface import implements
>>> class SimplePendable(dict):
... implements(IPendable)
>>> pendable = SimplePendable(type='foo', bar='baz')
>>> token = pendingdb.add(pendable)
>>> registrar.confirm(token)
False
>>> print pendingdb.confirm(token)
None
Fred registers with Mailman at the same time that he subscribes to a mailing list.
>>> token = registrar.register(
... mlist, 'fred.person@example.com', 'Fred Person')
Before confirmation, Fred is not a member of the mailing list.
>>> print mlist.members.get_member('fred.person@example.com')
None
But after confirmation, he is.
>>> registrar.confirm(token)
True
>>> print mlist.members.get_member('fred.person@example.com')
<Member: Fred Person <fred.person@example.com>
on alpha@example.com as MemberRole.member>