uTools-Manuals/docs/python/ftplib.html

<div class="body" role="main"><div class="section" id="module-ftplib"><h1><span class="yiyi-st" id="yiyi-10">21.13 <a class="reference internal" href="#module-ftplib" title="ftplib: FTP protocol client (requires sockets)."><code class="xref py py-mod docutils literal"><span class="pre">ftplib</span></code></a>  -  FTP协议客户端</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/ftplib.py">Lib / ftplib.py</a></span></p><p><span class="yiyi-st" id="yiyi-12">此模块定义类<a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>和一些相关项目。</span><span class="yiyi-st" id="yiyi-13"><a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>类实现FTP协议的客户端。</span><span class="yiyi-st" id="yiyi-14">您可以使用它来编写执行各种自动FTP作业的Python程序，例如镜像其他FTP服务器。</span><span class="yiyi-st" id="yiyi-15">模块<a class="reference internal" href="urllib.request.html#module-urllib.request" title="urllib.request: Extensible library for opening URLs."><code class="xref py py-mod docutils literal"><span class="pre">urllib.request</span></code></a>也使用它来处理使用FTP的URL。</span><span class="yiyi-st" id="yiyi-16">有关FTP（文件传输协议）的详细信息，请参见Internet <span class="target" id="index-1"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc959.html"><strong>RFC 959</strong></a>。</span></p><p><span class="yiyi-st" id="yiyi-17">下面是使用<a class="reference internal" href="#module-ftplib" title="ftplib: FTP protocol client (requires sockets)."><code class="xref py py-mod docutils literal"><span class="pre">ftplib</span></code></a>模块的示例会话：</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">ftplib</span> <span class="k">import</span> <span class="n">FTP</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftp</span> <span class="o">=</span> <span class="n">FTP</span><span class="p">(</span><span class="s1">'ftp.debian.org'</span><span class="p">)</span>     <span class="c1"># connect to host, default port</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftp</span><span class="o">.</span><span class="n">login</span><span class="p">()</span>                     <span class="c1"># user anonymous, passwd anonymous@</span>
<span class="go">'230 Login successful.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftp</span><span class="o">.</span><span class="n">cwd</span><span class="p">(</span><span class="s1">'debian'</span><span class="p">)</span>               <span class="c1"># change into "debian" directory</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftp</span><span class="o">.</span><span class="n">retrlines</span><span class="p">(</span><span class="s1">'LIST'</span><span class="p">)</span>           <span class="c1"># list directory contents</span>
<span class="go">-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README</span>
<span class="gp">...</span>
<span class="go">drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool</span>
<span class="go">drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project</span>
<span class="go">drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools</span>
<span class="go">'226 Directory send OK.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftp</span><span class="o">.</span><span class="n">retrbinary</span><span class="p">(</span><span class="s1">'RETR README'</span><span class="p">,</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'README'</span><span class="p">,</span> <span class="s1">'wb'</span><span class="p">)</span><span class="o">.</span><span class="n">write</span><span class="p">)</span>
<span class="go">'226 Transfer complete.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftp</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-18">模块定义以下项目：</span></p><dl class="class"><dt id="ftplib.FTP"><span class="yiyi-st" id="yiyi-19"> <em class="property">class </em><code class="descclassname">ftplib.</code><code class="descname">FTP</code><span class="sig-paren">(</span><em>host=''</em>, <em>user=''</em>, <em>passwd=''</em>, <em>acct=''</em>, <em>timeout=None</em>, <em>source_address=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-20">返回<a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>类的新实例。</span><span class="yiyi-st" id="yiyi-21">当给定<em>主机</em>时，将调用<code class="docutils literal"><span class="pre">connect(host)</span></code>的方法。</span><span class="yiyi-st" id="yiyi-22">当给定<em>用户</em>时，另外方法调用<code class="docutils literal"><span class="pre">login（user，</span> <span class="pre">passwd，</span> <span class="pre">acct）</span> t1&gt;（当未给出时，<em>passwd</em>和<em>acct</em>默认为空字符串）。</code></span><span class="yiyi-st" id="yiyi-23">可选的<em>timeout</em>参数指定阻塞操作（例如连接尝试）的超时（如果未指定，将使用全局默认超时设置）。</span><span class="yiyi-st" id="yiyi-24"><em>source_address</em>是套接字绑定到其源地址的2元组<code class="docutils literal"><span class="pre">（host，</span> <span class="pre">port）</span> 连接。</code></span></p><p><span class="yiyi-st" id="yiyi-25"><a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>类支持<a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal"><span class="pre">with</span></code></a>语句，例如</span><span class="yiyi-st" id="yiyi-26">：</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">ftplib</span> <span class="k">import</span> <span class="n">FTP</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">FTP</span><span class="p">(</span><span class="s2">"ftp1.at.proftpd.org"</span><span class="p">)</span> <span class="k">as</span> <span class="n">ftp</span><span class="p">:</span>
<span class="gp">... </span>    <span class="n">ftp</span><span class="o">.</span><span class="n">login</span><span class="p">()</span>
<span class="gp">... </span>    <span class="n">ftp</span><span class="o">.</span><span class="n">dir</span><span class="p">()</span>
<span class="gp">... </span>
<span class="go">'230 Anonymous login ok, restrictions apply.'</span>
<span class="go">dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .</span>
<span class="go">dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..</span>
<span class="go">dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS</span>
<span class="go">dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora</span>
<span class="go">&gt;&gt;&gt;</span>
</code></pre><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-27"><span class="versionmodified">在版本3.2中已更改：</span>添加了对<a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal"><span class="pre">with</span></code></a>语句的支持。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-28"><span class="versionmodified">在版本3.3中已更改：</span> <em>source_address</em>参数已添加。</span></p></div></dd></dl><dl class="class"><dt id="ftplib.FTP_TLS"><span class="yiyi-st" id="yiyi-29"> <em class="property">class </em><code class="descclassname">ftplib.</code><code class="descname">FTP_TLS</code><span class="sig-paren">(</span><em>host=''</em>, <em>user=''</em>, <em>passwd=''</em>, <em>acct=''</em>, <em>keyfile=None</em>, <em>certfile=None</em>, <em>context=None</em>, <em>timeout=None</em>, <em>source_address=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-30">如<span class="target" id="index-2"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc4217.html"><strong>RFC 4217</strong></a>中所述的<a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>子类，它为FTP添加了TLS支持。</span><span class="yiyi-st" id="yiyi-31">像往常一样连接到端口21，在认证之前隐式地保护FTP控制连接。</span><span class="yiyi-st" id="yiyi-32">保护数据连接需要用户通过调用<a class="reference internal" href="#ftplib.FTP_TLS.prot_p" title="ftplib.FTP_TLS.prot_p"><code class="xref py py-meth docutils literal"><span class="pre">prot_p()</span></code></a>方法显式地要求它。</span><span class="yiyi-st" id="yiyi-33"><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-34">有关最佳做法，请参阅<a class="reference internal" href="ssl.html#ssl-security"><span>Security considerations</span></a>。</span></p><p><span class="yiyi-st" id="yiyi-35"><em>键文件</em>和<em>certfile</em>是<em>上下文</em>的传统替代方式 - 它们可以分别指向SSL的PEM格式的私钥和证书链文件连接。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-36"><span class="versionmodified">版本3.2中的新功能。</span></span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-37"><span class="versionmodified">在版本3.3中已更改：</span> <em>source_address</em>参数已添加。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-38"><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><p><span class="yiyi-st" id="yiyi-39">以下是使用<a class="reference internal" href="#ftplib.FTP_TLS" title="ftplib.FTP_TLS"><code class="xref py py-class docutils literal"><span class="pre">FTP_TLS</span></code></a>类的示例会话：</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ftps</span> <span class="o">=</span> <span class="n">FTP_TLS</span><span class="p">(</span><span class="s1">'ftp.pureftpd.org'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftps</span><span class="o">.</span><span class="n">login</span><span class="p">()</span>
<span class="go">'230 Anonymous user logged in'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftps</span><span class="o">.</span><span class="n">prot_p</span><span class="p">()</span>
<span class="go">'200 Data protection level set to "private"'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ftps</span><span class="o">.</span><span class="n">nlst</span><span class="p">()</span>
<span class="go">['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']</span>
</code></pre></dd></dl><dl class="exception"><dt id="ftplib.error_reply"><span class="yiyi-st" id="yiyi-40"> <em class="property">exception </em><code class="descclassname">ftplib.</code><code class="descname">error_reply</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-41">从服务器收到意外的响应时引发异常。</span></p></dd></dl><dl class="exception"><dt id="ftplib.error_temp"><span class="yiyi-st" id="yiyi-42"> <em class="property">exception </em><code class="descclassname">ftplib.</code><code class="descname">error_temp</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-43">当接收到表示临时错误（范围400-499的响应代码）的错误代码时引发异常。</span></p></dd></dl><dl class="exception"><dt id="ftplib.error_perm"><span class="yiyi-st" id="yiyi-44"> <em class="property">exception </em><code class="descclassname">ftplib.</code><code class="descname">error_perm</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-45">当接收到表示永久错误的错误代码（响应代码在500-599范围内）时引发异常。</span></p></dd></dl><dl class="exception"><dt id="ftplib.error_proto"><span class="yiyi-st" id="yiyi-46"> <em class="property">exception </em><code class="descclassname">ftplib.</code><code class="descname">error_proto</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-47">当从不适合文件传输协议的响应规范的服务器接收到回复时产生异常，即</span><span class="yiyi-st" id="yiyi-48">以1-5范围内的数字开始。</span></p></dd></dl><dl class="data"><dt id="ftplib.all_errors"><span class="yiyi-st" id="yiyi-49"> <code class="descclassname">ftplib.</code><code class="descname">all_errors</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-50"><a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>实例的方法可能由于FTP连接问题而引发的所有异常（作为元组）的集合（而不是调用者发出的编程错误）。</span><span class="yiyi-st" id="yiyi-51">此集包括上面列出的四个异常以及<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal"><span class="pre">OSError</span></code></a>。</span></p></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-52">也可以看看</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-53">模块<a class="reference internal" href="netrc.html#module-netrc" title="netrc: Loading of .netrc files."><code class="xref py py-mod docutils literal"><span class="pre">netrc</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-54">解析<code class="file docutils literal"><span class="pre">.netrc</span></code>文件格式。</span><span class="yiyi-st" id="yiyi-55">文件<code class="file docutils literal"><span class="pre">.netrc</span></code>通常由FTP客户端用于在提示用户之前加载用户认证信息。</span></dd></dl></div><div class="section" id="ftp-objects"><h2><span class="yiyi-st" id="yiyi-56">21.13.1. </span><span class="yiyi-st" id="yiyi-57">FTP对象</span></h2><p><span class="yiyi-st" id="yiyi-58">有几种方法有两种类型：一种用于处理文本文件，另一种用于二进制文件。</span><span class="yiyi-st" id="yiyi-59">这些命令以命令的形式命名，后面紧跟<code class="docutils literal"><span class="pre">lines</span></code>用于文本版本，<code class="docutils literal"><span class="pre">binary</span></code>用于二进制版本。</span></p><p><span class="yiyi-st" id="yiyi-60"><a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>实例具有以下方法：</span></p><dl class="method"><dt id="ftplib.FTP.set_debuglevel"><span class="yiyi-st" id="yiyi-61"> <code class="descclassname">FTP.</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-62">设置实例的调试级别。</span><span class="yiyi-st" id="yiyi-63">这控制打印的调试输出量。</span><span class="yiyi-st" id="yiyi-64">默认值<code class="docutils literal"><span class="pre">0</span></code>不产生调试输出。</span><span class="yiyi-st" id="yiyi-65">值<code class="docutils literal"><span class="pre">1</span></code>产生适量的调试输出，通常每个请求都有一行。</span><span class="yiyi-st" id="yiyi-66">值<code class="docutils literal"><span class="pre">2</span></code>或更高会产生最大调试输出量，记录在控制连接上发送和接收的每行。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.connect"><span class="yiyi-st" id="yiyi-67"> <code class="descclassname">FTP.</code><code class="descname">connect</code><span class="sig-paren">(</span><em>host=''</em>, <em>port=0</em>, <em>timeout=None</em>, <em>source_address=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-68">连接到给定的主机和端口。</span><span class="yiyi-st" id="yiyi-69">默认端口号为<code class="docutils literal"><span class="pre">21</span></code>，由FTP协议规范指定。</span><span class="yiyi-st" id="yiyi-70">很少需要指定其他端口号。</span><span class="yiyi-st" id="yiyi-71">对于每个实例，此函数只应调用一次；如果在创建实例时给出了主机，则不应该调用它。</span><span class="yiyi-st" id="yiyi-72">所有其他方法只能在连接完成后使用。</span><span class="yiyi-st" id="yiyi-73">可选的<em>timeout</em>参数指定连接尝试的超时（以秒为单位）。</span><span class="yiyi-st" id="yiyi-74">如果未传递<em>超时</em>，将使用全局默认超时设置。</span><span class="yiyi-st" id="yiyi-75"><em>source_address</em>是套接字绑定到其源地址的2元组<code class="docutils literal"><span class="pre">（host，</span> <span class="pre">port）</span> 连接。</code></span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-76"><span class="versionmodified">在版本3.3中已更改：</span> <em>source_address</em>参数已添加。</span></p></div></dd></dl><dl class="method"><dt id="ftplib.FTP.getwelcome"><span class="yiyi-st" id="yiyi-77"> <code class="descclassname">FTP.</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-78">返回服务器发送的欢迎消息以回复初始连接。</span><span class="yiyi-st" id="yiyi-79">（此消息有时包含可能与用户相关的免责声明或帮助信息。）</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.login"><span class="yiyi-st" id="yiyi-80"> <code class="descclassname">FTP.</code><code class="descname">login</code><span class="sig-paren">(</span><em>user='anonymous'</em>, <em>passwd=''</em>, <em>acct=''</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-81">以给定的<em>用户</em>登录。</span><span class="yiyi-st" id="yiyi-82"><em>passwd</em>和<em>acct</em>参数是可选的，默认为空字符串。</span><span class="yiyi-st" id="yiyi-83">如果未指定<em>用户</em>，则默认为<code class="docutils literal"><span class="pre">'anonymous'</span></code>。</span><span class="yiyi-st" id="yiyi-84">如果<em>用户</em>为<code class="docutils literal"><span class="pre">'anonymous'</span></code>，则默认<em>passwd</em>为<code class="docutils literal"><span class="pre">'anonymous@'</span></code>。</span><span class="yiyi-st" id="yiyi-85">在建立连接后，每个实例只应调用一次此函数；如果在创建实例时给出了主机和用户，则不应该调用它。</span><span class="yiyi-st" id="yiyi-86">大多数FTP命令仅在客户端登录后才允许。</span><span class="yiyi-st" id="yiyi-87"><em>acct</em>参数提供“会计信息”；很少有系统实现这一点。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.abort"><span class="yiyi-st" id="yiyi-88"> <code class="descclassname">FTP.</code><code class="descname">abort</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-89">中止正在进行的文件传输。</span><span class="yiyi-st" id="yiyi-90">使用这并不总是工作，但它值得一试。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.sendcmd"><span class="yiyi-st" id="yiyi-91"> <code class="descclassname">FTP.</code><code class="descname">sendcmd</code><span class="sig-paren">(</span><em>cmd</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-92">向服务器发送一个简单的命令字符串并返回响应字符串。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.voidcmd"><span class="yiyi-st" id="yiyi-93"> <code class="descclassname">FTP.</code><code class="descname">voidcmd</code><span class="sig-paren">(</span><em>cmd</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-94">向服务器发送一个简单的命令字符串并处理响应。</span><span class="yiyi-st" id="yiyi-95">如果接收到与成功（200-299范围内的代码）对应的响应代码，则不返回任何内容。</span><span class="yiyi-st" id="yiyi-96">引发<a class="reference internal" href="#ftplib.error_reply" title="ftplib.error_reply"><code class="xref py py-exc docutils literal"><span class="pre">error_reply</span></code></a>。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.retrbinary"><span class="yiyi-st" id="yiyi-97"> <code class="descclassname">FTP.</code><code class="descname">retrbinary</code><span class="sig-paren">(</span><em>cmd</em>, <em>callback</em>, <em>blocksize=8192</em>, <em>rest=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-98">以二进制传输模式检索文件。</span><span class="yiyi-st" id="yiyi-99"><em>cmd</em>应为适当的<code class="docutils literal"><span class="pre">RETR</span></code>命令：<code class="docutils literal"><span class="pre">'RETR</span> <span class="pre">filename'</span></code>。</span><span class="yiyi-st" id="yiyi-100">对于接收的每个数据块，调用<em>回调</em>函数，其中一个字符串参数给出数据块。</span><span class="yiyi-st" id="yiyi-101">可选的<em>块大小</em>参数指定在创建进行实际传输的低级套接字对象上读取的最大块大小（这也是传递到<em>回调）。</em></span><span class="yiyi-st" id="yiyi-102">选择合理的默认值。</span><span class="yiyi-st" id="yiyi-103"><em>rest</em>表示与<a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code class="xref py py-meth docutils literal"><span class="pre">transfercmd()</span></code></a>方法中的相同。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.retrlines"><span class="yiyi-st" id="yiyi-104"> <code class="descclassname">FTP.</code><code class="descname">retrlines</code><span class="sig-paren">(</span><em>cmd</em>, <em>callback=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-105">在ASCII传输模式下检索文件或目录列表。</span><span class="yiyi-st" id="yiyi-106"><em>cmd  t&gt;&gt;应为适当的<code class="docutils literal"><span class="pre">RETR</span></code>命令（见<a class="reference internal" href="#ftplib.FTP.retrbinary" title="ftplib.FTP.retrbinary"><code class="xref py py-meth docutils literal"><span class="pre">retrbinary()</span></code></a>）或命令，例如<code class="docutils literal"><span class="pre">LIST</span></code>或<code class="docutils literal"><span class="pre">NLST</span></code>（通常只是字符串<code class="docutils literal"><span class="pre">'LIST'</span></code>）。</em></span><span class="yiyi-st" id="yiyi-107"><code class="docutils literal"><span class="pre">LIST</span></code>检索文件列表和有关这些文件的信息。</span><span class="yiyi-st" id="yiyi-108"><code class="docutils literal"><span class="pre">NLST</span></code>检索文件名列表。</span><span class="yiyi-st" id="yiyi-109">每个具有字符串参数的行调用<em>回调</em>函数，该参数包含尾随CRLF被剥离的行。</span><span class="yiyi-st" id="yiyi-110">默认的<em>回调</em>会将行打印到<code class="docutils literal"><span class="pre">sys.stdout</span></code>。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.set_pasv"><span class="yiyi-st" id="yiyi-111"> <code class="descclassname">FTP.</code><code class="descname">set_pasv</code><span class="sig-paren">(</span><em>boolean</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-112">如果<em>boolean</em>为true，则启用“被动”模式，其他禁用被动模式。</span><span class="yiyi-st" id="yiyi-113">被动模式默认为开启。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.storbinary"><span class="yiyi-st" id="yiyi-114"> <code class="descclassname">FTP.</code><code class="descname">storbinary</code><span class="sig-paren">(</span><em>cmd</em>, <em>fp</em>, <em>blocksize=8192</em>, <em>callback=None</em>, <em>rest=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-115">以二进制传输模式存储文件。</span><span class="yiyi-st" id="yiyi-116"><em>cmd</em>应为适当的<code class="docutils literal"><span class="pre">STOR</span></code>命令：<code class="docutils literal"><span class="pre">“STOR</span> <span class="pre">filename”</span></code>。</span><span class="yiyi-st" id="yiyi-117"><em>fp</em>是大小为<em>的块中使用其<code class="xref py py-meth docutils literal"><span class="pre">read()</span></code>方法读取的EOF之前读取的<a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>块大小</em>以提供要存储的数据。</span><span class="yiyi-st" id="yiyi-118"><em>blocksize</em>参数默认为8192. <em>callback</em>是一个可选的单个参数可调用，在每个数据块发送后调用。</span><span class="yiyi-st" id="yiyi-119"><em>rest</em>表示与<a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code class="xref py py-meth docutils literal"><span class="pre">transfercmd()</span></code></a>方法中的相同。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-120"><span class="versionmodified">在版本3.2中更改：</span> <em>rest</em>参数添加。</span></p></div></dd></dl><dl class="method"><dt id="ftplib.FTP.storlines"><span class="yiyi-st" id="yiyi-121"> <code class="descclassname">FTP.</code><code class="descname">storlines</code><span class="sig-paren">(</span><em>cmd</em>, <em>fp</em>, <em>callback=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-122">以ASCII传输模式存储文件。</span><span class="yiyi-st" id="yiyi-123"><em>cmd</em>应为适当的<code class="docutils literal"><span class="pre">STOR</span></code>命令（请参阅<a class="reference internal" href="#ftplib.FTP.storbinary" title="ftplib.FTP.storbinary"><code class="xref py py-meth docutils literal"><span class="pre">storbinary()</span></code></a>）。</span><span class="yiyi-st" id="yiyi-124">从<a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> <em>fp</em>（以二进制模式打开）使用<a class="reference internal" href="io.html#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal"><span class="pre">readline()</span></code></a>方法读取行，直到EOF为止，以提供要存储的数据。</span><span class="yiyi-st" id="yiyi-125"><em>callback</em>是一个可选的单个参数callable，在每行发送后调用。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.transfercmd"><span class="yiyi-st" id="yiyi-126"> <code class="descclassname">FTP.</code><code class="descname">transfercmd</code><span class="sig-paren">(</span><em>cmd</em>, <em>rest=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-127">通过数据连接启动传输。</span><span class="yiyi-st" id="yiyi-128">如果传输处于活动状态，请发送<code class="docutils literal"><span class="pre">EPRT</span></code>或<code class="docutils literal"><span class="pre">PORT</span></code>命令和<em>cmd</em>指定的传输命令，并接受连接。</span><span class="yiyi-st" id="yiyi-129">如果服务器是被动的，发送<code class="docutils literal"><span class="pre">EPSV</span></code>或<code class="docutils literal"><span class="pre">PASV</span></code>命令，连接到它，并启动传输命令。</span><span class="yiyi-st" id="yiyi-130">无论哪种方式，返回连接的套接字。</span></p><p><span class="yiyi-st" id="yiyi-131">如果给出了可选的<em>rest</em>，则向服务器发送<code class="docutils literal"><span class="pre">REST</span></code>命令，将<em>rest</em>作为参数传递。</span><span class="yiyi-st" id="yiyi-132"><em>rest</em>通常是一个字节偏移到请求的文件，告诉服务器重新发送文件的字节在请求的偏移量，跳过初始字节。</span><span class="yiyi-st" id="yiyi-133">然而，请注意，RFC 959仅要求<em>rest</em>是包含从ASCII代码33到ASCII代码126的可打印范围中的字符的字符串。</span><span class="yiyi-st" id="yiyi-134">因此，<a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code class="xref py py-meth docutils literal"><span class="pre">transfercmd()</span></code></a>方法将<em>rest</em>转换为字符串，但不对字符串的内容执行检查。</span><span class="yiyi-st" id="yiyi-135">如果服务器不能识别<code class="docutils literal"><span class="pre">REST</span></code>命令，则会引发<a class="reference internal" href="#ftplib.error_reply" title="ftplib.error_reply"><code class="xref py py-exc docutils literal"><span class="pre">error_reply</span></code></a>异常。</span><span class="yiyi-st" id="yiyi-136">如果发生这种情况，只需调用<a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code class="xref py py-meth docutils literal"><span class="pre">transfercmd()</span></code></a>，而不使用<em>休息</em>参数。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.ntransfercmd"><span class="yiyi-st" id="yiyi-137"> <code class="descclassname">FTP.</code><code class="descname">ntransfercmd</code><span class="sig-paren">(</span><em>cmd</em>, <em>rest=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-138">像<a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code class="xref py py-meth docutils literal"><span class="pre">transfercmd()</span></code></a>，但返回数据连接的元组和数据的预期大小。</span><span class="yiyi-st" id="yiyi-139">如果无法计算预期大小，则会将<code class="docutils literal"><span class="pre">None</span></code>作为预期大小返回。</span><span class="yiyi-st" id="yiyi-140"><em>cmd</em>和<em>rest</em>表示与<a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code class="xref py py-meth docutils literal"><span class="pre">transfercmd()</span></code></a>中相同的内容。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.mlsd"><span class="yiyi-st" id="yiyi-141"> <code class="descclassname">FTP.</code><code class="descname">mlsd</code><span class="sig-paren">(</span><em>path=""</em>, <em>facts=[]</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-142">使用<code class="docutils literal"><span class="pre">MLSD</span></code>命令（<span class="target" id="index-3"></span> <a class="rfc reference external" href="https://tools.ietf.org/html/rfc3659.html"><strong>RFC 3659</strong></a>）以标准化格式列出目录。</span><span class="yiyi-st" id="yiyi-143">如果省略<em>路径</em>，则假定当前目录。</span><span class="yiyi-st" id="yiyi-144"><em>facts</em>是表示期望的信息类型的字符串列表（例如，</span><span class="yiyi-st" id="yiyi-145"><code class="docutils literal"><span class="pre">[“type”，</span> <span class="pre">“size”，</span> <span class="pre">“perm”]</span></code>）。</span><span class="yiyi-st" id="yiyi-146">返回一个生成器对象，为路径中找到的每个文件产生一个两个元素的元组。</span><span class="yiyi-st" id="yiyi-147">第一个元素是文件名，第二个元素是包含文件名的事实的字典。</span><span class="yiyi-st" id="yiyi-148">此字典的内容可能受到<em>facts</em>参数的限制，但服务器不能保证返回所有请求的事实。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-149"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div></dd></dl><dl class="method"><dt id="ftplib.FTP.nlst"><span class="yiyi-st" id="yiyi-150"> <code class="descclassname">FTP.</code><code class="descname">nlst</code><span class="sig-paren">(</span><em>argument</em><span class="optional">[</span>, <em>...</em><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-151">返回由<code class="docutils literal"><span class="pre">NLST</span></code>命令返回的文件名列表。</span><span class="yiyi-st" id="yiyi-152">可选的<em>参数</em>是要列出的目录（默认为当前服务器目录）。</span><span class="yiyi-st" id="yiyi-153">多个参数可用于将非标准选项传递到<code class="docutils literal"><span class="pre">NLST</span></code>命令。</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-154">注意</span></p><p class="last"><span class="yiyi-st" id="yiyi-155">如果您的服务器支持该命令，<a class="reference internal" href="#ftplib.FTP.mlsd" title="ftplib.FTP.mlsd"><code class="xref py py-meth docutils literal"><span class="pre">mlsd()</span></code></a>提供了更好的API。</span></p></div></dd></dl><dl class="method"><dt id="ftplib.FTP.dir"><span class="yiyi-st" id="yiyi-156"> <code class="descclassname">FTP.</code><code class="descname">dir</code><span class="sig-paren">(</span><em>argument</em><span class="optional">[</span>, <em>...</em><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-157">生成由<code class="docutils literal"><span class="pre">LIST</span></code>命令返回的目录列表，将其打印到标准输出。</span><span class="yiyi-st" id="yiyi-158">可选的<em>参数</em>是要列出的目录（默认为当前服务器目录）。</span><span class="yiyi-st" id="yiyi-159">多个参数可用于将非标准选项传递到<code class="docutils literal"><span class="pre">LIST</span></code>命令。</span><span class="yiyi-st" id="yiyi-160">如果最后一个参数是一个函数，它被用作<em>回调</em>函数，因为<a class="reference internal" href="#ftplib.FTP.retrlines" title="ftplib.FTP.retrlines"><code class="xref py py-meth docutils literal"><span class="pre">retrlines()</span></code></a>；默认打印到<code class="docutils literal"><span class="pre">sys.stdout</span></code>。</span><span class="yiyi-st" id="yiyi-161">此方法返回<code class="docutils literal"><span class="pre">None</span></code>。</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-162">注意</span></p><p class="last"><span class="yiyi-st" id="yiyi-163">如果您的服务器支持该命令，<a class="reference internal" href="#ftplib.FTP.mlsd" title="ftplib.FTP.mlsd"><code class="xref py py-meth docutils literal"><span class="pre">mlsd()</span></code></a>提供了更好的API。</span></p></div></dd></dl><dl class="method"><dt id="ftplib.FTP.rename"><span class="yiyi-st" id="yiyi-164"> <code class="descclassname">FTP.</code><code class="descname">rename</code><span class="sig-paren">(</span><em>fromname</em>, <em>toname</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-165">将服务器上的文件<em>fromname</em>重命名为<em>toname</em>。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.delete"><span class="yiyi-st" id="yiyi-166"> <code class="descclassname">FTP.</code><code class="descname">delete</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-167">从服务器中删除名为<em>filename</em>的文件。</span><span class="yiyi-st" id="yiyi-168">如果成功，则返回响应的文本，否则对许可错误引发<a class="reference internal" href="#ftplib.error_perm" title="ftplib.error_perm"><code class="xref py py-exc docutils literal"><span class="pre">error_perm</span></code></a>或对其他错误引发<a class="reference internal" href="#ftplib.error_reply" title="ftplib.error_reply"><code class="xref py py-exc docutils literal"><span class="pre">error_reply</span></code></a>。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.cwd"><span class="yiyi-st" id="yiyi-169"> <code class="descclassname">FTP.</code><code class="descname">cwd</code><span class="sig-paren">(</span><em>pathname</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-170">设置服务器上的当前目录。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.mkd"><span class="yiyi-st" id="yiyi-171"> <code class="descclassname">FTP.</code><code class="descname">mkd</code><span class="sig-paren">(</span><em>pathname</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-172">在服务器上创建一个新目录。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.pwd"><span class="yiyi-st" id="yiyi-173"> <code class="descclassname">FTP.</code><code class="descname">pwd</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-174">返回服务器上当前目录的路径名。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.rmd"><span class="yiyi-st" id="yiyi-175"> <code class="descclassname">FTP.</code><code class="descname">rmd</code><span class="sig-paren">(</span><em>dirname</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-176">删除服务器上名为<em>dirname</em>的目录。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.size"><span class="yiyi-st" id="yiyi-177"> <code class="descclassname">FTP.</code><code class="descname">size</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-178">请求服务器上名为<em>filename</em>的文件的大小。</span><span class="yiyi-st" id="yiyi-179">成功时，文件的大小作为整数返回，否则返回<code class="docutils literal"><span class="pre">None</span></code>。</span><span class="yiyi-st" id="yiyi-180">请注意，<code class="docutils literal"><span class="pre">SIZE</span></code>命令不是标准化的，但是被许多常见的服务器实现支持。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.quit"><span class="yiyi-st" id="yiyi-181"> <code class="descclassname">FTP.</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-182">向服务器发送<code class="docutils literal"><span class="pre">QUIT</span></code>命令并关闭连接。</span><span class="yiyi-st" id="yiyi-183">这是关闭连接的“礼貌”方式，但如果服务器对<code class="docutils literal"><span class="pre">QUIT</span></code>命令作出响应，它可能引发异常。</span><span class="yiyi-st" id="yiyi-184">这意味着调用<a class="reference internal" href="#ftplib.FTP.close" title="ftplib.FTP.close"><code class="xref py py-meth docutils literal"><span class="pre">close()</span></code></a>方法，该方法使得<a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>实例对后续调用不起作用（见下文）。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP.close"><span class="yiyi-st" id="yiyi-185"> <code class="descclassname">FTP.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-186">单向关闭连接。</span><span class="yiyi-st" id="yiyi-187">这不应该应用于已经关闭的连接，例如成功调用<a class="reference internal" href="#ftplib.FTP.quit" title="ftplib.FTP.quit"><code class="xref py py-meth docutils literal"><span class="pre">quit()</span></code></a>之后。</span><span class="yiyi-st" id="yiyi-188">在此调用之后，不应再使用<a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>实例（在调用<a class="reference internal" href="#ftplib.FTP.close" title="ftplib.FTP.close"><code class="xref py py-meth docutils literal"><span class="pre">close()</span></code></a>或<a class="reference internal" href="#ftplib.FTP.quit" title="ftplib.FTP.quit"><code class="xref py py-meth docutils literal"><span class="pre">quit()</span></code></a>后，无法重新打开连接通过发出另一个<a class="reference internal" href="#ftplib.FTP.login" title="ftplib.FTP.login"><code class="xref py py-meth docutils literal"><span class="pre">login()</span></code></a>方法）。</span></p></dd></dl></div><div class="section" id="ftp-tls-objects"><h2><span class="yiyi-st" id="yiyi-189">21.13.2. </span><span class="yiyi-st" id="yiyi-190">FTP_TLS对象</span></h2><p><span class="yiyi-st" id="yiyi-191"><a class="reference internal" href="#ftplib.FTP_TLS" title="ftplib.FTP_TLS"><code class="xref py py-class docutils literal"><span class="pre">FTP_TLS</span></code></a>类继承自<a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code class="xref py py-class docutils literal"><span class="pre">FTP</span></code></a>，定义这些其他对象：</span></p><dl class="attribute"><dt id="ftplib.FTP_TLS.ssl_version"><span class="yiyi-st" id="yiyi-192"> <code class="descclassname">FTP_TLS.</code><code class="descname">ssl_version</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-193">要使用的SSL版本（默认为<a class="reference internal" href="ssl.html#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code class="xref py py-attr docutils literal"><span class="pre">ssl.PROTOCOL_SSLv23</span></code></a>）。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP_TLS.auth"><span class="yiyi-st" id="yiyi-194"> <code class="descclassname">FTP_TLS.</code><code class="descname">auth</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-195">根据<a class="reference internal" href="#ftplib.FTP_TLS.ssl_version" title="ftplib.FTP_TLS.ssl_version"><code class="xref py py-attr docutils literal"><span class="pre">ssl_version</span></code></a>属性中指定的内容，使用TLS或SSL设置安全控制连接。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-196"><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><dl class="method"><dt id="ftplib.FTP_TLS.ccc"><span class="yiyi-st" id="yiyi-197"> <code class="descclassname">FTP_TLS.</code><code class="descname">ccc</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-198">将控制通道恢复为纯文本。</span><span class="yiyi-st" id="yiyi-199">这可以有利于利用防火墙知道如何使用非安全FTP处理NAT，而无需打开固定端口。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-200"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div></dd></dl><dl class="method"><dt id="ftplib.FTP_TLS.prot_p"><span class="yiyi-st" id="yiyi-201"> <code class="descclassname">FTP_TLS.</code><code class="descname">prot_p</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-202">设置安全数据连接。</span></p></dd></dl><dl class="method"><dt id="ftplib.FTP_TLS.prot_c"><span class="yiyi-st" id="yiyi-203"> <code class="descclassname">FTP_TLS.</code><code class="descname">prot_c</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-204">设置明文数据连接。</span></p></dd></dl></div></div></div>