3 files changed, 214 insertions, 51 deletions

diff --git a/src/mailman/bin/unshunt.py b/src/mailman/bin/unshunt.py
deleted file mode 100644
index 2a4558fd4..000000000
--- a/src/mailman/bin/unshunt.py
+++ /dev/null
@@ -1,51 +0,0 @@
-# Copyright (C) 2002-2009 by the Free Software Foundation, Inc.
-#
-# This file is part of GNU Mailman.
-#
-# GNU Mailman is free software: you can redistribute it and/or modify it under
-# the terms of the GNU General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option)
-# any later version.
-#
-# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
-# more details.
-#
-# You should have received a copy of the GNU General Public License along with
-# GNU Mailman.  If not, see <http://www.gnu.org/licenses/>.
-
-__metaclass__ = type
-__all__ = [
-    'main',
-    ]
-
-
-import sys
-
-from mailman.config import config
-from mailman.core.i18n import _
-from mailman.options import Options
-
-
-
-def main():
-    options = Options()
-    options.initialize()
-
-    switchboard = config.switchboards['shunt']
-    switchboard.recover_backup_files()
-
-    for filebase in switchboard.files:
-        try:
-            msg, msgdata = switchboard.dequeue(filebase)
-            whichq = msgdata.get('whichq', 'in')
-            config.switchboards[whichq].enqueue(msg, msgdata)
-        except Exception, e:
-            # If there are any unshunting errors, log them and continue trying
-            # other shunted messages.
-            print >> sys.stderr, _(
-                'Cannot unshunt message $filebase, skipping:\n$e')
-        else:
-            # Unlink the .bak file left by dequeue()
-            switchboard.finish(filebase)
diff --git a/src/mailman/commands/cli_unshunt.py b/src/mailman/commands/cli_unshunt.py
new file mode 100644
index 000000000..917b6056b
--- /dev/null
+++ b/src/mailman/commands/cli_unshunt.py
@@ -0,0 +1,69 @@
+# Copyright (C) 2009 by the Free Software Foundation, Inc.
+#
+# This file is part of GNU Mailman.
+#
+# GNU Mailman is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Mailman.  If not, see <http://www.gnu.org/licenses/>.
+
+"""The 'unshunt' command."""
+
+from __future__ import absolute_import, unicode_literals
+
+__metaclass__ = type
+__all__ = [
+    'Unshunt',
+    ]
+
+
+from zope.interface import implements
+
+from mailman.config import config
+from mailman.core.i18n import _
+from mailman.interfaces.command import ICLISubCommand
+
+
+
+class Unshunt:
+    """Unshunt messages."""
+
+    implements(ICLISubCommand)
+
+    name = 'unshunt'
+
+    def add(self, parser, command_parser):
+        """See `ICLISubCommand`."""
+        self.parser = parser
+        command_parser.add_argument(
+            '-d', '--discard',
+            default=False, action='store_true',
+            help=_("""\
+            Discard all shunted messages instead of moving them back to their
+            original queue."""))
+
+    def process(self, args):
+        """See `ICLISubCommand`."""
+        shunt_queue = config.switchboards['shunt']
+        shunt_queue.recover_backup_files()
+
+        for filebase in shunt_queue.files:
+            try:
+                msg, msgdata = shunt_queue.dequeue(filebase)
+                which_queue = msgdata.get('whichq', 'in')
+                if not args.discard:
+                    config.switchboards[which_queue].enqueue(msg, msgdata)
+            except Exception as error:
+                print >> sys.stderr, _(
+                    'Cannot unshunt message $filebase, skipping:\n$error')
+            else:
+                # Unlink the .bak file left by dequeue()
+                shunt_queue.finish(filebase)
diff --git a/src/mailman/commands/docs/unshunt.txt b/src/mailman/commands/docs/unshunt.txt
new file mode 100644
index 000000000..2c2ed5712
--- /dev/null
+++ b/src/mailman/commands/docs/unshunt.txt
@@ -0,0 +1,145 @@
+=======
+Unshunt
+=======
+
+When errors occur while processing email messages, the messages will end up in
+the 'shunt' queue.  The 'unshunt' command allows system administrators to
+manage the shunt queue.
+
+    >>> from mailman.commands.cli_unshunt import Unshunt
+    >>> command = Unshunt()
+
+    >>> class FakeArgs:
+    ...     discard = False
+
+Let's say there is a message in the shunt queue.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test@example.com
+    ... Subject: A broken message
+    ... Message-ID: <aardvark>
+    ...
+    ... """)
+
+    >>> shuntq = config.switchboards['shunt']
+    >>> base_name = shuntq.enqueue(msg, {})
+    >>> len(list(shuntq.files))
+    1
+
+The unshunt command by default moves the message back to the incoming queue.
+
+    >>> inq = config.switchboards['in']
+    >>> len(list(inq.files))
+    0
+
+    >>> command.process(FakeArgs)
+
+    >>> from mailman.testing.helpers import get_queue_messages
+    >>> items = get_queue_messages('in')
+    >>> len(items)
+    1
+    >>> print items[0].msg.as_string()
+    From: aperson@example.com
+    To: test@example.com
+    Subject: A broken message
+    Message-ID: <aardvark>
+    <BLANKLINE>
+    <BLANKLINE>
+
+'unshunt' moves all shunt queue messages.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test@example.com
+    ... Subject: A broken message
+    ... Message-ID: <badgers>
+    ...
+    ... """)
+    >>> base_name = shuntq.enqueue(msg, {})
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test@example.com
+    ... Subject: A broken message
+    ... Message-ID: <crow>
+    ...
+    ... """)
+    >>> base_name = shuntq.enqueue(msg, {})
+
+    >>> len(list(shuntq.files))
+    2
+
+    >>> command.process(FakeArgs)
+    >>> items = get_queue_messages('in')
+    >>> len(items)
+    2
+
+    >>> sorted(item.msg['message-id'] for item in items)
+    [u'<badgers>', u'<crow>']
+
+
+Return to the original queue
+============================
+
+While the messages in the shunt queue are generally returned to the incoming
+queue, if the error occurred while the message was being processed from a
+different queue, it will be returned to the queue it came from.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test@example.com
+    ... Subject: A broken message
+    ... Message-ID: <dingo>
+    ...
+    ... """)
+
+The queue that the message comes from is in message metadata.
+
+    >>> base_name = shuntq.enqueue(msg, {}, whichq='bounces')
+
+    >>> len(list(shuntq.files))
+    1
+    >>> len(list(config.switchboards['bounces'].files))
+    0
+
+The message is automatically re-queued to the bounces queue.
+
+    >>> command.process(FakeArgs)
+    >>> len(list(shuntq.files))
+    0
+    >>> items = get_queue_messages('bounces')
+    >>> len(items)
+    1
+
+    >>> print items[0].msg.as_string()
+    From: aperson@example.com
+    To: test@example.com
+    Subject: A broken message
+    Message-ID: <dingo>
+    <BLANKLINE>
+    <BLANKLINE>
+
+
+Discarding all shunted messages
+===============================
+
+If you don't care about the shunted messages, just discard them.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test@example.com
+    ... Subject: A broken message
+    ... Message-ID: <elephant>
+    ...
+    ... """)
+    >>> base_name = shuntq.enqueue(msg, {})
+
+    >>> FakeArgs.discard = True
+    >>> command.process(FakeArgs)
+
+The messages are now gone.
+
+    >>> items = get_queue_messages('in')
+    >>> len(items)
+    0