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)
+    []