1 files changed, 170 insertions, 0 deletions

diff --git a/src/mailman/queue/docs/command.txt b/src/mailman/queue/docs/command.txt
new file mode 100644
index 000000000..0b384de01
--- /dev/null
+++ b/src/mailman/queue/docs/command.txt
@@ -0,0 +1,170 @@
+The command queue runner
+========================
+
+This queue runner's purpose is to process and respond to email commands.
+Commands are extensible using the Mailman plugin system, but Mailman comes
+with a number of email commands out of the box.  These are processed when a
+message is sent to the list's -request address.
+
+    >>> from mailman.app.lifecycle import create_list
+    >>> mlist = create_list(u'test@example.com')
+
+
+A command in the Subject
+------------------------
+
+For example, the 'echo' command simply echoes the original command back to the
+sender.  The command can be in the Subject header.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test-request@example.com
+    ... Subject: echo hello
+    ... Message-ID: <aardvark>
+    ...
+    ... """)
+
+    >>> from mailman.inject import inject_message
+    >>> inject_message(mlist, msg, switchboard='command')
+    >>> from mailman.queue.command import CommandRunner
+    >>> from mailman.testing.helpers import make_testable_runner
+    >>> command = make_testable_runner(CommandRunner)
+    >>> command.run()
+
+And now the response is in the virgin queue.
+
+    >>> from mailman.queue import Switchboard
+    >>> virgin_queue = config.switchboards['virgin']
+    >>> len(virgin_queue.files)
+    1
+    >>> from mailman.testing.helpers import get_queue_messages
+    >>> item = get_queue_messages('virgin')[0]
+    >>> print item.msg.as_string()
+    Subject: The results of your email commands
+    From: test-bounces@example.com
+    To: aperson@example.com
+    ...
+    <BLANKLINE>
+    The results of your email command are provided below.
+    <BLANKLINE>
+    - Original message details:
+        From: aperson@example.com
+        Subject: echo hello
+        Date: ...
+        Message-ID: <aardvark>
+    <BLANKLINE>
+    - Results:
+    echo hello
+    <BLANKLINE>
+    - Done.
+    <BLANKLINE>
+    >>> sorted(item.msgdata.items())
+    [..., ('listname', u'test@example.com'), ...,
+     ('recips', [u'aperson@example.com']),
+     ...]
+
+
+A command in the body
+---------------------
+
+The command can also be found in the body of the message, as long as the
+message is plain text.
+
+    >>> msg = message_from_string("""\
+    ... From: bperson@example.com
+    ... To: test-request@example.com
+    ... Message-ID: <bobcat>
+    ...
+    ... echo foo bar
+    ... """)
+
+    >>> inject_message(mlist, msg, switchboard='command')
+    >>> command.run()
+    >>> len(virgin_queue.files)
+    1
+    >>> item = get_queue_messages('virgin')[0]
+    >>> print item.msg.as_string()
+    Subject: The results of your email commands
+    From: test-bounces@example.com
+    To: bperson@example.com
+    ...
+    Precedence: bulk
+    <BLANKLINE>
+    The results of your email command are provided below.
+    <BLANKLINE>
+    - Original message details:
+        From: bperson@example.com
+        Subject: n/a
+        Date: ...
+        Message-ID: <bobcat>
+    <BLANKLINE>
+    - Results:
+    echo foo bar
+    <BLANKLINE>
+    - Done.
+    <BLANKLINE>
+
+
+Stopping command processing
+---------------------------
+
+The 'end' command stops email processing, so that nothing following is looked
+at by the command queue.
+
+    >>> msg = message_from_string("""\
+    ... From: cperson@example.com
+    ... To: test-request@example.com
+    ... Message-ID: <caribou>
+    ...
+    ... echo foo bar
+    ... end ignored
+    ... echo baz qux
+    ... """)
+
+    >>> inject_message(mlist, msg, switchboard='command')
+    >>> command.run()
+    >>> len(virgin_queue.files)
+    1
+    >>> item = get_queue_messages('virgin')[0]
+    >>> print item.msg.as_string()
+    Subject: The results of your email commands
+    ...
+    <BLANKLINE>
+    - Results:
+    echo foo bar
+    <BLANKLINE>
+    - Unprocessed:
+    echo baz qux
+    <BLANKLINE>
+    - Done.
+    <BLANKLINE>
+
+The 'stop' command is an alias for 'end'.
+
+    >>> msg = message_from_string("""\
+    ... From: cperson@example.com
+    ... To: test-request@example.com
+    ... Message-ID: <caribou>
+    ...
+    ... echo foo bar
+    ... stop ignored
+    ... echo baz qux
+    ... """)
+
+    >>> inject_message(mlist, msg, switchboard='command')
+    >>> command.run()
+    >>> len(virgin_queue.files)
+    1
+    >>> item = get_queue_messages('virgin')[0]
+    >>> print item.msg.as_string()
+    Subject: The results of your email commands
+    ...
+    <BLANKLINE>
+    - Results:
+    echo foo bar
+    <BLANKLINE>
+    - Unprocessed:
+    echo baz qux
+    <BLANKLINE>
+    - Done.
+    <BLANKLINE>