356 lines
16 KiB
TeX
356 lines
16 KiB
TeX
\section{\module{nntplib} ---
|
|
NNTP protocol client}
|
|
|
|
\declaremodule{standard}{nntplib}
|
|
\modulesynopsis{NNTP protocol client (requires sockets).}
|
|
|
|
\indexii{NNTP}{protocol}
|
|
\index{Network News Transfer Protocol}
|
|
|
|
This module defines the class \class{NNTP} which implements the client
|
|
side of the NNTP protocol. It can be used to implement a news reader
|
|
or poster, or automated news processors. For more information on NNTP
|
|
(Network News Transfer Protocol), see Internet \rfc{977}.
|
|
|
|
Here are two small examples of how it can be used. To list some
|
|
statistics about a newsgroup and print the subjects of the last 10
|
|
articles:
|
|
|
|
\begin{verbatim}
|
|
>>> s = NNTP('news.cwi.nl')
|
|
>>> resp, count, first, last, name = s.group('comp.lang.python')
|
|
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
|
|
Group comp.lang.python has 59 articles, range 3742 to 3803
|
|
>>> resp, subs = s.xhdr('subject', first + '-' + last)
|
|
>>> for id, sub in subs[-10:]: print id, sub
|
|
...
|
|
3792 Re: Removing elements from a list while iterating...
|
|
3793 Re: Who likes Info files?
|
|
3794 Emacs and doc strings
|
|
3795 a few questions about the Mac implementation
|
|
3796 Re: executable python scripts
|
|
3797 Re: executable python scripts
|
|
3798 Re: a few questions about the Mac implementation
|
|
3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
|
|
3802 Re: executable python scripts
|
|
3803 Re: \POSIX{} wait and SIGCHLD
|
|
>>> s.quit()
|
|
'205 news.cwi.nl closing connection. Goodbye.'
|
|
\end{verbatim}
|
|
|
|
To post an article from a file (this assumes that the article has
|
|
valid headers):
|
|
|
|
\begin{verbatim}
|
|
>>> s = NNTP('news.cwi.nl')
|
|
>>> f = open('/tmp/article')
|
|
>>> s.post(f)
|
|
'240 Article posted successfully.'
|
|
>>> s.quit()
|
|
'205 news.cwi.nl closing connection. Goodbye.'
|
|
\end{verbatim}
|
|
|
|
The module itself defines the following items:
|
|
|
|
\begin{classdesc}{NNTP}{host\optional{, port
|
|
\optional{, user\optional{, password
|
|
\optional{, readermode}
|
|
\optional{, usenetrc}}}}}
|
|
Return a new instance of the \class{NNTP} class, representing a
|
|
connection to the NNTP server running on host \var{host}, listening at
|
|
port \var{port}. The default \var{port} is 119. If the optional
|
|
\var{user} and \var{password} are provided,
|
|
or if suitable credentials are present in \file{~/.netrc} and the
|
|
optional flag \var{usenetrc} is true (the default),
|
|
the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used to
|
|
identify and authenticate the user to the server. If the optional
|
|
flag \var{readermode} is true, then a \samp{mode reader} command is
|
|
sent before authentication is performed. Reader mode is sometimes
|
|
necessary if you are connecting to an NNTP server on the local machine
|
|
and intend to call reader-specific commands, such as \samp{group}. If
|
|
you get unexpected \exception{NNTPPermanentError}s, you might need to set
|
|
\var{readermode}. \var{readermode} defaults to \code{None}.
|
|
\var{usenetrc} defaults to \code{True}.
|
|
|
|
\versionchanged[\var{usenetrc} argument added]{2.4}
|
|
\end{classdesc}
|
|
|
|
\begin{excdesc}{NNTPError}
|
|
Derived from the standard exception \exception{Exception}, this is the
|
|
base class for all exceptions raised by the \module{nntplib} module.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{NNTPReplyError}
|
|
Exception raised when an unexpected reply is received from the
|
|
server. For backwards compatibility, the exception \code{error_reply}
|
|
is equivalent to this class.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{NNTPTemporaryError}
|
|
Exception raised when an error code in the range 400--499 is
|
|
received. For backwards compatibility, the exception
|
|
\code{error_temp} is equivalent to this class.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{NNTPPermanentError}
|
|
Exception raised when an error code in the range 500--599 is
|
|
received. For backwards compatibility, the exception
|
|
\code{error_perm} is equivalent to this class.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{NNTPProtocolError}
|
|
Exception raised when a reply is received from the server that does
|
|
not begin with a digit in the range 1--5. For backwards
|
|
compatibility, the exception \code{error_proto} is equivalent to this
|
|
class.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{NNTPDataError}
|
|
Exception raised when there is some error in the response data. For
|
|
backwards compatibility, the exception \code{error_data} is
|
|
equivalent to this class.
|
|
\end{excdesc}
|
|
|
|
|
|
\subsection{NNTP Objects \label{nntp-objects}}
|
|
|
|
NNTP instances have the following methods. The \var{response} that is
|
|
returned as the first item in the return tuple of almost all methods
|
|
is the server's response: a string beginning with a three-digit code.
|
|
If the server's response indicates an error, the method raises one of
|
|
the above exceptions.
|
|
|
|
|
|
\begin{methoddesc}{getwelcome}{}
|
|
Return the welcome message sent by the server in reply to the initial
|
|
connection. (This message sometimes contains disclaimers or help
|
|
information that may be relevant to the user.)
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{set_debuglevel}{level}
|
|
Set the instance's debugging level. This controls the amount of
|
|
debugging output printed. The default, \code{0}, produces no debugging
|
|
output. A value of \code{1} produces a moderate amount of debugging
|
|
output, generally a single line per request or response. A value of
|
|
\code{2} or higher produces the maximum amount of debugging output,
|
|
logging each line sent and received on the connection (including
|
|
message text).
|
|
\end{methoddesc}
|
|
|
|
\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, \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 message 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}{\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
|
|
\var{group} is a group name, \var{last} and \var{first} are the last
|
|
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}{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})}.
|
|
|
|
\versionadded{2.4}
|
|
\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()}.
|
|
|
|
\versionadded{2.4}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{group}{name}
|
|
Send a \samp{GROUP} command, where \var{name} is the group name.
|
|
Return a tuple \code{(\var{response}, \var{count}, \var{first},
|
|
\var{last}, \var{name})} where \var{count} is the (estimated) number
|
|
of articles in the group, \var{first} is the first article number in
|
|
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}{\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}
|
|
Send a \samp{STAT} command, where \var{id} is the message id (enclosed
|
|
in \character{<} and \character{>}) or an article number (as a string).
|
|
Return a triple \code{(\var{response}, \var{number}, \var{id})} where
|
|
\var{number} is the article number (as a string) and \var{id} is the
|
|
message id (enclosed in \character{<} and \character{>}).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{next}{}
|
|
Send a \samp{NEXT} command. Return as for \method{stat()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{last}{}
|
|
Send a \samp{LAST} command. Return as for \method{stat()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{head}{id}
|
|
Send a \samp{HEAD} command, where \var{id} has the same meaning as for
|
|
\method{stat()}. Return a tuple
|
|
\code{(\var{response}, \var{number}, \var{id}, \var{list})}
|
|
where the first three are the same as for \method{stat()},
|
|
and \var{list} is a list of the article's headers (an uninterpreted
|
|
list of lines, without trailing newlines).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{body}{id,\optional{file}}
|
|
Send a \samp{BODY} command, where \var{id} has the same meaning as for
|
|
\method{stat()}. If the \var{file} parameter is supplied, then
|
|
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
|
|
the returned \var{list} is an empty list.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{article}{id}
|
|
Send an \samp{ARTICLE} command, where \var{id} has the same meaning as
|
|
for \method{stat()}. Return as for \method{head()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{slave}{}
|
|
Send a \samp{SLAVE} command. Return the server's \var{response}.
|
|
\end{methoddesc}
|
|
|
|
\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
|
|
the form \code{'\var{first}-\var{last}'} where \var{first} and
|
|
\var{last} are the first and last article numbers to search. Return a
|
|
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 number
|
|
(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}
|
|
Post an article using the \samp{POST} command. The \var{file}
|
|
argument is an open file object which is read until EOF using its
|
|
\method{readline()} method. It should be a well-formed news article,
|
|
including the required headers. The \method{post()} method
|
|
automatically escapes lines beginning with \samp{.}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{ihave}{id, file}
|
|
Send an \samp{IHAVE} command. \var{id} is a message id (enclosed in
|
|
\character{<} and \character{>}).
|
|
If the response is not an error, treat
|
|
\var{file} exactly as for the \method{post()} method.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{date}{}
|
|
Return a triple \code{(\var{response}, \var{date}, \var{time})},
|
|
containing the current date and time in a form suitable for the
|
|
\method{newnews()} and \method{newgroups()} methods.
|
|
This is an optional NNTP extension, and may not be supported by all
|
|
servers.
|
|
\end{methoddesc}
|
|
|
|
\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.
|
|
|
|
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}}
|
|
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}
|
|
|
|
\begin{methoddesc}{xpath}{id}
|
|
Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
|
|
directory path to the article with message ID \var{id}. This is an
|
|
optional NNTP extension, and may not be supported by all servers.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{quit}{}
|
|
Send a \samp{QUIT} command and close the connection. Once this method
|
|
has been called, no other methods of the NNTP object should be called.
|
|
\end{methoddesc}
|