11.5 ftplib -- FTP protocol client
Keywords: lib

# 11.5 `ftplib` -- FTP protocol client

This module defines the class `FTP` and a few related items. The `FTP` 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 `urllib` to handle URLs that use FTP. For more information on FTP (File Transfer Protocol), see Internet RFC 959.

Here's a sample session using the `ftplib` module:

      >>> from ftplib import FTP
      >>> ftp = FTP('ftp.cwi.nl')   # connect to host, default port
      >>> ftp.login()               # user anonymous, passwd user@hostname
      >>> ftp.retrlines('LIST')     # list directory contents
      total 24418
      drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
      dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
      -rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
       .
       .
       .
      >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
      '226 Transfer complete.'
      >>> ftp.quit()

The module defines the following items:

`FTP` ([host[, user[, passwd[, acct]]]])
  Return a new instance of the `FTP` class. When host is given, the method call `connect(host)` is made. When user is given, additionally the method call `login(user, passwd, acct)` is made (where passwd and acct default to the empty string when not given).

`all_errors`
  The set of all exceptions (as a tuple) that methods of `FTP` 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 below as well as `socket.error` and `IOError`.

`error_reply`
  Exception raised when an unexpected reply is received from the server.

`error_temp`
  Exception raised when an error code in the range 400-499 is received.

`error_perm`
  Exception raised when an error code in the range 500-599 is received.

`error_proto`
  Exception raised when a reply is received from the server that does not begin with a digit in the range 1-5.

See Also:

Module `netrc`:
  Parser for the .netrc file format. The file .netrc is typically used by FTP clients to load user authentication information before prompting the user.

The file Tools/scripts/ftpmirror.py in the Python source distribution is a script that can mirror FTP sites, or portions thereof, using the `ftplib` module. It can be used as an extended example that applies this module.

Subsections

- 11.5.1 FTP Objects