First cut at a rules processor, separate from the disposition of rule hits.

The basic idea is that we process rules on a mlist, message, metadata triplet
making a list of all rules that hit.  Then a different part of the system will
decide on the disposition of a message based on which rules hit and their
priority.

The doctest and plugin architecture is in place, including the tie-in to
setup.py.  Ported the first rule -- emergency.py -- to the new rule
processor.

We no longer need SQLAlchemy as a requirement, and the setuptools/bzr plugin
name has changed.

1 files changed, 112 insertions, 0 deletions

diff --git a/Mailman/docs/rules.txt b/Mailman/docs/rules.txt
new file mode 100644
index 000000000..6f7c8b680
--- /dev/null
+++ b/Mailman/docs/rules.txt
@@ -0,0 +1,112 @@
+Rules
+=====
+
+The rule processor is used to determine the status of a message.  Should the
+message be posted to the list, or held for moderator approval?  Should the
+message be discarded or rejected (i.e. bounced back to the original sender)?
+
+Actually, these actions are not part of rule processing!  Instead, Mailman
+first runs through a set of rules looking for matches.  Then later, the
+matched rules are prioritized and matched to an action.  Action matching is
+described elsewhere; this documentation describes only the rule processing
+system.
+
+
+Rule processors
+===============
+
+IRuleProcessor is the interface that describes a rule processor.  Mailman can
+be extended by plugging in additional rule processors, but it also comes with
+a default rule processor, called the 'built-in rule processor'.
+
+    >>> from zope.interface.verify import verifyObject
+    >>> from Mailman.interfaces import IRuleProcessor
+    >>> from Mailman.rules import BuiltinRules
+    >>> processor = BuiltinRules()
+    >>> verifyObject(IRuleProcessor, processor)
+    True
+
+You can iterator over all the rules in a rule processor.
+
+    >>> from Mailman.interfaces import IRule
+    >>> rule = None
+    >>> for rule in processor.rules:
+    ...     if rule.name == 'emergency':
+    ...         break
+    >>> verifyObject(IRule, rule)
+    True
+    >>> rule.name
+    'emergency'
+    >>> print rule.description
+    The mailing list is in emergency hold and this message was not pre-approved
+    by the list administrator.
+
+You can ask for a rule by name.
+
+    >>> processor['emergency'].name
+    'emergency'
+    >>> processor.get('emergency').name
+    'emergency'
+
+Processors act like dictionaries when the rule is missing.
+
+    >>> processor['no such rule']
+    Traceback (most recent call last):
+    ...
+    KeyError: 'no such rule'
+    >>> print processor.get('no such rule')
+    None
+    >>> missing = object()
+    >>> processor.get('no such rule', missing) is missing
+    True
+
+
+Rule checks
+-----------
+
+Individual rules can be checked to see if they match, by running the rule's
+`check()` method.  This returns a boolean indicating whether the rule was
+matched or not.
+
+    >>> from Mailman.configuration import config
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ...
+    ... An important message.
+    ... """)
+
+For example, the emergency rule just checks to see if the emergency flag is
+set on the mailing list, and the message has not been pre-approved by the list
+administrator.
+
+    >>> rule = processor['emergency']
+    >>> rule.name
+    'emergency'
+    >>> mlist.emergency = False
+    >>> rule.check(mlist, msg, {})
+    False
+    >>> mlist.emergency = True
+    >>> rule.check(mlist, msg, {})
+    True
+    >>> rule.check(mlist, msg, dict(adminapproved=True))
+    False
+
+
+Rule processing
+---------------
+
+Mailman has a global rule processor which will return a set of all the rule
+names that match the current message.
+
+    >>> from Mailman.app.rules import process
+    >>> matches = process(mlist, msg, {})
+    >>> matches & set(['emergency'])
+    set(['emergency'])
+    >>> matches = process(mlist, msg, dict(adminapproved=True))
+    >>> matches & set(['emergency'])
+    set([])
+    >>> mlist.emergency = False
+    >>> matches = process(mlist, msg, {})
+    >>> matches & set(['emergency'])
+    set([])