list-style-descriptions

8 files changed, 41 insertions, 10 deletions

diff --git a/src/mailman/interfaces/styles.py b/src/mailman/interfaces/styles.py
index 9c7d13479..b36547b40 100644
--- a/src/mailman/interfaces/styles.py
+++ b/src/mailman/interfaces/styles.py
@@ -34,6 +34,9 @@ class IStyle(Interface):
     name = Attribute(
         """The name of this style.  Must be unique.""")
 
+    description = Attribute(
+        """A short description of this list style.""")
+
     def apply(mailing_list):
         """Apply the style to the mailing list.
 
diff --git a/src/mailman/rest/docs/lists.rst b/src/mailman/rest/docs/lists.rst
index 6a034df94..67cbb697a 100644
--- a/src/mailman/rest/docs/lists.rst
+++ b/src/mailman/rest/docs/lists.rst
@@ -191,10 +191,13 @@ Apply a style at list creation time
 of a particular type, e.g. discussion lists.  We can see which styles are
 available, and which is the default style.
 
-    >>> dump_json('http://localhost:9001/3.0/lists/styles')
-    default: legacy-default
-    http_etag: "..."
-    style_names: ['legacy-announce', 'legacy-default']
+    >>> json = call_http('http://localhost:9001/3.0/lists/styles')
+    >>> json['default']
+    'legacy-default'
+    >>> for style in json['styles']:
+    ...     print('{}: {}'.format(style['name'], style['description']))
+    legacy-announce: Announce only mailing list style.
+    legacy-default: Ordinary discussion mailing list style.
 
 When creating a list, if we don't specify a style to apply, the default style
 is used.  However, we can provide a style name in the POST data to choose a
diff --git a/src/mailman/rest/lists.py b/src/mailman/rest/lists.py
index 4b467afb3..482d3e2d7 100644
--- a/src/mailman/rest/lists.py
+++ b/src/mailman/rest/lists.py
@@ -414,9 +414,10 @@ class Styles:
 
     def __init__(self):
         manager = getUtility(IStyleManager)
-        style_names = sorted(style.name for style in manager.styles)
+        styles = [dict(name=style.name, description=style.description)
+                  for style in manager.styles]
         self._resource = dict(
-            style_names=style_names,
+            styles=styles,
             default=config.styles.default)
 
     def on_get(self, request, response):
diff --git a/src/mailman/rest/tests/test_lists.py b/src/mailman/rest/tests/test_lists.py
index 0f3b99393..44446b289 100644
--- a/src/mailman/rest/tests/test_lists.py
+++ b/src/mailman/rest/tests/test_lists.py
@@ -347,6 +347,27 @@ class TestLists(unittest.TestCase):
         self.assertEqual(cm.exception.reason, 'Missing parameters: emails')
 
 
+class TestListStyles(unittest.TestCase):
+    """Test /lists/styles."""
+
+    layer = RESTLayer
+
+    def test_styles(self):
+        json, response = call_api('http://localhost:9001/3.0/lists/styles')
+        self.assertEqual(response.status_code, 200)
+        # Remove the variable data.
+        json.pop('http_etag')
+        self.assertEqual(json, {
+            'styles': [
+                {'name': 'legacy-announce',
+                 'description': 'Announce only mailing list style.'},
+                {'name': 'legacy-default',
+                 'description': 'Ordinary discussion mailing list style.'}
+                    ],
+            'default': 'legacy-default'
+            })
+
+
 class TestListArchivers(unittest.TestCase):
     """Test corner cases for list archivers."""
 
diff --git a/src/mailman/runners/tests/test_bounce.py b/src/mailman/runners/tests/test_bounce.py
index 69198d881..4a21e0e52 100644
--- a/src/mailman/runners/tests/test_bounce.py
+++ b/src/mailman/runners/tests/test_bounce.py
@@ -227,6 +227,7 @@ class TestStyle:
     """See `IStyle`."""
 
     name = 'test'
+    description = 'A test style.'
 
     def apply(self, mailing_list):
         """See `IStyle`."""
diff --git a/src/mailman/styles/default.py b/src/mailman/styles/default.py
index 01b6764da..97c57a94d 100644
--- a/src/mailman/styles/default.py
+++ b/src/mailman/styles/default.py
@@ -17,6 +17,7 @@
 
 """Application of list styles to new and existing lists."""
 
+from mailman.core.i18n import _
 from mailman.interfaces.styles import IStyle
 from mailman.styles.base import (
     Announcement, BasicOperation, Bounces, Discussion, Identity, Moderation,
@@ -33,6 +34,7 @@ class LegacyDefaultStyle(
     """The legacy default style."""
 
     name = 'legacy-default'
+    description = _('Ordinary discussion mailing list style.')
 
     def apply(self, mailing_list):
         """See `IStyle`."""
@@ -52,6 +54,7 @@ class LegacyAnnounceOnly(
     """Similar to the legacy-default style, but for announce-only lists."""
 
     name = 'legacy-announce'
+    description = _('Announce only mailing list style.')
 
     def apply(self, mailing_list):
         """See `IStyle`."""
diff --git a/src/mailman/styles/docs/styles.rst b/src/mailman/styles/docs/styles.rst
index 270b0cdcc..a296bab54 100644
--- a/src/mailman/styles/docs/styles.rst
+++ b/src/mailman/styles/docs/styles.rst
@@ -49,6 +49,7 @@ New styles must implement the ``IStyle`` interface.
     >>> @implementer(IStyle)
     ... class TestStyle:
     ...     name = 'a-test-style'
+    ...     description = 'Testing mailing list style.'
     ...     def apply(self, mailing_list):
     ...         # Just does something very simple.
     ...         mailing_list.display_name = 'TEST STYLE LIST'
@@ -115,6 +116,7 @@ If no style name is provided when creating the list, the system default style
     >>> @implementer(IStyle)
     ... class AnotherStyle:
     ...     name = 'another-style'
+    ...     description = 'Another testing mailing list style.'
     ...     def apply(self, mailing_list):
     ...         # Just does something very simple.
     ...         mailing_list.display_name = 'ANOTHER STYLE LIST'
diff --git a/src/mailman/styles/tests/test_styles.py b/src/mailman/styles/tests/test_styles.py
index a763082bf..a09967eb6 100644
--- a/src/mailman/styles/tests/test_styles.py
+++ b/src/mailman/styles/tests/test_styles.py
@@ -31,14 +31,11 @@ from zope.interface.exceptions import DoesNotImplement
 class DummyStyle:
 
     name = 'dummy'
-    priority = 1
+    description = 'A dummy style.'
 
     def apply(self, mlist):
         pass
 
-    def match(self, mlist, styles):
-        styles.append(self)
-
 
 class TestStyle(unittest.TestCase):
     """Test styles."""