19.4. Network News Network News, also known as Usenet, is mostly transmitted with the Network News Transport Protocol (NNTP). The specifications of the POP protocol are at http://www.ietf.org/rfc/rfc977.txt and http://www.ietf.org/rfc/rfc2980.txt. The Python standard library supports this protocol in module nntplib. The nntplib module supplies a class NNTP to connect to an NNTP server. NNTP | class NNTP(host, port=119, user=None, password=None, readermode=False, usenetrc=true) Returns an instance n of class NNTP connected to the host and port, and optionally authenticated with the given user and password if user is not None. When readermode is true, also sends a 'mode reader' command; you may need this, depending on the NNTP server and on the NNTP commands you send to that server. When usenetrc is true, TRies getting user and password for authentication from a file named .netrc in the current user's home directory, if not explicitly specified. |
19.4.1. Response Strings An instance n of NNTP supplies many methods. Each of n's methods returns a tuple whose first item is a string (known as response in the following), which is the response from the NNTP server to the NNTP command that corresponds to the method (method post just returns the response string, not a tuple). Each method returns the response string just as the NNTP server supplies it. The string starts with an integer in decimal form (the integer is known as the return code), followed by a space, followed by explanatory text. For some commands, the extra text after the return code is just a comment or explanation supplied by the NNTP server. For other commands, the NNTP standard specifies the format of the text that follows the return code on the response line. In those cases, the relevant method also parses the text in question, yielding other items in the method's resulting tuple, so your code need not perform such parsing itself; rather, you just access further items in the method's result tuple, as specified in the following sections. Return codes of the form 2xx, for any two digits xx, are success codes (i.e., they indicate that the corresponding NNTP command succeeded). Return codes of other forms, such as 4xx and 5xx, indicate failures in some NNTP command. In these cases, the method does not return a result. Rather, the method raises an instance of exception class nntplib.NNTPError, or some subclass of it, such as NNTPTemporaryError for errors that may (or may not) be automatically resolved if you try again, or NNTPPermanentError for errors that are sure to occur again if you retry. When a method of an NNTP instance raises an NNTPError instance e, the server's response string, starting with a return code such as 4xx, is str(e). 19.4.2. Methods The most frequently used methods of an NNTP instance n are as follows. article | n.article(id) id is a string, either an article ID enclosed in angle brackets (<>) or an article number in the current group. Returns a tuple with three strings and a list (response,number,id,lines), where number is the article number in the current group, id is the article ID enclosed in angle brackets, and lines is a list of strings that are the lines in the article (headers, then body, with an empty-line separator, and without end-of-line characters). | body | n.body(id,file) id is a string, either an article ID enclosed in angle brackets (<>) or an article number in the current group. Returns a tuple with three strings and a list (response,number,id,lines), where number is the article number in the current group, id is the article ID enclosed in angle brackets, and lines is a list of strings that are the lines in the article's body, without end-of-line characters. When file is not None, it can be either a string that names a file that body then opens for writing, or a file object already open for writing. In either case, body writes the article's body to the file, and, in these cases, lines in the tuple body returns is an empty list. | group | n.group(group_name) Makes group_name the current group and returns a tuple of five strings (response,count,first,last,group_name), where count is the total number of articles in the group, last is the number of the most recent article, first is the number of the oldest article, and group_name is the group's name. group_name is usually the same one you requested (i.e., the argument to n.group). However, an NNTP server can set up aliases, or synonyms; therefore, you may want to check the last item of the returned tuple to ascertain which newsgroup has been set as current. | head | n.head(id) Returns an article's headers. id is a string, either an article ID enclosed in angle brackets (<>) or an article number in the current group. head returns a tuple of three strings and a list (response,number,id,lines), where number is the article number in the current group, id is the article ID enclosed in angle brackets, and lines is a list of strings that are the lines in the article's headers, without end-of-line characters. | last | n.last( ) Returns a tuple of three strings (response,number,id), where number is the latest (highest) article number in the current group and id is the article ID, enclosed in angle brackets, for the last article in the current group. | list | n.list( ) Returns a pair (response,group_stats), where group_stats is a list of tuples with information about each group on the server. Each item of group_stats is a tuple of four strings (group_name,last,first,group_flag), where group_name is the group's name, last is the number of the most recent article, first is the number of the oldest article, and group_flag is 'y' when you're allowed to post, 'n' when you're not allowed to post, and 'm' when the group is moderated. | newgroups | n.newgroups(date,time) date is a string that indicates a date, of the form 'yymmdd'. time is a string that indicates a time, of the form 'hhmmss'. newgroups returns a pair (response,group_names), where group_names is the list of the names of groups created since the given date and time. | newnews | n.newnews(group,date,time) group is a string that is either a group name, meaning you only want data about articles in that group, or '*', meaning you want data about articles in any newsgroup on the server. date is a string that indicates a date, of the form 'yymmdd'. time is a string that indicates a time, of the form 'hhmmss'. newnews returns a pair (response,article_ids), where article_ids is the list of the identifiers of articles received since the given date and time. | next | n.next( ) Returns a tuple of three strings (response,number,id), where number is the next article number in the current group and id is the article ID, enclosed in angle brackets, for the next article in the current group. The current group is set by calling n.group. Each time you call n.next, you receive information about another article (i.e., n implicitly maintains a pointer to a current article within the group and advances the pointer on each call to n.next). When there is no next article (i.e., the current article is the last one in the current group), n.next raises NNTPTemporaryError (the error is deemed to be "temporary" because, presumably, there will be more articles in the future). | post | n.post(file) Posts an article to the current group, reading it from file. file is a file-like object open for reading; post reads the article's headers and body from the file by repeatedly calling file.readline. file contains all headers, then an empty-line separator, then the body. post returns a string, which is the response from the server to the posting request. | quit | n.quit( ) Closes the connection to the NNTP server. Call as the last method call on n. | stat | n.stat(id) id is a string, either an article ID in angle brackets or an article number in the current group. Returns a tuple of three strings (response,number,id), where number is the article number in the current group and id is the article ID in angle brackets. |
19.4.3. Example Here is a typical, simple example of nntplib use in an interactive interpreter session, using the free public NNTP server at news.gmane.org: >>> import nntplib >>> n = nntplib.NNTP('news.gmane.org') >>> response, groups = n.list( ) >>> print response 215 Newsgroups in form "group high low flags". >>> print 'gmane.org carries', len(groups), 'newsgroups' gmane.org carries 8094 newsgroups >>> pg_groups = [g for g in groups if 'postgresql' in g[0]] >>> print 'gmane.org carries', len(pg_groups), 'groups about postgresql' gmane.org carries 1162 groups about postgresql >>> n.group('gmane.comp.db.postgresql.announce') ('211 699 1 699 gmane.comp.db.postgresql.announce', '699', '1', '699', 'gmane.comp.db.postgresql.announce') >>> response, artnum, artid, headers = n.head('699') >>> len(headers) 71 >>> [h for h in headers if h.startswith('Subject:')] ['Subject: EMS SQL Manager 2005 for PostgreSQL ver. 3.4 released'] >>> n.quit( ) '205 .'
|
