imaplib
— IMAP4 协议客户端
¶
源代码：
Lib/imaplib.py
此模块定义 3 个类，
IMAP4
,
IMAP4_SSL
and
IMAP4_stream
，封装到 IMAP4 服务器的连接和实现 IMAP4rev1 客户端协议的大子集作为定义在
RFC 2060
。它向后兼容 IMAP4 (
RFC 1730
) 服务器，但注意
STATUS
命令在 IMAP4 中不支持。
可用性
：非 WASI。
This module does not work or is not available on WebAssembly. See
WebAssembly 平台
了解更多信息。
3 个类的提供是通过
imaplib
模块，
IMAP4
是基类：
-
class
imaplib.
IMAP4
(
host
=
''
,
port
=
IMAP4_PORT
,
timeout
=
None
)
¶
-
此类实现实际 IMAP4 协议。创建连接并确定协议版本 (IMAP4 或 IMAP4rev1) 当初始化实例时。若
host
未指定，
''
(本地主机) 的使用。若
port
被省略，标准 IMAP4 端口 (143) 被使用。可选
timeout
parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is
None
, the global default socket timeout is used.
The
IMAP4
类支持
with
语句。当像这样使用时，IMAP4
LOGOUT
命令被自动发出当
with
语句退出。如：
>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
... M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
3.5 版改变：
支持
with
语句被添加。
3.9 版改变：
可选
timeout
参数被添加。
3 个异常被定义作为属性对于
IMAP4
类：
-
exception
IMAP4.
error
¶
-
由任何错误引发的异常。异常原因以字符串形式被传递给构造函数。
-
exception
IMAP4.
abort
¶
-
IMAP4 服务器错误导致此异常被引发。这是子类化的
IMAP4.error
。注意，关闭实例并实例化新的实例通常允许从此异常恢复。
-
exception
IMAP4.
readonly
¶
-
此异常被引发当通过服务器改变可写邮箱的状态时。这是子类化的
IMAP4.error
。某些其它客户端现在拥有写权限，但需要重新打开邮箱以重新获得写权限。
还有用于安全连接的子类：
-
class
imaplib.
IMAP4_SSL
(
host
=
''
,
port
=
IMAP4_SSL_PORT
,
*
,
ssl_context
=
None
,
timeout
=
None
)
¶
-
这是子类派生自
IMAP4
通过 SSL (安全套接字层) 加密套接字连接 (要使用此类需要采用 SSL 支持编译的套接字模块)。若
host
未指定，
''
(本地主机) 的使用。若
port
被省略，使用标准 IMAP4-over-SSL 端口 993。
ssl_context
是
ssl.SSLContext
对象允许捆绑 SSL 配置选项、证书及私钥成单一 (潜在长期存活) 结构。请阅读
安全注意事项
了解最佳实践。
可选
timeout
parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is
None
, the global default socket timeout is used.
3.3 版改变：
ssl_context
参数被添加。
3.4 版改变：
类现在支持主机名校验采用
ssl.SSLContext.check_hostname
and
SNI (服务器名称指示)
(见
ssl.HAS_SNI
).
3.9 版改变：
可选
timeout
参数被添加。
3.12 版改变：
The deprecated
keyfile
and
certfile
parameters have been removed.
第 2 个子类允许通过子级进程创建连接：
-
class
imaplib.
IMAP4_stream
(
命令
)
¶
-
这是子类派生自
IMAP4
连接到
stdin/stdout
文件描述符创建通过传递
命令
to
subprocess.Popen()
.
定义以下实用函数：
-
imaplib.
Internaldate2tuple
(
datestr
)
¶
-
剖析 IMAP4
INTERNALDATE
字符串并返回相应当地时间。返回值为
time.struct_time
元组或
None
如果字符串格式错误。
-
imaplib.
Int2AP
(
num
)
¶
-
将整数转换成字节表示使用字符来自集 [
A
..
P
].
-
imaplib.
ParseFlags
(
flagstr
)
¶
-
转换 IMAP4
FLAGS
响应成单个标志的元组。
-
imaplib.
Time2Internaldate
(
date_time
)
¶
-
转换
date_time
到 IMAP4
INTERNALDATE
表示。返回值是以下形式字符串：
"DD-Mmm-YYYY HH:MM:SS
+HHMM"
(包括双引号)。
date_time
argument can be a number (int or float) representing seconds since epoch (as returned by
time.time()
), a 9-tuple representing local time an instance of
time.struct_time
(如返回通过
time.localtime()
), an aware instance of
datetime.datetime
, or a double-quoted string. In the last case, it is assumed to already be in the correct format.
Note that IMAP4 message numbers change as the mailbox changes; in particular, after an
EXPUNGE
command performs deletions the remaining messages are renumbered. So it is highly advisable to use UIDs instead, with the UID command.
At the end of the module, there is a test section that contains a more extensive example of usage.
另请参阅
Documents describing the protocol, sources for servers implementing it, by the University of Washington’s IMAP Information Center can all be found at (
源代码
)
https://github.com/uw-imap/imap
(
无维护
).
IMAP4 对象
¶
All IMAP4rev1 commands are represented by methods of the same name, either uppercase or lowercase.
All arguments to commands are converted to strings, except for
AUTHENTICATE
, and the last argument to
APPEND
which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn’t enclosed with either parentheses or double quotes) each string is quoted. However, the
password
自变量到
LOGIN
command is always quoted. If you want to avoid having an argument string quoted (eg: the
flags
自变量对于
STORE
) then enclose the string in parentheses (eg:
r'(\Deleted)'
).
Each command returns a tuple:
(type, [data, ...])
where
type
通常是
'OK'
or
'NO'
，和
data
is either the text from the command response, or mandated results from the command. Each
data
is either a
bytes
, or a tuple. If a tuple, then the first part is the header of the response, and the second part contains the data (ie: ‘literal’ value).
The
message_set
options to commands below is a string specifying one or more messages to be acted upon. It may be a simple message number (
'1'
), a range of message numbers (
'2:4'
), or a group of non-contiguous ranges separated by commas (
'1:3,6:9'
). A range can contain an asterisk to indicate an infinite upper bound (
'3:*'
).
An
IMAP4
实例具有下列方法：
-
IMAP4.
append
(
mailbox
,
flags
,
date_time
,
message
)
¶
-
追加
message
到命名邮箱。
-
IMAP4.
authenticate
(
mechanism
,
authobject
)
¶
-
验证命令 - 要求响应处理。
mechanism
specifies which authentication mechanism is to be used - it should appear in the instance variable
capabilities
in the form
AUTH=mechanism
.
authobject
必须是可调用对象：
data = authobject(response)
IMAP4 范例
¶
这里是 (不带错误校验) 打开邮箱、检索和打印所有消息的最小范例：
import getpass, imaplib
M = imaplib.IMAP4(host='example.org')
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
typ, data = M.fetch(num, '(RFC822)')
print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()
