Convert the administrivia check from the Hold handler to the administrivia

rule.  Add doctest as appropriate.

DEFAULT_MAIL_COMMANDS_MAX_LINES -> EMAIL_COMMANDS_MAX_LINES

2 files changed, 101 insertions, 21 deletions

diff --git a/Mailman/docs/administrivia.txt b/Mailman/docs/administrivia.txt
new file mode 100644
index 000000000..0e48fdd1b
--- /dev/null
+++ b/Mailman/docs/administrivia.txt
@@ -0,0 +1,101 @@
+Administrivia
+=============
+
+The 'administrivia' rule matches when the message contains some common email
+commands in the Subject header or first few lines of the payload.  This is
+used to catch messages posted to the list which should have been sent to the
+-request robot address.
+
+    >>> from Mailman.configuration import config
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+    >>> mlist.administrivia = True
+    >>> from Mailman.app.rules import find_rule
+    >>> rule = find_rule('administrivia')
+    >>> rule.name
+    'administrivia'
+
+For example, if the Subject header contains the word 'unsubscribe', the rule
+matches.
+
+    >>> msg_1 = message_from_string(u"""\
+    ... From: aperson@example.com
+    ... Subject: unsubscribe
+    ...
+    ... """)
+    >>> rule.check(mlist, msg_1, {})
+    True
+
+Similarly, if the body of the message contains the word 'subscribe' in the
+first few lines of text, the rule matches.
+
+    >>> msg_2 = message_from_string(u"""\
+    ... From: aperson@example.com
+    ... Subject: I wish to join your list
+    ...
+    ... subscribe
+    ... """)
+    >>> rule.check(mlist, msg_2, {})
+    True
+
+In both cases, administrivia checking can be disabled.
+
+    >>> mlist.administrivia = False
+    >>> rule.check(mlist, msg_1, {})
+    False
+    >>> rule.check(mlist, msg_2, {})
+    False
+
+To make the administrivia heuristics a little more robust, the rule actually
+looks for a minimum and maximum number of arguments, so that it really does
+seem like a mis-addressed email command.  In this case, the 'confirm' command
+requires at least one argument.  We don't give that here so the rule will not
+match.
+
+    >>> mlist.administrivia = True
+    >>> msg = message_from_string(u"""\
+    ... From: aperson@example.com
+    ... Subject: confirm
+    ...
+    ... """)
+    >>> rule.check(mlist, msg, {})
+    False
+
+But a real 'confirm' message will match.
+
+    >>> msg = message_from_string(u"""\
+    ... From: aperson@example.com
+    ... Subject: confirm 12345
+    ...
+    ... """)
+    >>> rule.check(mlist, msg, {})
+    True
+
+We don't show all the other possible email commands, but you get the idea.
+
+
+Non-administrivia
+-----------------
+
+Of course, messages that don't contain administrivia, don't match the rule.
+
+    >>> msg = message_from_string(u"""\
+    ... From: aperson@example.com
+    ... Subject: examine
+    ...
+    ... persuade
+    ... """)
+    >>> rule.check(mlist, msg, {})
+    False
+
+Also, only text/plain parts are checked for administrivia, so any email
+commands in other content type subparts are ignored.
+
+    >>> msg = message_from_string(u"""\
+    ... From: aperson@example.com
+    ... Subject: some administrivia
+    ... Content-Type: text/x-special
+    ...
+    ... subscribe
+    ... """)
+    >>> rule.check(mlist, msg, {})
+    False
diff --git a/Mailman/docs/hold.txt b/Mailman/docs/hold.txt
index a93953435..4ee5f8d67 100644
--- a/Mailman/docs/hold.txt
+++ b/Mailman/docs/hold.txt
@@ -57,27 +57,6 @@ handler returns immediately.
     {'approved': True}
 
 
-Administrivia
--------------
-
-Mailman scans parts of the message for administrivia, meaning text that looks
-like an email command.  This is to prevent people sending 'help' or
-'subscribe' message, etc. to the list members.  First, we enable the scanning
-of administrivia for the list.
-
-    >>> mlist.administrivia = True
-    >>> msg = message_from_string("""\
-    ... From: aperson@example.com
-    ... Subject: unsubscribe
-    ...
-    ... """)
-    >>> process(mlist, msg, {})
-    Traceback (most recent call last):
-    ...
-    Administrivia
-    >>> clear()
-
-
 Maximum number of recipients
 ----------------------------