# 11.9 `nntplib` -- NNTP protocol client

This module defines the class `NNTP` which implements the client side of the NNTP protocol. It can be used to implement a news reader or poster, or automated news processors. For more information on NNTP (Network News Transfer Protocol), see Internet RFC 977 .

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 = NNTP('news.cwi.nl')
      >>> resp, count, first, last, name = s.group('comp.lang.python')
      >>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
      Group comp.lang.python has 59 articles, range 3742 to 3803
      >>> resp, subs = s.xhdr('subject', first + '-' + last)
      >>> for id, sub in subs[-10:]: print id, sub
      ...
      3792 Re: Removing elements from a list while iterating...
      3793 Re: Who likes Info files?
      3794 Emacs and doc strings
      3795 a few questions about the Mac implementation
      3796 Re: executable python scripts
      3797 Re: executable python scripts
      3798 Re: a few questions about the Mac implementation
      3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
      3802 Re: executable python scripts
      3803 Re: \POSIX{} wait and SIGCHLD
      >>> s.quit()
      '205 news.cwi.nl closing connection.  Goodbye.'

To post an article from a file (this assumes that the article has valid headers):

      >>> s = NNTP('news.cwi.nl')
      >>> f = open('/tmp/article')
      >>> s.post(f)
      '240 Article posted successfully.'
      >>> s.quit()
      '205 news.cwi.nl closing connection.  Goodbye.'

The module itself defines the following items:

`NNTP` (host[, port [, user[, password [, readermode]]]])
  Return a new instance of the `NNTP` class, representing a connection to the NNTP server running on host host, listening at port port. The default port is 119. If the optional user and password are provided, the "`AUTHINFO USER`" and "`AUTHINFO PASS`" commands are used to identify and authenticate the user to the server. If the optional flag readermode is true, then a "`mode 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 as "`group`". If you get unexpected `NNTPPermanentError`s, you might need to set readermode. readermode defaults to `None`.

`NNTPError` ()
  Derived from the standard exception `Exception`, this is the base class for all exceptions raised by the `nntplib` module.

`NNTPReplyError` ()
  Exception raised when an unexpected reply is received from the server. For backwards compatibility, the exception `error_reply` is equivalent to this class.

`NNTPTemporaryError` ()
  Exception raised when an error code in the range 400-499 is received. For backwards compatibility, the exception `error_temp` is equivalent to this class.

`NNTPPermanentError` ()
  Exception raised when an error code in the range 500-599 is received. For backwards compatibility, the exception `error_perm` is equivalent to this class.

`NNTPProtocolError` ()
  Exception raised when a reply is received from the server that does not begin with a digit in the range 1-5. For backwards compatibility, the exception `error_proto` is equivalent to this class.

`NNTPDataError` ()
  Exception raised when there is some error in the response data. For backwards compatibility, the exception `error_data` is equivalent to this class.

Subsections

- 11.9.1 NNTP Objects