##
11.4.1 FTP Objects

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 "`lines`" for the text version or "`binary`" for the binary version.

`FTP` instances have the following methods:

`set_debuglevel` (level)
  Set the instance's debugging level. This controls the amount of debugging output printed. The default, `0`, produces no debugging output. A value of `1` produces a moderate amount of debugging output, generally a single line per request. A value of `2` or higher produces the maximum amount of debugging output, logging each line sent and received on the control connection.

`connect` (host[, port])
  Connect to the given host and port. The default port number is `21`, 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.

`getwelcome` ()
  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.)

`login` ([user[, passwd[, acct]]])
  Log in as the given user. The passwd and acct parameters are optional and default to the empty string. If no user is specified, it defaults to `'anonymous'`. If user is `'anonymous'`, the default passwd is "`realuser@host`" where realuser is the real user name (glanced from the $LOGNAME or $USER environment variable) and host is the hostname as returned by `socket.gethostname()`. 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.

`abort` ()
  Abort a file transfer that is in progress. Using this does not always work, but it's worth a try.

`sendcmd` (command)
  Send a simple command string to the server and return the response string.

`voidcmd` (command)
  Send a simple command string to the server and handle the response. Return nothing if a response code in the range 200-299 is received. Raise an exception otherwise.

`retrbinary` (command, callback[, maxblocksize])
  Retrieve a file in binary transfer mode. command should be an appropriate "`RETR`" command, i.e. `'RETR filename'`. The callback function is called for each block of data received, with a single string argument giving the data block. The optional maxblocksize 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 callback). A reasonable default is chosen.

`retrlines` (command[, callback])
  Retrieve a file or directory listing in ASCII transfer mode. command should be an appropriate "`RETR`" command (see `retrbinary()` or a "`LIST`" command (usually just the string `'LIST'`). The callback function is called for each line, with the trailing CRLF stripped. The default callback prints the line to `sys.stdout`.

`set_pasv` (boolean)
  Enable ``passive'' mode if boolean is true, other disable passive mode.

`storbinary` (command, file, blocksize)
  Store a file in binary transfer mode. command should be an appropriate "`STOR`" command, i.e. `"STOR filename"`. file is an open file object which is read until EOF using its `read()` method in blocks of size blocksize to provide the data to be stored.

`storlines` (command, file)
  Store a file in ASCII transfer mode. command should be an appropriate "`STOR`" command (see `storbinary()`). Lines are read until EOF from the open file object file using its `readline()` method to privide the data to be stored.

`transfercmd` (cmd)
  Initiate a transfer over the data connection. If the transfer is active, send a "`PORT`" command and the transfer command specified by cmd, and accept the connection. If the server is passive, send a "`PASV`" command, connect to it, and start the transfer command. Either way, return the socket for the connection.

`ntransfercmd` (cmd)
  Like `transfercmd()`, but returns a tuple of the data connection and the expected size of the data. If the expected size could not be computed, `None` will be returned as the expected size.

`nlst` (argument[, ...])
  Return a list of files as returned by the "`NLST`" command. The optional argument is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the "`NLST`" command.

`dir` (argument[, ...])
  Return a directory listing as returned by the "`LIST`" command, as a list of lines. The optional argument is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the "`LIST`" command. If the last argument is a function, it is used as a callback function as for `retrlines()`.

`rename` (fromname, toname)
  Rename file fromname on the server to toname.

`delete` (filename)
  Remove the file named filename from the server. If successful, returns the text of the response, otherwise raises `error_perm` on permission errors or `error_reply` on other errors.

`cwd` (pathname)
  Set the current directory on the server.

`mkd` (pathname)
  Create a new directory on the server.

`pwd` ()
  Return the pathname of the current directory on the server.

`rmd` (dirname)
  Remove the directory named dirname on the server.

`size` (filename)
  Request the size of the file named filename on the server. On success, the size of the file is returned as an integer, otherwise `None` is returned. Note that the "`SIZE`" command is not standardized, but is supported by many common server implementations.

`quit` ()
  Send a "`QUIT`" command to the server and close the connection. This is the ``polite'' way to close a connection, but it may raise an exception of the server reponds with an error to the "`QUIT`" command. This implies a call to the `close()` method which renders the `FTP` instance useless for subsequent calls (see below).

`close` ()
  Close the connection unilaterally. This should not be applied to an already closed connection (e.g. after a successful call to `quit()`. After this call the `FTP` instance should not be used any more (i.e., after a call to `close()` or `quit()` you cannot reopen the connection by issueing another `login()` method).