uTools-Manuals/docs/python/poplib.html

<div class="body" role="main"><div class="section" id="module-poplib"><h1><span class="yiyi-st" id="yiyi-10">21.14. <a class="reference internal" href="#module-poplib" title="poplib: POP3 protocol client (requires sockets)."><code class="xref py py-mod docutils literal"><span class="pre">poplib</span></code></a>  -  POP3协议客户端</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>源代码：</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/poplib.py">Lib / poplib.py</a></span></p><p><span class="yiyi-st" id="yiyi-12">此模块定义了一个类<a class="reference internal" href="#poplib.POP3" title="poplib.POP3"><code class="xref py py-class docutils literal"><span class="pre">POP3</span></code></a>，它封装了到POP3服务器的连接，并实现了<span class="target" id="index-1"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc1939.html"><strong>RFC 1939</strong></a>中定义的协议。</span><span class="yiyi-st" id="yiyi-13"><a class="reference internal" href="#poplib.POP3" title="poplib.POP3"><code class="xref py py-class docutils literal"><span class="pre">POP3</span></code></a>类支持<span class="target" id="index-2"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc1939.html"><strong>RFC 1939</strong></a>的最小和可选命令集。</span><span class="yiyi-st" id="yiyi-14"><a class="reference internal" href="#poplib.POP3" title="poplib.POP3"><code class="xref py py-class docutils literal"><span class="pre">POP3</span></code></a>类还支持在<span class="target" id="index-3"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc2595.html"><strong>RFC 2595</strong></a>中引入的<code class="docutils literal"><span class="pre">STLS</span></code>命令，以在已建立的连接上启用加密通信。</span></p><p><span class="yiyi-st" id="yiyi-15">此外，此模块还提供了一个类<a class="reference internal" href="#poplib.POP3_SSL" title="poplib.POP3_SSL"><code class="xref py py-class docutils literal"><span class="pre">POP3_SSL</span></code></a>，它支持连接到使用SSL作为基础协议层的POP3服务器。</span></p><p><span class="yiyi-st" id="yiyi-16">请注意，虽然广泛支持，POP3是过时的。</span><span class="yiyi-st" id="yiyi-17">POP3服务器的实现质量差异很大，太多的都相当差。</span><span class="yiyi-st" id="yiyi-18">如果您的邮件服务器支持IMAP，则最好使用<a class="reference internal" href="imaplib.html#imaplib.IMAP4" title="imaplib.IMAP4"><code class="xref py py-class docutils literal"><span class="pre">imaplib.IMAP4</span></code></a>类，因为IMAP服务器往往会更好地实现。</span></p><p><span class="yiyi-st" id="yiyi-19"><a class="reference internal" href="#module-poplib" title="poplib: POP3 protocol client (requires sockets)."><code class="xref py py-mod docutils literal"><span class="pre">poplib</span></code></a>模块提供了两个类：</span></p><dl class="class"><dt id="poplib.POP3"><span class="yiyi-st" id="yiyi-20"> <em class="property">class </em><code class="descclassname">poplib.</code><code class="descname">POP3</code><span class="sig-paren">(</span><em>host</em>, <em>port=POP3_PORT</em><span class="optional">[</span>, <em>timeout</em><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-21">这个类实现了实际的POP3协议。</span><span class="yiyi-st" id="yiyi-22">当实例初始化时创建连接。</span><span class="yiyi-st" id="yiyi-23">如果省略<em>端口</em>，则使用标准POP3端口（110）。</span><span class="yiyi-st" id="yiyi-24">可选的<em>timeout</em>参数指定连接尝试的超时（以秒为单位）（如果未指定，将使用全局默认超时设置）。</span></p></dd></dl><dl class="class"><dt id="poplib.POP3_SSL"><span class="yiyi-st" id="yiyi-25"> <em class="property">class </em><code class="descclassname">poplib.</code><code class="descname">POP3_SSL</code><span class="sig-paren">(</span><em>host</em>, <em>port=POP3_SSL_PORT</em>, <em>keyfile=None</em>, <em>certfile=None</em>, <em>timeout=None</em>, <em>context=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-26">这是<a class="reference internal" href="#poplib.POP3" title="poplib.POP3"><code class="xref py py-class docutils literal"><span class="pre">POP3</span></code></a>的子类，通过SSL加密的套接字连接到服务器。</span><span class="yiyi-st" id="yiyi-27">如果未指定<em>端口</em>，则使用标准的POP3 over SSL端口。</span><span class="yiyi-st" id="yiyi-28"><em>超时</em>的工作方式与<a class="reference internal" href="#poplib.POP3" title="poplib.POP3"><code class="xref py py-class docutils literal"><span class="pre">POP3</span></code></a>构造函数中的相同。</span><span class="yiyi-st" id="yiyi-29"><em>上下文</em>是可选的<a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal"><span class="pre">ssl.SSLContext</span></code></a>对象，允许将SSL配置选项，证书和私钥捆绑到单个（可能长期）结构中。</span><span class="yiyi-st" id="yiyi-30">有关最佳做法，请参阅<a class="reference internal" href="ssl.html#ssl-security"><span>Security considerations</span></a>。</span></p><p><span class="yiyi-st" id="yiyi-31"><em>键文件</em>和<em>certfile</em>是<em>上下文</em>的传统替代方式 - 它们可以分别指向SSL的PEM格式的私钥和证书链文件连接。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-32"><span class="versionmodified">在版本3.2中更改：</span> <em>上下文</em>参数添加。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-33"><span class="versionmodified">在版本3.4中更改：</span>此类现在支持使用<a class="reference internal" href="ssl.html#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code class="xref py py-attr docutils literal"><span class="pre">ssl.SSLContext.check_hostname</span></code></a>和<em>服务器名称指示</em>（请参阅<a class="reference internal" href="ssl.html#ssl.HAS_SNI" title="ssl.HAS_SNI"><code class="xref py py-data docutils literal"><span class="pre">ssl.HAS_SNI</span></code></a>）。</span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-34">一个例外被定义为<a class="reference internal" href="#module-poplib" title="poplib: POP3 protocol client (requires sockets)."><code class="xref py py-mod docutils literal"><span class="pre">poplib</span></code></a>模块的属性：</span></p><dl class="exception"><dt id="poplib.error_proto"><span class="yiyi-st" id="yiyi-35"> <em class="property">exception </em><code class="descclassname">poplib.</code><code class="descname">error_proto</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-36">对此模块的任何错误引发的异常（未捕获来自<a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal"><span class="pre">socket</span></code></a>模块的错误）。</span><span class="yiyi-st" id="yiyi-37">异常的原因作为字符串传递给构造函数。</span></p></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-38">也可以看看</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-39">模块<a class="reference internal" href="imaplib.html#module-imaplib" title="imaplib: IMAP4 protocol client (requires sockets)."><code class="xref py py-mod docutils literal"><span class="pre">imaplib</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-40">标准的Python IMAP模块。</span></dd><dt><span class="yiyi-st" id="yiyi-41"><a class="reference external" href="http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html">关于Fetchmail的常见问题</a></span></dt><dd><span class="yiyi-st" id="yiyi-42"><strong class="program">fetchmail</strong> POP / IMAP客户端的常见问题解答收集有关POP3服务器变体和RFC不符合的信息，如果您需要基于POP协议编写应用程序，这些信息可能很有用。</span></dd></dl></div><div class="section" id="pop3-objects"><h2><span class="yiyi-st" id="yiyi-43">21.14.1. </span><span class="yiyi-st" id="yiyi-44">POP3 Objects</span></h2><p><span class="yiyi-st" id="yiyi-45">所有POP3命令由相同名称的方法表示，小写；最多返回服务器发送的响应文本。</span></p><p><span class="yiyi-st" id="yiyi-46"><a class="reference internal" href="#poplib.POP3" title="poplib.POP3"><code class="xref py py-class docutils literal"><span class="pre">POP3</span></code></a>实例具有以下方法：</span></p><dl class="method"><dt id="poplib.POP3.set_debuglevel"><span class="yiyi-st" id="yiyi-47"> <code class="descclassname">POP3.</code><code class="descname">set_debuglevel</code><span class="sig-paren">(</span><em>level</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-48">设置实例的调试级别。</span><span class="yiyi-st" id="yiyi-49">这控制打印的调试输出量。</span><span class="yiyi-st" id="yiyi-50">默认值<code class="docutils literal"><span class="pre">0</span></code>不产生调试输出。</span><span class="yiyi-st" id="yiyi-51">值<code class="docutils literal"><span class="pre">1</span></code>产生适量的调试输出，通常每个请求都有一行。</span><span class="yiyi-st" id="yiyi-52">值<code class="docutils literal"><span class="pre">2</span></code>或更高会产生最大调试输出量，记录在控制连接上发送和接收的每行。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.getwelcome"><span class="yiyi-st" id="yiyi-53"> <code class="descclassname">POP3.</code><code class="descname">getwelcome</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-54">返回由POP3服务器发送的问候字符串。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.capa"><span class="yiyi-st" id="yiyi-55"> <code class="descclassname">POP3.</code><code class="descname">capa</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-56">查询<span class="target" id="index-4"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc2449.html"><strong>RFC 2449</strong></a>中指定的服务器功能。</span><span class="yiyi-st" id="yiyi-57">以<code class="docutils literal"><span class="pre">{'name'：</span> <span class="pre">['param'...]}</span></code>的形式返回字典。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-58"><span class="versionmodified">版本3.4中的新功能。</span></span></p></div></dd></dl><dl class="method"><dt id="poplib.POP3.user"><span class="yiyi-st" id="yiyi-59"> <code class="descclassname">POP3.</code><code class="descname">user</code><span class="sig-paren">(</span><em>username</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-60">发送用户命令，响应应该指示需要密码。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.pass_"><span class="yiyi-st" id="yiyi-61"> <code class="descclassname">POP3.</code><code class="descname">pass_</code><span class="sig-paren">(</span><em>password</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-62">发送密码，响应包括邮件数量和邮箱大小。</span><span class="yiyi-st" id="yiyi-63">注意：服务器上的邮箱被锁定，直到调用<code class="xref py py-meth docutils literal"><span class="pre">quit()</span></code>。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.apop"><span class="yiyi-st" id="yiyi-64"> <code class="descclassname">POP3.</code><code class="descname">apop</code><span class="sig-paren">(</span><em>user</em>, <em>secret</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-65">使用更安全的APOP身份验证登录POP3服务器。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.rpop"><span class="yiyi-st" id="yiyi-66"> <code class="descclassname">POP3.</code><code class="descname">rpop</code><span class="sig-paren">(</span><em>user</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-67">使用RPOP认证（类似于UNIX r命令）登录到POP3服务器。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.stat"><span class="yiyi-st" id="yiyi-68"> <code class="descclassname">POP3.</code><code class="descname">stat</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-69">获取邮箱状态。</span><span class="yiyi-st" id="yiyi-70">结果是2个整数的元组：<code class="docutils literal"><span class="pre">（message</span> <span class="pre">count，</span> <span class="pre">mailbox</span> <span class="pre">size）</span>  t0 &gt;。</code></span></p></dd></dl><dl class="method"><dt id="poplib.POP3.list"><span class="yiyi-st" id="yiyi-71"> <code class="descclassname">POP3.</code><code class="descname">list</code><span class="sig-paren">(</span><span class="optional">[</span><em>which</em><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-72">请求消息列表，结果为<code class="docutils literal"><span class="pre">（响应，</span> <span class="pre">['mesg_num</span> <span class="pre">octets'，</span> <span class="pre">...] </span> <span class="pre">octets）</span></code>。</span><span class="yiyi-st" id="yiyi-73">如果<em>其中</em>设置，它是要列出的消息。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.retr"><span class="yiyi-st" id="yiyi-74"> <code class="descclassname">POP3.</code><code class="descname">retr</code><span class="sig-paren">(</span><em>which</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-75">检索整个消息号<em>其中</em>，并设置其看到的标志。</span><span class="yiyi-st" id="yiyi-76">结果为<code class="docutils literal"><span class="pre">（响应，</span> <span class="pre">['line'，</span> <span class="pre">...]，</span> <span class="pre">八位字节）</span> </code>。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.dele"><span class="yiyi-st" id="yiyi-77"> <code class="descclassname">POP3.</code><code class="descname">dele</code><span class="sig-paren">(</span><em>which</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-78">标志消息号<em>其中</em>用于删除。</span><span class="yiyi-st" id="yiyi-79">在大多数服务器上，删除实际上不执行，直到QUIT（主要例外是Eudora QPOP，故意违反RFC通过在任何断开连接进行挂起删除）。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.rset"><span class="yiyi-st" id="yiyi-80"> <code class="descclassname">POP3.</code><code class="descname">rset</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-81">删除邮箱的所有删除标记。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.noop"><span class="yiyi-st" id="yiyi-82"> <code class="descclassname">POP3.</code><code class="descname">noop</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-83">没做什么。</span><span class="yiyi-st" id="yiyi-84">可能用作保持活动。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.quit"><span class="yiyi-st" id="yiyi-85"> <code class="descclassname">POP3.</code><code class="descname">quit</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-86">注销：提交更改，解锁邮箱，删除连接。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.top"><span class="yiyi-st" id="yiyi-87"> <code class="descclassname">POP3.</code><code class="descname">top</code><span class="sig-paren">(</span><em>which</em>, <em>howmuch</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-88">检索邮件标头<em>&gt;</em>之后的邮件标头和<em>howmuch</em>行。</span><span class="yiyi-st" id="yiyi-89">结果为<code class="docutils literal"><span class="pre">（响应，</span> <span class="pre">['line'，</span> <span class="pre">...]，</span> <span class="pre">八位字节）</span> </code>。</span></p><p><span class="yiyi-st" id="yiyi-90">与RETR命令不同，此方法使用的POP3 TOP命令不设置消息的见过标志；不幸的是，TOP在RFC中指定不好，并且经常在非品牌服务器上断开。</span><span class="yiyi-st" id="yiyi-91">手动测试此方法对您将使用的POP3服务器在信任它之前。</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.uidl"><span class="yiyi-st" id="yiyi-92"> <code class="descclassname">POP3.</code><code class="descname">uidl</code><span class="sig-paren">(</span><em>which=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-93">返回消息摘要（唯一ID）列表。</span><span class="yiyi-st" id="yiyi-94">If <em>which</em> is specified, result contains the unique id for that message in the form <code class="docutils literal"><span class="pre">'response</span> <span class="pre">mesgnum</span> <span class="pre">uid</span></code>, otherwise result is list <code class="docutils literal"><span class="pre">(response,</span> <span class="pre">['mesgnum</span> <span class="pre">uid',</span> <span class="pre">...],</span> <span class="pre">octets)</span></code>.</span></p></dd></dl><dl class="method"><dt id="poplib.POP3.utf8"><span class="yiyi-st" id="yiyi-95"> <code class="descclassname">POP3.</code><code class="descname">utf8</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-96">尝试切换到UTF-8模式。</span><span class="yiyi-st" id="yiyi-97">如果成功，返回服务器响应，如果不成功，则引发<a class="reference internal" href="#poplib.error_proto" title="poplib.error_proto"><code class="xref py py-class docutils literal"><span class="pre">error_proto</span></code></a>。</span><span class="yiyi-st" id="yiyi-98">在<span class="target" id="index-5"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc6856.html"><strong>RFC 6856</strong></a>中指定。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-99"><span class="versionmodified">版本3.5中的新功能。</span></span></p></div></dd></dl><dl class="method"><dt id="poplib.POP3.stls"><span class="yiyi-st" id="yiyi-100"> <code class="descclassname">POP3.</code><code class="descname">stls</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-101">按照<span class="target" id="index-6"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc2595.html"><strong>RFC 2595</strong></a>中指定的在活动连接上启动TLS会话。</span><span class="yiyi-st" id="yiyi-102">这只有在用户身份验证之前才允许</span></p><p><span class="yiyi-st" id="yiyi-103"><em>上下文</em>参数是一个<a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal"><span class="pre">ssl.SSLContext</span></code></a>对象，它允许将SSL配置选项，证书和私钥捆绑到单个（可能长期）结构中。</span><span class="yiyi-st" id="yiyi-104">有关最佳做法，请参阅<a class="reference internal" href="ssl.html#ssl-security"><span>Security considerations</span></a>。</span></p><p><span class="yiyi-st" id="yiyi-105">此方法支持通过<a class="reference internal" href="ssl.html#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code class="xref py py-attr docutils literal"><span class="pre">ssl.SSLContext.check_hostname</span></code></a>和<em>服务器名称指示</em>（请参阅<a class="reference internal" href="ssl.html#ssl.HAS_SNI" title="ssl.HAS_SNI"><code class="xref py py-data docutils literal"><span class="pre">ssl.HAS_SNI</span></code></a>）进行主机名检查。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-106"><span class="versionmodified">版本3.4中的新功能。</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-107"><a class="reference internal" href="#poplib.POP3_SSL" title="poplib.POP3_SSL"><code class="xref py py-class docutils literal"><span class="pre">POP3_SSL</span></code></a>的实例没有其他方法。</span><span class="yiyi-st" id="yiyi-108">此子类的接口与其父类相同。</span></p></div><div class="section" id="pop3-example"><h2><span class="yiyi-st" id="yiyi-109">21.14.2. </span><span class="yiyi-st" id="yiyi-110">POP3 Example</span></h2><p><span class="yiyi-st" id="yiyi-111">下面是一个打开邮箱并检索和打印所有邮件的最小示例（无错误检查）：</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">getpass</span><span class="o">,</span> <span class="nn">poplib</span>

<span class="n">M</span> <span class="o">=</span> <span class="n">poplib</span><span class="o">.</span><span class="n">POP3</span><span class="p">(</span><span class="s1">'localhost'</span><span class="p">)</span>
<span class="n">M</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="n">getpass</span><span class="o">.</span><span class="n">getuser</span><span class="p">())</span>
<span class="n">M</span><span class="o">.</span><span class="n">pass_</span><span class="p">(</span><span class="n">getpass</span><span class="o">.</span><span class="n">getpass</span><span class="p">())</span>
<span class="n">numMessages</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">M</span><span class="o">.</span><span class="n">list</span><span class="p">()[</span><span class="mi">1</span><span class="p">])</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">numMessages</span><span class="p">):</span>
    <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">M</span><span class="o">.</span><span class="n">retr</span><span class="p">(</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">)[</span><span class="mi">1</span><span class="p">]:</span>
        <span class="nb">print</span><span class="p">(</span><span class="n">j</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-112">在模块的结尾，有一个测试部分，其中包含更广泛的使用示例。</span></p></div></div></div>