diff options
| -rw-r--r-- | Doc/lib/libnntplib.tex | 58 | ||||
| -rw-r--r-- | Lib/nntplib.py | 28 | ||||
| -rw-r--r-- | Misc/ACKS | 1 | ||||
| -rw-r--r-- | Misc/NEWS | 4 |
4 files changed, 69 insertions, 22 deletions
diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex index 5565289..8616fb9 100644 --- a/Doc/lib/libnntplib.tex +++ b/Doc/lib/libnntplib.tex @@ -132,23 +132,35 @@ logging each line sent and received on the connection (including message text). \end{methoddesc} -\begin{methoddesc}{newgroups}{date, time} +\begin{methoddesc}{newgroups}{date, time, \optional{file}} Send a \samp{NEWGROUPS} command. The \var{date} argument should be a string of the form \code{'\var{yy}\var{mm}\var{dd}'} indicating the date, and \var{time} should be a string of the form \code{'\var{hh}\var{mm}\var{ss}'} indicating the time. Return a pair \code{(\var{response}, \var{groups})} where \var{groups} is a list of group names that are new since the given date and time. +If the \var{file} parameter is supplied, then the output of the +\samp{NEWGROUPS} command is stored in a file. If \var{file} is a string, +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. \end{methoddesc} -\begin{methoddesc}{newnews}{group, date, time} +\begin{methoddesc}{newnews}{group, date, time, \optional{file}} Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or \code{'*'}, and \var{date} and \var{time} have the same meaning as for \method{newgroups()}. Return a pair \code{(\var{response}, \var{articles})} where \var{articles} is a list of article ids. +If the \var{file} parameter is supplied, then the output of the +\samp{NEWNEWS} command is stored in a file. If \var{file} is a string, +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. \end{methoddesc} -\begin{methoddesc}{list}{} +\begin{methoddesc}{list}{\optional{file}} Send a \samp{LIST} command. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of tuples. Each tuple has the form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where @@ -157,6 +169,12 @@ and first article numbers (as strings), and \var{flag} is \code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if the newsgroup is moderated. (Note the ordering: \var{last}, \var{first}.) +If the \var{file} parameter is supplied, then the output of the +\samp{LIST} command is stored in a file. If \var{file} is a string, +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. \end{methoddesc} \begin{methoddesc}{group}{name} @@ -168,9 +186,15 @@ the group, \var{last} is the last article number in the group, and \var{name} is the group name. The numbers are returned as strings. \end{methoddesc} -\begin{methoddesc}{help}{} +\begin{methoddesc}{help}{\optional{file}} Send a \samp{HELP} command. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of help strings. +If the \var{file} parameter is supplied, then the output of the +\samp{HELP} command is stored in a file. If \var{file} is a string, +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. \end{methoddesc} \begin{methoddesc}{stat}{id} @@ -205,7 +229,7 @@ the body is stored in a file. If \var{file} is a string, 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 body. -Return as for \method{head()}. If \var{file} is supplied. Then +Return as for \method{head()}. If \var{file} is supplied, then the returned \var{list} is an empty list. \end{methoddesc} @@ -218,7 +242,7 @@ for \method{stat()}. Return as for \method{head()}. Send a \samp{SLAVE} command. Return the server's \var{response}. \end{methoddesc} -\begin{methoddesc}{xhdr}{header, string} +\begin{methoddesc}{xhdr}{header, string, \optional{file}} Send an \samp{XHDR} command. This command is not defined in the RFC but is a common extension. The \var{header} argument is a header keyword, e.g. \code{'subject'}. The \var{string} argument should have @@ -228,6 +252,12 @@ pair \code{(\var{response}, \var{list})}, where \var{list} is a list of pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id (as a string) and \var{text} is the text of the requested header for that article. +If the \var{file} parameter is supplied, then the output of the +\samp{XHDR} command is stored in a file. If \var{file} is a string, +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. \end{methoddesc} \begin{methoddesc}{post}{file} @@ -251,21 +281,33 @@ This is an optional NNTP extension, and may not be supported by all servers. \end{methoddesc} -\begin{methoddesc}{xgtitle}{name} +\begin{methoddesc}{xgtitle}{name, \optional{file}} Process an \samp{XGTITLE} command, returning a pair \code{(\var{response}, \var{list})}, where \var{list} is a list of tuples containing \code{(\var{name}, \var{title})}. % XXX huh? Should that be name, description? +If the \var{file} parameter is supplied, then the output of the +\samp{XGTITLE} command is stored in a file. If \var{file} is a string, +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. This is an optional NNTP extension, and may not be supported by all servers. \end{methoddesc} -\begin{methoddesc}{xover}{start, end} +\begin{methoddesc}{xover}{start, end, \optional{file}} Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list of tuples, one for each article in the range delimited by the \var{start} and \var{end} article numbers. Each tuple is of the form \code{(\var{article number}, \var{subject}, \var{poster}, \var{date}, \var{id}, \var{references}, \var{size}, \var{lines})}. +If the \var{file} parameter is supplied, then the output of the +\samp{XOVER} command is stored in a file. If \var{file} is a string, +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. This is an optional NNTP extension, and may not be supported by all servers. \end{methoddesc} diff --git a/Lib/nntplib.py b/Lib/nntplib.py index d52286f..6299ba2 100644 --- a/Lib/nntplib.py +++ b/Lib/nntplib.py @@ -264,7 +264,7 @@ class NNTP: self.putcmd(line) return self.getlongresp(file) - def newgroups(self, date, time): + def newgroups(self, date, time, file=None): """Process a NEWGROUPS command. Arguments: - date: string 'yymmdd' indicating the date - time: string 'hhmmss' indicating the time @@ -272,9 +272,9 @@ class NNTP: - resp: server response if successful - list: list of newsgroup names""" - return self.longcmd('NEWGROUPS ' + date + ' ' + time) + return self.longcmd('NEWGROUPS ' + date + ' ' + time, file) - def newnews(self, group, date, time): + def newnews(self, group, date, time, file=None): """Process a NEWNEWS command. Arguments: - group: group name or '*' - date: string 'yymmdd' indicating the date @@ -284,14 +284,14 @@ class NNTP: - list: list of article ids""" cmd = 'NEWNEWS ' + group + ' ' + date + ' ' + time - return self.longcmd(cmd) + return self.longcmd(cmd, file) - def list(self): + def list(self, file=None): """Process a LIST command. Return: - resp: server response if successful - list: list of (group, last, first, flag) (strings)""" - resp, list = self.longcmd('LIST') + resp, list = self.longcmd('LIST', file) for i in range(len(list)): # Parse lines into "group last first flag" list[i] = tuple(list[i].split()) @@ -323,12 +323,12 @@ class NNTP: name = words[4].lower() return resp, count, first, last, name - def help(self): + def help(self, file=None): """Process a HELP command. Returns: - resp: server response if successful - list: list of strings""" - return self.longcmd('HELP') + return self.longcmd('HELP',file) def statparse(self, resp): """Internal: parse the response of a STAT, NEXT or LAST command.""" @@ -414,7 +414,7 @@ class NNTP: return self.shortcmd('SLAVE') - def xhdr(self, hdr, str): + def xhdr(self, hdr, str, file=None): """Process an XHDR command (optional server extension). Arguments: - hdr: the header type (e.g. 'subject') - str: an article nr, a message id, or a range nr1-nr2 @@ -423,7 +423,7 @@ class NNTP: - list: list of (nr, value) strings""" pat = re.compile('^([0-9]+) ?(.*)\n?') - resp, lines = self.longcmd('XHDR ' + hdr + ' ' + str) + resp, lines = self.longcmd('XHDR ' + hdr + ' ' + str, file) for i in range(len(lines)): line = lines[i] m = pat.match(line) @@ -431,7 +431,7 @@ class NNTP: lines[i] = m.group(1, 2) return resp, lines - def xover(self,start,end): + def xover(self, start, end, file=None): """Process an XOVER command (optional server extension) Arguments: - start: start of range - end: end of range @@ -440,7 +440,7 @@ class NNTP: - list: list of (art-nr, subject, poster, date, id, references, size, lines)""" - resp, lines = self.longcmd('XOVER ' + start + '-' + end) + resp, lines = self.longcmd('XOVER ' + start + '-' + end, file) xover_lines = [] for line in lines: elem = line.split("\t") @@ -457,7 +457,7 @@ class NNTP: raise NNTPDataError(line) return resp,xover_lines - def xgtitle(self, group): + def xgtitle(self, group, file=None): """Process an XGTITLE command (optional server extension) Arguments: - group: group name wildcard (i.e. news.*) Returns: @@ -465,7 +465,7 @@ class NNTP: - list: list of (name,title) strings""" line_pat = re.compile("^([^ \t]+)[ \t]+(.*)$") - resp, raw_lines = self.longcmd('XGTITLE ' + group) + resp, raw_lines = self.longcmd('XGTITLE ' + group, file) lines = [] for raw_line in raw_lines: match = line_pat.search(raw_line.strip()) @@ -86,6 +86,7 @@ Ralph Butler Daniel Calvelo Brett Cannon Mike Carlton +Terry Carroll Luke Kenneth Casson Leighton Donn Cave Per Cederqvist @@ -118,6 +118,10 @@ Extension modules Library ------- +- Several methods of nntplib.NNTP have grown an optional file argument + which specifies a file where to divert the command's output + (already supported by the body() method). (SF patch #720468) + - The self-documenting XML server library DocXMLRPCServer was added. - Support for internationalized domain names has been added through |