2 - RFC 977: Network News Transfer Protocol
3 - RFC 2980: Common NNTP Extensions
4 - RFC 3977: Network News Transfer Protocol (version 2)
13 >>> resp, subs = s.xhdr('subject', '{0}-{1}'.format(first, last))
17 Here 'resp' is the server response line.
34 # - all commands are encoded as UTF-8 data (using the "surrogateescape"
36 # - all responses are decoded as UTF-8 data (using the "surrogateescape"
38 # - the `file` argument to various methods is keyword-only
40 # - NNTP.date() returns a datetime object
41 # - NNTP.newgroups() and NNTP.newnews() take a datetime (or date) object,
43 # - NNTP.newgroups() and NNTP.list() return a list of GroupInfo named tuples
44 # - NNTP.descriptions() returns a dict mapping group names to descriptions
45 # - NNTP.xover() returns a list of dicts mapping field names (header or metadata)
47 # - NNTP.article(), NNTP.head() and NNTP.body() return a (response, ArticleInfo)
49 # - the "internal" methods have been marked private (they now start with
53 # - automatic querying of capabilities at connect
54 # - New method NNTP.getcapabilities()
55 # - New method NNTP.over()
56 # - New helper function decode_header()
57 # - NNTP.post() and NNTP.ihave() accept file objects, bytes-like objects and
59 # - An extensive test suite :-)
62 # - return structured data (GroupInfo etc.) everywhere
63 # - support HDR
91 # maximal line length when calling readline(). This is to prevent
92 # reading arbitrary length lines. RFC 3977 limits NNTP line length to
121     """Response does not begin with [1-5]"""
137     '211',   # LISTGROUP   (also not multi-line with GROUP)
151     "subject", "from", "date", "message-id", "references", ":bytes", ":lines"]
159 # Line terminators (we always output CRLF, but accept any of CRLF, CR, LF)
172     and decodes it as a (possibly non-ASCII) readable value."""
187     for line in lines:
188         if line[0] == ':':
190             name, _, suffix = line[1:].partition(':')
194             name, _, suffix = line.partition(':')
207     """Parse the response to an OVER or XOVER command according to the
211     for line in lines:
213         article_number, *tokens = line.split('\t')
224                 # Non-default header names are included in full in the response
238     concatenated together (e.g. response to the DATE command).
241         time_str = date_str[-6:]
242         date_str = date_str[:-6]
246     year = int(date_str[:-4])
247     month = int(date_str[-4:-2])
248     day = int(date_str[-2:])
249     # RFC 3977 doesn't say how to interpret 2-char years.  Assume that
287         - sock: Socket to wrap
288         - context: SSL context to use for the encrypted connection
290         - sock: New, encrypted socket.
300     # UTF-8 is the character set for all NNTP commands and responses: they
303     # However, some multi-line data blocks can contain arbitrary bytes (for
304     # example, latin-1 or utf-16 data in the body of a message). Commands
307     # Furthermore, since there could be non-compliant servers out there,
309     # and easy round-tripping. This could be useful for some applications
312     encoding = 'utf-8'
319         - host: hostname to connect to
320         - port: port to connect to (default the standard NNTP port)
321         - user: username to authenticate with
322         - password: password to use with username
323         - readermode: if true, send 'mode reader' command after
325         - usenetrc: allow loading username and password from ~/.netrc file
327         - timeout: timeout (in seconds) used for socket connections
331         reader-specific commands, such as `group'.  If you get
400             raise ValueError('Non-blocking socket (timeout=0) is not supported')
415         If the CAPABILITIES command is not supported, an empty dict is
444     def _putline(self, line):  argument
445         """Internal: send one line to the server, appending CRLF.
446         The `line` must be a bytes-like object."""
447         sys.audit("nntplib.putline", self, line)
448         line = line + _CRLF
449         if self.debugging > 1: print('*put*', repr(line))
450         self.file.write(line)
453     def _putcmd(self, line):  argument
454         """Internal: send one command to the server (through _putline()).
455         The `line` must be a unicode string."""
456         if self.debugging: print('*cmd*', repr(line))
457         line = line.encode(self.encoding, self.errors)
458         self._putline(line)
461         """Internal: return one line from the server, stripping _CRLF.
464         line = self.file.readline(_MAXLINE +1)
465         if len(line) > _MAXLINE:
466             raise NNTPDataError('line too long')
468             print('*get*', repr(line))
469         if not line: raise EOFError
471             if line[-2:] == _CRLF:
472                 line = line[:-2]
473             elif line[-1:] in _CRLF:
474                 line = line[:-1]
475         return line
499         If `file` is a file-like object, it must be open in binary mode.
517                     line = self._getline(False)
518                     if line in terminators:
520                     if line.startswith(b'..'):
521                         line = line[1:]
522                     file.write(line)
526                     line = self._getline()
527                     if line == terminator:
529                     if line.startswith(b'..'):
530                         line = line[1:]
531                     lines.append(line)
539     def _shortcmd(self, line):  argument
540         """Internal: send a command and get the response.
542         self._putcmd(line)
545     def _longcmd(self, line, file=None):  argument
546         """Internal: send a command and get the response plus following text.
548         self._putcmd(line)
551     def _longcmdstring(self, line, file=None):  argument
552         """Internal: send a command and get the response plus following text.
556         self._putcmd(line)
558         return resp, [line.decode(self.encoding, self.errors)
559                       for line in list]
580         return [GroupInfo(*line.split()) for line in lines]
583         """Process a CAPABILITIES command.  Not supported by all servers.
585         - resp: server response if successful
586         - caps: a dictionary mapping capability names to lists of tokens
591         for line in lines:
592             name, *tokens = line.split()
597         """Process a NEWGROUPS command.  Arguments:
598         - date: a date or datetime object
600         - resp: server response if successful
601         - list: list of newsgroup names
613         """Process a NEWNEWS command.  Arguments:
614         - group: group name or '*'
615         - date: a date or datetime object
617         - resp: server response if successful
618         - list: list of message ids
629         """Process a LIST or LIST ACTIVE command. Arguments:
630         - group_pattern: a pattern indicating which groups to query
631         - file: Filename string or file object to store the result in
633         - resp: server response if successful
634         - list: list of (group, last, first, flag) (strings)
637             command = 'LIST ACTIVE ' + group_pattern
639             command = 'LIST'
640         resp, lines = self._longcmdstring(command, file)
684         """Process a GROUP command.  Argument:
685         - group: the group name
687         - resp: server response if successful
688         - count: number of articles
689         - first: first article number
690         - last: last article number
691         - name: the group name
710         """Process a HELP command. Argument:
711         - file: Filename string or file object to store the result in
713         - resp: server response if successful
714         - list: list of strings returned by the server in response to the
715                 HELP command
720         """Internal: parse the response line of a STAT, NEXT, LAST,
721         ARTICLE, HEAD or BODY command."""
729     def _statcmd(self, line):  argument
730         """Internal: process a STAT, NEXT or LAST command."""
731         resp = self._shortcmd(line)
735         """Process a STAT command.  Argument:
736         - message_spec: article number or message id (if not specified,
739         - resp: server response if successful
740         - art_num: the article number
741         - message_id: the message id
749         """Process a NEXT command.  No arguments.  Return as for STAT."""
753         """Process a LAST command.  No arguments.  Return as for STAT."""
756     def _artcmd(self, line, file=None):  argument
757         """Internal: process a HEAD, BODY or ARTICLE command."""
758         resp, lines = self._longcmd(line, file)
763         """Process a HEAD command.  Argument:
764         - message_spec: article number or message id
765         - file: filename string or file object to store the headers in
767         - resp: server response if successful
768         - ArticleInfo: (article number, message id, list of header lines)
777         """Process a BODY command.  Argument:
778         - message_spec: article number or message id
779         - file: filename string or file object to store the body in
781         - resp: server response if successful
782         - ArticleInfo: (article number, message id, list of body lines)
791         """Process an ARTICLE command.  Argument:
792         - message_spec: article number or message id
793         - file: filename string or file object to store the article in
795         - resp: server response if successful
796         - ArticleInfo: (article number, message id, list of article lines)
805         """Process a SLAVE command.  Returns:
806         - resp: server response if successful
811         """Process an XHDR command (optional server extension).  Arguments:
812         - hdr: the header type (e.g. 'subject')
813         - str: an article nr, a message id, or a range nr1-nr2
814         - file: Filename string or file object to store the result in
816         - resp: server response if successful
817         - list: list of (nr, value) strings
819         pat = re.compile('^([0-9]+) ?(.*)\n?')
821         def remove_number(line):  argument
822             m = pat.match(line)
823             return m.group(1, 2) if m else line
824         return resp, [remove_number(line) for line in lines]
827         """Process an XOVER command (optional server extension) Arguments:
828         - start: start of range
829         - end: end of range
830         - file: Filename string or file object to store the result in
832         - resp: server response if successful
833         - list: list of dicts containing the response fields
835         resp, lines = self._longcmdstring('XOVER {0}-{1}'.format(start, end),
841         """Process an OVER command.  If the command isn't supported, fall
843         - message_spec:
844             - either a message id, indicating the article to fetch
846             - or a (start, end) tuple, indicating a range of article numbers;
849             - or None, indicating the current article number must be used
850         - file: Filename string or file object to store the result in
852         - resp: server response if successful
853         - list: list of dicts containing the response fields
860             cmd += ' {0}-{1}'.format(start, end or '')
868         """Process the DATE command.
870         - resp: server response if successful
871         - date: datetime object
884     def _post(self, command, f):  argument
885         resp = self._shortcmd(command)
892         # - we don't want additional CRLF if the file or iterable is already
894         # - we don't want a spurious flush() after each line is written
895         for line in f:
896             if not line.endswith(_CRLF):
897                 line = line.rstrip(b"\r\n") + _CRLF
898             if line.startswith(b'.'):
899                 line = b'.' + line
900             self.file.write(line)
906         """Process a POST command.  Arguments:
907         - data: bytes object, iterable or file containing the article
909         - resp: server response if successful"""
913         """Process an IHAVE command.  Arguments:
914         - message_id: message-id of the article
915         - data: file containing the article
917         - resp: server response if successful
930         """Process a QUIT command and close the socket.  Returns:
931         - resp: server response if successful"""
994             """Process a STARTTLS command. Arguments:
995             - context: SSL context to use for the encrypted connection
1049         nntplib built-in demo - display the latest articles in a newsgroup""")
1050     parser.add_argument('-g', '--group', default='gmane.comp.python.general',
1052     parser.add_argument('-s', '--server', default='news.gmane.io',
1054     parser.add_argument('-p', '--port', default=-1, type=int,
1056     parser.add_argument('-n', '--nb-articles', default=10, type=int,
1058     parser.add_argument('-S', '--ssl', action='store_true', default=False,
1064         if port == -1:
1068         if port == -1:
1080             s = s[:lim - 4] + "..."
1083     first = str(int(last) - args.nb_articles + 1)