1 2:mod:`nntplib` --- NNTP protocol client 3======================================= 4 5.. module:: nntplib 6 :synopsis: NNTP protocol client (requires sockets). 7 8 9.. index:: 10 pair: NNTP; protocol 11 single: Network News Transfer Protocol 12 13**Source code:** :source:`Lib/nntplib.py` 14 15-------------- 16 17This module defines the class :class:`NNTP` which implements the client side of 18the NNTP protocol. It can be used to implement a news reader or poster, or 19automated news processors. For more information on NNTP (Network News Transfer 20Protocol), see Internet :rfc:`977`. 21 22Here are two small examples of how it can be used. To list some statistics 23about a newsgroup and print the subjects of the last 10 articles:: 24 25 >>> s = NNTP('news.gmane.org') 26 >>> resp, count, first, last, name = s.group('gmane.comp.python.committers') 27 >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last 28 Group gmane.comp.python.committers has 1071 articles, range 1 to 1071 29 >>> resp, subs = s.xhdr('subject', first + '-' + last) 30 >>> for id, sub in subs[-10:]: print id, sub 31 ... 32 1062 Re: Mercurial Status? 33 1063 Re: [python-committers] (Windows) buildbots on 3.x 34 1064 Re: Mercurial Status? 35 1065 Re: Mercurial Status? 36 1066 Python 2.6.6 status 37 1067 Commit Privileges for Ask Solem 38 1068 Re: Commit Privileges for Ask Solem 39 1069 Re: Commit Privileges for Ask Solem 40 1070 Re: Commit Privileges for Ask Solem 41 1071 2.6.6 rc 2 42 >>> s.quit() 43 '205 Bye!' 44 45To post an article from a file (this assumes that the article has valid 46headers, and that you have right to post on the particular newsgroup):: 47 48 >>> s = NNTP('news.gmane.org') 49 >>> f = open('articlefile') 50 >>> s.post(f) 51 '240 Article posted successfully.' 52 >>> s.quit() 53 '205 Bye!' 54 55The module itself defines the following items: 56 57 58.. class:: NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]]) 59 60 Return a new instance of the :class:`NNTP` class, representing a connection 61 to the NNTP server running on host *host*, listening at port *port*. The 62 default *port* is 119. If the optional *user* and *password* are provided, 63 or if suitable credentials are present in :file:`/.netrc` and the optional 64 flag *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO 65 PASS`` commands are used to identify and authenticate the user to the server. 66 If the optional flag *readermode* is true, then a ``mode reader`` command is 67 sent before authentication is performed. Reader mode is sometimes necessary 68 if you are connecting to an NNTP server on the local machine and intend to 69 call reader-specific commands, such as ``group``. If you get unexpected 70 :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. 71 *readermode* defaults to ``None``. *usenetrc* defaults to ``True``. 72 73 .. versionchanged:: 2.4 74 *usenetrc* argument added. 75 76 77.. exception:: NNTPError 78 79 Derived from the standard exception :exc:`Exception`, this is the base class for 80 all exceptions raised by the :mod:`nntplib` module. 81 82 83.. exception:: NNTPReplyError 84 85 Exception raised when an unexpected reply is received from the server. For 86 backwards compatibility, the exception ``error_reply`` is equivalent to this 87 class. 88 89 90.. exception:: NNTPTemporaryError 91 92 Exception raised when an error code in the range 400--499 is received. For 93 backwards compatibility, the exception ``error_temp`` is equivalent to this 94 class. 95 96 97.. exception:: NNTPPermanentError 98 99 Exception raised when an error code in the range 500--599 is received. For 100 backwards compatibility, the exception ``error_perm`` is equivalent to this 101 class. 102 103 104.. exception:: NNTPProtocolError 105 106 Exception raised when a reply is received from the server that does not begin 107 with a digit in the range 1--5. For backwards compatibility, the exception 108 ``error_proto`` is equivalent to this class. 109 110 111.. exception:: NNTPDataError 112 113 Exception raised when there is some error in the response data. For backwards 114 compatibility, the exception ``error_data`` is equivalent to this class. 115 116 117.. _nntp-objects: 118 119NNTP Objects 120------------ 121 122NNTP instances have the following methods. The *response* that is returned as 123the first item in the return tuple of almost all methods is the server's 124response: a string beginning with a three-digit code. If the server's response 125indicates an error, the method raises one of the above exceptions. 126 127 128.. method:: NNTP.getwelcome() 129 130 Return the welcome message sent by the server in reply to the initial 131 connection. (This message sometimes contains disclaimers or help information 132 that may be relevant to the user.) 133 134 135.. method:: NNTP.set_debuglevel(level) 136 137 Set the instance's debugging level. This controls the amount of debugging 138 output printed. The default, ``0``, produces no debugging output. A value of 139 ``1`` produces a moderate amount of debugging output, generally a single line 140 per request or response. A value of ``2`` or higher produces the maximum amount 141 of debugging output, logging each line sent and received on the connection 142 (including message text). 143 144 145.. method:: NNTP.newgroups(date, time, [file]) 146 147 Send a ``NEWGROUPS`` command. The *date* argument should be a string of the 148 form ``'yymmdd'`` indicating the date, and *time* should be a string of the form 149 ``'hhmmss'`` indicating the time. Return a pair ``(response, groups)`` where 150 *groups* is a list of group names that are new since the given date and time. If 151 the *file* parameter is supplied, then the output of the ``NEWGROUPS`` command 152 is stored in a file. If *file* is a string, then the method will open a file 153 object with that name, write to it then close it. If *file* is a file object, 154 then it will start calling :meth:`write` on it to store the lines of the command 155 output. If *file* is supplied, then the returned *list* is an empty list. 156 157 158.. method:: NNTP.newnews(group, date, time, [file]) 159 160 Send a ``NEWNEWS`` command. Here, *group* is a group name or ``'*'``, and 161 *date* and *time* have the same meaning as for :meth:`newgroups`. Return a pair 162 ``(response, articles)`` where *articles* is a list of message ids. If the 163 *file* parameter is supplied, then the output of the ``NEWNEWS`` command is 164 stored in a file. If *file* is a string, then the method will open a file 165 object with that name, write to it then close it. If *file* is a file object, 166 then it will start calling :meth:`write` on it to store the lines of the command 167 output. If *file* is supplied, then the returned *list* is an empty list. 168 169 170.. method:: NNTP.list([file]) 171 172 Send a ``LIST`` command. Return a pair ``(response, list)`` where *list* is a 173 list of tuples. Each tuple has the form ``(group, last, first, flag)``, where 174 *group* is a group name, *last* and *first* are the last and first article 175 numbers (as strings), and *flag* is ``'y'`` if posting is allowed, ``'n'`` if 176 not, and ``'m'`` if the newsgroup is moderated. (Note the ordering: *last*, 177 *first*.) If the *file* parameter is supplied, then the output of the ``LIST`` 178 command is stored in a file. If *file* is a string, then the method will open 179 a file object with that name, write to it then close it. If *file* is a file 180 object, then it will start calling :meth:`write` on it to store the lines of the 181 command output. If *file* is supplied, then the returned *list* is an empty 182 list. 183 184 185.. method:: NNTP.descriptions(grouppattern) 186 187 Send a ``LIST NEWSGROUPS`` command, where *grouppattern* is a wildmat string as 188 specified in RFC2980 (it's essentially the same as DOS or UNIX shell wildcard 189 strings). Return a pair ``(response, list)``, where *list* is a list of tuples 190 containing ``(name, title)``. 191 192 .. versionadded:: 2.4 193 194 195.. method:: NNTP.description(group) 196 197 Get a description for a single group *group*. If more than one group matches 198 (if 'group' is a real wildmat string), return the first match. If no group 199 matches, return an empty string. 200 201 This elides the response code from the server. If the response code is needed, 202 use :meth:`descriptions`. 203 204 .. versionadded:: 2.4 205 206 207.. method:: NNTP.group(name) 208 209 Send a ``GROUP`` command, where *name* is the group name. Return a tuple 210 ``(response, count, first, last, name)`` where *count* is the (estimated) number 211 of articles in the group, *first* is the first article number in the group, 212 *last* is the last article number in the group, and *name* is the group name. 213 The numbers are returned as strings. 214 215 216.. method:: NNTP.help([file]) 217 218 Send a ``HELP`` command. Return a pair ``(response, list)`` where *list* is a 219 list of help strings. If the *file* parameter is supplied, then the output of 220 the ``HELP`` command is stored in a file. If *file* is a string, then the 221 method will open a file object with that name, write to it then close it. If 222 *file* is a file object, then it will start calling :meth:`write` on it to store 223 the lines of the command output. If *file* is supplied, then the returned *list* 224 is an empty list. 225 226 227.. method:: NNTP.stat(id) 228 229 Send a ``STAT`` command, where *id* is the message id (enclosed in ``'<'`` and 230 ``'>'``) or an article number (as a string). Return a triple ``(response, 231 number, id)`` where *number* is the article number (as a string) and *id* is the 232 message id (enclosed in ``'<'`` and ``'>'``). 233 234 235.. method:: NNTP.next() 236 237 Send a ``NEXT`` command. Return as for :meth:`.stat`. 238 239 240.. method:: NNTP.last() 241 242 Send a ``LAST`` command. Return as for :meth:`.stat`. 243 244 245.. method:: NNTP.head(id) 246 247 Send a ``HEAD`` command, where *id* has the same meaning as for :meth:`.stat`. 248 Return a tuple ``(response, number, id, list)`` where the first three are the 249 same as for :meth:`.stat`, and *list* is a list of the article's headers (an 250 uninterpreted list of lines, without trailing newlines). 251 252 253.. method:: NNTP.body(id,[file]) 254 255 Send a ``BODY`` command, where *id* has the same meaning as for :meth:`.stat`. 256 If the *file* parameter is supplied, then the body is stored in a file. If 257 *file* is a string, then the method will open a file object with that name, 258 write to it then close it. If *file* is a file object, then it will start 259 calling :meth:`write` on it to store the lines of the body. Return as for 260 :meth:`head`. If *file* is supplied, then the returned *list* is an empty list. 261 262 263.. method:: NNTP.article(id) 264 265 Send an ``ARTICLE`` command, where *id* has the same meaning as for 266 :meth:`.stat`. Return as for :meth:`head`. 267 268 269.. method:: NNTP.slave() 270 271 Send a ``SLAVE`` command. Return the server's *response*. 272 273 274.. method:: NNTP.xhdr(header, string, [file]) 275 276 Send an ``XHDR`` command. This command is not defined in the RFC but is a 277 common extension. The *header* argument is a header keyword, e.g. 278 ``'subject'``. The *string* argument should have the form ``'first-last'`` 279 where *first* and *last* are the first and last article numbers to search. 280 Return a pair ``(response, list)``, where *list* is a list of pairs ``(id, 281 text)``, where *id* is an article number (as a string) and *text* is the text of 282 the requested header for that article. If the *file* parameter is supplied, then 283 the output of the ``XHDR`` command is stored in a file. If *file* is a string, 284 then the method will open a file object with that name, write to it then close 285 it. If *file* is a file object, then it will start calling :meth:`write` on it 286 to store the lines of the command output. If *file* is supplied, then the 287 returned *list* is an empty list. 288 289 290.. method:: NNTP.post(file) 291 292 Post an article using the ``POST`` command. The *file* argument is an open file 293 object which is read until EOF using its :meth:`~file.readline` method. It should be 294 a well-formed news article, including the required headers. The :meth:`post` 295 method automatically escapes lines beginning with ``.``. 296 297 298.. method:: NNTP.ihave(id, file) 299 300 Send an ``IHAVE`` command. *id* is a message id (enclosed in ``'<'`` and 301 ``'>'``). If the response is not an error, treat *file* exactly as for the 302 :meth:`post` method. 303 304 305.. method:: NNTP.date() 306 307 Return a triple ``(response, date, time)``, containing the current date and time 308 in a form suitable for the :meth:`newnews` and :meth:`newgroups` methods. This 309 is an optional NNTP extension, and may not be supported by all servers. 310 311 312.. method:: NNTP.xgtitle(name, [file]) 313 314 Process an ``XGTITLE`` command, returning a pair ``(response, list)``, where 315 *list* is a list of tuples containing ``(name, title)``. If the *file* parameter 316 is supplied, then the output of the ``XGTITLE`` command is stored in a file. 317 If *file* is a string, then the method will open a file object with that name, 318 write to it then close it. If *file* is a file object, then it will start 319 calling :meth:`write` on it to store the lines of the command output. If *file* 320 is supplied, then the returned *list* is an empty list. This is an optional NNTP 321 extension, and may not be supported by all servers. 322 323 RFC2980 says "It is suggested that this extension be deprecated". Use 324 :meth:`descriptions` or :meth:`description` instead. 325 326 327.. method:: NNTP.xover(start, end, [file]) 328 329 Return a pair ``(resp, list)``. *list* is a list of tuples, one for each 330 article in the range delimited by the *start* and *end* article numbers. Each 331 tuple is of the form ``(article number, subject, poster, date, id, references, 332 size, lines)``. If the *file* parameter is supplied, then the output of the 333 ``XOVER`` command is stored in a file. If *file* is a string, then the method 334 will open a file object with that name, write to it then close it. If *file* 335 is a file object, then it will start calling :meth:`write` on it to store the 336 lines of the command output. If *file* is supplied, then the returned *list* is 337 an empty list. This is an optional NNTP extension, and may not be supported by 338 all servers. 339 340 341.. method:: NNTP.xpath(id) 342 343 Return a pair ``(resp, path)``, where *path* is the directory path to the 344 article with message ID *id*. This is an optional NNTP extension, and may not 345 be supported by all servers. 346 347 348.. method:: NNTP.quit() 349 350 Send a ``QUIT`` command and close the connection. Once this method has been 351 called, no other methods of the NNTP object should be called. 352 353