===========
Preferences
===========

Addresses have preferences.
::

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

    >>> anne = user_manager.create_address('anne@example.com')
    >>> transaction.commit()

Although to start with, an address has no preferences.

    >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com'
    ...           '/preferences')
    http_etag: "..."
    self_link: http://localhost:9001/3.0/addresses/anne@example.com/preferences

Once the address is given some preferences, they are available through the
REST API.

    >>> anne.preferences.acknowledge_posts = True
    >>> transaction.commit()
    >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com'
    ...           '/preferences')
    acknowledge_posts: True
    http_etag: "..."
    self_link: http://localhost:9001/3.0/addresses/anne@example.com/preferences

Similarly, users have their own set of preferences, which also start out empty.
::

    >>> bart = user_manager.create_user('bart@example.com')
    >>> transaction.commit()

    >>> dump_json('http://localhost:9001/3.0/addresses/bart@example.com'
    ...           '/preferences')
    http_etag: "..."
    self_link: http://localhost:9001/3.0/addresses/bart@example.com/preferences

Setting a preference on the user's address does not set them on the user.
::

    >>> list(bart.addresses)[0].preferences.acknowledge_posts = True
    >>> transaction.commit()

    >>> dump_json('http://localhost:9001/3.0/addresses/bart@example.com'
    ...           '/preferences')
    acknowledge_posts: True
    http_etag: "..."
    self_link: http://localhost:9001/3.0/addresses/bart@example.com/preferences

    >>> dump_json('http://localhost:9001/3.0/users/1/preferences')
    http_etag: "..."
    self_link: http://localhost:9001/3.0/users/1/preferences

Users have their own set of preferences.

    >>> bart.preferences.receive_own_postings = False
    >>> transaction.commit()
    >>> dump_json('http://localhost:9001/3.0/users/1/preferences')
    http_etag: "..."
    receive_own_postings: False
    self_link: http://localhost:9001/3.0/users/1/preferences

Similarly, members have their own separate set of preferences, and just like
the above, setting a preference on the member's address or user does not set
the preference on the member.
::

    >>> from mailman.interfaces.member import MemberRole
    >>> mlist = create_list('test@example.com')
    >>> bart_member = mlist.subscribe(list(bart.addresses)[0])
    >>> bart_member.preferences.receive_list_copy = False
    >>> transaction.commit()
    >>> dump_json('http://localhost:9001/3.0/members/1/preferences')
    http_etag: "..."
    receive_list_copy: False
    self_link: http://localhost:9001/3.0/members/1/preferences


Changing preferences
====================

Preferences for the address, user, or member can be changed through the API.
You can change all the preferences for a particular object by using an HTTP
PUT operation.
::

    >>> dump_json('http://localhost:9001/3.0/addresses/bart@example.com'
    ...           '/preferences', {
    ...           'acknowledge_posts': True,
    ...           'delivery_mode': 'plaintext_digests',
    ...           'delivery_status': 'by_user',
    ...           'hide_address': False,
    ...           'preferred_language': 'ja',
    ...           'receive_list_copy': True,
    ...           'receive_own_postings': False,
    ...           }, method='PUT')
    content-length: 0
    date: ...
    server: ...
    status: 204

    >>> dump_json('http://localhost:9001/3.0/addresses/bart@example.com'
    ...           '/preferences')
    acknowledge_posts: True
    delivery_mode: plaintext_digests
    delivery_status: by_user
    hide_address: False
    http_etag: "..."
    preferred_language: ja
    receive_list_copy: True
    receive_own_postings: False
    self_link: http://localhost:9001/3.0/addresses/bart@example.com/preferences

You can also update just a few of the attributes using PATCH.
::

    >>> dump_json('http://localhost:9001/3.0/addresses/bart@example.com'
    ...           '/preferences', {
    ...           'delivery_mode': 'plaintext_digests',
    ...           'receive_list_copy': False,
    ...           }, method='PATCH')
    content-length: 0
    date: ...
    server: ...
    status: 204

    >>> dump_json('http://localhost:9001/3.0/addresses/bart@example.com'
    ...           '/preferences')
    acknowledge_posts: True
    delivery_mode: plaintext_digests
    delivery_status: by_user
    hide_address: False
    http_etag: "..."
    preferred_language: ja
    receive_list_copy: False
    receive_own_postings: False
    self_link: http://localhost:9001/3.0/addresses/bart@example.com/preferences


Deleting preferences
====================

Preferences for any of the levels, member, user, or address, can be entirely
deleted.
::

    >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com'
    ...           '/preferences', {
    ...           'preferred_language': 'ja',
    ...           }, method='PATCH')
    content-length: 0
    date: ...
    server: ...
    status: 204

    >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com'
    ...           '/preferences')
    acknowledge_posts: True
    http_etag: "..."
    preferred_language: ja
    self_link: http://localhost:9001/3.0/addresses/anne@example.com/preferences

    >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com'
    ...           '/preferences', method='DELETE')
    content-length: 0
    date: ...
    server: ...
    status: 204

    >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com'
    ...           '/preferences')
    http_etag: "..."
    self_link: http://localhost:9001/3.0/addresses/anne@example.com/preferences


Combined member preferences
===========================

The member resource provides a way to access the set of preference in effect
for a specific subscription.  This stacks the preferences, so that a value is
always available.  The preference value is looked up first on the member,
falling back to the address, then user, then system preference.

Preferences accessed through this interface are always read only.

    >>> dump_json('http://localhost:9001/3.0/members/1/all/preferences')
    acknowledge_posts: True
    delivery_mode: plaintext_digests
    delivery_status: by_user
    http_etag: "..."
    preferred_language: ja
    receive_list_copy: False
    receive_own_postings: False
    self_link: http://localhost:9001/3.0/members/1/all/preferences


System preferences
==================

The Mailman system itself has a default set of preference.  All preference
look ups fall back to these values, which are read-only.

    >>> dump_json('http://localhost:9001/3.0/system/preferences')
    acknowledge_posts: False
    delivery_mode: regular
    delivery_status: enabled
    hide_address: True
    http_etag: "..."
    preferred_language: en
    receive_list_copy: True
    receive_own_postings: True
    self_link: http://localhost:9001/3.0/system/preferences