Issue #10283: Add a `group_pattern` argument to NNTP.list().

Doc/library/nntplib.rst

@@ -182,13 +182,15 @@ response indicates an error, the method raises one of the above exceptions.
    This command is frequently disabled by NNTP server administrators.
 
 
-.. method:: NNTP.list(*, file=None)
+.. method:: NNTP.list(group_pattern=None, *, file=None)
 
-   Send a ``LIST`` command.  Return a pair ``(response, list)`` where *list* is a
+   Send a ``LIST`` or ``LIST ACTIVE`` command.  Return a pair
-   list of tuples representing all the groups available from this NNTP server.
+   ``(response, list)`` where *list* is a list of tuples representing all
-   Each tuple has the form ``(group, last, first, flag)``, where
+   the groups available from this NNTP server, optionally matching the
-   *group* is a group name, *last* and *first* are the last and first article
+   pattern string *group_pattern*.  Each tuple has the form
-   numbers, and *flag* usually takes one of these values:
+   ``(group, last, first, flag)``, where *group* is a group name, *last*
+   and *first* are the last and first article numbers, and *flag* usually
+   takes one of these values:
 
    * ``y``: Local postings and articles from peers are allowed.
    * ``m``: The group is moderated and all postings must be approved.
@@ -200,8 +202,12 @@ response indicates an error, the method raises one of the above exceptions.
    If *flag* has another value, then the status of the newsgroup should be
    considered unknown.
 
-   This command will often return very large results.  It is best to cache the
+   This command can return very large results, especially if *group_pattern*
-   results offline unless you really need to refresh them.
+   is not specified.  It is best to cache the results offline unless you
+   really need to refresh them.
+
+   .. versionchanged:: 3.2
+      *group_pattern* was added.
 
 
 .. method:: NNTP.descriptions(grouppattern)

Lib/nntplib.py

@@ -571,14 +571,19 @@ class _NNTPBase:
         cmd = 'NEWNEWS {0} {1} {2}'.format(group, date_str, time_str)
         return self._longcmdstring(cmd, file)
 
-    def list(self, *, file=None):
+    def list(self, group_pattern=None, *, file=None):
-        """Process a LIST command. Argument:
+        """Process a LIST or LIST ACTIVE command. Arguments:
+        - group_pattern: a pattern indicating which groups to query
         - file: Filename string or file object to store the result in
         Returns:
         - resp: server response if successful
         - list: list of (group, last, first, flag) (strings)
         """
-        resp, lines = self._longcmdstring('LIST', file)
+        if group_pattern is not None:
+            command = 'LIST ACTIVE ' + group_pattern
+        else:
+            command = 'LIST'
+        resp, lines = self._longcmdstring(command, file)
         return resp, self._grouplist(lines)
 
     def _getdescriptions(self, group_pattern, return_all):

Lib/test/test_nntplib.py

@@ -22,16 +22,22 @@ class NetworkedNNTPTestsMixin:
         self.assertEqual(str, type(welcome))
 
     def test_help(self):
-        resp, list = self.server.help()
+        resp, lines = self.server.help()
         self.assertTrue(resp.startswith("100 "), resp)
-        for line in list:
+        for line in lines:
             self.assertEqual(str, type(line))
 
     def test_list(self):
-        resp, list = self.server.list()
+        resp, groups = self.server.list()
-        if len(list) > 0:
+        if len(groups) > 0:
-            self.assertEqual(GroupInfo, type(list[0]))
+            self.assertEqual(GroupInfo, type(groups[0]))
-            self.assertEqual(str, type(list[0].group))
+            self.assertEqual(str, type(groups[0].group))
+
+    def test_list_active(self):
+        resp, groups = self.server.list(self.GROUP_PAT)
+        if len(groups) > 0:
+            self.assertEqual(GroupInfo, type(groups[0]))
+            self.assertEqual(str, type(groups[0].group))
 
     def test_unknown_command(self):
         with self.assertRaises(nntplib.NNTPPermanentError) as cm:
@@ -383,6 +389,17 @@ class NNTPv1Handler:
                 free.it.comp.lang.python.learner 0000000000 0000000001 y
                 tw.bbs.comp.lang.python 0000000304 0000000304 y
                 .""")
+        elif action == "ACTIVE":
+            if param == "*distutils*":
+                self.push_lit("""\
+                    215 Newsgroups in form "group high low flags"
+                    gmane.comp.python.distutils.devel 0000014104 0000000001 m
+                    gmane.comp.python.distutils.cvs 0000000000 0000000001 m
+                    .""")
+            else:
+                self.push_lit("""\
+                    215 Newsgroups in form "group high low flags"
+                    .""")
         elif action == "OVERVIEW.FMT":
             self.push_lit("""\
                 215 Order of fields in overview database.
@@ -608,6 +625,12 @@ class NNTPv1v2TestsMixin:
         self.assertEqual(g,
             GroupInfo("comp.lang.python.announce", "0000001153",
                       "0000000993", "m"))
+        resp, groups = self.server.list("*distutils*")
+        self.assertEqual(len(groups), 2)
+        g = groups[0]
+        self.assertEqual(g,
+            GroupInfo("gmane.comp.python.distutils.devel", "0000014104",
+                      "0000000001", "m"))
 
     def test_stat(self):
         resp, art_num, message_id = self.server.stat(3000234)

Misc/NEWS

@@ -65,6 +65,8 @@ Core and Builtins
 Library
 -------
 
+- Issue #10283: Add a ``group_pattern`` argument to NNTP.list().
+
 - Issue #10155: Add IISCGIHandler to wsgiref.handlers to support IIS
   CGI environment better, and to correct unicode environment values
   for WSGI 1.0.1.