nntplib
— NNTP (网络新闻传输协议) 客户端
¶
源代码： Lib/nntplib.py
此模块定义类
NNTP
which implements the client side of the NNTP protocol. It can be used to implement a news reader or poster, or automated news processors. For more information on NNTP (Network News Transfer Protocol), see Internet
RFC 977
.
这里是如何使用它的 2 个小范例。要列出有关新闻组的一些统计和打印最后 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!'
To post an article from a file (this assumes that the article has valid headers, and that you have right to post on the particular newsgroup):
>>> s = NNTP('news.gmane.org') >>> f = open('articlefile') >>> s.post(f) '240 Article posted successfully.' >>> s.quit() '205 Bye!'
The module itself defines the following items:
nntplib.
NNTP
(
host[, port [, user[, password [, readermode] [, usenetrc]]]]
)
¶
返回新的实例化
NNTP
class, representing a connection to the NNTP server running on host
host
, listening at port
port
。默认
port
is 119. If the optional
user
and
password
are provided, or if suitable credentials are present in
/.netrc
and the optional flag
usenetrc
is true (the default), the
AUTHINFO USER
and
AUTHINFO
PASS
commands are used to identify and authenticate the user to the server. If the optional flag
readermode
is true, then a
mode reader
command is sent before authentication is performed. Reader mode is sometimes necessary if you are connecting to an NNTP server on the local machine and intend to call reader-specific commands, such as
group
. If you get unexpected
NNTPPermanentError
s, you might need to set
readermode
.
readermode
默认为
None
.
usenetrc
默认为
True
.
2.4 版改变： usenetrc argument added.
nntplib.
NNTPError
¶
派生自标准异常
Exception
, this is the base class for all exceptions raised by the
nntplib
模块。
nntplib.
NNTPReplyError
¶
Exception raised when an unexpected reply is received from the server. For backwards compatibility, the exception
error_reply
is equivalent to this class.
nntplib.
NNTPTemporaryError
¶
Exception raised when an error code in the range 400–499 is received. For backwards compatibility, the exception
error_temp
is equivalent to this class.
nntplib.
NNTPPermanentError
¶
Exception raised when an error code in the range 500–599 is received. For backwards compatibility, the exception
error_perm
is equivalent to this class.
nntplib.
NNTPProtocolError
¶
Exception raised when a reply is received from the server that does not begin with a digit in the range 1–5. For backwards compatibility, the exception
error_proto
is equivalent to this class.
nntplib.
NNTPDataError
¶
Exception raised when there is some error in the response data. For backwards compatibility, the exception
error_data
is equivalent to this class.
NNTP instances have the following methods. The response that is returned as the first item in the return tuple of almost all methods is the server’s response: a string beginning with a three-digit code. If the server’s response indicates an error, the method raises one of the above exceptions.
NNTP.
getwelcome
(
)
¶
Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.)
NNTP.
set_debuglevel
(
level
)
¶
Set the instance’s debugging level. This controls the amount of debugging output printed. The default,
0
, produces no debugging output. A value of
1
produces a moderate amount of debugging output, generally a single line per request or response. A value of
2
or higher produces the maximum amount of debugging output, logging each line sent and received on the connection (including message text).
NNTP.
newgroups
(
date
,
time
[
,
file
]
)
¶
发送
NEWGROUPS
命令。
date
argument should be a string of the form
'yymmdd'
indicating the date, and
time
should be a string of the form
'hhmmss'
indicating the time. Return a pair
(response, groups)
where
groups
is a list of group names that are new since the given date and time. If the
file
parameter is supplied, then the output of the
NEWGROUPS
command is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the command output. If
file
is supplied, then the returned
list
是空列表。
NNTP.
newnews
(
group
,
date
,
time
[
,
file
]
)
¶
发送
NEWNEWS
command. Here,
group
is a group name or
'*'
，和
date
and
time
have the same meaning as for
newgroups()
. Return a pair
(response, articles)
where
articles
is a list of message ids. If the
file
parameter is supplied, then the output of the
NEWNEWS
command is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the command output. If
file
is supplied, then the returned
list
是空列表。
NNTP.
list
(
[
file
]
)
¶
发送
LIST
command. Return a pair
(response, list)
where
list
is a list of tuples. Each tuple has the form
(group, last, first, flag)
，其中
group
is a group name,
last
and
第一
are the last and first article numbers (as strings), and
flag
is
'y'
if posting is allowed,
'n'
if not, and
'm'
if the newsgroup is moderated. (Note the ordering:
last
,
第一
.) If the
file
parameter is supplied, then the output of the
LIST
command is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the command output. If
file
is supplied, then the returned
list
是空列表。
NNTP.
descriptions
(
grouppattern
)
¶
发送
LIST NEWSGROUPS
命令，其中
grouppattern
is a wildmat string as specified in RFC2980 (it’s essentially the same as DOS or UNIX shell wildcard strings). Return a pair
(response, list)
，其中
list
is a list of tuples containing
(name, title)
.
2.4 版新增。
NNTP.
description
(
group
)
¶
Get a description for a single group group . If more than one group matches (if ‘group’ is a real wildmat string), return the first match. If no group matches, return an empty string.
This elides the response code from the server. If the response code is needed, use
descriptions()
.
2.4 版新增。
NNTP.
group
(
名称
)
¶
发送
GROUP
命令，其中
name
is the group name. Return a tuple
(response, count, first, last, name)
where
count
is the (estimated) number of articles in the group,
第一
is the first article number in the group,
last
is the last article number in the group, and
name
is the group name. The numbers are returned as strings.
NNTP.
help
(
[
file
]
)
¶
发送
HELP
command. Return a pair
(response, list)
where
list
is a list of help strings. If the
file
parameter is supplied, then the output of the
HELP
command is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the command output. If
file
is supplied, then the returned
list
是空列表。
NNTP.
stat
(
id
)
¶
发送
STAT
命令，其中
id
is the message id (enclosed in
'<'
and
'>'
) or an article number (as a string). Return a triple
(response,
number,
id)
where
number
is the article number (as a string) and
id
is the message id (enclosed in
'<'
and
'>'
).
NNTP.
head
(
id
)
¶
发送
HEAD
命令，其中
id
has the same meaning as for
stat()
. Return a tuple
(response, number, id, list)
where the first three are the same as for
stat()
，和
list
is a list of the article’s headers (an uninterpreted list of lines, without trailing newlines).
NNTP.
body
(
id
[
,
file
]
)
¶
发送
BODY
命令，其中
id
has the same meaning as for
stat()
。若
file
parameter is supplied, then the body is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the body. Return as for
head()
。若
file
is supplied, then the returned
list
是空列表。
NNTP.
slave
(
)
¶
发送
SLAVE
command. Return the server’s
response
.
NNTP.
xhdr
(
header
,
string
[
,
file
]
)
¶
发送
XHDR
command. This command is not defined in the RFC but is a common extension. The
header
argument is a header keyword, e.g.
'subject'
。
string
argument should have the form
'first-last'
where
第一
and
last
are the first and last article numbers to search. Return a pair
(response, list)
，其中
list
is a list of pairs
(id,
text)
，其中
id
is an article number (as a string) and
text
is the text of the requested header for that article. If the
file
parameter is supplied, then the output of the
XHDR
command is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the command output. If
file
is supplied, then the returned
list
是空列表。
NNTP.
post
(
file
)
¶
Post an article using the
POST
命令。
file
argument is an open file object which is read until EOF using its
readline()
method. It should be a well-formed news article, including the required headers. The
post()
method automatically escapes lines beginning with
.
.
NNTP.
ihave
(
id
,
file
)
¶
发送
IHAVE
命令。
id
is a message id (enclosed in
'<'
and
'>'
). If the response is not an error, treat
file
exactly as for the
post()
方法。
NNTP.
date
(
)
¶
返回 3 元组
(response, date, time)
, containing the current date and time in a form suitable for the
newnews()
and
newgroups()
methods. This is an optional NNTP extension, and may not be supported by all servers.
NNTP.
xgtitle
(
名称
[
,
file
]
)
¶
Process an
XGTITLE
command, returning a pair
(response, list)
，其中
list
is a list of tuples containing
(name, title)
。若
file
parameter is supplied, then the output of the
XGTITLE
command is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the command output. If
file
is supplied, then the returned
list
is an empty list. This is an optional NNTP extension, and may not be supported by all servers.
RFC2980 says “It is suggested that this extension be deprecated”. Use
descriptions()
or
description()
代替。
NNTP.
xover
(
start
,
end
[
,
file
]
)
¶
返回一对
(resp, list)
.
list
is a list of tuples, one for each article in the range delimited by the
start
and
end
article numbers. Each tuple is of the form
(article number, subject, poster, date, id, references,
size, lines)
。若
file
parameter is supplied, then the output of the
XOVER
command is stored in a file. If
file
is a string, then the method will open a file object with that name, write to it then close it. If
file
is a file object, then it will start calling
write()
on it to store the lines of the command output. If
file
is supplied, then the returned
list
is an empty list. This is an optional NNTP extension, and may not be supported by all servers.
NNTP.
xpath
(
id
)
¶
返回一对
(resp, path)
，其中
path
is the directory path to the article with message ID
id
. This is an optional NNTP extension, and may not be supported by all servers.
NNTP.
quit
(
)
¶
发送
QUIT
command and close the connection. Once this method has been called, no other methods of the NNTP object should be called.