Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{nntplib} --- |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 2 | NNTP protocol client} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{nntplib} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{NNTP protocol client (requires sockets).} |
| 6 | |
Fred Drake | 6279fcc | 1998-01-07 13:23:32 +0000 | [diff] [blame] | 7 | \indexii{NNTP}{protocol} |
Fred Drake | 3f6034d | 1998-07-02 19:33:43 +0000 | [diff] [blame] | 8 | \index{Network News Transfer Protocol} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 9 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 10 | This module defines the class \class{NNTP} which implements the client |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 11 | side of the NNTP protocol. It can be used to implement a news reader |
| 12 | or poster, or automated news processors. For more information on NNTP |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 13 | (Network News Transfer Protocol), see Internet \rfc{977}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 14 | |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 15 | Here are two small examples of how it can be used. To list some |
| 16 | statistics about a newsgroup and print the subjects of the last 10 |
| 17 | articles: |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 18 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 19 | \begin{verbatim} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 20 | >>> s = NNTP('news.cwi.nl') |
| 21 | >>> resp, count, first, last, name = s.group('comp.lang.python') |
| 22 | >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last |
| 23 | Group comp.lang.python has 59 articles, range 3742 to 3803 |
| 24 | >>> resp, subs = s.xhdr('subject', first + '-' + last) |
| 25 | >>> for id, sub in subs[-10:]: print id, sub |
| 26 | ... |
| 27 | 3792 Re: Removing elements from a list while iterating... |
| 28 | 3793 Re: Who likes Info files? |
| 29 | 3794 Emacs and doc strings |
| 30 | 3795 a few questions about the Mac implementation |
| 31 | 3796 Re: executable python scripts |
| 32 | 3797 Re: executable python scripts |
| 33 | 3798 Re: a few questions about the Mac implementation |
| 34 | 3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules |
| 35 | 3802 Re: executable python scripts |
Fred Drake | 65b32f7 | 1998-02-09 20:27:12 +0000 | [diff] [blame] | 36 | 3803 Re: \POSIX{} wait and SIGCHLD |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 37 | >>> s.quit() |
| 38 | '205 news.cwi.nl closing connection. Goodbye.' |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 39 | \end{verbatim} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 40 | |
| 41 | To post an article from a file (this assumes that the article has |
| 42 | valid headers): |
| 43 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 44 | \begin{verbatim} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 45 | >>> s = NNTP('news.cwi.nl') |
| 46 | >>> f = open('/tmp/article') |
| 47 | >>> s.post(f) |
| 48 | '240 Article posted successfully.' |
| 49 | >>> s.quit() |
| 50 | '205 news.cwi.nl closing connection. Goodbye.' |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 51 | \end{verbatim} |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 52 | |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 53 | The module itself defines the following items: |
| 54 | |
Fred Drake | c46973c | 1998-11-16 17:11:30 +0000 | [diff] [blame] | 55 | \begin{classdesc}{NNTP}{host\optional{, port |
Barry Warsaw | 41d8463 | 2000-02-10 20:26:45 +0000 | [diff] [blame] | 56 | \optional{, user\optional{, password |
| 57 | \optional{, readermode}}}}} |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 58 | Return a new instance of the \class{NNTP} class, representing a |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 59 | connection to the NNTP server running on host \var{host}, listening at |
Fred Drake | c46973c | 1998-11-16 17:11:30 +0000 | [diff] [blame] | 60 | port \var{port}. The default \var{port} is 119. If the optional |
Eric S. Raymond | 2852cba | 2002-12-31 15:28:44 +0000 | [diff] [blame] | 61 | \var{user} and \var{password} are provided, |
| 62 | or if suitable credentials are present in \file{~/.netrc}, |
| 63 | the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used to |
Barry Warsaw | 41d8463 | 2000-02-10 20:26:45 +0000 | [diff] [blame] | 64 | identify and authenticate the user to the server. If the optional |
| 65 | flag \var{readermode} is true, then a \samp{mode reader} command is |
| 66 | sent before authentication is performed. Reader mode is sometimes |
| 67 | necessary if you are connecting to an NNTP server on the local machine |
| 68 | and intend to call reader-specific commands, such as \samp{group}. If |
| 69 | you get unexpected \code{NNTPPermanentError}s, you might need to set |
| 70 | \var{readermode}. \var{readermode} defaults to \code{None}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 71 | \end{classdesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 72 | |
Barry Warsaw | 41d8463 | 2000-02-10 20:26:45 +0000 | [diff] [blame] | 73 | \begin{classdesc}{NNTPError}{} |
| 74 | Derived from the standard exception \code{Exception}, this is the base |
| 75 | class for all exceptions raised by the \code{nntplib} module. |
| 76 | \end{classdesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 77 | |
Barry Warsaw | 41d8463 | 2000-02-10 20:26:45 +0000 | [diff] [blame] | 78 | \begin{classdesc}{NNTPReplyError}{} |
| 79 | Exception raised when an unexpected reply is received from the |
| 80 | server. For backwards compatibility, the exception \code{error_reply} |
| 81 | is equivalent to this class. |
| 82 | \end{classdesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 83 | |
Barry Warsaw | 41d8463 | 2000-02-10 20:26:45 +0000 | [diff] [blame] | 84 | \begin{classdesc}{NNTPTemporaryError}{} |
| 85 | Exception raised when an error code in the range 400--499 is |
| 86 | received. For backwards compatibility, the exception |
| 87 | \code{error_temp} is equivalent to this class. |
| 88 | \end{classdesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 89 | |
Barry Warsaw | 41d8463 | 2000-02-10 20:26:45 +0000 | [diff] [blame] | 90 | \begin{classdesc}{NNTPPermanentError}{} |
| 91 | Exception raised when an error code in the range 500--599 is |
| 92 | received. For backwards compatibility, the exception |
| 93 | \code{error_perm} is equivalent to this class. |
| 94 | \end{classdesc} |
| 95 | |
| 96 | \begin{classdesc}{NNTPProtocolError}{} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 97 | Exception raised when a reply is received from the server that does |
Barry Warsaw | 41d8463 | 2000-02-10 20:26:45 +0000 | [diff] [blame] | 98 | not begin with a digit in the range 1--5. For backwards |
| 99 | compatibility, the exception \code{error_proto} is equivalent to this |
| 100 | class. |
| 101 | \end{classdesc} |
| 102 | |
| 103 | \begin{classdesc}{NNTPDataError}{} |
| 104 | Exception raised when there is some error in the response data. For |
| 105 | backwards compatibility, the exception \code{error_data} is |
| 106 | equivalent to this class. |
| 107 | \end{classdesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 108 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 109 | |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 110 | \subsection{NNTP Objects \label{nntp-objects}} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 111 | |
| 112 | NNTP instances have the following methods. The \var{response} that is |
| 113 | returned as the first item in the return tuple of almost all methods |
| 114 | is the server's response: a string beginning with a three-digit code. |
| 115 | If the server's response indicates an error, the method raises one of |
| 116 | the above exceptions. |
| 117 | |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 118 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 119 | \begin{methoddesc}{getwelcome}{} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 120 | Return the welcome message sent by the server in reply to the initial |
| 121 | connection. (This message sometimes contains disclaimers or help |
| 122 | information that may be relevant to the user.) |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 123 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 124 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 125 | \begin{methoddesc}{set_debuglevel}{level} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 126 | Set the instance's debugging level. This controls the amount of |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 127 | debugging output printed. The default, \code{0}, produces no debugging |
| 128 | output. A value of \code{1} produces a moderate amount of debugging |
| 129 | output, generally a single line per request or response. A value of |
| 130 | \code{2} or higher produces the maximum amount of debugging output, |
| 131 | logging each line sent and received on the connection (including |
| 132 | message text). |
| 133 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 134 | |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 135 | \begin{methoddesc}{newgroups}{date, time, \optional{file}} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 136 | Send a \samp{NEWGROUPS} command. The \var{date} argument should be a |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 137 | string of the form \code{'\var{yy}\var{mm}\var{dd}'} indicating the |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 138 | date, and \var{time} should be a string of the form |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 139 | \code{'\var{hh}\var{mm}\var{ss}'} indicating the time. Return a pair |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 140 | \code{(\var{response}, \var{groups})} where \var{groups} is a list of |
| 141 | group names that are new since the given date and time. |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 142 | If the \var{file} parameter is supplied, then the output of the |
| 143 | \samp{NEWGROUPS} command is stored in a file. If \var{file} is a string, |
| 144 | then the method will open a file object with that name, write to it |
| 145 | then close it. If \var{file} is a file object, then it will start |
| 146 | calling \method{write()} on it to store the lines of the command output. |
| 147 | If \var{file} is supplied, then the returned \var{list} is an empty list. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 148 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 149 | |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 150 | \begin{methoddesc}{newnews}{group, date, time, \optional{file}} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 151 | Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 152 | \code{'*'}, and \var{date} and \var{time} have the same meaning as for |
| 153 | \method{newgroups()}. Return a pair \code{(\var{response}, |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 154 | \var{articles})} where \var{articles} is a list of article ids. |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 155 | If the \var{file} parameter is supplied, then the output of the |
| 156 | \samp{NEWNEWS} command is stored in a file. If \var{file} is a string, |
| 157 | then the method will open a file object with that name, write to it |
| 158 | then close it. If \var{file} is a file object, then it will start |
| 159 | calling \method{write()} on it to store the lines of the command output. |
| 160 | If \var{file} is supplied, then the returned \var{list} is an empty list. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 161 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 162 | |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 163 | \begin{methoddesc}{list}{\optional{file}} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 164 | Send a \samp{LIST} command. Return a pair \code{(\var{response}, |
| 165 | \var{list})} where \var{list} is a list of tuples. Each tuple has the |
| 166 | form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where |
| 167 | \var{group} is a group name, \var{last} and \var{first} are the last |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 168 | and first article numbers (as strings), and \var{flag} is |
| 169 | \code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if |
| 170 | the newsgroup is moderated. (Note the ordering: \var{last}, |
| 171 | \var{first}.) |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 172 | If the \var{file} parameter is supplied, then the output of the |
| 173 | \samp{LIST} command is stored in a file. If \var{file} is a string, |
| 174 | then the method will open a file object with that name, write to it |
| 175 | then close it. If \var{file} is a file object, then it will start |
| 176 | calling \method{write()} on it to store the lines of the command output. |
| 177 | If \var{file} is supplied, then the returned \var{list} is an empty list. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 178 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 179 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 180 | \begin{methoddesc}{group}{name} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 181 | Send a \samp{GROUP} command, where \var{name} is the group name. |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 182 | Return a tuple \code{(\var{response}, \var{count}, \var{first}, |
| 183 | \var{last}, \var{name})} where \var{count} is the (estimated) number |
| 184 | of articles in the group, \var{first} is the first article number in |
| 185 | the group, \var{last} is the last article number in the group, and |
| 186 | \var{name} is the group name. The numbers are returned as strings. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 187 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 188 | |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 189 | \begin{methoddesc}{help}{\optional{file}} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 190 | Send a \samp{HELP} command. Return a pair \code{(\var{response}, |
| 191 | \var{list})} where \var{list} is a list of help strings. |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 192 | If the \var{file} parameter is supplied, then the output of the |
| 193 | \samp{HELP} command is stored in a file. If \var{file} is a string, |
| 194 | then the method will open a file object with that name, write to it |
| 195 | then close it. If \var{file} is a file object, then it will start |
| 196 | calling \method{write()} on it to store the lines of the command output. |
| 197 | If \var{file} is supplied, then the returned \var{list} is an empty list. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 198 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 199 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 200 | \begin{methoddesc}{stat}{id} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 201 | Send a \samp{STAT} command, where \var{id} is the message id (enclosed |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 202 | in \character{<} and \character{>}) or an article number (as a string). |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 203 | Return a triple \code{(\var{response}, \var{number}, \var{id})} where |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 204 | \var{number} is the article number (as a string) and \var{id} is the |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 205 | article id (enclosed in \character{<} and \character{>}). |
| 206 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 207 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 208 | \begin{methoddesc}{next}{} |
| 209 | Send a \samp{NEXT} command. Return as for \method{stat()}. |
| 210 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 211 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 212 | \begin{methoddesc}{last}{} |
| 213 | Send a \samp{LAST} command. Return as for \method{stat()}. |
| 214 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 215 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 216 | \begin{methoddesc}{head}{id} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 217 | Send a \samp{HEAD} command, where \var{id} has the same meaning as for |
Guido van Rossum | cd90509 | 1998-06-30 14:53:41 +0000 | [diff] [blame] | 218 | \method{stat()}. Return a tuple |
| 219 | \code{(\var{response}, \var{number}, \var{id}, \var{list})} |
| 220 | where the first three are the same as for \method{stat()}, |
| 221 | and \var{list} is a list of the article's headers (an uninterpreted |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 222 | list of lines, without trailing newlines). |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 223 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 224 | |
Fredrik Lundh | a5e6165 | 2001-10-18 20:58:25 +0000 | [diff] [blame] | 225 | \begin{methoddesc}{body}{id,\optional{file}} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 226 | Send a \samp{BODY} command, where \var{id} has the same meaning as for |
Fredrik Lundh | a5e6165 | 2001-10-18 20:58:25 +0000 | [diff] [blame] | 227 | \method{stat()}. If the \var{file} parameter is supplied, then |
| 228 | the body is stored in a file. If \var{file} is a string, then |
Guido van Rossum | e7877df | 2001-10-01 13:50:15 +0000 | [diff] [blame] | 229 | the method will open a file object with that name, write to it then close it. |
Fredrik Lundh | a5e6165 | 2001-10-18 20:58:25 +0000 | [diff] [blame] | 230 | If \var{file} is a file object, then it will start calling |
Guido van Rossum | e7877df | 2001-10-01 13:50:15 +0000 | [diff] [blame] | 231 | \method{write()} on it to store the lines of the body. |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 232 | Return as for \method{head()}. If \var{file} is supplied, then |
Guido van Rossum | e7877df | 2001-10-01 13:50:15 +0000 | [diff] [blame] | 233 | the returned \var{list} is an empty list. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 234 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 235 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 236 | \begin{methoddesc}{article}{id} |
Fred Drake | 506a7a8 | 2000-07-01 17:43:19 +0000 | [diff] [blame] | 237 | Send an \samp{ARTICLE} command, where \var{id} has the same meaning as |
Guido van Rossum | cd90509 | 1998-06-30 14:53:41 +0000 | [diff] [blame] | 238 | for \method{stat()}. Return as for \method{head()}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 239 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 240 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 241 | \begin{methoddesc}{slave}{} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 242 | Send a \samp{SLAVE} command. Return the server's \var{response}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 243 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 244 | |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 245 | \begin{methoddesc}{xhdr}{header, string, \optional{file}} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 246 | Send an \samp{XHDR} command. This command is not defined in the RFC |
| 247 | but is a common extension. The \var{header} argument is a header |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 248 | keyword, e.g. \code{'subject'}. The \var{string} argument should have |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 249 | the form \code{'\var{first}-\var{last}'} where \var{first} and |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 250 | \var{last} are the first and last article numbers to search. Return a |
| 251 | pair \code{(\var{response}, \var{list})}, where \var{list} is a list of |
| 252 | pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id |
| 253 | (as a string) and \var{text} is the text of the requested header for |
| 254 | that article. |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 255 | If the \var{file} parameter is supplied, then the output of the |
| 256 | \samp{XHDR} command is stored in a file. If \var{file} is a string, |
| 257 | then the method will open a file object with that name, write to it |
| 258 | then close it. If \var{file} is a file object, then it will start |
| 259 | calling \method{write()} on it to store the lines of the command output. |
| 260 | If \var{file} is supplied, then the returned \var{list} is an empty list. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 261 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 262 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 263 | \begin{methoddesc}{post}{file} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 264 | Post an article using the \samp{POST} command. The \var{file} |
| 265 | argument is an open file object which is read until EOF using its |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 266 | \method{readline()} method. It should be a well-formed news article, |
| 267 | including the required headers. The \method{post()} method |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 268 | automatically escapes lines beginning with \samp{.}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 269 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 270 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 271 | \begin{methoddesc}{ihave}{id, file} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 272 | Send an \samp{IHAVE} command. If the response is not an error, treat |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 273 | \var{file} exactly as for the \method{post()} method. |
| 274 | \end{methoddesc} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 275 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 276 | \begin{methoddesc}{date}{} |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 277 | Return a triple \code{(\var{response}, \var{date}, \var{time})}, |
| 278 | containing the current date and time in a form suitable for the |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 279 | \method{newnews()} and \method{newgroups()} methods. |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 280 | This is an optional NNTP extension, and may not be supported by all |
| 281 | servers. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 282 | \end{methoddesc} |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 283 | |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 284 | \begin{methoddesc}{xgtitle}{name, \optional{file}} |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 285 | Process an \samp{XGTITLE} command, returning a pair \code{(\var{response}, |
Fred Drake | fac431e | 1998-02-16 21:57:37 +0000 | [diff] [blame] | 286 | \var{list})}, where \var{list} is a list of tuples containing |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 287 | \code{(\var{name}, \var{title})}. |
| 288 | % XXX huh? Should that be name, description? |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 289 | If the \var{file} parameter is supplied, then the output of the |
| 290 | \samp{XGTITLE} command is stored in a file. If \var{file} is a string, |
| 291 | then the method will open a file object with that name, write to it |
| 292 | then close it. If \var{file} is a file object, then it will start |
| 293 | calling \method{write()} on it to store the lines of the command output. |
| 294 | If \var{file} is supplied, then the returned \var{list} is an empty list. |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 295 | This is an optional NNTP extension, and may not be supported by all |
| 296 | servers. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 297 | \end{methoddesc} |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 298 | |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 299 | \begin{methoddesc}{xover}{start, end, \optional{file}} |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 300 | Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list |
| 301 | of tuples, one for each article in the range delimited by the \var{start} |
| 302 | and \var{end} article numbers. Each tuple is of the form |
Fred Drake | dd6c6d9 | 1999-04-22 16:45:26 +0000 | [diff] [blame] | 303 | \code{(\var{article number}, \var{subject}, \var{poster}, \var{date}, |
| 304 | \var{id}, \var{references}, \var{size}, \var{lines})}. |
Guido van Rossum | a268540 | 2003-04-19 18:04:57 +0000 | [diff] [blame^] | 305 | If the \var{file} parameter is supplied, then the output of the |
| 306 | \samp{XOVER} command is stored in a file. If \var{file} is a string, |
| 307 | then the method will open a file object with that name, write to it |
| 308 | then close it. If \var{file} is a file object, then it will start |
| 309 | calling \method{write()} on it to store the lines of the command output. |
| 310 | If \var{file} is supplied, then the returned \var{list} is an empty list. |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 311 | This is an optional NNTP extension, and may not be supported by all |
| 312 | servers. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 313 | \end{methoddesc} |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 314 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 315 | \begin{methoddesc}{xpath}{id} |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 316 | Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the |
| 317 | directory path to the article with message ID \var{id}. This is an |
| 318 | optional NNTP extension, and may not be supported by all servers. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 319 | \end{methoddesc} |
Guido van Rossum | 94adab5 | 1997-06-02 17:27:50 +0000 | [diff] [blame] | 320 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 321 | \begin{methoddesc}{quit}{} |
Guido van Rossum | 1b91cda | 1995-03-24 15:56:02 +0000 | [diff] [blame] | 322 | Send a \samp{QUIT} command and close the connection. Once this method |
| 323 | has been called, no other methods of the NNTP object should be called. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 324 | \end{methoddesc} |