FTP Objects¶

Several methods are available in two flavors: one for handling text files andanother for binary files. These are named for the command which is usedfollowed bylines for the text version orbinary for the binary version.

FTP instances have the following methods:

FTP.set_debuglevel(level)¶

Set the instance’s debugging level. This controls the amount of debuggingoutput printed. The default,0, produces no debugging output. A value of1 produces a moderate amount of debugging output, generally a single lineper request. A value of2 or higher produces the maximum amount ofdebugging output, logging each line sent and received on the control connection.

FTP.connect(host='',port=0,timeout=None,source_address=None)¶

Connect to the given host and port. The default port number is21, asspecified by the FTP protocol specification. It is rarely needed to specify adifferent port number. This function should be called only once for eachinstance; it should not be called at all if a host was given when the instancewas created. All other methods can only be used after a connection has beenmade.The optionaltimeout parameter specifies a timeout in seconds for theconnection attempt. If notimeout is passed, the global default timeoutsetting will be used.source_address is a 2-tuple(host,port) for the socket to bind to asits source address before connecting.

Raises anauditing eventftplib.connect with argumentsself,host,port.

Changed in version 3.3:source_address parameter was added.

FTP.getwelcome()¶

Return the welcome message sent by the server in reply to the initialconnection. (This message sometimes contains disclaimers or help informationthat may be relevant to the user.)

FTP.login(user='anonymous',passwd='',acct='')¶

Log in as the givenuser. Thepasswd andacct parameters are optional anddefault to the empty string. If nouser is specified, it defaults to'anonymous'. Ifuser is'anonymous', the defaultpasswd is'anonymous@'. This function should be called only once for each instance,after a connection has been established; it should not be called at all if ahost and user were given when the instance was created. Most FTP commands areonly allowed after the client has logged in. Theacct parameter supplies“accounting information”; few systems implement this.

FTP.abort()¶

Abort a file transfer that is in progress. Using this does not always work, butit’s worth a try.

FTP.sendcmd(cmd)¶

Send a simple command string to the server and return the response string.

Raises anauditing eventftplib.sendcmd with argumentsself,cmd.

FTP.voidcmd(cmd)¶

Send a simple command string to the server and handle the response. Returnnothing if a response code corresponding to success (codes in the range200–299) is received. Raiseerror_reply otherwise.

Raises anauditing eventftplib.sendcmd with argumentsself,cmd.

FTP.retrbinary(cmd,callback,blocksize=8192,rest=None)¶

Retrieve a file in binary transfer mode.cmd should be an appropriateRETR command:'RETRfilename'. Thecallback function is called foreach block of data received, with a single bytes argument giving the datablock. The optionalblocksize argument specifies the maximum chunk size toread on the low-level socket object created to do the actual transfer (whichwill also be the largest size of the data blocks passed tocallback). Areasonable default is chosen.rest means the same thing as in thetransfercmd() method.

FTP.retrlines(cmd,callback=None)¶

Retrieve a file or directory listing in ASCII transfer mode.cmd should bean appropriateRETR command (seeretrbinary()) or a command such asLIST orNLST (usually just the string'LIST').LIST retrieves a list of files and information about those files.NLST retrieves a list of file names.Thecallback function is called for each line with a string argumentcontaining the line with the trailing CRLF stripped. The defaultcallbackprints the line tosys.stdout.

FTP.set_pasv(val)¶

Enable “passive” mode ifval is true, otherwise disable passive mode.Passive mode is on by default.

FTP.storbinary(cmd,fp,blocksize=8192,callback=None,rest=None)¶

Store a file in binary transfer mode.cmd should be an appropriateSTOR command:"STORfilename".fp is afile object(opened in binary mode) which is read until EOF using itsread()method in blocks of sizeblocksize to provide the data to be stored.Theblocksize argument defaults to 8192.callback is an optional singleparameter callable that is called on each block of data after it is sent.rest means the same thing as in thetransfercmd() method.

Changed in version 3.2:rest parameter added.

FTP.storlines(cmd,fp,callback=None)¶

Store a file in ASCII transfer mode.cmd should be an appropriateSTOR command (seestorbinary()). Lines are read until EOF from thefile objectfp (opened in binary mode) using itsreadline()method to provide the data to be stored.callback is an optional singleparameter callable that is called on each line after it is sent.

FTP.transfercmd(cmd,rest=None)¶

Initiate a transfer over the data connection. If the transfer is active, send anEPRT orPORT command and the transfer command specified bycmd, andaccept the connection. If the server is passive, send anEPSV orPASVcommand, connect to it, and start the transfer command. Either way, return thesocket for the connection.

If optionalrest is given, aREST command is sent to the server, passingrest as an argument.rest 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 thatRFC 959 requires only thatrest be a string containing characters in the printable range from ASCII code33 to ASCII code 126. Thetransfercmd() method, therefore, convertsrest to a string, but no check is performed on the string’s contents. If theserver does not recognize theREST command, anerror_reply exceptionwill be raised. If this happens, simply calltransfercmd() without arest argument.

FTP.ntransfercmd(cmd,rest=None)¶

Liketransfercmd(), but returns a tuple of the data connection and theexpected size of the data. If the expected size could not be computed,Nonewill be returned as the expected size.cmd andrest means the same thing asintransfercmd().

FTP.mlsd(path="",facts=[])¶

List a directory in a standardized format by usingMLSD command(RFC 3659). Ifpath is omitted the current directory is assumed.facts is a list of strings representing the type of information desired(e.g.["type","size","perm"]). Return a generator object yielding atuple of two elements for every file found in path. First element is thefile name, the second one is a dictionary containing facts about the filename. Content of this dictionary might be limited by thefacts argumentbut server is not guaranteed to return all requested facts.

New in version 3.3.

FTP.nlst(argument[,...])¶

Return a list of file names as returned by theNLST command. Theoptionalargument is a directory to list (default is the current serverdirectory). Multiple arguments can be used to pass non-standard options totheNLST command.

Note

If your server supports the command,mlsd() offers a better API.

FTP.dir(argument[,...])¶

Produce a directory listing as returned by theLIST command, printing it tostandard output. The optionalargument is a directory to list (default is thecurrent server directory). Multiple arguments can be used to pass non-standardoptions to theLIST command. If the last argument is a function, it is usedas acallback function as forretrlines(); the default prints tosys.stdout. This method returnsNone.

Note

If your server supports the command,mlsd() offers a better API.

FTP.rename(fromname,toname)¶

Rename filefromname on the server totoname.

FTP.delete(filename)¶

Remove the file namedfilename from the server. If successful, returns thetext of the response, otherwise raiseserror_perm on permission errors orerror_reply on other errors.

FTP.cwd(pathname)¶

Set the current directory on the server.

FTP.mkd(pathname)¶

Create a new directory on the server.

FTP.pwd()¶

Return the pathname of the current directory on the server.

FTP.rmd(dirname)¶

Remove the directory nameddirname on the server.

FTP.size(filename)¶

Request the size of the file namedfilename on the server. On success, thesize of the file is returned as an integer, otherwiseNone is returned.Note that theSIZE command is not standardized, but is supported by manycommon server implementations.

FTP.quit()¶

Send aQUIT 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 serverresponds with an error to theQUIT command. This implies a call to theclose() method which renders theFTP instance useless forsubsequent calls (see below).

FTP.close()¶

Close the connection unilaterally. This should not be applied to an alreadyclosed connection such as after a successful call toquit().After this call theFTP instance should not be used any more (aftera call toclose() orquit() you cannot reopen theconnection by issuing anotherlogin() method).

FTP_TLS Objects¶

FTP_TLS class inherits fromFTP, defining these additional objects:

FTP_TLS.ssl_version¶

The SSL version to use (defaults tossl.PROTOCOL_SSLv23).

FTP_TLS.auth()¶

Set up a secure control connection by using TLS or SSL, depending on whatis specified in thessl_version attribute.

Changed in version 3.4:The method now supports hostname check withssl.SSLContext.check_hostname andServer Name Indication (seessl.HAS_SNI).

FTP_TLS.ccc()¶

Revert control channel back to plaintext. This can be useful to takeadvantage of firewalls that know how to handle NAT with non-secure FTPwithout opening fixed ports.

New in version 3.3.

FTP_TLS.prot_p()¶

Set up secure data connection.

FTP_TLS.prot_c()¶

Set up clear text data connection.