From cc0f93233a1715ae8358fb0fa35b1ab8786bade3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20v=2E=20L=C3=B6wis?= <martin@v.loewis.de>
Date: Mon, 26 Jul 2004 12:40:50 +0000
Subject: [PATCH] Patch #605370: Add description[s] for RFC 2980 compliance.

---
 Doc/lib/libnntplib.tex | 20 ++++++++++++++++++++
 Lib/nntplib.py         | 36 ++++++++++++++++++++++++++++++++++++
 Misc/ACKS              |  1 +
 Misc/NEWS              |  3 +++
 4 files changed, 60 insertions(+)

diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
index 8616fb93f72..9b9217b1676 100644
--- a/Doc/lib/libnntplib.tex
+++ b/Doc/lib/libnntplib.tex
@@ -175,6 +175,23 @@ then the method will open a file object with that name, write to it
 then close it.  If \var{file} is a file object, then it will start
 calling \method{write()} on it to store the lines of the command output.
 If \var{file} is supplied, then the returned \var{list} is an empty list.
+
+\begin{methoddesc}{descriptions}{grouppattern}
+Send a \samp{LIST NEWSGROUPS} command, where \var{grouppattern} is a wildmat
+string as specified in RFC2980 (it's essentially the same as DOS or UNIX
+shell wildcard strings).  Return a pair \code{(\var{response},
+\var{list})}, where \var{list} is a list of tuples containing
+\code{(\var{name}, \var{title})}.
+\end{methoddesc}
+
+\begin{methoddesc}{description}{group}
+Get a description for a single group \var{group}.  If more than one group
+matches (if 'group' is a real wildmat string), return the first match.  If no group
+matches, return an empty string.
+
+This elides the response code from the server.  If the response code is
+needed, use \method{descriptions()}.
+
 \end{methoddesc}
 
 \begin{methoddesc}{group}{name}
@@ -294,6 +311,9 @@ calling \method{write()} on it to store the lines of the command output.
 If \var{file} is supplied, then the returned \var{list} is an empty list.
 This is an optional NNTP extension, and may not be supported by all
 servers.
+
+RFC2980 says ``It is suggested that this extension be deprecated''.  Use
+\method{descriptions()} or \method{description()} instead.
 \end{methoddesc}
 
 \begin{methoddesc}{xover}{start, end, \optional{file}}
diff --git a/Lib/nntplib.py b/Lib/nntplib.py
index 83544b893be..d0bd5adcfd0 100644
--- a/Lib/nntplib.py
+++ b/Lib/nntplib.py
@@ -297,6 +297,42 @@ class NNTP:
             list[i] = tuple(list[i].split())
         return resp, list
 
+    def description(self, group):
+
+        """Get a description for a single group.  If more than one
+        group matches ('group' is a pattern), return the first.  If no
+        group matches, return an empty string.
+
+        This elides the response code from the server, since it can
+        only be '215' or '285' (for xgtitle) anyway.  If the response
+        code is needed, use the 'descriptions' method.
+
+        NOTE: This neither checks for a wildcard in 'group' nor does
+        it check whether the group actually exists."""
+
+        resp, lines = self.descriptions(group)
+        if len(lines) == 0:
+            return ""
+        else:
+            return lines[0][1]
+
+    def descriptions(self, group_pattern):
+        """Get descriptions for a range of groups."""
+        line_pat = re.compile("^(?P<group>[^ \t]+)[ \t]+(.*)$")
+        # Try the more std (acc. to RFC2980) LIST NEWSGROUPS first
+        resp, raw_lines = self.longcmd('LIST NEWSGROUPS ' + group_pattern)
+        if resp[:3] != "215":
+            # Now the deprecated XGTITLE.  This either raises an error
+            # or succeeds with the same output structure as LIST
+            # NEWSGROUPS.
+            resp, raw_lines = self.longcmd('XGTITLE ' + group_pattern)
+        lines = []
+        for raw_line in raw_lines:
+            match = line_pat.search(raw_line.strip())
+            if match:
+                lines.append(match.group(1, 2))
+        return resp, lines
+
     def group(self, name):
         """Process a GROUP command.  Argument:
         - group: the group name
diff --git a/Misc/ACKS b/Misc/ACKS
index 348949c78f0..071f86ec6b6 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -163,6 +163,7 @@ David Ely
 Jeff Epler
 Tom Epperly
 Stoffel Erasmus
+Jürgen A. Erhard
 Michael Ernst
 Ben Escoto
 Andy Eskilsson
diff --git a/Misc/NEWS b/Misc/NEWS
index 4b5fae1d1b0..e48309c41e7 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -44,6 +44,9 @@ Extension modules
 Library
 -------
 
+- nntplib has two new methods: description and descriptions. They
+  use a more RFC-compliant way of getting a newsgroup description.
+
 - Bug #993394.  Fix a possible red herring of KeyError in 'threading' being
   raised during interpreter shutdown from a registered function with atexit
   when dummy_threading is being used.