20.11. ntplib — NNTP 协议客户端

源代码： :source:`Lib/nntplib.py`

该模块定义了类 NNTP，它实现了 NNTP 协议的客户端。它可用于实现新闻阅读器或海报，或自动化新闻处理器。有关 NNTP（网络新闻传输协议）的更多信息，请参阅 Internet RFC 977。

下面是两个如何使用它的小例子。要列出有关新闻组的一些统计信息并打印最近 10 篇文章的主题：

>>> s = 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 1071 articles, range 1 to 1071
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print id, sub
...
1062 Re: Mercurial Status?
1063 Re: [python-committers]  (Windows) buildbots on 3.x
1064 Re: Mercurial Status?
1065 Re: Mercurial Status?
1066 Python 2.6.6 status
1067 Commit Privileges for Ask Solem
1068 Re: Commit Privileges for Ask Solem
1069 Re: Commit Privileges for Ask Solem
1070 Re: Commit Privileges for Ask Solem
1071 2.6.6 rc 2
>>> s.quit()
'205 Bye!'

从文件发布文章（假设文章具有有效标题，并且您有权在特定新闻组上发布）：

>>> s = NNTP('news.gmane.org')
>>> f = open('articlefile')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'

模块本身定义了以下项目：

class nntplib.NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]]): 返回 NNTP 类的新实例，表示与运行在主机主机上的 NNTP 服务器的连接，监听端口端口。默认端口为 119。如果提供了可选的 user 和 password，或者 /.netrc 中存在合适的凭据并且可选标志 usenetrc 为真（默认)，AUTHINFO USER 和 AUTHINFO PASS 命令用于向服务器识别和验证用户。如果可选标志 readermode 为真，则在执行身份验证之前发送 mode reader 命令。如果您连接到本地机器上的 NNTP 服务器并打算调用特定于阅读器的命令，例如 group，有时需要阅读器模式。如果您收到意外的 NNTPPermanentErrors，您可能需要设置 readermode。 readermode 默认为 None。 usenetrc 默认为 True。

在 2.4 版更改：添加了 usenetrc 参数。

exception nntplib.NNTPError: 派生自标准异常 Exception，这是由 nntplib 模块引发的所有异常的基类。

exception nntplib.NNTPReplyError: 从服务器收到意外回复时引发异常。为了向后兼容，异常 error_reply 等效于此类。

exception nntplib.NNTPTemporaryError: 收到 400-499 范围内的错误代码时引发异常。为了向后兼容，异常 error_temp 等效于此类。

exception nntplib.NNTPPermanentError: 收到 500-599 范围内的错误代码时引发异常。为了向后兼容，异常 error_perm 等效于此类。

exception nntplib.NNTPProtocolError: 当从服务器收到不以 1-5 范围内的数字开头的回复时引发异常。为了向后兼容，异常 error_proto 等效于此类。

exception nntplib.NNTPDataError: 响应数据中存在错误时引发异常。为了向后兼容，异常 error_data 等效于此类。

20.11.1。 NNTP 对象

NNTP 实例具有以下方法。在几乎所有方法的返回元组中作为第一项返回的 response 是服务器的响应：一个以三位数代码开头的字符串。如果服务器的响应指示错误，则该方法会引发上述异常之一。

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

NNTP.set_debuglevel(level): 设置实例的调试级别。这控制打印的调试输出量。默认值 0 不产生调试输出。 1 的值会产生适量的调试输出，通常每个请求或响应只有一行。 2 或更高的值会产生最大数量的调试输出，记录连接上发送和接收的每一行（包括消息文本）。

NNTP.newgroups(date, time[, file]): 发送 NEWGROUPS 命令。 date 参数应该是表示日期的 'yymmdd' 形式的字符串，time 应该是表示时间的 'hhmmss' 形式的字符串. 返回一对 (response, groups)，其中 groups 是自给定日期和时间以来新的组名称列表。如果提供 file 参数，则 NEWGROUPS 命令的输出存储在文件中。如果 file 是一个字符串，则该方法将打开一个具有该名称的文件对象，写入然后关闭它。如果 file 是一个文件对象，那么它将开始调用 write() 来存储命令输出的行。如果提供了 file，则返回的 list 是一个空列表。

NNTP.newnews(group, date, time[, file]): 发送 NEWNEWS 命令。这里，group 是组名或 '*'，date 和 time 与 newgroups()[ X131X]。返回一对 (response, articles)，其中 articles 是消息 ID 列表。如果提供 file 参数，则 NEWNEWS 命令的输出存储在文件中。如果 file 是一个字符串，那么该方法将打开一个具有该名称的文件对象，写入它然后关闭它。如果 file 是一个文件对象，那么它将开始调用 write() 来存储命令输出的行。如果提供了 file，则返回的 list 是一个空列表。

NNTP.list([file]): 发送 LIST 命令。返回一对 (response, list)，其中 list 是元组列表。每个元组的格式为 (group, last, first, flag)，其中 group 是组名，last 和 first 是最后和第一个文章编号（作为字符串)，如果允许发布，则 flag 为 'y'，否则为 'n'，如果新闻组被审核，则为 'm'。（注意顺序：last, first。）如果提供了 file 参数，则 LIST 命令的输出存储在一份文件。如果 file 是一个字符串，那么该方法将打开一个具有该名称的文件对象，写入它然后关闭它。如果 file 是一个文件对象，那么它将开始调用 write() 来存储命令输出的行。如果提供了 file，则返回的 list 是一个空列表。

NNTP.descriptions(grouppattern): 发送 LIST NEWSGROUPS 命令，其中 grouppattern 是 RFC2980 中指定的通配符字符串（它本质上与 DOS 或 UNIX shell 通配符字符串相同）。返回一对 (response, list)，其中 list 是包含 (name, title) 的元组列表。

2.4 版中的新功能。

NNTP.description(group)

获取单个组组的描述。如果多个组匹配（如果 'group' 是一个真正的 Wildmat 字符串），则返回第一个匹配项。如果没有组匹配，则返回一个空字符串。

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

2.4 版中的新功能。

NNTP.group(name): 发送 GROUP 命令，其中 name 是组名。返回一个元组 (response, count, first, last, name)，其中 count 是组中的（估计）文章数，first 是组中的第一个文章编号，last[ X163X]为组中最后一个货号，name为组名。数字作为字符串返回。

NNTP.help([file]): 发送 HELP 命令。返回一对 (response, list)，其中 list 是帮助字符串列表。如果提供 file 参数，则 HELP 命令的输出存储在文件中。如果 file 是一个字符串，则该方法将打开一个具有该名称的文件对象，写入然后关闭它。如果 file 是一个文件对象，那么它将开始调用 write() 来存储命令输出的行。如果提供了 file，则返回的 list 是一个空列表。

NNTP.stat(id): 发送 STAT 命令，其中 id 是消息 ID（包含在 '<' 和 '>' 中）或商品编号（作为字符串）。返回一个三元组 (response, number, id)，其中 number 是商品编号（作为字符串），id 是消息 ID（包含在 '<' 和 '>'）。

NNTP.next(): 发送 NEXT 命令。返回 stat()。

NNTP.last(): 发送 LAST 命令。返回 stat()。

NNTP.head(id): 发送 HEAD 命令，其中 id 与 stat() 的含义相同。返回一个元组 (response, number, id, list)，其中前三个与 stat() 相同，list 是文章标题的列表（未解释的行列表，没有尾随换行符）。

NNTP.body(id[, file]): 发送 BODY 命令，其中 id 与 stat() 的含义相同。如果提供了 file 参数，则正文存储在文件中。如果 file 是一个字符串，则该方法将打开一个具有该名称的文件对象，写入然后关闭它。如果 file 是一个文件对象，那么它会开始在它上面调用 write() 来存储正文的行。返回 head()。如果提供了 file，则返回的 list 是一个空列表。

NNTP.article(id): 发送 ARTICLE 命令，其中 id 与 stat() 的含义相同。返回 head()。

NNTP.slave(): 发送 SLAVE 命令。返回服务器的响应。

NNTP.xhdr(header, string[, file]): 发送 XHDR 命令。该命令未在 RFC 中定义，而是一个常见的扩展。 header 参数是一个标题关键字，例如 'subject'。 string 参数的格式应为 'first-last'，其中 first 和 last 是要搜索的第一个和最后一个文章编号。返回一对 (response, list)，其中 list 是对 (id, text) 的列表，其中 id 是商品编号（作为字符串）和 ]text 是该文章请求标题的文本。如果提供 file 参数，则 XHDR 命令的输出存储在文件中。如果 file 是一个字符串，那么该方法将打开一个具有该名称的文件对象，写入它然后关闭它。如果 file 是一个文件对象，那么它将开始调用 write() 来存储命令输出的行。如果提供了 file，则返回的 list 是一个空列表。

NNTP.post(file): 使用 POST 命令发表文章。 file 参数是一个打开的文件对象，使用其 readline() 方法读取直到 EOF。它应该是一篇格式良好的新闻文章，包括所需的标题。 post() 方法自动转义以 . 开头的行。

NNTP.ihave(id, file): 发送 IHAVE 命令。 id 是消息 ID（包含在 '<' 和 '>' 中）。如果响应不是错误，请完全按照 post() 方法处理 file。

NNTP.date(): 返回一个三元组 (response, date, time)，以适合 newnews() 和 newgroups() 方法的形式包含当前日期和时间。这是一个可选的 NNTP 扩展，可能并非所有服务器都支持。

NNTP.xgtitle(name[, file])

处理 XGTITLE 命令，返回一对 (response, list)，其中 list 是包含 (name, title) 的元组列表。如果提供 file 参数，则 XGTITLE 命令的输出存储在文件中。如果 file 是一个字符串，则该方法将打开一个具有该名称的文件对象，写入然后关闭它。如果 file 是一个文件对象，那么它将开始调用 write() 来存储命令输出的行。如果提供了 file，则返回的 list 是一个空列表。这是一个可选的 NNTP 扩展，可能并非所有服务器都支持。

RFC2980 说“建议弃用此扩展”。请改用 descriptions() 或 description()。

NNTP.xover(start, end[, file]): 返回一对 (resp, list)。 list 是一个元组列表，每个文章对应一个由 start 和 end 文章编号分隔的范围内的文章。每个元组的形式为 (article number, subject, poster, date, id, references, size, lines)。如果提供 file 参数，则 XOVER 命令的输出存储在文件中。如果 file 是一个字符串，则该方法将打开一个具有该名称的文件对象，写入然后关闭它。如果 file 是一个文件对象，那么它将开始调用 write() 来存储命令输出的行。如果提供了 file，则返回的 list 是一个空列表。这是一个可选的 NNTP 扩展，可能并非所有服务器都支持。

NNTP.xpath(id): 返回一对(resp, path)，其中path是消息ID为id的文章的目录路径。这是一个可选的 NNTP 扩展，可能并非所有服务器都支持。

NNTP.quit(): 发送 QUIT 命令并关闭连接。一旦调用了此方法，就不应调用 NNTP 对象的其他方法。

20.11. nntplib — NNTP 协议客户端 — Python 文档

20.11. ntplib — NNTP 协议客户端

20.11.1。 NNTP 对象