~barry/mailman/events-and-web

« back to all changes in this revision

Viewing changes to Mailman/rules/docs/administrivia.txt

  • Committer: Barry Warsaw
  • Date: 2008-02-03 04:03:19 UTC
  • mfrom: (6581.1.27 rules)
  • Revision ID: barry@python.org-20080203040319-mnb1sar9bumaih01
Merge the 'rules' branch.

Give the first alpha a code name.

This branch mostly gets rid of all the approval oriented handlers in favor of
a chain-of-rules based approach.  This will be much more powerful and
extensible, allowing rule definition by plugin and chain creation via web
page.

When a message is processed by the incoming queue, it gets sent through a
chain of rules.  The starting chain is defined on the mailing list object, and
there is a built-in default starting chain, called 'built-in'.  Each chain is
made up of links, which describe a rule and an action, along with possibly
some other information.  Actions allow processing to take a detour through
another chain, jump to another chain, stop processing, run a function, etc.

The built-in chain essentially implements the original early part of the
handler pipeline.  If a message makes it through the built-in chain, it gets
sent to the prep queue, where the message is decorated and such before sending
out to the list membership.  The 'accept' chain is what moves the message into
the prep queue.

There are also 'hold', 'discard', and 'reject' chains, which do what you would
expect them to.  There are lots of built-in rules, implementing everything
from the old emergency handler to new handlers such as one not allowing empty
subject headers.

IMember grows an is_moderated attribute.

The 'adminapproved' metadata key is renamed 'moderator_approved'.

Fix some bogus uses of noreply_address to no_reply_address.

Stash an 'original_size' attribute on the message after parsing its plain
text.  This can be used later to ensure the original message does not exceed a
specified size without have to flatten the message again.

The KNOWN_SPAMMERS global variable is replaced with HEADER_MATCHES.  The
mailing list's header_filter_rules variable is replaced with header_matches
which has the same semantics as HEADER_MATCHES, but is list-specific.

DEFAULT_MAIL_COMMANDS_MAX_LINES -> EMAIL_COMMANDS_MAX_LINES.

Update smtplistener.py to be much better, to use maildir format instead of
mbox format, to respond to RSET commands by clearing the maildir, and by
silencing annoying asyncore error messages.

Extend the doctest runner so that it will run .txt files in any docs
subdirectory in the code tree.

Add plugable keys 'mailman.mta' and 'mailman.rules'.  The latter may have only
one setting while the former is extensible.

There are lots of doctests which should give all the gory details.

Mailman/Post.py -> Mailman/inject.py and the command line usage of this module
is removed.

SQLALCHEMY_ECHO, which was unused, is removed.

Backport the ability to specify additional footer interpolation variables by
the message metadata 'decoration-data' key.

can_acknowledge() defines whether a message can be responded to by the email
robot.

Simplify the implementation of _reset() based on Storm fixes.  Be able to
handle lists in Storm values.

Do some reorganization.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Administrivia
 
2
=============
 
3
 
 
4
The 'administrivia' rule matches when the message contains some common email
 
5
commands in the Subject header or first few lines of the payload.  This is
 
6
used to catch messages posted to the list which should have been sent to the
 
7
-request robot address.
 
8
 
 
9
    >>> from Mailman.configuration import config
 
10
    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
 
11
    >>> mlist.administrivia = True
 
12
    >>> rule = config.rules['administrivia']
 
13
    >>> rule.name
 
14
    'administrivia'
 
15
 
 
16
For example, if the Subject header contains the word 'unsubscribe', the rule
 
17
matches.
 
18
 
 
19
    >>> msg_1 = message_from_string(u"""\
 
20
    ... From: aperson@example.com
 
21
    ... Subject: unsubscribe
 
22
    ...
 
23
    ... """)
 
24
    >>> rule.check(mlist, msg_1, {})
 
25
    True
 
26
 
 
27
Similarly, if the body of the message contains the word 'subscribe' in the
 
28
first few lines of text, the rule matches.
 
29
 
 
30
    >>> msg_2 = message_from_string(u"""\
 
31
    ... From: aperson@example.com
 
32
    ... Subject: I wish to join your list
 
33
    ...
 
34
    ... subscribe
 
35
    ... """)
 
36
    >>> rule.check(mlist, msg_2, {})
 
37
    True
 
38
 
 
39
In both cases, administrivia checking can be disabled.
 
40
 
 
41
    >>> mlist.administrivia = False
 
42
    >>> rule.check(mlist, msg_1, {})
 
43
    False
 
44
    >>> rule.check(mlist, msg_2, {})
 
45
    False
 
46
 
 
47
To make the administrivia heuristics a little more robust, the rule actually
 
48
looks for a minimum and maximum number of arguments, so that it really does
 
49
seem like a mis-addressed email command.  In this case, the 'confirm' command
 
50
requires at least one argument.  We don't give that here so the rule will not
 
51
match.
 
52
 
 
53
    >>> mlist.administrivia = True
 
54
    >>> msg = message_from_string(u"""\
 
55
    ... From: aperson@example.com
 
56
    ... Subject: confirm
 
57
    ...
 
58
    ... """)
 
59
    >>> rule.check(mlist, msg, {})
 
60
    False
 
61
 
 
62
But a real 'confirm' message will match.
 
63
 
 
64
    >>> msg = message_from_string(u"""\
 
65
    ... From: aperson@example.com
 
66
    ... Subject: confirm 12345
 
67
    ...
 
68
    ... """)
 
69
    >>> rule.check(mlist, msg, {})
 
70
    True
 
71
 
 
72
We don't show all the other possible email commands, but you get the idea.
 
73
 
 
74
 
 
75
Non-administrivia
 
76
-----------------
 
77
 
 
78
Of course, messages that don't contain administrivia, don't match the rule.
 
79
 
 
80
    >>> msg = message_from_string(u"""\
 
81
    ... From: aperson@example.com
 
82
    ... Subject: examine
 
83
    ...
 
84
    ... persuade
 
85
    ... """)
 
86
    >>> rule.check(mlist, msg, {})
 
87
    False
 
88
 
 
89
Also, only text/plain parts are checked for administrivia, so any email
 
90
commands in other content type subparts are ignored.
 
91
 
 
92
    >>> msg = message_from_string(u"""\
 
93
    ... From: aperson@example.com
 
94
    ... Subject: some administrivia
 
95
    ... Content-Type: text/x-special
 
96
    ...
 
97
    ... subscribe
 
98
    ... """)
 
99
    >>> rule.check(mlist, msg, {})
 
100
    False