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