Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 13 | **Source code:** :source:`Lib/nntplib.py` |
| 14 | |
| 15 | -------------- |
| 16 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | This module defines the class :class:`NNTP` which implements the client side of |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 18 | the Network News Transfer Protocol. It can be used to implement a news reader |
| 19 | or poster, or automated news processors. It is compatible with :rfc:`3977` |
| 20 | as well as the older :rfc:`977` and :rfc:`2980`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | |
| 22 | Here are two small examples of how it can be used. To list some statistics |
| 23 | about a newsgroup and print the subjects of the last 10 articles:: |
| 24 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 25 | >>> s = nntplib.NNTP('news.gmane.org') |
Antoine Pitrou | e339651 | 2010-09-07 18:44:12 +0000 | [diff] [blame] | 26 | >>> resp, count, first, last, name = s.group('gmane.comp.python.committers') |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 27 | >>> print('Group', name, 'has', count, 'articles, range', first, 'to', last) |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 28 | Group gmane.comp.python.committers has 1096 articles, range 1 to 1096 |
| 29 | >>> resp, overviews = s.over((last - 9, last)) |
| 30 | >>> for id, over in overviews: |
| 31 | ... print(id, nntplib.decode_header(over['subject'])) |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 32 | ... |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 33 | 1087 Re: Commit privileges for Łukasz Langa |
| 34 | 1088 Re: 3.2 alpha 2 freeze |
| 35 | 1089 Re: 3.2 alpha 2 freeze |
| 36 | 1090 Re: Commit privileges for Łukasz Langa |
| 37 | 1091 Re: Commit privileges for Łukasz Langa |
| 38 | 1092 Updated ssh key |
| 39 | 1093 Re: Updated ssh key |
| 40 | 1094 Re: Updated ssh key |
| 41 | 1095 Hello fellow committers! |
| 42 | 1096 Re: Hello fellow committers! |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | >>> s.quit() |
Antoine Pitrou | e339651 | 2010-09-07 18:44:12 +0000 | [diff] [blame] | 44 | '205 Bye!' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 46 | To post an article from a binary file (this assumes that the article has valid |
Antoine Pitrou | e339651 | 2010-09-07 18:44:12 +0000 | [diff] [blame] | 47 | headers, and that you have right to post on the particular newsgroup):: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 49 | >>> s = nntplib.NNTP('news.gmane.org') |
| 50 | >>> f = open('/tmp/article.txt', 'rb') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | >>> s.post(f) |
| 52 | '240 Article posted successfully.' |
| 53 | >>> s.quit() |
Antoine Pitrou | e339651 | 2010-09-07 18:44:12 +0000 | [diff] [blame] | 54 | '205 Bye!' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 56 | The module itself defines the following classes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | |
Antoine Pitrou | 859c4ef | 2010-11-09 18:58:42 +0000 | [diff] [blame] | 59 | .. class:: NNTP(host, port=119, user=None, password=None, readermode=None, usenetrc=False, [timeout]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
Antoine Pitrou | a078115 | 2010-11-05 19:16:37 +0000 | [diff] [blame] | 61 | Return a new :class:`NNTP` object, representing a connection |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 62 | to the NNTP server running on host *host*, listening at port *port*. |
| 63 | An optional *timeout* can be specified for the socket connection. |
| 64 | If the optional *user* and *password* are provided, or if suitable |
| 65 | credentials are present in :file:`/.netrc` and the optional flag *usenetrc* |
Antoine Pitrou | 859c4ef | 2010-11-09 18:58:42 +0000 | [diff] [blame] | 66 | is true, the ``AUTHINFO USER`` and ``AUTHINFO PASS`` commands are used |
| 67 | to identify and authenticate the user to the server. If the optional |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 68 | flag *readermode* is true, then a ``mode reader`` command is sent before |
| 69 | authentication is performed. Reader mode is sometimes necessary if you are |
| 70 | connecting to an NNTP server on the local machine and intend to call |
| 71 | reader-specific commands, such as ``group``. If you get unexpected |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. |
Giampaolo Rodolà | 424298a | 2011-03-03 18:34:06 +0000 | [diff] [blame] | 73 | :class:`NNTP` class supports the :keyword:`with` statement to |
| 74 | unconditionally consume :exc:`socket.error` exceptions and to close the NNTP |
| 75 | connection when done. Here is a sample on how using it: |
| 76 | |
| 77 | >>> from nntplib import NNTP |
Ezio Melotti | 04f648c | 2011-07-26 09:37:46 +0300 | [diff] [blame] | 78 | >>> with NNTP('news.gmane.org') as n: |
Giampaolo Rodolà | 424298a | 2011-03-03 18:34:06 +0000 | [diff] [blame] | 79 | ... n.group('gmane.comp.python.committers') |
| 80 | ... |
Ezio Melotti | 04f648c | 2011-07-26 09:37:46 +0300 | [diff] [blame] | 81 | ('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers') |
Giampaolo Rodolà | 424298a | 2011-03-03 18:34:06 +0000 | [diff] [blame] | 82 | >>> |
| 83 | |
Antoine Pitrou | 859c4ef | 2010-11-09 18:58:42 +0000 | [diff] [blame] | 84 | |
| 85 | .. versionchanged:: 3.2 |
| 86 | *usenetrc* is now False by default. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
Giampaolo Rodolà | 424298a | 2011-03-03 18:34:06 +0000 | [diff] [blame] | 88 | .. versionchanged:: 3.3 |
| 89 | Support for the :keyword:`with` statement was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
Antoine Pitrou | 859c4ef | 2010-11-09 18:58:42 +0000 | [diff] [blame] | 91 | .. class:: NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False, [timeout]) |
Antoine Pitrou | 1cb121e | 2010-11-09 18:54:37 +0000 | [diff] [blame] | 92 | |
| 93 | Return a new :class:`NNTP_SSL` object, representing an encrypted |
| 94 | connection to the NNTP server running on host *host*, listening at |
| 95 | port *port*. :class:`NNTP_SSL` objects have the same methods as |
| 96 | :class:`NNTP` objects. If *port* is omitted, port 563 (NNTPS) is used. |
| 97 | *ssl_context* is also optional, and is a :class:`~ssl.SSLContext` object. |
| 98 | All other parameters behave the same as for :class:`NNTP`. |
| 99 | |
| 100 | Note that SSL-on-563 is discouraged per :rfc:`4642`, in favor of |
| 101 | STARTTLS as described below. However, some servers only support the |
| 102 | former. |
| 103 | |
| 104 | .. versionadded:: 3.2 |
| 105 | |
| 106 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | .. exception:: NNTPError |
| 108 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 109 | Derived from the standard exception :exc:`Exception`, this is the base |
| 110 | class for all exceptions raised by the :mod:`nntplib` module. Instances |
| 111 | of this class have the following attribute: |
| 112 | |
| 113 | .. attribute:: response |
| 114 | |
| 115 | The response of the server if available, as a :class:`str` object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | |
| 118 | .. exception:: NNTPReplyError |
| 119 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 120 | Exception raised when an unexpected reply is received from the server. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
| 122 | |
| 123 | .. exception:: NNTPTemporaryError |
| 124 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 125 | Exception raised when a response code in the range 400--499 is received. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | |
| 128 | .. exception:: NNTPPermanentError |
| 129 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 130 | Exception raised when a response code in the range 500--599 is received. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
| 132 | |
| 133 | .. exception:: NNTPProtocolError |
| 134 | |
| 135 | Exception raised when a reply is received from the server that does not begin |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 136 | with a digit in the range 1--5. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 137 | |
| 138 | |
| 139 | .. exception:: NNTPDataError |
| 140 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 141 | Exception raised when there is some error in the response data. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | |
| 144 | .. _nntp-objects: |
| 145 | |
| 146 | NNTP Objects |
| 147 | ------------ |
| 148 | |
Antoine Pitrou | 1cb121e | 2010-11-09 18:54:37 +0000 | [diff] [blame] | 149 | When connected, :class:`NNTP` and :class:`NNTP_SSL` objects support the |
| 150 | following methods and attributes. |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 151 | |
Antoine Pitrou | a078115 | 2010-11-05 19:16:37 +0000 | [diff] [blame] | 152 | Attributes |
| 153 | ^^^^^^^^^^ |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 154 | |
Antoine Pitrou | a078115 | 2010-11-05 19:16:37 +0000 | [diff] [blame] | 155 | .. attribute:: NNTP.nntp_version |
| 156 | |
| 157 | An integer representing the version of the NNTP protocol supported by the |
| 158 | server. In practice, this should be ``2`` for servers advertising |
| 159 | :rfc:`3977` compliance and ``1`` for others. |
| 160 | |
| 161 | .. versionadded:: 3.2 |
| 162 | |
| 163 | .. attribute:: NNTP.nntp_implementation |
| 164 | |
| 165 | A string describing the software name and version of the NNTP server, |
| 166 | or :const:`None` if not advertised by the server. |
| 167 | |
| 168 | .. versionadded:: 3.2 |
| 169 | |
| 170 | Methods |
| 171 | ^^^^^^^ |
| 172 | |
| 173 | The *response* that is returned as the first item in the return tuple of almost |
| 174 | all methods is the server's response: a string beginning with a three-digit |
| 175 | code. If the server's response indicates an error, the method raises one of |
| 176 | the above exceptions. |
| 177 | |
| 178 | Many of the following methods take an optional keyword-only argument *file*. |
| 179 | When the *file* argument is supplied, it must be either a :term:`file object` |
| 180 | opened for binary writing, or the name of an on-disk file to be written to. |
| 181 | The method will then write any data returned by the server (except for the |
| 182 | response line and the terminating dot) to the file; any list of lines, |
| 183 | tuples or objects that the method normally returns will be empty. |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 184 | |
| 185 | .. versionchanged:: 3.2 |
| 186 | Many of the following methods have been reworked and fixed, which makes |
| 187 | them incompatible with their 3.1 counterparts. |
| 188 | |
| 189 | |
| 190 | .. method:: NNTP.quit() |
| 191 | |
| 192 | Send a ``QUIT`` command and close the connection. Once this method has been |
| 193 | called, no other methods of the NNTP object should be called. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | |
| 195 | |
| 196 | .. method:: NNTP.getwelcome() |
| 197 | |
| 198 | Return the welcome message sent by the server in reply to the initial |
| 199 | connection. (This message sometimes contains disclaimers or help information |
| 200 | that may be relevant to the user.) |
| 201 | |
| 202 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 203 | .. method:: NNTP.getcapabilities() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 204 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 205 | Return the :rfc:`3977` capabilities advertised by the server, as a |
| 206 | :class:`dict` instance mapping capability names to (possibly empty) lists |
| 207 | of values. On legacy servers which don't understand the ``CAPABILITIES`` |
| 208 | command, an empty dictionary is returned instead. |
| 209 | |
| 210 | >>> s = NNTP('news.gmane.org') |
| 211 | >>> 'POST' in s.getcapabilities() |
| 212 | True |
| 213 | |
| 214 | .. versionadded:: 3.2 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | |
| 216 | |
Antoine Pitrou | 1cb121e | 2010-11-09 18:54:37 +0000 | [diff] [blame] | 217 | .. method:: NNTP.login(user=None, password=None, usenetrc=True) |
| 218 | |
| 219 | Send ``AUTHINFO`` commands with the user name and password. If *user* |
| 220 | and *password* are None and *usenetrc* is True, credentials from |
| 221 | ``~/.netrc`` will be used if possible. |
| 222 | |
| 223 | Unless intentionally delayed, login is normally performed during the |
| 224 | :class:`NNTP` object initialization and separately calling this function |
| 225 | is unnecessary. To force authentication to be delayed, you must not set |
| 226 | *user* or *password* when creating the object, and must set *usenetrc* to |
| 227 | False. |
| 228 | |
| 229 | .. versionadded:: 3.2 |
| 230 | |
| 231 | |
| 232 | .. method:: NNTP.starttls(ssl_context=None) |
| 233 | |
| 234 | Send a ``STARTTLS`` command. The *ssl_context* argument is optional |
| 235 | and should be a :class:`ssl.SSLContext` object. This will enable |
| 236 | encryption on the NNTP connection. |
| 237 | |
| 238 | Note that this may not be done after authentication information has |
| 239 | been transmitted, and authentication occurs by default if possible during a |
| 240 | :class:`NNTP` object initialization. See :meth:`NNTP.login` for information |
| 241 | on suppressing this behavior. |
| 242 | |
| 243 | .. versionadded:: 3.2 |
| 244 | |
| 245 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 246 | .. method:: NNTP.newgroups(date, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 248 | Send a ``NEWGROUPS`` command. The *date* argument should be a |
| 249 | :class:`datetime.date` or :class:`datetime.datetime` object. |
| 250 | Return a pair ``(response, groups)`` where *groups* is a list representing |
| 251 | the groups that are new since the given *date*. If *file* is supplied, |
| 252 | though, then *groups* will be empty. |
| 253 | |
| 254 | >>> from datetime import date, timedelta |
| 255 | >>> resp, groups = s.newgroups(date.today() - timedelta(days=3)) |
| 256 | >>> len(groups) |
| 257 | 85 |
| 258 | >>> groups[0] |
| 259 | GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 260 | |
| 261 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 262 | .. method:: NNTP.newnews(group, date, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | |
| 264 | Send a ``NEWNEWS`` command. Here, *group* is a group name or ``'*'``, and |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 265 | *date* has the same meaning as for :meth:`newgroups`. Return a pair |
| 266 | ``(response, articles)`` where *articles* is a list of message ids. |
| 267 | |
| 268 | This command is frequently disabled by NNTP server administrators. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 269 | |
| 270 | |
Antoine Pitrou | 08eeada | 2010-11-04 21:36:15 +0000 | [diff] [blame] | 271 | .. method:: NNTP.list(group_pattern=None, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 272 | |
Antoine Pitrou | 08eeada | 2010-11-04 21:36:15 +0000 | [diff] [blame] | 273 | Send a ``LIST`` or ``LIST ACTIVE`` command. Return a pair |
| 274 | ``(response, list)`` where *list* is a list of tuples representing all |
| 275 | the groups available from this NNTP server, optionally matching the |
| 276 | pattern string *group_pattern*. Each tuple has the form |
| 277 | ``(group, last, first, flag)``, where *group* is a group name, *last* |
| 278 | and *first* are the last and first article numbers, and *flag* usually |
| 279 | takes one of these values: |
Antoine Pitrou | 7dd1af0 | 2010-11-03 18:32:54 +0000 | [diff] [blame] | 280 | |
| 281 | * ``y``: Local postings and articles from peers are allowed. |
| 282 | * ``m``: The group is moderated and all postings must be approved. |
| 283 | * ``n``: No local postings are allowed, only articles from peers. |
| 284 | * ``j``: Articles from peers are filed in the junk group instead. |
| 285 | * ``x``: No local postings, and articles from peers are ignored. |
| 286 | * ``=foo.bar``: Articles are filed in the ``foo.bar`` group instead. |
| 287 | |
| 288 | If *flag* has another value, then the status of the newsgroup should be |
| 289 | considered unknown. |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 290 | |
Antoine Pitrou | 08eeada | 2010-11-04 21:36:15 +0000 | [diff] [blame] | 291 | This command can return very large results, especially if *group_pattern* |
| 292 | is not specified. It is best to cache the results offline unless you |
| 293 | really need to refresh them. |
| 294 | |
| 295 | .. versionchanged:: 3.2 |
| 296 | *group_pattern* was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 297 | |
| 298 | |
| 299 | .. method:: NNTP.descriptions(grouppattern) |
| 300 | |
| 301 | Send a ``LIST NEWSGROUPS`` command, where *grouppattern* is a wildmat string as |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 302 | specified in :rfc:`3977` (it's essentially the same as DOS or UNIX shell wildcard |
| 303 | strings). Return a pair ``(response, descriptions)``, where *descriptions* |
| 304 | is a dictionary mapping group names to textual descriptions. |
| 305 | |
| 306 | >>> resp, descs = s.descriptions('gmane.comp.python.*') |
| 307 | >>> len(descs) |
| 308 | 295 |
| 309 | >>> descs.popitem() |
| 310 | ('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 311 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 312 | |
| 313 | .. method:: NNTP.description(group) |
| 314 | |
| 315 | Get a description for a single group *group*. If more than one group matches |
| 316 | (if 'group' is a real wildmat string), return the first match. If no group |
| 317 | matches, return an empty string. |
| 318 | |
| 319 | This elides the response code from the server. If the response code is needed, |
| 320 | use :meth:`descriptions`. |
| 321 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 322 | |
| 323 | .. method:: NNTP.group(name) |
| 324 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 325 | Send a ``GROUP`` command, where *name* is the group name. The group is |
| 326 | selected as the current group, if it exists. Return a tuple |
| 327 | ``(response, count, first, last, name)`` where *count* is the (estimated) |
| 328 | number of articles in the group, *first* is the first article number in |
| 329 | the group, *last* is the last article number in the group, and *name* |
| 330 | is the group name. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 331 | |
| 332 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 333 | .. method:: NNTP.over(message_spec, *, file=None) |
| 334 | |
| 335 | Send a ``OVER`` command, or a ``XOVER`` command on legacy servers. |
| 336 | *message_spec* can be either a string representing a message id, or |
| 337 | a ``(first, last)`` tuple of numbers indicating a range of articles in |
| 338 | the current group, or a ``(first, None)`` tuple indicating a range of |
| 339 | articles starting from *first* to the last article in the current group, |
| 340 | or :const:`None` to select the current article in the current group. |
| 341 | |
| 342 | Return a pair ``(response, overviews)``. *overviews* is a list of |
| 343 | ``(article_number, overview)`` tuples, one for each article selected |
| 344 | by *message_spec*. Each *overview* is a dictionary with the same number |
| 345 | of items, but this number depends on the server. These items are either |
| 346 | message headers (the key is then the lower-cased header name) or metadata |
| 347 | items (the key is then the metadata name prepended with ``":"``). The |
| 348 | following items are guaranteed to be present by the NNTP specification: |
| 349 | |
| 350 | * the ``subject``, ``from``, ``date``, ``message-id`` and ``references`` |
| 351 | headers |
| 352 | * the ``:bytes`` metadata: the number of bytes in the entire raw article |
| 353 | (including headers and body) |
| 354 | * the ``:lines`` metadata: the number of lines in the article body |
| 355 | |
Antoine Pitrou | 4103bc0 | 2010-11-03 18:18:43 +0000 | [diff] [blame] | 356 | The value of each item is either a string, or :const:`None` if not present. |
| 357 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 358 | It is advisable to use the :func:`decode_header` function on header |
| 359 | values when they may contain non-ASCII characters:: |
| 360 | |
| 361 | >>> _, _, first, last, _ = s.group('gmane.comp.python.devel') |
| 362 | >>> resp, overviews = s.over((last, last)) |
| 363 | >>> art_num, over = overviews[0] |
| 364 | >>> art_num |
| 365 | 117216 |
| 366 | >>> list(over.keys()) |
| 367 | ['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject'] |
| 368 | >>> over['from'] |
| 369 | '=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <martin@v.loewis.de>' |
| 370 | >>> nntplib.decode_header(over['from']) |
| 371 | '"Martin v. Löwis" <martin@v.loewis.de>' |
| 372 | |
| 373 | .. versionadded:: 3.2 |
| 374 | |
| 375 | |
| 376 | .. method:: NNTP.help(*, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 377 | |
| 378 | Send a ``HELP`` command. Return a pair ``(response, list)`` where *list* is a |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 379 | list of help strings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 380 | |
| 381 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 382 | .. method:: NNTP.stat(message_spec=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 383 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 384 | Send a ``STAT`` command, where *message_spec* is either a message id |
| 385 | (enclosed in ``'<'`` and ``'>'``) or an article number in the current group. |
| 386 | If *message_spec* is omitted or :const:`None`, the current article in the |
| 387 | current group is considered. Return a triple ``(response, number, id)`` |
| 388 | where *number* is the article number and *id* is the message id. |
| 389 | |
| 390 | >>> _, _, first, last, _ = s.group('gmane.comp.python.devel') |
| 391 | >>> resp, number, message_id = s.stat(first) |
| 392 | >>> number, message_id |
| 393 | (9099, '<20030112190404.GE29873@epoch.metaslash.com>') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 394 | |
| 395 | |
| 396 | .. method:: NNTP.next() |
| 397 | |
| 398 | Send a ``NEXT`` command. Return as for :meth:`stat`. |
| 399 | |
| 400 | |
| 401 | .. method:: NNTP.last() |
| 402 | |
| 403 | Send a ``LAST`` command. Return as for :meth:`stat`. |
| 404 | |
| 405 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 406 | .. method:: NNTP.article(message_spec=None, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 407 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 408 | Send an ``ARTICLE`` command, where *message_spec* has the same meaning as |
| 409 | for :meth:`stat`. Return a tuple ``(response, info)`` where *info* |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 410 | is a :class:`~collections.namedtuple` with three attributes *number*, |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 411 | *message_id* and *lines* (in that order). *number* is the article number |
| 412 | in the group (or 0 if the information is not available), *message_id* the |
| 413 | message id as a string, and *lines* a list of lines (without terminating |
| 414 | newlines) comprising the raw message including headers and body. |
| 415 | |
| 416 | >>> resp, info = s.article('<20030112190404.GE29873@epoch.metaslash.com>') |
| 417 | >>> info.number |
| 418 | 0 |
| 419 | >>> info.message_id |
| 420 | '<20030112190404.GE29873@epoch.metaslash.com>' |
| 421 | >>> len(info.lines) |
| 422 | 65 |
| 423 | >>> info.lines[0] |
| 424 | b'Path: main.gmane.org!not-for-mail' |
| 425 | >>> info.lines[1] |
| 426 | b'From: Neal Norwitz <neal@metaslash.com>' |
| 427 | >>> info.lines[-3:] |
| 428 | [b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal'] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 429 | |
| 430 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 431 | .. method:: NNTP.head(message_spec=None, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 432 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 433 | Same as :meth:`article()`, but sends a ``HEAD`` command. The *lines* |
| 434 | returned (or written to *file*) will only contain the message headers, not |
| 435 | the body. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 436 | |
| 437 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 438 | .. method:: NNTP.body(message_spec=None, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 439 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 440 | Same as :meth:`article()`, but sends a ``BODY`` command. The *lines* |
| 441 | returned (or written to *file*) will only contain the message body, not the |
| 442 | headers. |
| 443 | |
| 444 | |
| 445 | .. method:: NNTP.post(data) |
| 446 | |
| 447 | Post an article using the ``POST`` command. The *data* argument is either |
| 448 | a :term:`file object` opened for binary reading, or any iterable of bytes |
| 449 | objects (representing raw lines of the article to be posted). It should |
| 450 | represent a well-formed news article, including the required headers. The |
| 451 | :meth:`post` method automatically escapes lines beginning with ``.`` and |
| 452 | appends the termination line. |
| 453 | |
| 454 | If the method succeeds, the server's response is returned. If the server |
| 455 | refuses posting, a :class:`NNTPReplyError` is raised. |
| 456 | |
| 457 | |
| 458 | .. method:: NNTP.ihave(message_id, data) |
| 459 | |
| 460 | Send an ``IHAVE`` command. *message_id* is the id of the message to send |
| 461 | to the server (enclosed in ``'<'`` and ``'>'``). The *data* parameter |
| 462 | and the return value are the same as for :meth:`post()`. |
| 463 | |
| 464 | |
| 465 | .. method:: NNTP.date() |
| 466 | |
| 467 | Return a pair ``(response, date)``. *date* is a :class:`~datetime.datetime` |
| 468 | object containing the current date and time of the server. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 469 | |
| 470 | |
| 471 | .. method:: NNTP.slave() |
| 472 | |
| 473 | Send a ``SLAVE`` command. Return the server's *response*. |
| 474 | |
| 475 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 476 | .. method:: NNTP.set_debuglevel(level) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 477 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 478 | Set the instance's debugging level. This controls the amount of debugging |
| 479 | output printed. The default, ``0``, produces no debugging output. A value of |
| 480 | ``1`` produces a moderate amount of debugging output, generally a single line |
| 481 | per request or response. A value of ``2`` or higher produces the maximum amount |
| 482 | of debugging output, logging each line sent and received on the connection |
| 483 | (including message text). |
| 484 | |
| 485 | |
| 486 | The following are optional NNTP extensions defined in :rfc:`2980`. Some of |
| 487 | them have been superseded by newer commands in :rfc:`3977`. |
| 488 | |
| 489 | |
| 490 | .. method:: NNTP.xhdr(header, string, *, file=None) |
| 491 | |
| 492 | Send an ``XHDR`` command. The *header* argument is a header keyword, e.g. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 493 | ``'subject'``. The *string* argument should have the form ``'first-last'`` |
| 494 | where *first* and *last* are the first and last article numbers to search. |
| 495 | Return a pair ``(response, list)``, where *list* is a list of pairs ``(id, |
| 496 | text)``, where *id* is an article number (as a string) and *text* is the text of |
| 497 | the requested header for that article. If the *file* parameter is supplied, then |
| 498 | the output of the ``XHDR`` command is stored in a file. If *file* is a string, |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 499 | then the method will open a file with that name, write to it then close it. |
| 500 | If *file* is a :term:`file object`, then it will start calling :meth:`write` on |
| 501 | it to store the lines of the command output. If *file* is supplied, then the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 502 | returned *list* is an empty list. |
| 503 | |
| 504 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 505 | .. method:: NNTP.xover(start, end, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 506 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 507 | Send an ``XOVER`` command. *start* and *end* are article numbers |
| 508 | delimiting the range of articles to select. The return value is the |
| 509 | same of for :meth:`over()`. It is recommended to use :meth:`over()` |
| 510 | instead, since it will automatically use the newer ``OVER`` command |
| 511 | if available. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 512 | |
| 513 | |
| 514 | .. method:: NNTP.xpath(id) |
| 515 | |
| 516 | Return a pair ``(resp, path)``, where *path* is the directory path to the |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 517 | article with message ID *id*. Most of the time, this extension is not |
| 518 | enabled by NNTP server administrators. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 519 | |
Florent Xicluna | 6731775 | 2011-12-10 11:07:42 +0100 | [diff] [blame] | 520 | .. deprecated:: 3.3 |
| 521 | The XPATH extension is not actively used. |
| 522 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 523 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 524 | .. XXX deprecated: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 525 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 526 | .. method:: NNTP.xgtitle(name, *, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 527 | |
Antoine Pitrou | 69ab951 | 2010-09-29 15:03:40 +0000 | [diff] [blame] | 528 | Process an ``XGTITLE`` command, returning a pair ``(response, list)``, where |
| 529 | *list* is a list of tuples containing ``(name, title)``. If the *file* parameter |
| 530 | is supplied, then the output of the ``XGTITLE`` command is stored in a file. |
| 531 | If *file* is a string, then the method will open a file with that name, write |
| 532 | to it then close it. If *file* is a :term:`file object`, then it will start |
| 533 | calling :meth:`write` on it to store the lines of the command output. If *file* |
| 534 | is supplied, then the returned *list* is an empty list. This is an optional NNTP |
| 535 | extension, and may not be supported by all servers. |
| 536 | |
| 537 | RFC2980 says "It is suggested that this extension be deprecated". Use |
| 538 | :meth:`descriptions` or :meth:`description` instead. |
| 539 | |
| 540 | |
| 541 | Utility functions |
| 542 | ----------------- |
| 543 | |
| 544 | The module also defines the following utility function: |
| 545 | |
| 546 | |
| 547 | .. function:: decode_header(header_str) |
| 548 | |
| 549 | Decode a header value, un-escaping any escaped non-ASCII characters. |
| 550 | *header_str* must be a :class:`str` object. The unescaped value is |
| 551 | returned. Using this function is recommended to display some headers |
| 552 | in a human readable form:: |
| 553 | |
| 554 | >>> decode_header("Some subject") |
| 555 | 'Some subject' |
| 556 | >>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=") |
| 557 | 'Débuter en Python' |
| 558 | >>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=") |
| 559 | 'Re: problème de matrice' |