20.14. nntplib
— NNTP protocol client¶
Source code: Lib/nntplib.py
This module defines the class NNTP
which implements the client side of
the Network News Transfer Protocol. It can be used to implement a news reader
or poster, or automated news processors. It is compatible with RFC 3977
as well as the older RFC 977 and RFC 2980.
Here are two small examples of how it can be used. To list some statistics about a newsgroup and print the subjects of the last 10 articles:
>>> s = nntplib.NNTP('news.gmane.org')
>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
>>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)
Group gmane.comp.python.committers has 1096 articles, range 1 to 1096
>>> resp, overviews = s.over((last - 9, last))
>>> for id, over in overviews:
... print(id, nntplib.decode_header(over['subject']))
...
1087 Re: Commit privileges for Łukasz Langa
1088 Re: 3.2 alpha 2 freeze
1089 Re: 3.2 alpha 2 freeze
1090 Re: Commit privileges for Łukasz Langa
1091 Re: Commit privileges for Łukasz Langa
1092 Updated ssh key
1093 Re: Updated ssh key
1094 Re: Updated ssh key
1095 Hello fellow committers!
1096 Re: Hello fellow committers!
>>> s.quit()
'205 Bye!'
To post an article from a binary file (this assumes that the article has valid headers, and that you have right to post on the particular newsgroup):
>>> s = nntplib.NNTP('news.gmane.org')
>>> f = open('/tmp/article.txt', 'rb')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'
The module itself defines the following classes:
-
class
nntplib.
NNTP
(host, port=119, user=None, password=None, readermode=None, usenetrc=False[, timeout])¶ Return a new
NNTP
object, representing a connection to the NNTP server running on host host, listening at port port. An optional timeout can be specified for the socket connection. If the optional user and password are provided, or if suitable credentials are present in/.netrc
and the optional flag usenetrc is true, theAUTHINFO USER
andAUTHINFO PASS
commands are used to identify and authenticate the user to the server. If the optional flag readermode is true, then amode reader
command is sent before authentication is performed. Reader mode is sometimes necessary if you are connecting to an NNTP server on the local machine and intend to call reader-specific commands, such asgroup
. If you get unexpectedNNTPPermanentError
s, you might need to set readermode.Changed in version 3.2:
Changed in version 3.2: usenetrc is now False by default.
-
class
nntplib.
NNTP_SSL
(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False[, timeout])¶ Return a new
NNTP_SSL
object, representing an encrypted connection to the NNTP server running on host host, listening at port port.NNTP_SSL
objects have the same methods asNNTP
objects. If port is omitted, port 563 (NNTPS) is used. ssl_context is also optional, and is aSSLContext
object. All other parameters behave the same as forNNTP
.Note that SSL-on-563 is discouraged per RFC 4642, in favor of STARTTLS as described below. However, some servers only support the former.
New in version 3.2:
New in version 3.2.
-
exception
nntplib.
NNTPError
¶ Derived from the standard exception
Exception
, this is the base class for all exceptions raised by thenntplib
module. Instances of this class have the following attribute:
-
exception
nntplib.
NNTPReplyError
¶ Exception raised when an unexpected reply is received from the server.
-
exception
nntplib.
NNTPTemporaryError
¶ Exception raised when a response code in the range 400–499 is received.
-
exception
nntplib.
NNTPPermanentError
¶ Exception raised when a response code in the range 500–599 is received.
-
exception
nntplib.
NNTPProtocolError
¶ Exception raised when a reply is received from the server that does not begin with a digit in the range 1–5.
-
exception
nntplib.
NNTPDataError
¶ Exception raised when there is some error in the response data.
20.14.1.2. Methods¶
The response that is returned as the first item in the return tuple of almost all methods is the server’s response: a string beginning with a three-digit code. If the server’s response indicates an error, the method raises one of the above exceptions.
Many of the following methods take an optional keyword-only argument file. When the file argument is supplied, it must be either a file object opened for binary writing, or the name of an on-disk file to be written to. The method will then write any data returned by the server (except for the response line and the terminating dot) to the file; any list of lines, tuples or objects that the method normally returns will be empty.
Changed in version 3.2:
Changed in version 3.2: Many of the following methods have been reworked and fixed, which makes them incompatible with their 3.1 counterparts.
-
NNTP.
quit
()¶ Send a
QUIT
command and close the connection. Once this method has been called, no other methods of the NNTP object should be called.
-
NNTP.
getwelcome
()¶ Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.)
-
NNTP.
getcapabilities
()¶ Return the RFC 3977 capabilities advertised by the server, as a
dict
instance mapping capability names to (possibly empty) lists of values. On legacy servers which don’t understand theCAPABILITIES
command, an empty dictionary is returned instead.>>> s = NNTP('news.gmane.org') >>> 'POST' in s.getcapabilities() True
New in version 3.2:
New in version 3.2.
-
NNTP.
login
(user=None, password=None, usenetrc=True)¶ Send
AUTHINFO
commands with the user name and password. If user and password are None and usenetrc is True, credentials from~/.netrc
will be used if possible.Unless intentionally delayed, login is normally performed during the
NNTP
object initialization and separately calling this function is unnecessary. To force authentication to be delayed, you must not set user or password when creating the object, and must set usenetrc to False.New in version 3.2:
New in version 3.2.
-
NNTP.
starttls
(ssl_context=None)¶ Send a
STARTTLS
command. The ssl_context argument is optional and should be assl.SSLContext
object. This will enable encryption on the NNTP connection.Note that this may not be done after authentication information has been transmitted, and authentication occurs by default if possible during a
NNTP
object initialization. SeeNNTP.login()
for information on suppressing this behavior.New in version 3.2:
New in version 3.2.