Convert the tests for the CalcRecips handler to doc tests. There are

some XXX's in the doc test because digest recipients aren't tested
(though those may go in a different doctest), and neither are urgent
messages.  This latter is for the same reason that the Approved
handler is not yet tested; which password do you use in that header?

The CalcRecips tests would also seem the natural place to test the
receive_list_copy preference, but that actually gets processed in the
AvoidDuplicates handler, so it isn't tested here.

Add delivery_status (of type enum DeliveryStatus) to preferences.  I'm
not entirely sure that's the right place for it, but it lets me finish
converting the test for now.

Expose the rest of the preferences through the IMember interface.

1 files changed, 130 insertions, 0 deletions

diff --git a/Mailman/docs/calc-recips.txt b/Mailman/docs/calc-recips.txt
new file mode 100644
index 000000000..9646778d6
--- /dev/null
+++ b/Mailman/docs/calc-recips.txt
@@ -0,0 +1,130 @@
+Calculating recipients
+======================
+
+Every message that makes it through to the list membership gets sent to a set
+of recipient addresses.  These addresses are calculated by one of the handler
+modules and depends on a host of factors.
+
+    >>> from email import message_from_string
+    >>> from Mailman.Message import Message
+    >>> from Mailman.Handlers.CalcRecips import process
+    >>> from Mailman.configuration import config
+    >>> from Mailman.database import flush
+    >>> mlist = config.list_manager.create('_xtest@example.com')
+    >>> flush()
+
+
+Recipients are calculate from the list members, so add a bunch of members to
+start out with.  First, create a bunch of addresses...
+
+    >>> address_a = config.user_manager.create_address('aperson@example.com')
+    >>> address_b = config.user_manager.create_address('bperson@example.com')
+    >>> address_c = config.user_manager.create_address('cperson@example.com')
+    >>> address_d = config.user_manager.create_address('dperson@example.com')
+    >>> address_e = config.user_manager.create_address('eperson@example.com')
+    >>> address_f = config.user_manager.create_address('fperson@example.com')
+
+...then subscribe these addresses to the mailing list as members...
+
+    >>> from Mailman.constants import MemberRole
+    >>> member_a = address_a.subscribe(mlist, MemberRole.member)
+    >>> member_b = address_b.subscribe(mlist, MemberRole.member)
+    >>> member_c = address_c.subscribe(mlist, MemberRole.member)
+    >>> member_d = address_d.subscribe(mlist, MemberRole.member)
+    >>> member_e = address_e.subscribe(mlist, MemberRole.member)
+    >>> member_f = address_f.subscribe(mlist, MemberRole.member)
+
+...then make some of the members digest members.
+
+    >>> from Mailman.constants import DeliveryMode
+    >>> member_d.preferences.delivery_mode = DeliveryMode.plaintext_digests
+    >>> member_e.preferences.delivery_mode = DeliveryMode.mime_digests
+    >>> member_f.preferences.delivery_mode = DeliveryMode.summary_digests
+    >>> flush()
+
+
+Short-circuiting
+----------------
+
+Sometimes, the list of recipients already exists in the message metadata.
+This can happen for example, when a message was previously delivered to some
+but not all of the recipients.
+
+    >>> msg = message_from_string("""\
+    ... From: Xavier Person <xperson@example.com>
+    ...
+    ... Something of great import.
+    ... """, Message)
+    >>> recips = set(('qperson@example.com', 'zperson@example.com'))
+    >>> msgdata = dict(recips=recips)
+    >>> process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    ['qperson@example.com', 'zperson@example.com']
+
+
+Regular delivery recipients
+---------------------------
+
+Regular delivery recipients are those people who get messages from the list as
+soon as they are posted.  In other words, these folks are not digest members.
+
+    >>> msgdata = {}
+    >>> process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    ['aperson@example.com', 'bperson@example.com', 'cperson@example.com']
+
+Members can elect not to receive a list copy of their own postings.
+
+    >>> member_c.preferences.receive_own_postings = False
+    >>> flush()
+    >>> msg = message_from_string("""\
+    ... From: Claire Person <cperson@example.com>
+    ...
+    ... Something of great import.
+    ... """, Message)
+    >>> msgdata = {}
+    >>> process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    ['aperson@example.com', 'bperson@example.com']
+
+Members can also elect not to receive a list copy of any message on which they
+are explicitly named as a recipient.  However, see the AvoidDuplicates handler
+for details.
+
+
+Digest recipients
+-----------------
+
+XXX Test various digest deliveries.
+
+
+Urgent messages
+---------------
+
+XXX Test various urgent deliveries:
+    * test_urgent_moderator()
+    * test_urgent_admin()
+    * test_urgent_reject()
+
+
+Clean up
+--------
+
+    >>> for member in mlist.members.members:
+    ...     member.unsubscribe()
+    >>> flush()
+    >>> list(mlist.members.members)
+    []
+    >>> for user in config.user_manager.users:
+    ...     config.user_manager.delete_user(user)
+    >>> for address in config.user_manager.addresses:
+    ...     config.user_manager.delete_address(address)
+    >>> for mlist in config.list_manager.mailing_lists:
+    ...     config.list_manager.delete(mlist)
+    >>> flush()
+    >>> list(config.user_manager.users)
+    []
+    >>> list(config.user_manager.addresses)
+    []
+    >>> list(config.list_manager.mailing_lists)
+    []