You are here:  Home » Python » – NNTP协议客户端 – Internet协议和支持(Python教程)(参考资料)

nntplibNNTP协议客户端

源代码: Lib / nntplib.py


这个模块定义了实现网络新闻传输客户端的类NNTP协议。它可用于实现新闻阅读器或海报,或自动新闻处理器。它兼容 RFC 3977 以及旧版 RFC 977 RFC 2980 .

以下是两个如何使用它的小例子。列出一些关于新闻组的统计数据并打印最近10篇文章的主题:

>>> 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 Langa1088 Re: 3.2 alpha 2 freeze1089 Re: 3.2 alpha 2 freeze1090 Re: Commit privileges for Łukasz Langa1091 Re: Commit privileges for Łukasz Langa1092 Updated ssh key1093 Re: Updated ssh key1094 Re: Updated ssh key1095 Hello fellow committers!1096 Re: Hello fellow committers!>>> s.quit()"205 Bye!"

从二进制文件发布文章(这假定文章有有效的标题,并且您有权在特定新闻组上发布):

>>> s = nntplib.NNTP("news.gmane.org")>>> f = open("article.txt", "rb")>>> s.post(f)"240 Article posted successfully.">>> s.quit()"205 Bye!"

模块本身定义了以下类:

class nntplib.NNTPhost, port=119, user=None, password=None, readermode=None, usenetrc=False [, timeout]

返回一个新的NNTP对象,表示与主机host上运行的NNTP服务器的连接,在端口port监听。可以为可选的timeout指定socket连接。如果可选userpassword提供,或者如果/.netrc中存在合适的赋值并且可选标志usenetrc为真,则AUTHINFO USERAUTHINFO PASS命令用于识别和验证用户到服务器。如果optionalflag readermode为true,则在执行身份验证之前发送mode reader命令。如果您连接到本地计算机上的NNTP服务器并打算调用特定于调度程序的命令(例如group),则有时需要使用Reader模式。如果你得到意想不到的NNTPPermanentError s,你可能需要设置readermodeNNTP类支持with语句tounconditional consume OSError例外并在完成后关闭NNTP连接,例如:

>>> from nntplib import NNTP>>> with NNTP("news.gmane.org") as n:...     n.group("gmane.comp.python.committers")... # doctest: +SKIP("211 1755 1 1755 gmane.comp.python.committers", 1755, 1, 1755, "gmane.comp.python.committers")>>>

在版本3.2中更改:usenetrc现在是False默认情况下

在版本3.3中更改:添加了对with声明的支持.

class nntplib.NNTP_SSL (host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False [, timeout])

返回一个新的NNTP_SSL对象,表示加密连接到主机host上运行的NNTP服务器,监听atport port. NNTP_SSL对象的方法与NNTP对象。如果省略port,则使用端口563(NNTPS).ssl_context也是可选的,是SSLContext对象。请阅读安全注意事项用于最佳实践。所有其他参数的行为与NNTP.

的行为相同请注意,对于 RFC 4642 ,不鼓励使用SSL-on-563,赞成ofSTARTTLS如下所述。但是,有些服务器只支持变形器.

新版本3.2.

更改版本3.4:该类现在支持使用ssl.SSLContext.check_hostname进行主机名检查Server Name Indication(参见ssl.HAS_SNI).

exception nntplib.NNTPError

从标准异常Exception派生出来,这是nntplib引发的所有异常的基类模块。此类的实例具有以下属性:

response

服务器的响应(如果可用),如str object.

exception nntplib.NNTPReplyError

当从服务器收到意外回复时引发异常。

exception nntplib.NNTPTemporaryError

收到400-499范围内的响应代码时引发异常.

exception nntplib.NNTPPermanentError

收到500-599范围内的响应代码时出现异常.

exception nntplib.NNTPProtocolError

当从服务器收到不以1-5的范围内的数字开头的回复时引发异常.

exception nntplib.NNTPDataError

当响应数据中出现错误时引发异常.

NNTP对象

连接时,NNTPNNTP_SSL对象支持以下方法和属性.

Attributes

NNTP.nntp_version

表示NNTP协议版本的整数由服务器支持。在实践中,这应该是2用于服务器广告 RFC 3977 遵守和1为其他人.

新版本3.2.

NNTP.nntp_implementation

描述NNTP服务器软件名称和版本的字符串,或None如果服务器没有公布的话

新版本3.2.

Methods

作为几乎所有方法的返回元组中的第一项返回的response是服务器的响应:以三个digitcode开头的字符串。如果服务器的响应指示错误,则该方法引发上述异常之一.

以下许多方法采用可选的仅关键字参数file。当提供file参数时,它必须是文件对象打开以进行二进制写入,或者写入要写入的磁盘文件的名称。然后,该方法将服务器返回的任何数据(响应行和终止点除外)写入文件;方法通常返回的任何行,元组或对象列表都将为空.

在版本3.2中更改:以下许多方法已经过重新修改和修复,这使得它们与3.1对应方不兼容.

NNTP.quit ( )

寄一个 QUIT命令并关闭连接。一旦调用了这个方法,就不应该调用NNTP对象的其他方法.

NNTP.getwelcome ( )

返回服务器发送的欢迎消息以回复初始连接。(此消息有时包含可能与用户相关的免责声明或帮助信息。)

NNTP.getcapabilities

返回 RFC 3977 服务器通告的功能,作为dict实例映射功能命名为(可能为空)值列表。在不了解CAPABILITIES命令,返回一个空字典.

>>> s = NNTP("news.gmane.org")>>> "POST" in s.getcapabilities()True

版本3.2.

NNTP.loginuser=None, password=None, usenetrc=True

发送AUTHINFO用户名和密码的命令。如果userpasswordNoneusenetrc如果可能,将使用来自~/.netrc的凭据.

除非故意延迟,否则通常在NNTP对象初始化和单独调用此函数是不必要的。要强制进行身份验证,在创建对象时不能设置userpassword,并且必须设置usenetrctoFalse.

新版本3.2.

NNTP.starttls (context=None)

发一个STARTTLS命令。这将启用NNTP连接上的加密。context参数是可选的,应该是ssl.SSLContext宾语。请阅读安全考虑以获得最佳实践.

请注意,在传输身份验证信息后可能无法执行此操作,并且在NNTP对象初始化期间,如果可能,默认情况下会进行身份验证。见NNTP.login()有关抑制此行为的信息.

版本3.2.

版本3.4更改:该方法现在支持使用ssl.SSLContext.check_hostnameServer Name Indication(看到ssl.HAS_SNI).

NNTP.newgroupsdate, *, file=None

发送NEWGROUPS命令。date参数应该是datetime.datedatetime.datetime对象。返回一对(response, groups)其中groups是一个表示新组的列表既然给定了date。如果file然后提供groups将是空的.

>>> from datetime import date, timedelta>>> resp, groups = s.newgroups(date.today() - timedelta(days=3))>>> len(groups) # doctest: +SKIP85>>> groups[0] # doctest: +SKIPGroupInfo(group="gmane.network.tor.devel", last="4", first="1", flag="m")
NNTP.newnewsgroup, date, *, file=None

寄一个 NEWNEWS命令。这里, group是一个组名或"*",和date与具有相同的含义newgroups()。返回一对(response, articles)其中articles是一个消息ID列表.

这个命令经常被NNTP服务器管理员禁用.

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

发送LISTLIST ACTIVE命令。返回一对(response, list) list是表示此NNTP服务器中可用的所有组的元组列表,可选地匹配模式字符串group_pattern。每个元组都有(group, last, first, flag)的形式,其中group是一个组名,lastfirst是最后和第一个文章编号,flag通常取这些值中的一个:

  • y:允许来自同行的本地帖子和文章.
  • m:小组被审核,所有帖子必须被批准.
  • n:否允许本地帖子,只允许来自同行的文章.
  • j:来自同行的文章反而在垃圾集团中提交.
  • x:没有本地帖子,同行的文章被忽略了
  • =foo.bar//:文章是在foo.bar组中提交的.

如果flag有另一个值,那么新闻组的状态应该被认为是未知的.

此命令可以返回非常大的结果,尤其是在未指定group_pattern的情况下。最好是离线缓存结果,除非你真的需要刷新它们.

在版本3.2中更改:group_pattern添加了

NNTP.descriptions// (grouppattern)

寄一个 LIST NEWSGROUPS命令,其中grouppattern RFC 3977 中指定的wildmat字符串(它与DOS或UNIX shell通配符串基本相同)。返回一对(response, descriptions),其中descriptions是一个字典映射组名称到文本描述.

>>> resp, descs = s.descriptions("gmane.comp.python.*")>>> len(descs) # doctest: +SKIP295>>> descs.popitem() # doctest: +SKIP("gmane.comp.python.bio.general", "BioPython discussion list (Moderated)")
NNTP.description (group)

获取单个组的描述group。如果多个组匹配(如果’group’是真正的wildmat字符串),则返回第一个匹配项。如果没有组匹配,则返回一个空字符串.

这省略了服务器的响应代码。如果需要响应代码,请使用descriptions().

NNTP.groupname

发送GROUP命令,其中name是组名。如果存在,则选择该组作为当前组。返回一个元组(response, count, first, last, name)其中count是该组中的(估计)文章数量,first是组中的第一个文章编号,last是组中的最后一个文章编号,而name是组名.

NNTP.over (message_spec, *, file=None

发送OVER命令,或XOVER遗留服务器上的命令.message_spec可以是表示消息ID的字符串,ora (first, last)表示当前组中文章范围的数字元组,或者(first, None)元组表示从开始的一系列文章first到当前组的最后一篇文章,或None选择当前组中的当前文章.

返回一对(response, overviews). overviews是的列表(article_number, overview)元组,每个文章一个由message_spec选择。每个overview是一个具有相同项目数的字典,但这个数字取决于服务器。这些项目是消息标题(密钥是较低的标题名称)或metadataitems(然后是密钥是":")。NNTP规范保证以下项目存在:

  • subject, from, date, message-idreferences标题
  • :bytes元数据:整个原始文章中的字节数(包括标题和正文)
  • :lines元数据:文章正文中的行数

每个项的值是一个字符串,如果不存在则None

当它们可能包含非ASCII字符时,建议在headervalues上使用decode_header()函数:

>>> _, _, 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>"

版本3.2.

NNTP.help*, file=None

寄一个 HELP命令。返回一对(response, list)/list是一个帮助字符串列表.

NNTP.statmessage_spec=None

寄一个 STAT命令,message_spec是一个消息ID(包含在"<"">"中)或当前组中的文章编号。如果message_spec被省略或None,考虑当前小组的当前文章。返回三个(response, number, id)其中number是文章编号而id是信息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 ()

寄一个 NEXT命令。返回stat().

NNTP.last

寄一个 LAST命令。返回stat().

NNTP.articlemessage_spec=None, *, file=None

发送ARTICLE命令,message_spec与具有相同的含义stat()。返回一个元组(response, info)其中infonamedtuple,有三个属性number,message_idlines(按此顺序)。number是组中的文章编号(如果信息不可用,则为0),message_idthemessage id as a string,和lines一个行列表(没有终止新行),包括包含标题和正文的原始消息.

>>> 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)

article()相同,但发送HEAD命令。lines返回(或写入file)只包含邮件标题,而不是正文.

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

同名如article(),但发送一个BODY命令。lines返回(或写入file)只包含消息正文,而不是theheaders.

NNTP.post(data)

Post一篇使用POST命令的文章。data参数是eithera 文件对象为二进制读取打开,或者任何可迭代的bytesobjects(表示要发布的文章的原始行)。它应该代表一个结构良好的新闻文章,包括所需的标题。post()方法自动转义以.开头的行,并显示终止行.

如果方法成功,则返回服务器的响应。如果服务器拒绝发布,则会引发NNTPReplyError.

NNTP.ihave(message_id, data)

发送IHAVE命令。message_id是要发送到服务器的消息的id(包含在"<"">"中)。data参数和返回值与post().

NNTP.date)相同

返回一对(response, date). datedatetime包含服务器当前日期和时间的对象.

NNTP.slave()

发送SLAVE命令。返回服务器的response.

NNTP.set_debuglevellevel

设置实例的调试级别。这可以控制打印的debuggingoutput数量。默认值0不产生调试输出。值1产生适量的调试输出,通常是单个线路请求或响应。值2或更高版本产生最大调试输出量,记录连接上发送和接收的每一行(包括消息文本).

以下是RFC 2980 。其中一些已被 RFC 3977 .

NNTP.xhdrhdr, str, *, file=None

发送XHDR命令中的新命令所取代。hdrargument是一个标题关键字,例如"subject"str参数的格式应为"first-last",其中firstlast是要查找的第一个和最后一个文章编号。返回一对(response, list),其中list是对的列表(id,text),其中id是文章编号(作为字符串),text是请求标题的文本那篇文章。如果提供了file参数,则XHDR命令的输出存储在文件中。如果file是一个字符串,那么该方法将打开一个具有该名称的文件,写入然后关闭它。如果file文件对象,然后它将开始调用write() onit来存储命令输出的行。如果提供了file,那么list就是一个空列表

NNTP.xoverstart, end, *, file=None)

发一个XOVER命令。startend是文章编号,用于界定要选择的文章范围。返回值与over()相同。建议使用over()代替,因为它会自动使用较新的OVER命令.

NNTP.xpathid

返回一对(resp, path),其中path是具有消息ID id的文章的目录路径。大多数情况下,NNTP服务器管理员无法启用此扩展.

自版本3.3以后删除: XPATH扩展未被主动使用.

实用功能

该模块还定义了以下实用程序函数:

nntplib.decode_headerheader_str

解码标题值,取消转义任何转义的非ASCII字符.header_str必须是str对象。未转义的价值被撤回。建议使用此功能以人类可读的形式显示一些标题:

>>> decode_header("Some subject")"Some subject">>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=")"Débuter en Python">>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=")"Re: problème de matrice"

评论被关闭。