20.11. nntplib — NNTP 协议 Client 端

源代码： Lib/nntplib.py

---

该模块定义了实现 NNTP 协议 Client 端的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类的新实例，该实例表示与在主机* host 上运行的 NNTP 服务器的连接，侦听端口 port 。默认的 port 为 119.如果提供了可选的 user 和 password ，或者/.netrc中存在适当的凭据并且可选标记 usenetrc 为 true(默认值)，则使用AUTHINFO USER和AUTHINFO PASS命令标识用户并向服务器验证身份。如果可选标志 readermode 为 true，则在执行身份验证之前发送mode reader命令。如果要连接到本地计算机上的 NNTP 服务器并打算调用特定于读取器的命令，例如group，则有时需要读取器模式。如果出现意外的NNTPPermanentError，则可能需要设置 readermode *。 * readermode *默认为None。 * usenetrc *默认为True。

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

• exception nntplib. NNTPError

  • 从标准异常Exception派生，这是nntplib模块引发的所有异常的 Base Class。

• 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 实例具有以下方法。几乎所有方法的返回 Tuples 中作为第一项返回的* response *是服务器的响应：一个以三位数代码开头的字符串。如果服务器的响应指示错误，则该方法将引发上述异常之一。

• NNTP. getwelcome ( )

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

• NNTP. set_debuglevel(级别)

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

• NNTP. newgroups(日期，时间 [，文件])

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

• NNTP. newnews(* group ， date ， time * [，* file *])

  • 发送NEWNEWS命令。在此，* group 是组名或'*'，而 date 和 time 具有与newgroups()相同的含义。返回Pair(response, articles)，其中 articles 是消息 ID 的列表。如果提供了 file 参数，则NEWNEWS命令的输出存储在文件中。如果 file 是字符串，则该方法将打开具有该名称的文件对象，对其进行写入，然后将其关闭。如果 file 是文件对象，则它将开始在其上调用write()来存储命令输出的行。如果提供了 file ，则返回的 list *是一个空列表。

• NNTP. list([* file *])

  • 发送LIST命令。返回Pair(response, list)，其中* list 是 Tuples 列表。每个 Tuples 的格式均为(group, last, first, flag)，其中 group 是组名， last 和 first 是最后和第一条文章编号(以字符串形式)，如果允许发布，则 flag 是'y'，如果不允许则是'n'，和'm'(如果新闻组受到审核)。 (请注意 Sequences： last ， first .)如果提供了 file 参数，则LIST命令的输出存储在文件中。如果 file 是字符串，则该方法将打开具有该名称的文件对象，对其进行写入，然后将其关闭。如果 file 是文件对象，则它将开始在其上调用write()来存储命令输出的行。如果提供了 file ，则返回的 list *是一个空列表。

• NNTP. descriptions(* grouppattern *)

  • 发送LIST NEWSGROUPS命令，其中* grouppattern 是 RFC2980 中指定的通配符字符串(与 DOS 或 UNIX shell 通配符字符串基本相同)。返回Pair(response, list)，其中 list *是包含(name, title)的 Tuples 列表。

2.4 版的新Function。

• NNTP. description(* group *)
  • 获取单个组* group *的描述。如果多个组匹配(如果'group'是真实的 wildmat 字符串)，则返回第一个匹配项。如果没有组匹配，则返回一个空字符串。

这消除了服务器的响应代码。如果需要响应代码，请使用descriptions()。

2.4 版的新Function。

• NNTP. group(* name *)

  • 发送GROUP命令，其中* name 是组名。返回一个 Tuples(response, count, first, last, name)，其中 count 是组中商品的(估计)数量， first 是组中的第一个商品编号， last 是组中的最后一个商品编号， name *是组中的最后一个商品编号团队名字。数字以字符串形式返回。

• NNTP. help([* file *])

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

• NNTP. stat(* id *)

  • 发送STAT命令，其中* id 是消息 ID(用'<'和'>'括起来)或商品编号(作为字符串)。返回一个三 Tuples(response, number, id)，其中 number 是商品编号(作为字符串)， id *是消息 id(用'<'和'>'括起来)。

• NNTP. next ( )

  • 发送NEXT命令。返回stat()。

• NNTP. last ( )

  • 发送LAST命令。返回stat()。

• NNTP. head(* id *)

  • 发送HEAD命令，其中* id 与stat()的含义相同。返回一个 Tuples(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命令。返回服务器的* response *。

• NNTP. xhdr(* header ， string * [，* file *])

  • 发送XHDR命令。该命令未在 RFC 中定义，但是常用扩展。 * header *参数是 header 关键字，例如'subject'。 * string 参数的格式应为'first-last'，其中 first 和 last 是要搜索的第一和最后一个商品编号。返回对(response, list)，其中 list 是对(id, text)的列表，其中 id 是商品编号(作为字符串)，而 text 是该商品请求的 Headers 的文本。如果提供了 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 ( )

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

• NNTP. xgtitle(* name * [，* file *])

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

RFC2980 说“建议不要使用此 extensions”。请改用descriptions()或description()。

• NNTP. xover(* start ， end * [，* file *])

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

• NNTP. xpath(* id *)

  • 返回Pair(resp, path)，其中* path *是带有消息 ID * id *的文章的目录路径。这是可选的 NNTP 扩展，并非所有服务器都支持。

• NNTP. quit ( )

  • 发送QUIT命令并关闭连接。调用此方法后，不应再调用 NNTP 对象的其他方法。