diff options
Diffstat (limited to 'src/mailman/app')
| -rw-r--r-- | src/mailman/app/docs/bounces.txt | 4 | ||||
| -rw-r--r-- | src/mailman/app/docs/chains.txt | 22 | ||||
| -rw-r--r-- | src/mailman/app/docs/hooks.txt | 6 | ||||
| -rw-r--r-- | src/mailman/app/docs/lifecycle.txt | 9 | ||||
| -rw-r--r-- | src/mailman/app/docs/message.txt | 12 | ||||
| -rw-r--r-- | src/mailman/app/docs/styles.txt | 10 | ||||
| -rw-r--r-- | src/mailman/app/docs/system.txt | 10 |
7 files changed, 44 insertions, 29 deletions
diff --git a/src/mailman/app/docs/bounces.txt b/src/mailman/app/docs/bounces.txt index a12305154..3d21ee423 100644 --- a/src/mailman/app/docs/bounces.txt +++ b/src/mailman/app/docs/bounces.txt @@ -28,7 +28,7 @@ Any message can be bounced. Bounce a message by passing in the original message, and an optional error message. The bounced message ends up in the virgin queue, awaiting sending -to the original messageauthor. +to the original message author. >>> from mailman.app.bounces import bounce_message >>> bounce_message(mlist, msg) @@ -66,7 +66,7 @@ to the original messageauthor. An error message can be given when the message is bounced, and this will be included in the payload of the text/plain part. The error message must be -passed in as an instance of a RejectMessage exception. +passed in as an instance of a ``RejectMessage`` exception. >>> from mailman.core.errors import RejectMessage >>> error = RejectMessage("This wasn't very important after all.") diff --git a/src/mailman/app/docs/chains.txt b/src/mailman/app/docs/chains.txt index 216bf2f5b..18cd61443 100644 --- a/src/mailman/app/docs/chains.txt +++ b/src/mailman/app/docs/chains.txt @@ -13,7 +13,8 @@ processing of messages. The Discard chain ================= -The Discard chain simply throws the message away. +The `discard` chain simply throws the message away. +:: >>> from zope.interface.verify import verifyObject >>> from mailman.interfaces.chain import IChain @@ -50,8 +51,9 @@ The Discard chain simply throws the message away. The Reject chain ================ -The Reject chain bounces the message back to the original sender, and logs +The `reject` chain bounces the message back to the original sender, and logs this action. +:: >>> chain = config.chains['reject'] >>> verifyObject(IChain, chain) @@ -65,7 +67,7 @@ this action. ... process(mlist, msg, {}, 'reject') REJECT: <first> -The bounce message is now sitting in the Virgin queue. +The bounce message is now sitting in the `virgin` queue. >>> from mailman.testing.helpers import get_queue_messages >>> qfiles = get_queue_messages('virgin') @@ -94,9 +96,10 @@ The bounce message is now sitting in the Virgin queue. The Hold Chain ============== -The Hold chain places the message into the admin request database and +The `hold` chain places the message into the admin request database and depending on the list's settings, sends a notification to both the original sender and the list moderators. +:: >>> chain = config.chains['hold'] >>> verifyObject(IChain, chain) @@ -203,6 +206,7 @@ for them to be disposed of by the original author or the list moderators. The database is essentially a dictionary, with the keys being the randomly selected tokens included in the urls and the values being a 2-tuple where the first item is a type code and the second item is a message id. +:: >>> import re >>> cookie = None @@ -221,6 +225,7 @@ first item is a type code and the second item is a message id. [(u'id', ...), (u'type', u'held message')] The message itself is held in the message store. +:: >>> from mailman.interfaces.requests import IRequests >>> list_requests = getUtility(IRequests).get_list_requests(mlist) @@ -245,7 +250,7 @@ The message itself is held in the message store. The Accept chain ================ -The Accept chain sends the message on the 'prep' queue, where it will be +The `accept` chain sends the message on the `pipeline` queue, where it will be processed and sent on to the list membership. >>> chain = config.chains['accept'] @@ -278,10 +283,10 @@ Run-time chains We can also define chains at run time, and these chains can be mutated. Run-time chains are made up of links where each link associates both a rule -and a 'jump'. The rule is really a rule name, which is looked up when +and a `jump`. The rule is really a rule name, which is looked up when needed. The jump names a chain which is jumped to if the rule matches. -There is one built-in run-time chain, called appropriately 'built-in'. This +There is one built-in run-time chain, called appropriately `built-in`. This is the default chain to use when no other input chain is defined for a mailing list. It runs through the default rules, providing functionality similar to the Hold handler from previous versions of Mailman. @@ -295,7 +300,8 @@ the Hold handler from previous versions of Mailman. The built-in moderation chain. The previously created message is innocuous enough that it should pass through -all default rules. This message will end up in the pipeline queue. +all default rules. This message will end up in the `pipeline` queue. +:: >>> with event_subscribers(print_msgid): ... process(mlist, msg, {}) diff --git a/src/mailman/app/docs/hooks.txt b/src/mailman/app/docs/hooks.txt index efd5530f5..7e214f13f 100644 --- a/src/mailman/app/docs/hooks.txt +++ b/src/mailman/app/docs/hooks.txt @@ -4,7 +4,8 @@ Hooks Mailman defines two initialization hooks, one which is run early in the initialization process and the other run late in the initialization process. -Hooks name an importable callable so it must be accessible on sys.path. +Hooks name an importable callable so it must be accessible on ``sys.path``. +:: >>> import os, sys >>> from mailman.config import config @@ -46,6 +47,7 @@ We can set the pre-hook in the configuration file. The hooks are run in the second and third steps of initialization. However, we can't run those initialization steps in process, so call a command line script that will produce no output to force the hooks to run. +:: >>> import subprocess >>> from mailman.testing.layers import ConfigLayer @@ -71,6 +73,7 @@ Post-hook ========= We can set the post-hook in the configuration file. +:: >>> with open(config_path, 'w') as fp: ... print >> fp, """\ @@ -92,6 +95,7 @@ Running both hooks ================== We can set the pre- and post-hooks in the configuration file. +:: >>> with open(config_path, 'w') as fp: ... print >> fp, """\ diff --git a/src/mailman/app/docs/lifecycle.txt b/src/mailman/app/docs/lifecycle.txt index 959c08cc8..43ba1f565 100644 --- a/src/mailman/app/docs/lifecycle.txt +++ b/src/mailman/app/docs/lifecycle.txt @@ -3,8 +3,8 @@ Application level list life cycle ================================= The low-level way to create and delete a mailing list is to use the -IListManager interface. This interface simply adds or removes the appropriate -database entries to record the list's creation. +``IListManager`` interface. This interface simply adds or removes the +appropriate database entries to record the list's creation. There is a higher level interface for creating and deleting mailing lists which performs additional tasks such as: @@ -17,8 +17,6 @@ which performs additional tasks such as: * notifying watchers of list creation; * creating ancillary artifacts (such as the list's on-disk directory) - >>> from mailman.app.lifecycle import create_list - Posting address validation ========================== @@ -44,6 +42,7 @@ Creating a list applies its styles ================================== Start by registering a test style. +:: >>> from zope.interface import implements >>> from mailman.interfaces.styles import IStyle @@ -102,6 +101,7 @@ However, all addresses are linked to users. If you create a mailing list with owner addresses that are already known to the system, they won't be created again. +:: >>> from mailman.interfaces.usermanager import IUserManager >>> from zope.component import getUtility @@ -126,6 +126,7 @@ Deleting a list Removing a mailing list deletes the list, all its subscribers, and any related artifacts. +:: >>> from mailman.app.lifecycle import remove_list >>> remove_list(mlist_2.fqdn_listname, mlist_2, True) diff --git a/src/mailman/app/docs/message.txt b/src/mailman/app/docs/message.txt index 41607ff44..3e3293196 100644 --- a/src/mailman/app/docs/message.txt +++ b/src/mailman/app/docs/message.txt @@ -3,19 +3,19 @@ Messages ======== Mailman has its own Message classes, derived from the standard -email.message.Message class, but providing additional useful methods. +``email.message.Message`` class, but providing additional useful methods. User notifications ================== -When Mailman needs to send a message to a user, it creates a UserNotification -instance, and then calls the .send() method on this object. This method -requires a mailing list instance. +When Mailman needs to send a message to a user, it creates a +``UserNotification`` instance, and then calls the ``.send()`` method on this +object. This method requires a mailing list instance. >>> mlist = create_list('_xtest@example.com') -The UserNotification constructor takes the recipient address, the sender +The ``UserNotification`` constructor takes the recipient address, the sender address, an optional subject, optional body text, and optional language. >>> from mailman.email.message import UserNotification @@ -26,7 +26,7 @@ address, an optional subject, optional body text, and optional language. ... 'I needed to tell you this.') >>> msg.send(mlist) -The message will end up in the virgin queue. +The message will end up in the `virgin` queue. >>> switchboard = config.switchboards['virgin'] >>> len(switchboard.files) diff --git a/src/mailman/app/docs/styles.txt b/src/mailman/app/docs/styles.txt index 10312cd3a..63ec999bf 100644 --- a/src/mailman/app/docs/styles.txt +++ b/src/mailman/app/docs/styles.txt @@ -13,6 +13,7 @@ or not. And finally, application of a style to a mailing list can really modify the mailing list any way it wants. Let's start with a vanilla mailing list and a default style manager. +:: >>> from mailman.interfaces.listmanager import IListManager >>> from zope.component import getUtility @@ -44,9 +45,9 @@ last. Given a mailing list, you can ask the style manager to find all the styles that match the list. The registered styles will be sorted by decreasing -priority and each style's `match()` method will be called in turn. The sorted -list of matching styles will be returned -- but not applied -- by the style -manager's `lookup()` method. +priority and each style's ``match()`` method will be called in turn. The +sorted list of matching styles will be returned -- but not applied -- by the +style manager's ``lookup()`` method. >>> [style.name for style in style_manager.lookup(mlist)] ['default'] @@ -55,7 +56,7 @@ manager's `lookup()` method. Registering styles ================== -New styles must implement the IStyle interface. +New styles must implement the ``IStyle`` interface. >>> from zope.interface import implements >>> from mailman.interfaces.styles import IStyle @@ -93,6 +94,7 @@ Style priority When multiple styles match a particular mailing list, they are applied in descending order of priority. In other words, a priority zero style would be applied last. +:: >>> class AnotherTestStyle(TestStyle): ... name = 'another' diff --git a/src/mailman/app/docs/system.txt b/src/mailman/app/docs/system.txt index 035833047..844db9ee6 100644 --- a/src/mailman/app/docs/system.txt +++ b/src/mailman/app/docs/system.txt @@ -2,8 +2,9 @@ System versions =============== -Mailman system information is available through the System object, which -implements the ISystem interface. +Mailman system information is available through the ``system`` object, which +implements the ``ISystem`` interface. +:: >>> from mailman.interfaces.system import ISystem >>> from mailman.core.system import system @@ -12,13 +13,14 @@ implements the ISystem interface. >>> verifyObject(ISystem, system) True -The Mailman version is available via the system object. +The Mailman version is also available via the ``system`` object. >>> print system.mailman_version GNU Mailman ... -The Python version running underneath is also available via the system +The Python version running underneath is also available via the ``system`` object. +:: # The entire python_version string is variable, so this is the best test # we can do. |