1 files changed, 169 insertions, 0 deletions

diff --git a/mailman/pipeline/docs/avoid-duplicates.txt b/mailman/pipeline/docs/avoid-duplicates.txt
new file mode 100644
index 000000000..9fd332d1b
--- /dev/null
+++ b/mailman/pipeline/docs/avoid-duplicates.txt
@@ -0,0 +1,169 @@
+Avoid duplicates
+================
+
+The AvoidDuplicates handler module implements several strategies to try to
+reduce the reception of duplicate messages.  It does this by removing certain
+recipients from the list of recipients that earlier handler modules
+(e.g. CalcRecips) calculates.
+
+    >>> from mailman.configuration import config
+    >>> handler = config.handlers['avoid-duplicates']
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+
+Create some members we're going to use.
+
+    >>> from mailman.interfaces import MemberRole
+    >>> address_a = config.db.user_manager.create_address(
+    ...     u'aperson@example.com')
+    >>> address_b = config.db.user_manager.create_address(
+    ...     u'bperson@example.com')
+    >>> member_a = address_a.subscribe(mlist, MemberRole.member)
+    >>> member_b = address_b.subscribe(mlist, MemberRole.member)
+    >>> # This is the message metadata dictionary as it would be produced by
+    >>> # the CalcRecips handler.
+    >>> recips = dict(recips=[u'aperson@example.com', u'bperson@example.com'])
+
+
+Short circuiting
+----------------
+
+The module short-circuits if there are no recipients.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... Subject: A message of great import
+    ...
+    ... Something
+    ... """)
+    >>> msgdata = {}
+    >>> handler.process(mlist, msg, msgdata)
+    >>> msgdata
+    {}
+    >>> print msg.as_string()
+    From: aperson@example.com
+    Subject: A message of great import
+    <BLANKLINE>
+    Something
+    <BLANKLINE>
+
+
+Suppressing the list copy
+-------------------------
+
+Members can elect not to receive a list copy of any message on which they are
+explicitly named as a recipient.  This is done by setting their
+receive_list_copy preference to False.  However, if they aren't mentioned in
+one of the recipient headers (i.e. To, CC, Resent-To, or Resent-CC), then they
+will get a list copy.
+
+    >>> member_a.preferences.receive_list_copy = False
+    >>> msg = message_from_string("""\
+    ... From: Claire Person <cperson@example.com>
+    ...
+    ... Something of great import.
+    ... """)
+    >>> msgdata = recips.copy()
+    >>> handler.process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    [u'aperson@example.com', u'bperson@example.com']
+    >>> print msg.as_string()
+    From: Claire Person <cperson@example.com>
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>
+
+If they're mentioned on the CC line, they won't get a list copy.
+
+    >>> msg = message_from_string("""\
+    ... From: Claire Person <cperson@example.com>
+    ... CC: aperson@example.com
+    ...
+    ... Something of great import.
+    ... """)
+    >>> msgdata = recips.copy()
+    >>> handler.process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    [u'bperson@example.com']
+    >>> print msg.as_string()
+    From: Claire Person <cperson@example.com>
+    CC: aperson@example.com
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>
+
+But if they're mentioned on the CC line and have receive_list_copy set to True
+(the default), then they still get a list copy.
+
+    >>> msg = message_from_string("""\
+    ... From: Claire Person <cperson@example.com>
+    ... CC: bperson@example.com
+    ...
+    ... Something of great import.
+    ... """)
+    >>> msgdata = recips.copy()
+    >>> handler.process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    [u'aperson@example.com', u'bperson@example.com']
+    >>> print msg.as_string()
+    From: Claire Person <cperson@example.com>
+    CC: bperson@example.com
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>
+
+Other headers checked for recipients include the To...
+
+    >>> msg = message_from_string("""\
+    ... From: Claire Person <cperson@example.com>
+    ... To: aperson@example.com
+    ...
+    ... Something of great import.
+    ... """)
+    >>> msgdata = recips.copy()
+    >>> handler.process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    [u'bperson@example.com']
+    >>> print msg.as_string()
+    From: Claire Person <cperson@example.com>
+    To: aperson@example.com
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>
+
+...Resent-To...
+
+    >>> msg = message_from_string("""\
+    ... From: Claire Person <cperson@example.com>
+    ... Resent-To: aperson@example.com
+    ...
+    ... Something of great import.
+    ... """)
+    >>> msgdata = recips.copy()
+    >>> handler.process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    [u'bperson@example.com']
+    >>> print msg.as_string()
+    From: Claire Person <cperson@example.com>
+    Resent-To: aperson@example.com
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>
+
+...and Resent-CC headers.
+
+    >>> msg = message_from_string("""\
+    ... From: Claire Person <cperson@example.com>
+    ... Resent-Cc: aperson@example.com
+    ...
+    ... Something of great import.
+    ... """)
+    >>> msgdata = recips.copy()
+    >>> handler.process(mlist, msg, msgdata)
+    >>> sorted(msgdata['recips'])
+    [u'bperson@example.com']
+    >>> print msg.as_string()
+    From: Claire Person <cperson@example.com>
+    Resent-Cc: aperson@example.com
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>