diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/commands/docs/echo.rst | 11 | ||||
| -rw-r--r-- | src/mailman/commands/docs/end.rst | 7 | ||||
| -rw-r--r-- | src/mailman/commands/docs/help.rst | 71 | ||||
| -rw-r--r-- | src/mailman/commands/docs/membership.rst | 19 | ||||
| -rw-r--r-- | src/mailman/commands/eml_confirm.py | 5 | ||||
| -rw-r--r-- | src/mailman/commands/eml_echo.py | 8 | ||||
| -rw-r--r-- | src/mailman/commands/eml_end.py | 3 | ||||
| -rw-r--r-- | src/mailman/commands/eml_help.py | 81 | ||||
| -rw-r--r-- | src/mailman/commands/eml_membership.py | 22 | ||||
| -rw-r--r-- | src/mailman/commands/tests/test_help.py | 70 | ||||
| -rw-r--r-- | src/mailman/docs/NEWS.rst | 1 |
11 files changed, 266 insertions, 32 deletions
diff --git a/src/mailman/commands/docs/echo.rst b/src/mailman/commands/docs/echo.rst index ced483ea8..db5161e1e 100644 --- a/src/mailman/commands/docs/echo.rst +++ b/src/mailman/commands/docs/echo.rst @@ -1,3 +1,4 @@ +================== The 'echo' command ================== @@ -5,12 +6,12 @@ The mail command 'echo' simply replies with the original command and arguments to the sender. >>> command = config.commands['echo'] - >>> command.name - 'echo' - >>> command.argument_description - '[args]' + >>> print command.name + echo + >>> print command.argument_description + [args] >>> print command.description - Echo an acknowledgement. Arguments are return unchanged. + Echo back your arguments. The original message is ignored, but the results receive the echoed command. :: diff --git a/src/mailman/commands/docs/end.rst b/src/mailman/commands/docs/end.rst index a11bea095..accf91b90 100644 --- a/src/mailman/commands/docs/end.rst +++ b/src/mailman/commands/docs/end.rst @@ -1,3 +1,4 @@ +================= The 'end' command ================= @@ -5,8 +6,8 @@ The mail command processor recognized an 'end' command which tells it to stop processing email messages. >>> command = config.commands['end'] - >>> command.name - 'end' + >>> print command.name + end >>> print command.description Stop processing commands. @@ -29,7 +30,7 @@ The 'stop' command is a synonym for 'end'. >>> print command.name stop >>> print command.description - Stop processing commands. + An alias for 'end'. >>> command.argument_description '' >>> print command.process(mlist, Message(), {}, (), None) diff --git a/src/mailman/commands/docs/help.rst b/src/mailman/commands/docs/help.rst new file mode 100644 index 000000000..a12a4008f --- /dev/null +++ b/src/mailman/commands/docs/help.rst @@ -0,0 +1,71 @@ +================== +Email command help +================== + +You can get some help about the various email commands that are available by +sending the word `help` to a mailing list's -request address. + + >>> mlist = create_list('test@example.com') + >>> from mailman.commands.eml_help import Help + >>> help = Help() + >>> print help.name + help + >>> print help.description + Get help about available email commands. + >>> print help.argument_description + [command] + +With no arguments, `help` provides a list of the available commands and a +short description of each of them. +:: + + >>> from mailman.runners.command import Results + >>> results = Results() + + >>> from mailman.email.message import Message + >>> print help.process(mlist, Message(), {}, (), results) + ContinueProcessing.yes + >>> print unicode(results) + The results of your email command are provided below. + <BLANKLINE> + confirm - Confirm a subscription request. + echo - Echo back your arguments. + end - Stop processing commands. + help - Get help about available email commands. + join - Join this mailing list. + leave - Leave this mailing list. + stop - An alias for 'end'. + subscribe - An alias for 'join'. + unsubscribe - An alias for 'leave'. + <BLANKLINE> + +With an argument, you can get more detailed help about a specific command. + + >>> results = Results() + >>> print help.process(mlist, Message(), {}, ('help',), results) + ContinueProcessing.yes + >>> print unicode(results) + The results of your email command are provided below. + <BLANKLINE> + help [command] + Get help about available email commands. + <BLANKLINE> + +Some commands have even more detailed help. + + >>> results = Results() + >>> print help.process(mlist, Message(), {}, ('join',), results) + ContinueProcessing.yes + >>> print unicode(results) + The results of your email command are provided below. + <BLANKLINE> + join [digest=<no|mime|plain>] + Join this mailing list. + <BLANKLINE> + You will be asked to confirm your subscription request and you may be + issued a provisional password. + <BLANKLINE> + By using the 'digest' option, you can specify whether you want digest + delivery or not. If not specified, the mailing list's default delivery + mode will be used. + <BLANKLINE> diff --git a/src/mailman/commands/docs/membership.rst b/src/mailman/commands/docs/membership.rst index d3643c2b1..7f4de8570 100644 --- a/src/mailman/commands/docs/membership.rst +++ b/src/mailman/commands/docs/membership.rst @@ -14,20 +14,17 @@ The mail command ``join`` subscribes an email address to the mailing list. ``subscribe`` is an alias for ``join``. >>> from mailman.commands.eml_membership import Join + >>> from mailman.utilities.string import wrap >>> join = Join() >>> print join.name join - >>> print join.description - Join this mailing list. You will be asked to confirm your subscription - request and you may be issued a provisional password. + >>> print wrap(join.description) + You will be asked to confirm your subscription request and you may be + issued a provisional password. <BLANKLINE> By using the 'digest' option, you can specify whether you want digest - delivery or not. If not specified, the mailing list's default will be - used. You can also subscribe an alternative address by using the - 'address' option. For example: - <BLANKLINE> - join address=myotheraddress@example.com - <BLANKLINE> + delivery or not. If not specified, the mailing list's default + delivery mode will be used. >>> print join.argument_description [digest=<no|mime|plain>] @@ -232,7 +229,9 @@ list. ``unsubscribe`` is an alias for ``leave``. >>> print leave.name leave >>> print leave.description - Leave this mailing list. You will be asked to confirm your request. + Leave this mailing list. + <BLANKLINE> + You may be asked to confirm your request. Anne is a member of the ``baker@example.com`` mailing list, when she decides to leave it. She sends a message to the ``-leave`` address for the list and diff --git a/src/mailman/commands/eml_confirm.py b/src/mailman/commands/eml_confirm.py index 2461192ed..55619a503 100644 --- a/src/mailman/commands/eml_confirm.py +++ b/src/mailman/commands/eml_confirm.py @@ -40,8 +40,9 @@ class Confirm: implements(IEmailCommand) name = 'confirm' - argument_description = '' - description = '' + argument_description = 'token' + description = _('Confirm a subscription request.') + short_description = description def process(self, mlist, msg, msgdata, arguments, results): """See `IEmailCommand`.""" diff --git a/src/mailman/commands/eml_echo.py b/src/mailman/commands/eml_echo.py index 4686d0e4d..06d5ee5e7 100644 --- a/src/mailman/commands/eml_echo.py +++ b/src/mailman/commands/eml_echo.py @@ -17,6 +17,8 @@ """The email command 'echo'.""" +from __future__ import absolute_import, print_function, unicode_literals + __metaclass__ = type __all__ = [ 'Echo', @@ -39,10 +41,10 @@ class Echo: name = 'echo' argument_description = '[args]' - description = _( - 'Echo an acknowledgement. Arguments are return unchanged.') + description = _('Echo back your arguments.') + short_description = description def process(self, mlist, msg, msgdata, arguments, results): """See `IEmailCommand`.""" - print >> results, 'echo', SPACE.join(arguments) + print('echo', SPACE.join(arguments), file=results) return ContinueProcessing.yes diff --git a/src/mailman/commands/eml_end.py b/src/mailman/commands/eml_end.py index 56fd705a2..3cd70813c 100644 --- a/src/mailman/commands/eml_end.py +++ b/src/mailman/commands/eml_end.py @@ -38,6 +38,7 @@ class End: name = 'end' argument_description = '' description = _('Stop processing commands.') + short_description = description def process(self, mlist, msg, msgdata, arguments, results): """See `IEmailCommand`.""" @@ -49,3 +50,5 @@ class Stop(End): """The email 'stop' command (an alias for 'end').""" name = 'stop' + description = _("An alias for 'end'.") + short_description = description diff --git a/src/mailman/commands/eml_help.py b/src/mailman/commands/eml_help.py new file mode 100644 index 000000000..6fddb4ef3 --- /dev/null +++ b/src/mailman/commands/eml_help.py @@ -0,0 +1,81 @@ +# Copyright (C) 2012 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 email command 'help'.""" + +from __future__ import absolute_import, print_function, unicode_literals + +__metaclass__ = type +__all__ = [ + 'Help', + ] + + +from zope.interface import implements + +from mailman.config import config +from mailman.core.i18n import _ +from mailman.interfaces.command import ContinueProcessing, IEmailCommand +from mailman.utilities.string import wrap + + +SPACE = ' ' + + + +class Help: + """The email 'help' command.""" + + implements(IEmailCommand) + + name = 'help' + argument_description = '[command]' + description = _('Get help about available email commands.') + short_description = description + + def process(self, mlist, msg, msgdata, arguments, results): + """See `IEmailCommand`.""" + # With no argument, print the command and a short description, which + # is contained in the short_description attribute. + if len(arguments) == 0: + length = max(len(command) for command in config.commands) + format = '{{0: <{0}s}} - {{1}}'.format(length) + for command_name in sorted(config.commands): + command = config.commands[command_name] + short_description = getattr( + command, 'short_description', _('n/a')) + print(format.format(command.name, short_description), + file=results) + return ContinueProcessing.yes + elif len(arguments) == 1: + command_name = arguments[0] + command = config.commands.get(command_name) + if command is None: + print(_('$self.name: no such command: $command_name'), + file=results) + return ContinueProcessing.no + print('{0} {1}'.format(command.name, command.argument_description), + file=results) + print(command.short_description, file=results) + if command.short_description != command.description: + print(wrap(command.description), file=results) + return ContinueProcessing.yes + else: + printable_arguments = SPACE.join(arguments) + print(_('$self.name: too many arguments: $printable_arguments'), + file=results) + return ContinueProcessing.no diff --git a/src/mailman/commands/eml_membership.py b/src/mailman/commands/eml_membership.py index b4f24b514..386316eb9 100644 --- a/src/mailman/commands/eml_membership.py +++ b/src/mailman/commands/eml_membership.py @@ -50,16 +50,14 @@ class Join: # XXX 2012-02-29 BAW: DeliveryMode.summary is not yet supported. argument_description = '[digest=<no|mime|plain>]' description = _("""\ -Join this mailing list. You will be asked to confirm your subscription -request and you may be issued a provisional password. +You will be asked to confirm your subscription request and you may be issued a +provisional password. By using the 'digest' option, you can specify whether you want digest delivery -or not. If not specified, the mailing list's default will be used. You can -also subscribe an alternative address by using the 'address' option. For -example: - - join address=myotheraddress@example.com +or not. If not specified, the mailing list's default delivery mode will be +used. """) + short_description = _('Join this mailing list.') def process(self, mlist, msg, msgdata, arguments, results): """See `IEmailCommand`.""" @@ -128,6 +126,8 @@ class Subscribe(Join): """The email 'subscribe' command (an alias for 'join').""" name = 'subscribe' + description = _("An alias for 'join'.") + short_description = description @@ -138,8 +138,10 @@ class Leave: name = 'leave' argument_description = '' - description = _( - 'Leave this mailing list. You will be asked to confirm your request.') + description = _("""Leave this mailing list. + +You may be asked to confirm your request.""") + short_description = _('Leave this mailing list.') def process(self, mlist, msg, msgdata, arguments, results): """See `IEmailCommand`.""" @@ -184,3 +186,5 @@ class Unsubscribe(Leave): """The email 'unsubscribe' command (an alias for 'leave').""" name = 'unsubscribe' + description = _("An alias for 'leave'.") + short_description = description diff --git a/src/mailman/commands/tests/test_help.py b/src/mailman/commands/tests/test_help.py new file mode 100644 index 000000000..3892aead5 --- /dev/null +++ b/src/mailman/commands/tests/test_help.py @@ -0,0 +1,70 @@ +# Copyright (C) 2012 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/>. + +"""Additional tests for the `help` email command.""" + +from __future__ import absolute_import, print_function, unicode_literals + +__metaclass__ = type +__all__ = [ + ] + + +import unittest + +from mailman.app.lifecycle import create_list +from mailman.commands.eml_help import Help +from mailman.email.message import Message +from mailman.interfaces.command import ContinueProcessing +from mailman.runners.command import Results +from mailman.testing.layers import ConfigLayer + + + +class TestHelp(unittest.TestCase): + """Test email help.""" + + layer = ConfigLayer + + def setUp(self): + self._mlist = create_list('test@example.com') + self._help = Help() + + def test_too_many_arguments(self): + # Error message when too many help arguments are given. + results = Results() + status = self._help.process(self._mlist, Message(), {}, + ('more', 'than', 'one'), + results) + self.assertEqual(status, ContinueProcessing.no) + self.assertEqual(unicode(results), """\ +The results of your email command are provided below. + +help: too many arguments: more than one +""") + + def test_no_such_command(self): + # Error message when asking for help on an existent command. + results = Results() + status = self._help.process(self._mlist, Message(), {}, + ('doesnotexist',), results) + self.assertEqual(status, ContinueProcessing.no) + self.assertEqual(unicode(results), """\ +The results of your email command are provided below. + +help: no such command: doesnotexist +""") diff --git a/src/mailman/docs/NEWS.rst b/src/mailman/docs/NEWS.rst index 2bad038f7..368483c05 100644 --- a/src/mailman/docs/NEWS.rst +++ b/src/mailman/docs/NEWS.rst @@ -53,6 +53,7 @@ Commands * The `join` email command no longer accepts an `address=` argument. Its `digest=` argument now accepts the following values: `no` (for regular delivery), `mime`, or `plain`. + * Added a `help` email command. Bug fixes --------- |