Patch #605370: Add description[s] for RFC 2980 compliance.
diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
index 8616fb9..9b9217b 100644
--- a/Doc/lib/libnntplib.tex
+++ b/Doc/lib/libnntplib.tex
@@ -175,6 +175,23 @@
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 @@
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 83544b8..d0bd5ad 100644
--- a/Lib/nntplib.py
+++ b/Lib/nntplib.py
@@ -297,6 +297,42 @@
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 348949c..071f86e 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -163,6 +163,7 @@
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 4b5fae1..e48309c 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -44,6 +44,9 @@
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.