path: root/src/mailman/model/docs/users.txt

=====
Users
=====

Users are entities that represent people.  A user has a real name and a
optional encoded password.  A user may also have an optional preferences and a
set of addresses they control.

See `usermanager.txt`_ for examples of how to create, delete, and find users.

    >>> from mailman.interfaces.usermanager import IUserManager
    >>> from zope.component import getUtility
    >>> user_manager = getUtility(IUserManager)


User data
=========

Users may have a real name and a password.

    >>> user_1 = user_manager.create_user()
    >>> user_1.password = 'my password'
    >>> user_1.real_name = 'Zoe Person'
    >>> dump_list(user.real_name for user in user_manager.users)
    Zoe Person
    >>> dump_list(user.password for user in user_manager.users)
    my password

The password and real name can be changed at any time.

    >>> user_1.real_name = 'Zoe X. Person'
    >>> user_1.password = 'another password'
    >>> dump_list(user.real_name for user in user_manager.users)
    Zoe X. Person
    >>> dump_list(user.password for user in user_manager.users)
    another password


Basic user identification
=========================

Although rarely visible to users, every user has a unique ID in Mailman, which
never changes.  This ID is generated randomly at the time the user is
created.

    # The test suite uses a predictable user id.
    >>> print user_1.user_id
    1

The user id cannot change.

    >>> user_1.user_id = 'foo'
    Traceback (most recent call last):
    ...
    AttributeError: can't set attribute

User records also have a date on which they where created.

    # The test suite uses a predictable timestamp.
    >>> print user_1.created_on
    2005-08-01 07:49:23


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('zperson@example.com', 'Zoe Person')
    <Address: Zoe Person <zperson@example.com> [not verified] at 0x...>
    >>> user_1.register('zperson@example.org')
    <Address: zperson@example.org [not verified] at 0x...>
    >>> dump_list(address.email for address in user_1.addresses)
    zperson@example.com
    zperson@example.org
    >>> dump_list(address.real_name for address in user_1.addresses)
    <BLANKLINE>
    Zoe Person

You can also create the address separately and then link it to the user.

    >>> address_1 = user_manager.create_address('zperson@example.net')
    >>> user_1.link(address_1)
    >>> dump_list(address.email for address in user_1.addresses)
    zperson@example.com
    zperson@example.net
    zperson@example.org
    >>> dump_list(address.real_name for address in user_1.addresses)
    <BLANKLINE>
    <BLANKLINE>
    Zoe Person

But don't try to link an address to more than one user.

    >>> another_user = user_manager.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.email)
    True
    >>> user_1.controls('bperson@example.com')
    False

Given a text email address, the user manager can find the user that controls
that address.

    >>> user_manager.get_user('zperson@example.com') is user_1
    True
    >>> user_manager.get_user('zperson@example.net') is user_1
    True
    >>> user_manager.get_user('zperson@example.org') is user_1
    True
    >>> print user_manager.get_user('bperson@example.com')
    None

Addresses can also be unlinked from a user.

    >>> user_1.unlink(address_1)
    >>> user_1.controls('zperson@example.net')
    False
    >>> print user_manager.get_user('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.interfaces.languages import ILanguageManager
    >>> getUtility(ILanguageManager).add('it', 'iso-8859-1', 'Italian')

    >>> from mailman.core.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
    >>> show_prefs(user_1.preferences)
    acknowledge_posts    : True
    preferred_language   : <Language [it] Italian>
    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)
    >>> dump_list(address.email for address in user_1.addresses)
    zperson@example.com
    zperson@example.net
    zperson@example.org
    >>> com = user_manager.get_address('zperson@example.com')
    >>> org = user_manager.get_address('zperson@example.org')
    >>> net = user_manager.get_address('zperson@example.net')

    >>> mlist_1 = create_list('xtest_1@example.com')
    >>> mlist_2 = create_list('xtest_2@example.com')
    >>> mlist_3 = create_list('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.email, member.mailing_list,
    ...             int(member.role))
    >>> for member in sorted(members, key=sortkey):
    ...     print member.address.email, 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


.. _`usermanager.txt`: usermanager.html