diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/python~3.12/library%2Fftplib.html | |
new repository
Diffstat (limited to 'devdocs/python~3.12/library%2Fftplib.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fftplib.html | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fftplib.html b/devdocs/python~3.12/library%2Fftplib.html new file mode 100644 index 00000000..6c90c34c --- /dev/null +++ b/devdocs/python~3.12/library%2Fftplib.html @@ -0,0 +1,161 @@ + <span id="ftplib-ftp-protocol-client"></span><h1>ftplib — FTP protocol client</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/ftplib.py">Lib/ftplib.py</a></p> <p>This module defines the class <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> and a few related items. The <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> class implements the client side of the FTP protocol. You can use this to write Python programs that perform a variety of automated FTP jobs, such as mirroring other FTP servers. It is also used by the module <a class="reference internal" href="urllib.request#module-urllib.request" title="urllib.request: Extensible library for opening URLs."><code>urllib.request</code></a> to handle URLs that use FTP. For more information on FTP (File Transfer Protocol), see internet <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc959.html"><strong>RFC 959</strong></a>.</p> <p>The default encoding is UTF-8, following <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2640.html"><strong>RFC 2640</strong></a>.</p> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p> <p>This module does not work or is not available on WebAssembly platforms <code>wasm32-emscripten</code> and <code>wasm32-wasi</code>. See <a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p> </div> <p>Here’s a sample session using the <a class="reference internal" href="#module-ftplib" title="ftplib: FTP protocol client (requires sockets)."><code>ftplib</code></a> module:</p> <pre data-language="python">>>> from ftplib import FTP +>>> ftp = FTP('ftp.us.debian.org') # connect to host, default port +>>> ftp.login() # user anonymous, passwd anonymous@ +'230 Login successful.' +>>> ftp.cwd('debian') # change into "debian" directory +'250 Directory successfully changed.' +>>> ftp.retrlines('LIST') # list directory contents +-rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README +... +drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool +drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project +drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools +'226 Directory send OK.' +>>> with open('README', 'wb') as fp: +>>> ftp.retrbinary('RETR README', fp.write) +'226 Transfer complete.' +>>> ftp.quit() +'221 Goodbye.' +</pre> <p>The module defines the following items:</p> <dl class="py class"> <dt class="sig sig-object py" id="ftplib.FTP"> +<code>class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')</code> </dt> <dd> +<p>Return a new instance of the <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> class. When <em>host</em> is given, the method call <code>connect(host)</code> is made. When <em>user</em> is given, additionally the method call <code>login(user, passwd, acct)</code> is made (where <em>passwd</em> and <em>acct</em> default to the empty string when not given). The optional <em>timeout</em> parameter specifies a timeout in seconds for blocking operations like the connection attempt (if is not specified, the global default timeout setting will be used). <em>source_address</em> is a 2-tuple <code>(host, port)</code> for the socket to bind to as its source address before connecting. The <em>encoding</em> parameter specifies the encoding for directories and filenames.</p> <p>The <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> class supports the <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement, e.g.:</p> <pre data-language="python">>>> from ftplib import FTP +>>> with FTP("ftp1.at.proftpd.org") as ftp: +... ftp.login() +... ftp.dir() +... +'230 Anonymous login ok, restrictions apply.' +dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 . +dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 .. +dr-xr-xr-x 5 ftp ftp 4096 May 6 10:43 CentOS +dr-xr-xr-x 3 ftp ftp 18 Jul 10 2008 Fedora +>>> +</pre> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Support for the <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>source_address</em> parameter was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>If the <em>timeout</em> parameter is set to be zero, it will raise a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> to prevent the creation of a non-blocking socket. The <em>encoding</em> parameter was added, and the default was changed from Latin-1 to UTF-8 to follow <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2640.html"><strong>RFC 2640</strong></a>.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py"> <span class="sig-name descname">FTP_TLS(host='', user='', passwd='', acct='', *, context=None,</span> +</dt> <dt class="sig sig-object py"> <span class="sig-name descname">timeout=None, source_address=None, encoding='utf-8')</span> +</dt> <dd> +<p>A <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> subclass which adds TLS support to FTP as described in <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc4217.html"><strong>RFC 4217</strong></a>. Connect as usual to port 21 implicitly securing the FTP control connection before authenticating. Securing the data connection requires the user to explicitly ask for it by calling the <code>prot_p()</code> method. <em>context</em> is a <a class="reference internal" href="ssl#ssl.SSLContext" title="ssl.SSLContext"><code>ssl.SSLContext</code></a> object which allows bundling SSL configuration options, certificates and private keys into a single (potentially long-lived) structure. Please read <a class="reference internal" href="ssl#ssl-security"><span class="std std-ref">Security considerations</span></a> for best practices.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>source_address</em> parameter was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>The class now supports hostname check with <a class="reference internal" href="ssl#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code>ssl.SSLContext.check_hostname</code></a> and <em>Server Name Indication</em> (see <a class="reference internal" href="ssl#ssl.HAS_SNI" title="ssl.HAS_SNI"><code>ssl.HAS_SNI</code></a>).</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>If the <em>timeout</em> parameter is set to be zero, it will raise a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> to prevent the creation of a non-blocking socket. The <em>encoding</em> parameter was added, and the default was changed from Latin-1 to UTF-8 to follow <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2640.html"><strong>RFC 2640</strong></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>The deprecated <em>keyfile</em> and <em>certfile</em> parameters have been removed.</p> </div> <p>Here’s a sample session using the <code>FTP_TLS</code> class:</p> <pre data-language="python">>>> ftps = FTP_TLS('ftp.pureftpd.org') +>>> ftps.login() +'230 Anonymous user logged in' +>>> ftps.prot_p() +'200 Data protection level set to "private"' +>>> ftps.nlst() +['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'] +</pre> </dd> +</dl> <dl class="py exception"> <dt class="sig sig-object py" id="ftplib.error_reply"> +<code>exception ftplib.error_reply</code> </dt> <dd> +<p>Exception raised when an unexpected reply is received from the server.</p> </dd> +</dl> <dl class="py exception"> <dt class="sig sig-object py" id="ftplib.error_temp"> +<code>exception ftplib.error_temp</code> </dt> <dd> +<p>Exception raised when an error code signifying a temporary error (response codes in the range 400–499) is received.</p> </dd> +</dl> <dl class="py exception"> <dt class="sig sig-object py" id="ftplib.error_perm"> +<code>exception ftplib.error_perm</code> </dt> <dd> +<p>Exception raised when an error code signifying a permanent error (response codes in the range 500–599) is received.</p> </dd> +</dl> <dl class="py exception"> <dt class="sig sig-object py" id="ftplib.error_proto"> +<code>exception ftplib.error_proto</code> </dt> <dd> +<p>Exception raised when a reply is received from the server that does not fit the response specifications of the File Transfer Protocol, i.e. begin with a digit in the range 1–5.</p> </dd> +</dl> <dl class="py data"> <dt class="sig sig-object py" id="ftplib.all_errors"> +<code>ftplib.all_errors</code> </dt> <dd> +<p>The set of all exceptions (as a tuple) that methods of <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> instances may raise as a result of problems with the FTP connection (as opposed to programming errors made by the caller). This set includes the four exceptions listed above as well as <a class="reference internal" href="exceptions#OSError" title="OSError"><code>OSError</code></a> and <a class="reference internal" href="exceptions#EOFError" title="EOFError"><code>EOFError</code></a>.</p> </dd> +</dl> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt> +<code>Module</code> <a class="reference internal" href="netrc#module-netrc" title="netrc: Loading of .netrc files."><code>netrc</code></a> +</dt> +<dd> +<p>Parser for the <code>.netrc</code> file format. The file <code>.netrc</code> is typically used by FTP clients to load user authentication information before prompting the user.</p> </dd> </dl> </div> <section id="ftp-objects"> <span id="id1"></span><h2>FTP Objects</h2> <p>Several methods are available in two flavors: one for handling text files and another for binary files. These are named for the command which is used followed by <code>lines</code> for the text version or <code>binary</code> for the binary version.</p> <p><a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> instances have the following methods:</p> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.set_debuglevel"> +<code>FTP.set_debuglevel(level)</code> </dt> <dd> +<p>Set the instance’s debugging level. This controls the amount of debugging output printed. The default, <code>0</code>, produces no debugging output. A value of <code>1</code> produces a moderate amount of debugging output, generally a single line per request. A value of <code>2</code> or higher produces the maximum amount of debugging output, logging each line sent and received on the control connection.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.connect"> +<code>FTP.connect(host='', port=0, timeout=None, source_address=None)</code> </dt> <dd> +<p>Connect to the given host and port. The default port number is <code>21</code>, as specified by the FTP protocol specification. It is rarely needed to specify a different port number. This function should be called only once for each instance; it should not be called at all if a host was given when the instance was created. All other methods can only be used after a connection has been made. The optional <em>timeout</em> parameter specifies a timeout in seconds for the connection attempt. If no <em>timeout</em> is passed, the global default timeout setting will be used. <em>source_address</em> is a 2-tuple <code>(host, port)</code> for the socket to bind to as its source address before connecting.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>ftplib.connect</code> with arguments <code>self</code>, <code>host</code>, <code>port</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>source_address</em> parameter was added.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.getwelcome"> +<code>FTP.getwelcome()</code> </dt> <dd> +<p>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.)</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.login"> +<code>FTP.login(user='anonymous', passwd='', acct='')</code> </dt> <dd> +<p>Log in as the given <em>user</em>. The <em>passwd</em> and <em>acct</em> parameters are optional and default to the empty string. If no <em>user</em> is specified, it defaults to <code>'anonymous'</code>. If <em>user</em> is <code>'anonymous'</code>, the default <em>passwd</em> is <code>'anonymous@'</code>. This function should be called only once for each instance, after a connection has been established; it should not be called at all if a host and user were given when the instance was created. Most FTP commands are only allowed after the client has logged in. The <em>acct</em> parameter supplies “accounting information”; few systems implement this.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.abort"> +<code>FTP.abort()</code> </dt> <dd> +<p>Abort a file transfer that is in progress. Using this does not always work, but it’s worth a try.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.sendcmd"> +<code>FTP.sendcmd(cmd)</code> </dt> <dd> +<p>Send a simple command string to the server and return the response string.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>ftplib.sendcmd</code> with arguments <code>self</code>, <code>cmd</code>.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.voidcmd"> +<code>FTP.voidcmd(cmd)</code> </dt> <dd> +<p>Send a simple command string to the server and handle the response. Return nothing if a response code corresponding to success (codes in the range 200–299) is received. Raise <a class="reference internal" href="#ftplib.error_reply" title="ftplib.error_reply"><code>error_reply</code></a> otherwise.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>ftplib.sendcmd</code> with arguments <code>self</code>, <code>cmd</code>.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.retrbinary"> +<code>FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)</code> </dt> <dd> +<p>Retrieve a file in binary transfer mode. <em>cmd</em> should be an appropriate <code>RETR</code> command: <code>'RETR filename'</code>. The <em>callback</em> function is called for each block of data received, with a single bytes argument giving the data block. The optional <em>blocksize</em> argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to <em>callback</em>). A reasonable default is chosen. <em>rest</em> means the same thing as in the <a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code>transfercmd()</code></a> method.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.retrlines"> +<code>FTP.retrlines(cmd, callback=None)</code> </dt> <dd> +<p>Retrieve a file or directory listing in the encoding specified by the <em>encoding</em> parameter at initialization. <em>cmd</em> should be an appropriate <code>RETR</code> command (see <a class="reference internal" href="#ftplib.FTP.retrbinary" title="ftplib.FTP.retrbinary"><code>retrbinary()</code></a>) or a command such as <code>LIST</code> or <code>NLST</code> (usually just the string <code>'LIST'</code>). <code>LIST</code> retrieves a list of files and information about those files. <code>NLST</code> retrieves a list of file names. The <em>callback</em> function is called for each line with a string argument containing the line with the trailing CRLF stripped. The default <em>callback</em> prints the line to <code>sys.stdout</code>.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.set_pasv"> +<code>FTP.set_pasv(val)</code> </dt> <dd> +<p>Enable “passive” mode if <em>val</em> is true, otherwise disable passive mode. Passive mode is on by default.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.storbinary"> +<code>FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)</code> </dt> <dd> +<p>Store a file in binary transfer mode. <em>cmd</em> should be an appropriate <code>STOR</code> command: <code>"STOR filename"</code>. <em>fp</em> is a <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file object</span></a> (opened in binary mode) which is read until EOF using its <code>read()</code> method in blocks of size <em>blocksize</em> to provide the data to be stored. The <em>blocksize</em> argument defaults to 8192. <em>callback</em> is an optional single parameter callable that is called on each block of data after it is sent. <em>rest</em> means the same thing as in the <a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code>transfercmd()</code></a> method.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span><em>rest</em> parameter added.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.storlines"> +<code>FTP.storlines(cmd, fp, callback=None)</code> </dt> <dd> +<p>Store a file in line mode. <em>cmd</em> should be an appropriate <code>STOR</code> command (see <a class="reference internal" href="#ftplib.FTP.storbinary" title="ftplib.FTP.storbinary"><code>storbinary()</code></a>). Lines are read until EOF from the <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file object</span></a> <em>fp</em> (opened in binary mode) using its <a class="reference internal" href="io#io.IOBase.readline" title="io.IOBase.readline"><code>readline()</code></a> method to provide the data to be stored. <em>callback</em> is an optional single parameter callable that is called on each line after it is sent.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.transfercmd"> +<code>FTP.transfercmd(cmd, rest=None)</code> </dt> <dd> +<p>Initiate a transfer over the data connection. If the transfer is active, send an <code>EPRT</code> or <code>PORT</code> command and the transfer command specified by <em>cmd</em>, and accept the connection. If the server is passive, send an <code>EPSV</code> or <code>PASV</code> command, connect to it, and start the transfer command. Either way, return the socket for the connection.</p> <p>If optional <em>rest</em> is given, a <code>REST</code> command is sent to the server, passing <em>rest</em> as an argument. <em>rest</em> is usually a byte offset into the requested file, telling the server to restart sending the file’s bytes at the requested offset, skipping over the initial bytes. Note however that the <a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code>transfercmd()</code></a> method converts <em>rest</em> to a string with the <em>encoding</em> parameter specified at initialization, but no check is performed on the string’s contents. If the server does not recognize the <code>REST</code> command, an <a class="reference internal" href="#ftplib.error_reply" title="ftplib.error_reply"><code>error_reply</code></a> exception will be raised. If this happens, simply call <a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code>transfercmd()</code></a> without a <em>rest</em> argument.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.ntransfercmd"> +<code>FTP.ntransfercmd(cmd, rest=None)</code> </dt> <dd> +<p>Like <a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code>transfercmd()</code></a>, but returns a tuple of the data connection and the expected size of the data. If the expected size could not be computed, <code>None</code> will be returned as the expected size. <em>cmd</em> and <em>rest</em> means the same thing as in <a class="reference internal" href="#ftplib.FTP.transfercmd" title="ftplib.FTP.transfercmd"><code>transfercmd()</code></a>.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.mlsd"> +<code>FTP.mlsd(path='', facts=[])</code> </dt> <dd> +<p>List a directory in a standardized format by using <code>MLSD</code> command (<span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3659.html"><strong>RFC 3659</strong></a>). If <em>path</em> is omitted the current directory is assumed. <em>facts</em> is a list of strings representing the type of information desired (e.g. <code>["type", "size", "perm"]</code>). Return a generator object yielding a tuple of two elements for every file found in path. First element is the file name, the second one is a dictionary containing facts about the file name. Content of this dictionary might be limited by the <em>facts</em> argument but server is not guaranteed to return all requested facts.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.nlst"> +<code>FTP.nlst(argument[, ...])</code> </dt> <dd> +<p>Return a list of file names as returned by the <code>NLST</code> command. The optional <em>argument</em> is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the <code>NLST</code> command.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If your server supports the command, <a class="reference internal" href="#ftplib.FTP.mlsd" title="ftplib.FTP.mlsd"><code>mlsd()</code></a> offers a better API.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.dir"> +<code>FTP.dir(argument[, ...])</code> </dt> <dd> +<p>Produce a directory listing as returned by the <code>LIST</code> command, printing it to standard output. The optional <em>argument</em> is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the <code>LIST</code> command. If the last argument is a function, it is used as a <em>callback</em> function as for <a class="reference internal" href="#ftplib.FTP.retrlines" title="ftplib.FTP.retrlines"><code>retrlines()</code></a>; the default prints to <code>sys.stdout</code>. This method returns <code>None</code>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If your server supports the command, <a class="reference internal" href="#ftplib.FTP.mlsd" title="ftplib.FTP.mlsd"><code>mlsd()</code></a> offers a better API.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.rename"> +<code>FTP.rename(fromname, toname)</code> </dt> <dd> +<p>Rename file <em>fromname</em> on the server to <em>toname</em>.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.delete"> +<code>FTP.delete(filename)</code> </dt> <dd> +<p>Remove the file named <em>filename</em> from the server. If successful, returns the text of the response, otherwise raises <a class="reference internal" href="#ftplib.error_perm" title="ftplib.error_perm"><code>error_perm</code></a> on permission errors or <a class="reference internal" href="#ftplib.error_reply" title="ftplib.error_reply"><code>error_reply</code></a> on other errors.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.cwd"> +<code>FTP.cwd(pathname)</code> </dt> <dd> +<p>Set the current directory on the server.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.mkd"> +<code>FTP.mkd(pathname)</code> </dt> <dd> +<p>Create a new directory on the server.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.pwd"> +<code>FTP.pwd()</code> </dt> <dd> +<p>Return the pathname of the current directory on the server.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.rmd"> +<code>FTP.rmd(dirname)</code> </dt> <dd> +<p>Remove the directory named <em>dirname</em> on the server.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.size"> +<code>FTP.size(filename)</code> </dt> <dd> +<p>Request the size of the file named <em>filename</em> on the server. On success, the size of the file is returned as an integer, otherwise <code>None</code> is returned. Note that the <code>SIZE</code> command is not standardized, but is supported by many common server implementations.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.quit"> +<code>FTP.quit()</code> </dt> <dd> +<p>Send a <code>QUIT</code> command to the server and close the connection. This is the “polite” way to close a connection, but it may raise an exception if the server responds with an error to the <code>QUIT</code> command. This implies a call to the <a class="reference internal" href="#ftplib.FTP.close" title="ftplib.FTP.close"><code>close()</code></a> method which renders the <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> instance useless for subsequent calls (see below).</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP.close"> +<code>FTP.close()</code> </dt> <dd> +<p>Close the connection unilaterally. This should not be applied to an already closed connection such as after a successful call to <a class="reference internal" href="#ftplib.FTP.quit" title="ftplib.FTP.quit"><code>quit()</code></a>. After this call the <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a> instance should not be used any more (after a call to <a class="reference internal" href="#ftplib.FTP.close" title="ftplib.FTP.close"><code>close()</code></a> or <a class="reference internal" href="#ftplib.FTP.quit" title="ftplib.FTP.quit"><code>quit()</code></a> you cannot reopen the connection by issuing another <a class="reference internal" href="#ftplib.FTP.login" title="ftplib.FTP.login"><code>login()</code></a> method).</p> </dd> +</dl> </section> <section id="ftp-tls-objects"> <h2>FTP_TLS Objects</h2> <p><code>FTP_TLS</code> class inherits from <a class="reference internal" href="#ftplib.FTP" title="ftplib.FTP"><code>FTP</code></a>, defining these additional objects:</p> <dl class="py attribute"> <dt class="sig sig-object py" id="ftplib.FTP_TLS.ssl_version"> +<code>FTP_TLS.ssl_version</code> </dt> <dd> +<p>The SSL version to use (defaults to <a class="reference internal" href="ssl#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code>ssl.PROTOCOL_SSLv23</code></a>).</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP_TLS.auth"> +<code>FTP_TLS.auth()</code> </dt> <dd> +<p>Set up a secure control connection by using TLS or SSL, depending on what is specified in the <a class="reference internal" href="#ftplib.FTP_TLS.ssl_version" title="ftplib.FTP_TLS.ssl_version"><code>ssl_version</code></a> attribute.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>The method now supports hostname check with <a class="reference internal" href="ssl#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code>ssl.SSLContext.check_hostname</code></a> and <em>Server Name Indication</em> (see <a class="reference internal" href="ssl#ssl.HAS_SNI" title="ssl.HAS_SNI"><code>ssl.HAS_SNI</code></a>).</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP_TLS.ccc"> +<code>FTP_TLS.ccc()</code> </dt> <dd> +<p>Revert control channel back to plaintext. This can be useful to take advantage of firewalls that know how to handle NAT with non-secure FTP without opening fixed ports.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP_TLS.prot_p"> +<code>FTP_TLS.prot_p()</code> </dt> <dd> +<p>Set up secure data connection.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="ftplib.FTP_TLS.prot_c"> +<code>FTP_TLS.prot_c()</code> </dt> <dd> +<p>Set up clear text data connection.</p> </dd> +</dl> </section> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/ftplib.html" class="_attribution-link">https://docs.python.org/3.12/library/ftplib.html</a> + </p> +</div> |