Attributes¶

NNTP.nntp_version¶

An integer representing the version of the NNTP protocol supported by theserver. In practice, this should be2 for servers advertisingRFC 3977 compliance and1 for others.

New in version 3.2.

NNTP.nntp_implementation¶

A string describing the software name and version of the NNTP server,orNone if not advertised by the server.

New in version 3.2.

Methods¶

Theresponse that is returned as the first item in the return tuple of almostall methods is the server’s response: a string beginning with a three-digitcode. If the server’s response indicates an error, the method raises one ofthe above exceptions.

Many of the following methods take an optional keyword-only argumentfile.When thefile argument is supplied, it must be either afile objectopened 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 theresponse line and the terminating dot) to the file; any list of lines,tuples or objects that the method normally returns will be empty.

NNTP.quit()¶

Send aQUIT command and close the connection. Once this method has beencalled, no other methods of the NNTP object should be called.

NNTP.getwelcome()¶

Return the welcome message sent by the server in reply to the initialconnection. (This message sometimes contains disclaimers or help informationthat may be relevant to the user.)

NNTP.getcapabilities()¶

Return theRFC 3977 capabilities advertised by the server, as adict instance mapping capability names to (possibly empty) listsof values. On legacy servers which don’t understand theCAPABILITIEScommand, an empty dictionary is returned instead.

>>>s=NNTP('news.gmane.io')>>>'POST'ins.getcapabilities()True

New in version 3.2.

NNTP.login(user=None,password=None,usenetrc=True)¶

SendAUTHINFO commands with the user name and password. Ifuserandpassword areNone andusenetrc is true, credentials from~/.netrc will be used if possible.

Unless intentionally delayed, login is normally performed during theNNTP object initialization and separately calling this functionis unnecessary. To force authentication to be delayed, you must not setuser orpassword when creating the object, and must setusenetrc toFalse.

New in version 3.2.

NNTP.starttls(context=None)¶

Send aSTARTTLS command. This will enable encryption on the NNTPconnection. Thecontext argument is optional and should be assl.SSLContext object. Please readSecurity considerations for bestpractices.

Note that this may not be done after authentication information hasbeen transmitted, and authentication occurs by default if possible during aNNTP object initialization. SeeNNTP.login() for informationon suppressing this behavior.

New in version 3.2.

Changed in version 3.4:The method now supports hostname check withssl.SSLContext.check_hostname andServer Name Indication (seessl.HAS_SNI).

NNTP.newgroups(date,*,file=None)¶

Send aNEWGROUPS command. Thedate argument should be adatetime.date ordatetime.datetime object.Return a pair(response,groups) wheregroups is a list representingthe groups that are new since the givendate. Iffile is supplied,though, thengroups will be empty.

>>>fromdatetimeimportdate,timedelta>>>resp,groups=s.newgroups(date.today()-timedelta(days=3))>>>len(groups)85>>>groups[0]GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m')

NNTP.newnews(group,date,*,file=None)¶

Send aNEWNEWS command. Here,group is a group name or'*', anddate has the same meaning as fornewgroups(). Return a pair(response,articles) wherearticles is a list of message ids.

This command is frequently disabled by NNTP server administrators.

NNTP.list(group_pattern=None,*,file=None)¶

Send aLIST orLISTACTIVE command. Return a pair(response,list) wherelist is a list of tuples representing allthe groups available from this NNTP server, optionally matching thepattern stringgroup_pattern. Each tuple has the form(group,last,first,flag), wheregroup is a group name,lastandfirst are the last and first article numbers, andflag usuallytakes one of these values:

• y: Local postings and articles from peers are allowed.

• m: The group is moderated and all postings must be approved.

• n: No local postings are allowed, only articles from peers.

• j: Articles from peers are filed in the junk group instead.

• x: No local postings, and articles from peers are ignored.

• =foo.bar: Articles are filed in thefoo.bar group instead.

Ifflag has another value, then the status of the newsgroup should beconsidered unknown.

This command can return very large results, especially ifgroup_patternis not specified. It is best to cache the results offline unless youreally need to refresh them.

Changed in version 3.2:group_pattern was added.

NNTP.descriptions(grouppattern)¶

Send aLISTNEWSGROUPS command, wheregrouppattern is a wildmat string asspecified inRFC 3977 (it’s essentially the same as DOS or UNIX shell wildcardstrings). Return a pair(response,descriptions), wheredescriptionsis a dictionary mapping group names to textual descriptions.

>>>resp,descs=s.descriptions('gmane.comp.python.*')>>>len(descs)295>>>descs.popitem()('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')

NNTP.description(group)¶

Get a description for a single groupgroup. If more than one group matches(if ‘group’ is a real wildmat string), return the first match. If no groupmatches, return an empty string.

This elides the response code from the server. If the response code is needed,usedescriptions().

NNTP.group(name)¶

Send aGROUP command, wherename is the group name. The group isselected as the current group, if it exists. Return a tuple(response,count,first,last,name) wherecount is the (estimated)number of articles in the group,first is the first article number inthe group,last is the last article number in the group, andnameis the group name.

NNTP.over(message_spec,*,file=None)¶

Send anOVER command, or anXOVER command on legacy servers.message_spec can be either a string representing a message id, ora(first,last) tuple of numbers indicating a range of articles inthe current group, or a(first,None) tuple indicating a range ofarticles starting fromfirst to the last article in the current group,orNone to select the current article in the current group.

Return a pair(response,overviews).overviews is a list of(article_number,overview) tuples, one for each article selectedbymessage_spec. Eachoverview is a dictionary with the same numberof items, but this number depends on the server. These items are eithermessage headers (the key is then the lower-cased header name) or metadataitems (the key is then the metadata name prepended with":"). Thefollowing items are guaranteed to be present by the NNTP specification:

• thesubject,from,date,message-id andreferencesheaders

• the:bytes metadata: the number of bytes in the entire raw article(including headers and body)

• the:lines metadata: the number of lines in the article body

The value of each item is either a string, orNone if not present.

It is advisable to use thedecode_header() function on headervalues when they may contain non-ASCII characters:

>>>_,_,first,last,_=s.group('gmane.comp.python.devel')>>>resp,overviews=s.over((last,last))>>>art_num,over=overviews[0]>>>art_num117216>>>list(over.keys())['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject']>>>over['from']'=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <martin@v.loewis.de>'>>>nntplib.decode_header(over['from'])'"Martin v. Löwis" <martin@v.loewis.de>'

New in version 3.2.

NNTP.help(*,file=None)¶

Send aHELP command. Return a pair(response,list) wherelist is alist of help strings.

NNTP.stat(message_spec=None)¶

Send aSTAT command, wheremessage_spec is either a message id(enclosed in'<' and'>') or an article number in the current group.Ifmessage_spec is omitted orNone, the current article in thecurrent group is considered. Return a triple(response,number,id)wherenumber is the article number andid is the message id.

>>>_,_,first,last,_=s.group('gmane.comp.python.devel')>>>resp,number,message_id=s.stat(first)>>>number,message_id(9099, '<20030112190404.GE29873@epoch.metaslash.com>')

NNTP.next()¶

Send aNEXT command. Return as forstat().

NNTP.last()¶

Send aLAST command. Return as forstat().

NNTP.article(message_spec=None,*,file=None)¶

Send anARTICLE command, wheremessage_spec has the same meaning asforstat(). Return a tuple(response,info) whereinfois anamedtuple with three attributesnumber,message_id andlines (in that order).number is the article numberin the group (or 0 if the information is not available),message_id themessage id as a string, andlines a list of lines (without terminatingnewlines) comprising the raw message including headers and body.

>>>resp,info=s.article('<20030112190404.GE29873@epoch.metaslash.com>')>>>info.number0>>>info.message_id'<20030112190404.GE29873@epoch.metaslash.com>'>>>len(info.lines)65>>>info.lines[0]b'Path: main.gmane.org!not-for-mail'>>>info.lines[1]b'From: Neal Norwitz <neal@metaslash.com>'>>>info.lines[-3:][b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal']

NNTP.head(message_spec=None,*,file=None)¶

Same asarticle(), but sends aHEAD command. Thelinesreturned (or written tofile) will only contain the message headers, notthe body.

NNTP.body(message_spec=None,*,file=None)¶

Same asarticle(), but sends aBODY command. Thelinesreturned (or written tofile) will only contain the message body, not theheaders.

NNTP.post(data)¶

Post an article using thePOST command. Thedata argument is eitherafile object opened for binary reading, or any iterable of bytesobjects (representing raw lines of the article to be posted). It shouldrepresent a well-formed news article, including the required headers. Thepost() method automatically escapes lines beginning with. andappends the termination line.

If the method succeeds, the server’s response is returned. If the serverrefuses posting, aNNTPReplyError is raised.

NNTP.ihave(message_id,data)¶

Send anIHAVE command.message_id is the id of the message to sendto the server (enclosed in'<' and'>'). Thedata parameterand the return value are the same as forpost().

NNTP.date()¶

Return a pair(response,date).date is adatetimeobject containing the current date and time of the server.

NNTP.slave()¶

Send aSLAVE command. Return the server’sresponse.

NNTP.set_debuglevel(level)¶

Set the instance’s debugging level. This controls the amount of debuggingoutput printed. The default,0, produces no debugging output. A value of1 produces a moderate amount of debugging output, generally a single lineper request or response. A value of2 or higher produces the maximum amountof debugging output, logging each line sent and received on the connection(including message text).

The following are optional NNTP extensions defined inRFC 2980. Some ofthem have been superseded by newer commands inRFC 3977.

NNTP.xhdr(hdr,str,*,file=None)¶

Send anXHDR command. Thehdr argument is a header keyword, e.g.'subject'. Thestr argument should have the form'first-last'wherefirst andlast are the first and last article numbers to search.Return a pair(response,list), wherelist is a list of pairs(id,text), whereid is an article number (as a string) andtext is the text ofthe requested header for that article. If thefile parameter is supplied, thenthe output of theXHDR command is stored in a file. Iffile is a string,then the method will open a file with that name, write to it then close it.Iffile is afile object, then it will start callingwrite() onit to store the lines of the command output. Iffile is supplied, then thereturnedlist is an empty list.

NNTP.xover(start,end,*,file=None)¶

Send anXOVER command.start andend are article numbersdelimiting the range of articles to select. The return value is thesame of forover(). It is recommended to useover()instead, since it will automatically use the newerOVER commandif available.

NNTP.xpath(id)¶

Return a pair(resp,path), wherepath is the directory path to thearticle with message IDid. Most of the time, this extension is notenabled by NNTP server administrators.

Deprecated since version 3.3:The XPATH extension is not actively used.