diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/rules/docs/administrivia.txt | 24 | ||||
| -rw-r--r-- | src/mailman/rules/docs/approve.txt | 57 | ||||
| -rw-r--r-- | src/mailman/rules/docs/emergency.txt | 7 | ||||
| -rw-r--r-- | src/mailman/rules/docs/header-matching.txt | 12 | ||||
| -rw-r--r-- | src/mailman/rules/docs/implicit-dest.txt | 9 | ||||
| -rw-r--r-- | src/mailman/rules/docs/loop.txt | 6 | ||||
| -rw-r--r-- | src/mailman/rules/docs/max-size.txt | 2 | ||||
| -rw-r--r-- | src/mailman/rules/docs/moderation.txt | 3 | ||||
| -rw-r--r-- | src/mailman/rules/docs/news-moderation.txt | 2 | ||||
| -rw-r--r-- | src/mailman/rules/docs/no-subject.txt | 8 | ||||
| -rw-r--r-- | src/mailman/rules/docs/recipients.txt | 8 | ||||
| -rw-r--r-- | src/mailman/rules/docs/rules.txt | 8 | ||||
| -rw-r--r-- | src/mailman/rules/docs/suspicious.txt | 2 | ||||
| -rw-r--r-- | src/mailman/rules/docs/truth.txt | 3 |
14 files changed, 84 insertions, 67 deletions
diff --git a/src/mailman/rules/docs/administrivia.txt b/src/mailman/rules/docs/administrivia.txt index 082409622..bfc5efdcc 100644 --- a/src/mailman/rules/docs/administrivia.txt +++ b/src/mailman/rules/docs/administrivia.txt @@ -2,10 +2,10 @@ 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. +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. >>> mlist = create_list('_xtest@example.com') >>> mlist.administrivia = True @@ -13,8 +13,8 @@ used to catch messages posted to the list which should have been sent to the >>> print rule.name administrivia -For example, if the Subject header contains the word 'unsubscribe', the rule -matches. +For example, if the ``Subject:`` header contains the word ``unsubscribe``, the +rule matches. >>> msg_1 = message_from_string("""\ ... From: aperson@example.com @@ -24,7 +24,7 @@ matches. >>> rule.check(mlist, msg_1, {}) True -Similarly, if the body of the message contains the word 'subscribe' in the +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("""\ @@ -46,9 +46,9 @@ In both cases, administrivia checking can be disabled. 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. +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("""\ @@ -59,7 +59,7 @@ match. >>> rule.check(mlist, msg, {}) False -But a real 'confirm' message will match. +But a real ``confirm`` message will match. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -86,7 +86,7 @@ Of course, messages that don't contain administrivia, don't match the rule. >>> rule.check(mlist, msg, {}) False -Also, only text/plain parts are checked for administrivia, so any email +Also, only ``text/plain`` parts are checked for administrivia, so any email commands in other content type subparts are ignored. >>> msg = message_from_string("""\ diff --git a/src/mailman/rules/docs/approve.txt b/src/mailman/rules/docs/approve.txt index b92df3bdc..90ef1d33c 100644 --- a/src/mailman/rules/docs/approve.txt +++ b/src/mailman/rules/docs/approve.txt @@ -11,13 +11,13 @@ approval queue. This has several use cases: - An automated script can be programmed to send a message to an otherwise moderated list. -In order to support this, a mailing list can be given a 'moderator password' +In order to support this, a mailing list can be given a *moderator password* which is shared among all the administrators. >>> mlist = create_list('_xtest@example.com') >>> mlist.moderator_password = 'abcxyz' -The 'approved' rule determines whether the message contains the proper +The ``approved`` rule determines whether the message contains the proper approval or not. >>> rule = config.rules['approved'] @@ -28,8 +28,8 @@ approval or not. No approval =========== -If the message has no Approve or Approved header, then the rule does not -match. +If the message has no ``Approve:`` or ``Approved:`` header, then the rule does +not match. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -39,9 +39,10 @@ match. >>> rule.check(mlist, msg, {}) False -If the message has an Approve or Approved header with a value that does not -match the moderator password, then the rule does not match. However, the -header is still removed. +If the message has an ``Approve:`` or ``Approved:`` header with a value that +does not match the moderator password, then the rule does not match. However, +the header is still removed. +:: >>> msg['Approve'] = '12345' >>> rule.check(mlist, msg, {}) @@ -62,8 +63,8 @@ header is still removed. Using an approval header ======================== -If the moderator password is given in an Approve header, then the rule -matches, and the Approve header is stripped. +If the moderator password is given in an ``Approve:`` header, then the rule +matches, and the ``Approve:`` header is stripped. >>> msg['Approve'] = 'abcxyz' >>> rule.check(mlist, msg, {}) @@ -71,7 +72,7 @@ matches, and the Approve header is stripped. >>> print msg['approve'] None -Similarly, for the Approved header. +Similarly, for the ``Approved:`` header. >>> msg['Approved'] = 'abcxyz' >>> rule.check(mlist, msg, {}) @@ -84,10 +85,11 @@ Using a pseudo-header ===================== Different mail user agents have varying degrees to which they support custom -headers like Approve and Approved. For this reason, Mailman also supports -using a 'pseudo-header', which is really just the first non-whitespace line in -the payload of the message. If this pseudo-header looks like a matching -Approve or Approved header, the message is similarly allowed to pass. +headers like ``Approve:`` and ``Approved:``. For this reason, Mailman also +supports using a *pseudo-header*, which is really just the first +non-whitespace line in the payload of the message. If this pseudo-header +looks like a matching ``Approve:`` or ``Approved:`` header, the message is +similarly allowed to pass. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -109,7 +111,8 @@ The pseudo-header is removed. An important message. <BLANKLINE> -Similarly for the Approved header. +Similarly for the ``Approved:`` header. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -131,6 +134,7 @@ Similarly for the Approved header. As before, a mismatch in the pseudo-header does not approve the message, but the pseudo-header line is still removed. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -150,7 +154,8 @@ the pseudo-header line is still removed. An important message. <BLANKLINE> -Similarly for the Approved header. +Similarly for the ``Approved:`` header. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -175,8 +180,8 @@ MIME multipart support ====================== Mailman searches for the pseudo-header as the first non-whitespace line in the -first text/plain message part of the message. This allows the feature to be -used with MIME documents. +first ``text/plain`` message part of the message. This allows the feature to +be used with MIME documents. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -221,7 +226,7 @@ Like before, the pseudo-header is removed, but only from the text parts. --AAA-- <BLANKLINE> -The same goes for the Approved message. +The same goes for the ``Approved:`` message. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -266,7 +271,7 @@ And the header is removed. --AAA-- <BLANKLINE> -Here, the correct password is in the non-text/plain part, so it is ignored. +Here, the correct password is in the non-``text/plain`` part, so it is ignored. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -310,7 +315,7 @@ And yet the pseudo-header is still stripped. An important message. --AAA-- -As before, the same goes for the Approved header. +As before, the same goes for the ``Approved:`` header. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -358,9 +363,10 @@ And the pseudo-header is removed. Stripping text/html parts ========================= -Because some mail readers will include both a text/plain part and a text/html -alternative, the 'approved' rule has to search the alternatives and strip -anything that looks like an Approve or Approved headers. +Because some mail readers will include both a ``text/plain`` part and a +``text/html`` alternative, the ``approved`` rule has to search the +alternatives and strip anything that looks like an ``Approve:`` or +``Approved:`` headers. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -388,7 +394,7 @@ anything that looks like an Approve or Approved headers. >>> rule.check(mlist, msg, {}) True -And the header-like text in the text/html part was stripped. +And the header-like text in the ``text/html`` part was stripped. >>> print msg.as_string() From: aperson@example.com @@ -418,6 +424,7 @@ And the header-like text in the text/html part was stripped. <BLANKLINE> This is true even if the rule does not match. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com diff --git a/src/mailman/rules/docs/emergency.txt b/src/mailman/rules/docs/emergency.txt index 70f455dca..2a94234c6 100644 --- a/src/mailman/rules/docs/emergency.txt +++ b/src/mailman/rules/docs/emergency.txt @@ -25,6 +25,7 @@ rule matches if the flag is set on the mailing list. There are two messages in the virgin queue. The one addressed to the original sender will contain a token we can use to grab the held message out of the pending requests. +:: >>> virginq = config.switchboards['virgin'] @@ -69,9 +70,9 @@ pending requests. An important message. <BLANKLINE> -However, if the message metadata has a 'moderator_approved' key set, then even -if the mailing list has its emergency flag set, the message still goes through -to the membership. +However, if the message metadata has a ``moderator_approved`` key set, then +even if the mailing list has its emergency flag set, the message still goes +through to the membership. >>> process(mlist, msg, dict(moderator_approved=True), 'built-in') >>> len(virginq.files) diff --git a/src/mailman/rules/docs/header-matching.txt b/src/mailman/rules/docs/header-matching.txt index 217625fb0..663fcbc8a 100644 --- a/src/mailman/rules/docs/header-matching.txt +++ b/src/mailman/rules/docs/header-matching.txt @@ -4,19 +4,20 @@ Header matching Mailman can do pattern based header matching during its normal rule processing. There is a set of site-wide default header matches specified in -the configuration file under the [spam.headers] section. +the configuration file under the ``[spam.headers]`` section. >>> mlist = create_list('_xtest@example.com') -Because the default [spam.headers] section is empty, we'll just extend the +Because the default ``[spam.headers]`` section is empty, we'll just extend the current header matching chain with a pattern that matches 4 or more stars, discarding the message if it hits. >>> chain = config.chains['header-match'] >>> chain.extend('x-spam-score', '[*]{4,}', 'discard') -First, if the message has no X-Spam-Score header, the message passes through -the chain untouched (i.e. no disposition). +First, if the message has no ``X-Spam-Score:`` header, the message passes +through the chain untouched (i.e. no disposition). +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -30,6 +31,7 @@ the chain untouched (i.e. no disposition). >>> from mailman.core.chains import process Pass through is seen as nothing being in the log file after processing. +:: # XXX This checks the vette log file because there is no other evidence # that this chain has done anything. @@ -98,7 +100,7 @@ List-specific header matching Each mailing list can also be configured with a set of header matching regular expression rules. These are used to impose list-specific header filtering -with the same semantics as the global [spam.headers] section. +with the same semantics as the global ``[spam.headers]`` section. The list administrator wants to match not on four stars, but on three plus signs, but only for the current mailing list. diff --git a/src/mailman/rules/docs/implicit-dest.txt b/src/mailman/rules/docs/implicit-dest.txt index 04e93615e..b0464d0a5 100644 --- a/src/mailman/rules/docs/implicit-dest.txt +++ b/src/mailman/rules/docs/implicit-dest.txt @@ -2,7 +2,7 @@ Implicit destination ==================== -The 'implicit-dest' rule matches when the mailing list's posting address is +The ``implicit-dest`` rule matches when the mailing list's posting address is not explicitly mentioned in the set of message recipients. >>> mlist = create_list('_xtest@example.com') @@ -18,6 +18,7 @@ to the appropriate interface. This rule matches messages that have an implicit destination, meaning that the mailing list's posting address isn't included in the explicit recipients. +:: >>> mlist.require_explicit_destination = True >>> alias_set.clear() @@ -52,6 +53,7 @@ Add the posting address as a recipient and the rule will no longer match. Alternatively, if one of the acceptable aliases is in the recipients list, then the rule will not match. +:: >>> del msg['cc'] >>> rule.check(mlist, msg, {}) @@ -69,6 +71,7 @@ that Mailman pulled it from the appropriate news group. False Additional aliases can be added. +:: >>> alias_set.add('other@example.com') >>> del msg['to'] @@ -86,6 +89,7 @@ Aliases can be removed. True Aliases can also be cleared. +:: >>> msg['Cc'] = 'myfriend@example.com' >>> rule.check(mlist, msg, {}) @@ -101,7 +105,8 @@ Alias patterns It's also possible to specify an alias pattern, i.e. a regular expression to match against the recipients. For example, we can say that if there is a -recipient in the example.net domain, then the rule does not match. +recipient in the ``example.net`` domain, then the rule does not match. +:: >>> alias_set.add('^.*@example.net') >>> rule.check(mlist, msg, {}) diff --git a/src/mailman/rules/docs/loop.txt b/src/mailman/rules/docs/loop.txt index d6be10f8a..716029065 100644 --- a/src/mailman/rules/docs/loop.txt +++ b/src/mailman/rules/docs/loop.txt @@ -3,7 +3,7 @@ Posting loops ============= To avoid a posting loop, Mailman has a rule to check for the existence of an -RFC 2369 List-Post header with the value of the list's posting address. +RFC 2369 ``List-Post:`` header with the value of the list's posting address. >>> mlist = create_list('_xtest@example.com') >>> rule = config.rules['loop'] @@ -34,8 +34,8 @@ matches. >>> rule.check(mlist, msg, {}) True -Even if there are multiple List-Post headers, as long as one with the posting -address exists, the rule matches. +Even if there are multiple ``List-Post:`` headers, as long as one with the +posting address exists, the rule matches. >>> msg = message_from_string("""\ ... From: aperson@example.com diff --git a/src/mailman/rules/docs/max-size.txt b/src/mailman/rules/docs/max-size.txt index e3cc0ccf9..87856f0f1 100644 --- a/src/mailman/rules/docs/max-size.txt +++ b/src/mailman/rules/docs/max-size.txt @@ -2,7 +2,7 @@ Message size ============ -The 'message-size' rule matches when the posted message is bigger than a +The ``message-size`` rule matches when the posted message is bigger than a specified maximum. Generally this is used to prevent huge attachments from getting posted to the list. This value is calculated in terms of KB (1024 bytes). diff --git a/src/mailman/rules/docs/moderation.txt b/src/mailman/rules/docs/moderation.txt index b268e9d4a..73a6b111d 100644 --- a/src/mailman/rules/docs/moderation.txt +++ b/src/mailman/rules/docs/moderation.txt @@ -25,6 +25,7 @@ moderation rule can't match. False Let's add the message author as a non-moderated member. +:: >>> from mailman.interfaces.usermanager import IUserManager >>> from zope.component import getUtility @@ -50,7 +51,7 @@ Non-members =========== There is another, related rule for matching non-members, which simply matches -if the sender is /not/ a member of the mailing list. +if the sender is *not* a member of the mailing list. >>> rule = config.rules['non-member'] >>> print rule.name diff --git a/src/mailman/rules/docs/news-moderation.txt b/src/mailman/rules/docs/news-moderation.txt index 79ebde772..c695740fa 100644 --- a/src/mailman/rules/docs/news-moderation.txt +++ b/src/mailman/rules/docs/news-moderation.txt @@ -2,7 +2,7 @@ Newsgroup moderation ==================== -The 'news-moderation' rule matches all messages posted to mailing lists that +The ``news-moderation`` rule matches all messages posted to mailing lists that gateway to a moderated newsgroup. The reason for this is that such messages must get forwarded on to the newsgroup moderator. From there it will get posted to the newsgroup, and from there, gated to the mailing list. It's a diff --git a/src/mailman/rules/docs/no-subject.txt b/src/mailman/rules/docs/no-subject.txt index 733de00e4..4876bc82c 100644 --- a/src/mailman/rules/docs/no-subject.txt +++ b/src/mailman/rules/docs/no-subject.txt @@ -2,8 +2,8 @@ No Subject header ================= -This rule matches if the message has no Subject header, or if the header is -the empty string when stripped. +This rule matches if the message has no ``Subject:`` header, or if the header +is the empty string when stripped. >>> mlist = create_list('_xtest@example.com') >>> rule = config.rules['no-subject'] @@ -21,13 +21,13 @@ A message with a non-empty subject does not match the rule. >>> rule.check(mlist, msg, {}) False -Delete the Subject header and the rule matches. +Delete the ``Subject:`` header and the rule matches. >>> del msg['subject'] >>> rule.check(mlist, msg, {}) True -Even a Subject header with only whitespace still matches the rule. +Even a ``Subject:`` header with only whitespace still matches the rule. >>> msg['Subject'] = ' ' >>> rule.check(mlist, msg, {}) diff --git a/src/mailman/rules/docs/recipients.txt b/src/mailman/rules/docs/recipients.txt index 344a5f95f..aabf397a5 100644 --- a/src/mailman/rules/docs/recipients.txt +++ b/src/mailman/rules/docs/recipients.txt @@ -2,16 +2,16 @@ Maximum number of recipients ============================ -The 'max-recipients' rule matches when there are more than the maximum allowed -number of explicit recipients addressed by the message. +This rule matches when there are more than the maximum allowed number of +explicit recipients addressed by the message. >>> mlist = create_list('_xtest@example.com') >>> rule = config.rules['max-recipients'] >>> print rule.name max-recipients -In this case, we'll create a message with 5 recipients. These include all -addresses in the To and CC headers. +In this case, we'll create a message with five recipients. These include all +addresses in the ``To:`` and ``CC:`` headers. >>> msg = message_from_string("""\ ... From: aperson@example.com diff --git a/src/mailman/rules/docs/rules.txt b/src/mailman/rules/docs/rules.txt index e61ea547e..2d59203f8 100644 --- a/src/mailman/rules/docs/rules.txt +++ b/src/mailman/rules/docs/rules.txt @@ -44,7 +44,7 @@ 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 +``check()`` method. This returns a boolean indicating whether the rule was matched or not. >>> mlist = create_list('_xtest@example.com') @@ -54,9 +54,9 @@ matched or not. ... 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. +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. >>> print rule.name emergency diff --git a/src/mailman/rules/docs/suspicious.txt b/src/mailman/rules/docs/suspicious.txt index e99fb49c4..9eb8ae7ae 100644 --- a/src/mailman/rules/docs/suspicious.txt +++ b/src/mailman/rules/docs/suspicious.txt @@ -24,7 +24,7 @@ Set the so-called suspicious header configuration variable. True But if the header doesn't match the regular expression, the rule won't match. -This one comes from a .org address. +This one comes from a ``.org`` address. >>> msg = message_from_string("""\ ... From: aperson@example.org diff --git a/src/mailman/rules/docs/truth.txt b/src/mailman/rules/docs/truth.txt index f331e852b..c715b98aa 100644 --- a/src/mailman/rules/docs/truth.txt +++ b/src/mailman/rules/docs/truth.txt @@ -1,7 +1,8 @@ +===== Truth ===== -The 'truth' rule always matches. This makes it useful as a terminus rule for +This rule always matches. This makes it useful as a terminus rule for unconditionally jumping to another chain. >>> rule = config.rules['truth'] |