Rework the 'bin/mailman lists' arguments to be more likely useful in the

common case.

2 files changed, 77 insertions, 58 deletions

diff --git a/src/mailman/commands/cli_lists.py b/src/mailman/commands/cli_lists.py
index d5686eca5..c7941d860 100644
--- a/src/mailman/commands/cli_lists.py
+++ b/src/mailman/commands/cli_lists.py
@@ -59,20 +59,23 @@ class Lists:
             help=_(
                 'List only those mailing lists that are publicly advertised'))
         command_parser.add_argument(
-            '-b', '--bare',
+            '-n', '--names',
             default=False, action='store_true',
-            help=_('Show only the list name, with no description'))
+            help=_('Show also the list names'))
         command_parser.add_argument(
-            '-d', '--domain',
+            '-d', '--descriptions',
+            default=False, action='store_true',
+            help=_('Show also the list descriptions'))
+        command_parser.add_argument(
+            '-q', '--quiet',
+            default=False, action='store_true',
+            help=_('Less verbosity'))
+        command_parser.add_argument(
+            '--domain',
             action='append', help=_("""\
             List only those mailing lists hosted on the given domain, which
             must be the email host name.  Multiple -d options may be given.
             """))
-        command_parser.add_argument(
-            '-f', '--full',
-            default=False, action='store_true',
-            help=_(
-                'Show the full mailing list name (i.e. the posting address'))
 
     def process(self, args):
         """See `ICLISubCommand`."""
@@ -89,28 +92,31 @@ class Lists:
             mailing_lists.append(mlist)
         # Maybe no mailing lists matched.
         if len(mailing_lists) == 0:
-            if not args.bare:
+            if not args.quiet:
                 print _('No matching mailing lists found')
             return
-        if not args.bare:
-            count = len(mailing_lists)
+        count = len(mailing_lists)
+        if not args.quiet:
             print _('$count matching mailing lists found:')
-        # Calculate the longest mailing list name.
-        longest = len(
-            max(mlist.fqdn_listname for mlist in mailing_lists)
-            if args.full else
-            max(mlist.real_name for mlist in mailing_lists))
-        # Print it out.
+        # Calculate the longest identifier.
+        longest = 0
+        output = []
         for mlist in mailing_lists:
-            name = (mlist.fqdn_listname if args.full else mlist.real_name)
-            if args.bare:
-                print name
+            if args.names:
+                identifier = '{0} [{1}]'.format(
+                    mlist.fqdn_listname, mlist.real_name)
             else:
-                description = (mlist.description
-                               if mlist.description is not None
-                               else _('[no description available]'))
-                print '{0:{2}} - {1:{3}}'.format(
-                    name, description, longest, 77 - longest)
+                identifier = mlist.fqdn_listname
+            longest = max(len(identifier), longest)
+            output.append((identifier, mlist.description))
+        # Print it out.
+        if args.descriptions:
+            format_string = '{0:{2}} - {1:{3}}'
+        else:
+            format_string = '{0:{2}}'
+        for identifier, description in output:
+            print format_string.format(
+                identifier, description, longest, 70 - longest)
 
 
 
diff --git a/src/mailman/commands/docs/lists.txt b/src/mailman/commands/docs/lists.txt
index 7673ffb03..ee4ec35e2 100644
--- a/src/mailman/commands/docs/lists.txt
+++ b/src/mailman/commands/docs/lists.txt
@@ -7,9 +7,10 @@ line.  When there are no mailing lists, a helpful message is displayed.
 
     >>> class FakeArgs:
     ...     advertised = False
-    ...     bare = False
+    ...     names = False
+    ...     descriptions = False
+    ...     quiet = False
     ...     domains = None
-    ...     full = False
 
     >>> from mailman.commands.cli_lists import Lists
     >>> command = Lists()
@@ -33,45 +34,58 @@ their fully qualified list names, with a description.
 
     >>> mlist_3 = create_list('list-one@example.net')
     >>> mlist_3.description = 'List One in Example.Net'
-    >>> transaction.commit()
 
     >>> command.process(FakeArgs)
     3 matching mailing lists found:
-    List-one - List One
-    List-one - List One in Example.Net
-    List-two - List Two
+    list-one@example.com
+    list-one@example.net
+    list-two@example.com
 
 
-Full names
-==========
+Names
+=====
 
-You can display the mailing lists' full names, i.e. their posting addresses,
-with the --full switch.
+You can display the mailing list names with their posting addresses, using the
+--names/-n switch.
 
-    >>> FakeArgs.full = True
+    >>> FakeArgs.names = True
     >>> command.process(FakeArgs)
     3 matching mailing lists found:
-    list-one@example.com - List One
-    list-one@example.net - List One in Example.Net
-    list-two@example.com - List Two
+    list-one@example.com [List-one]
+    list-one@example.net [List-one]
+    list-two@example.com [List-two]
+
 
+Descriptions
+============
 
-Bare names
-==========
+You can also display the mailing list descriptions, using the
+--descriptions/-d option.
 
-You can print less verbose output, such that only the mailing list's name is
-shown, with the --bare option.
+    >>> FakeArgs.descriptions = True
+    >>> command.process(FakeArgs)
+    3 matching mailing lists found:
+    list-one@example.com [List-one] - List One
+    list-one@example.net [List-one] - List One in Example.Net
+    list-two@example.com [List-two] - List Two
 
-    >>> FakeArgs.bare = True
-    >>> FakeArgs.full = False
+Maybe you want the descriptions but not the names.
+
+    >>> FakeArgs.names = False
     >>> command.process(FakeArgs)
-    List-one
-    List-one
-    List-two
+    3 matching mailing lists found:
+    list-one@example.com - List One
+    list-one@example.net - List One in Example.Net
+    list-two@example.com - List Two
 
---full and --bare can be combined.
 
-    >>> FakeArgs.full = True
+Less verbosity
+==============
+
+There's also a --quiet/-q switch which reduces the verbosity a bit.
+
+    >>> FakeArgs.quiet = True
+    >>> FakeArgs.descriptions = False
     >>> command.process(FakeArgs)
     list-one@example.com
     list-one@example.net
@@ -84,7 +98,7 @@ Specific domain
 You can narrow the search down to a specific domain with the --domain option.
 A helpful message is displayed if no matching domains are given.
 
-    >>> FakeArgs.bare = False
+    >>> FakeArgs.quiet = False
     >>> FakeArgs.domains = ['example.org']
     >>> command.process(FakeArgs)
     No matching mailing lists found
@@ -95,7 +109,7 @@ shown.
     >>> FakeArgs.domains = ['example.net']
     >>> command.process(FakeArgs)
     1 matching mailing lists found:
-    list-one@example.net - List One in Example.Net
+    list-one@example.net
 
 More than one --domain argument can be given; then all mailing lists in
 matching domains are shown.
@@ -103,9 +117,9 @@ matching domains are shown.
     >>> FakeArgs.domains = ['example.com', 'example.net']
     >>> command.process(FakeArgs)
     3 matching mailing lists found:
-    list-one@example.com - List One
-    list-one@example.net - List One in Example.Net
-    list-two@example.com - List Two
+    list-one@example.com
+    list-one@example.net
+    list-two@example.com
 
 
 Advertised lists
@@ -118,9 +132,8 @@ command line can select on this attribute.
     >>> FakeArgs.domains = []
     >>> FakeArgs.advertised = True
     >>> mlist_1.advertised = False
-    >>> transaction.commit()
 
     >>> command.process(FakeArgs)
     2 matching mailing lists found:
-    list-one@example.net - List One in Example.Net
-    list-two@example.com - List Two
+    list-one@example.net
+    list-two@example.com