poplib --- POP3 协议客户端

源代码： Lib/poplib.py

本模块定义了一个 POP3 类，该类封装了到 POP3 服务器的连接过程，并实现了 RFC 1939 中定义的协议。POP3 类同时支持 RFC 1939 中最小的和可选的命令集。POP3 类还支持在 RFC 2595 中引入的 STLS 命令，用于在已建立的连接上启用加密通信。

本模块额外提供一个 POP3_SSL 类，在连接到 POP3 服务器时，该类为使用 SSL 作为底层协议层提供了支持。

注意，尽管 POP3 具有广泛的支持，但它已经过时。POP3 服务器的实现质量差异很大，而且大多很糟糕。如果邮件服务器支持 IMAP，则最好使用 imaplib.IMAP4 类，因为 IMAP 服务器一般实现得更好。

The poplib module provides two classes:

class poplib.POP3(host, port=POP3_PORT[, timeout])

本类实现实际的 POP3 协议。实例初始化时，连接就会建立。如果省略 port，则使用标准 POP3 端口（110）。可选参数 timeout 指定连接尝试的超时时间（以秒为单位，如果未指定超时，将使用全局默认超时设置）。

Raises an auditing event poplib.connect with arguments self, host, port.

All commands will raise an auditing event poplib.putline with arguments self and line, where line is the bytes about to be sent to the remote host.

在 3.9 版更改: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)

一个 POP3 的子类，它使用经 SSL 加密的套接字连接到服务器。如果端口 port 未指定，则使用 995，它是标准的 POP3-over-SSL 端口。timeout 的作用与 POP3 构造函数中的相同。context 是一个可选的 ssl.SSLContext 对象，该对象可以将 SSL 配置选项、证书和私钥打包放入一个单独的（可以长久存在的）结构中。请阅读 安全考量 以获取最佳实践。

keyfile and certfile are a legacy alternative to context - they can point to PEM-formatted private key and certificate chain files, respectively, for the SSL connection.

Raises an auditing event poplib.connect with arguments self, host, port.

All commands will raise an auditing event poplib.putline with arguments self and line, where line is the bytes about to be sent to the remote host.

在 3.2 版更改: context parameter added.

在 3.4 版更改: 本类现在支持使用 ssl.SSLContext.check_hostname 和 服务器名称指示 （参阅 ssl.HAS_SNI）进行主机名检查。

3.6 版后已移除: keyfile 和 certfile 已弃用并转而推荐 context。 请改用 ssl.SSLContext.load_cert_chain() 或让 ssl.create_default_context() 为你选择系统所信任的 CA 证书。

在 3.9 版更改: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.

One exception is defined as an attribute of the poplib module:

exception poplib.error_proto

Exception raised on any errors from this module (errors from socket module are not caught). The reason for the exception is passed to the constructor as a string.

参见

Module imaplib

The standard Python IMAP module.

Frequently Asked Questions About Fetchmail

The FAQ for the fetchmail POP/IMAP client collects information on POP3 server variations and RFC noncompliance that may be useful if you need to write an application based on the POP protocol.

POP3 Objects

All POP3 commands are represented by methods of the same name, in lower-case; most return the response text sent by the server.

An POP3 instance has the following methods:

POP3.set_debuglevel(level)

设置实例的调试级别，它控制着调试信息的数量。默认值 0 不产生调试信息。值 1 产生中等数量的调试信息，通常每个请求产生一行。大于或等于 2 的值产生的调试信息最多，FTP 控制连接上发送和接收的每一行都将被记录下来。

POP3.getwelcome()

Returns the greeting string sent by the POP3 server.

POP3.capa()

Query the server's capabilities as specified in RFC 2449. Returns a dictionary in the form {'name': ['param'...]}.

3.4 新版功能.

POP3.user(username)

Send user command, response should indicate that a password is required.

POP3.pass_(password)

Send password, response includes message count and mailbox size. Note: the mailbox on the server is locked until quit() is called.

POP3.apop(user, secret)

Use the more secure APOP authentication to log into the POP3 server.

POP3.rpop(user)

Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.

POP3.stat()

Get mailbox status. The result is a tuple of 2 integers: (message count, mailbox size).

POP3.list([which])

Request message list, result is in the form (response, ['mesg_num octets', ...], octets). If which is set, it is the message to list.

POP3.retr(which)

Retrieve whole message number which, and set its seen flag. Result is in form (response, ['line', ...], octets).

POP3.dele(which)

Flag message number which for deletion. On most servers deletions are not actually performed until QUIT (the major exception is Eudora QPOP, which deliberately violates the RFCs by doing pending deletes on any disconnect).

POP3.rset()

Remove any deletion marks for the mailbox.

POP3.noop()

Do nothing. Might be used as a keep-alive.

POP3.quit()

Signoff: commit changes, unlock mailbox, drop connection.

POP3.top(which, howmuch)

Retrieves the message header plus howmuch lines of the message after the header of message number which. Result is in form (response, ['line', ...], octets).

The POP3 TOP command this method uses, unlike the RETR command, doesn't set the message's seen flag; unfortunately, TOP is poorly specified in the RFCs and is frequently broken in off-brand servers. Test this method by hand against the POP3 servers you will use before trusting it.

POP3.uidl(which=None)

Return message digest (unique id) list. If which is specified, result contains the unique id for that message in the form 'response mesgnum uid, otherwise result is list (response, ['mesgnum uid', ...], octets).

POP3.utf8()

Try to switch to UTF-8 mode. Returns the server response if successful, raises error_proto if not. Specified in RFC 6856.

3.5 新版功能.

POP3.stls(context=None)

Start a TLS session on the active connection as specified in RFC 2595. This is only allowed before user authentication

context parameter is a ssl.SSLContext object which allows bundling SSL configuration options, certificates and private keys into a single (potentially long-lived) structure. Please read 安全考量 for best practices.

This method supports hostname checking via ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

3.4 新版功能.

Instances of POP3_SSL have no additional methods. The interface of this subclass is identical to its parent.

POP3 Example

Here is a minimal example (without error checking) that opens a mailbox and retrieves and prints all messages:

import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
    for j in M.retr(i+1)[1]:
        print(j)

At the end of the module, there is a test section that contains a more extensive example of usage.