# 20.8. `ftplib` --- FTPプロトコルクライアント

Source code: Lib/ftplib.py

このモジュールでは `FTP` クラスと、それに関連するいくつかの項目を定義しています。 `FTP` クラスは、FTPプロトコルのクライアント側の機能を備えています。このクラスを使うとFTPのいろいろな機能の自動化、例えば他のFTPサーバのミラーリングといったことを実行するPythonプログラムを書くことができます。また、 `urllib` モジュールもFTPを使うURLを操作するのにこのクラスを使っています。 FTP (File Transfer Protocol)についての詳しい情報はInternet RFC 959 を参照して下さい。

`ftplib` モジュールを使ったサンプルを以下に示します:

    >>> from ftplib import FTP
    >>> ftp = FTP('ftp.debian.org')     # connect to host, default port
    >>> ftp.login()                     # user anonymous, passwd anonymous@
    '230 Login successful.'
    >>> ftp.cwd('debian')               # change into "debian" directory
    >>> 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.'
    >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
    '226 Transfer complete.'
    >>> ftp.quit()

このモジュールは以下の項目を定義しています:

class `ftplib.``FTP`([host[, user[, passwd[, acct[, timeout]]]]])

  `FTP` クラスの新しいインスタンスを返します。 host が与えられると、 `connect(host)` メソッドが実行されます。 user が与えられると、さらに `login(user, passwd, acct)` メソッドが実行されます（この passwd と acct は指定されなければデフォルトでは空文字列です）。

  バージョン 2.6 で変更: timeout が追加されました。

class `ftplib.``FTP_TLS`([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])

  RFC 4217 に記述されている TLS サポートを FTP に加えた `FTP` のサブクラスです。認証の前に FTP コントロール接続を暗黙にセキュアにし、通常通りに port 21 に接続します。データ接続をセキュアにするには、ユーザが `prot_p()` メソッドを呼び出してそれを明示的に要求しなければなりません。 context は SSL 設定オプション、証明書、秘密鍵を一つの(潜在的に長生きの)構造にまとめた `ssl.SSLContext` オブジェクトです。ベストプラクティスについての セキュリティで考慮すべき点 をお読みください。

  keyfile と certfile は context のレガシー版です -- これらは、SSL 接続のための、 PEM フォーマットの秘密鍵と証明書チェーンファイル名(前者が keyfile 、後者が certfile )を含むことができます。

  バージョン 2.7 で追加.

  バージョン 2.7.10 で変更: context パラメータが追加されました。

  `FTP_TLS` クラスを使ったサンプルセッションはこちらです:

      >>> from ftplib import FTP_TLS
      >>> ftps = FTP_TLS('ftp.python.org')
      >>> ftps.login()           # login anonymously before securing control channel
      >>> ftps.prot_p()          # switch to secure data connection
      >>> ftps.retrlines('LIST') # list directory content securely
      total 9
      drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 .
      drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 ..
      drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 bin
      drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 etc
      d-wxrwxr-x   2 ftp      wheel        1024 Sep  5 13:43 incoming
      drwxr-xr-x   2 root     wheel        1024 Nov 17  1993 lib
      drwxr-xr-x   6 1094     wheel        1024 Sep 13 19:07 pub
      drwxr-xr-x   3 root     wheel        1024 Jan  3  1994 usr
      -rw-r--r--   1 root     root          312 Aug  1  1994 welcome.msg
      '226 Transfer complete.'
      >>> ftps.quit()
      >>>

exception `ftplib.``error_reply`

  サーバから想定外の応答があった時に発生する例外。

exception `ftplib.``error_temp`

  一時的エラーを表すエラーコード(400--499の範囲の応答コード)を受け取った時に発生する例外。

exception `ftplib.``error_perm`

  永久エラーを表すエラーコード(500--599の範囲の応答コード)を受け取った時に発生する例外。

exception `ftplib.``error_proto`

  File Transfer Protocol の応答仕様に適合しない、すなわち1--5の数字で始まらない応答コードをサーバから受け取った時に発生する例外。

`ftplib.``all_errors`

  `FTP` インスタンスのメソッド実行時、FTP接続で (プログラミングのエラーと考えられるメソッドの実行によって) 発生する全ての例外 (タプル形式)。この例外には以上の４つのエラーはもちろん、 `socket.error` と `IOError` も含まれます。

参考

`netrc` モジュール
  `.netrc` ファイルフォーマットのパーザ。 `.netrc` ファイルは、 FTPクライアントがユーザにプロンプトを出す前に、ユーザ認証情報をロードするのによく使われます。

Pythonのソースディストリビューションの `Tools/scripts/ftpmirror.py` ファイルは、FTPサイトあるいはその一部をミラーリングするスクリプトで、 `ftplib` モジュールを使っています。このモジュールを適用した応用例として使うことができます。

## 20.8.1. FTP オブジェクト

いくつかのコマンドは２つのタイプについて実行します：１つはテキストファイルで、もう１つはバイナリファイルを扱います。これらのメソッドのテキストバージョンでは `lines` 、バイナリバージョンでは `binary` の語がメソッド名の終わりについています。

`FTP` インスタンスには以下のメソッドがあります:

`FTP.``set_debuglevel`(level)

  インスタンスのデバッグレベルを設定します。この設定によってデバッグ時に出力される量を調節します。デフォルトは `0` で、何も出力されません。 `1` なら、一般的に１つのコマンドあたり１行の適当な量のデバッグ出力を行います。 `2` 以上なら、コントロール接続で受信した各行を出力して、最大のデバッグ出力をします。

`FTP.``connect`(host[, port[, timeout]])

  指定されたホストとポートに接続します。ポート番号のデフォルト値はFTPプロトコルの仕様で定められた `21` です。他のポート番号を指定する必要はめったにありません。この関数はひとつのインスタンスに対して一度だけ実行すべきです；インスタンスが作られた時にホスト名が与えられていたら、呼び出すべきではありません。これ以外の他の全てのメソッドは接続された後で実行可能となります。

  オプションの timeout 引数は、コネクションの接続におけるタイムアウト時間を秒数で指定します。 timeout が渡されなかった場合、グローバルのデフォルトタイムアウト設定が利用されます。

  バージョン 2.6 で変更: timeout が追加されました。

`FTP.``getwelcome`()

  サーバに最初に接続した際に送信される応答中のウェルカムメッセージを返します。(このメッセージには時に、ユーザにとって重要な免責事項や ヘルプ情報が入っています。)

`FTP.``login`([user[, passwd[, acct]]])

  与えられた user でログインします。 passwd と acct のパラメータは省略可能で、デフォルトでは空文字列です。もし user が指定されないなら、デフォルトで `'anonymous'` になります。もし user が `'anonymous'` なら、デフォルトの passwd は `'anonymous@'` になります。この関数は各インスタンスについて一度だけ、接続が確立した後に呼び出さなければなりません。インスタンスが作られた時にホスト名とユーザ名が与えられていたら、このメソッドを実行すべきではありません。ほとんどのFTPコマンドはクライアントがログインした後に実行可能になります。 acct 引数は "accounting information" を提供します。ほとんどのシステムはこれを実装していません。

`FTP.``abort`()

  実行中のファイル転送を中止します。これはいつも機能するわけではありませんが、やってみる価値はあります。

`FTP.``sendcmd`(command)

  シンプルなコマンド文字列をサーバに送信して、受信した文字列を返します。

`FTP.``voidcmd`(command)

  シンプルなコマンド文字列をサーバに送信して、その応答を扱います。応答コードが成功に関係するもの(200--299の範囲にあるコード)なら何も返しません。それ以外は `error_reply` を発生します。

`FTP.``retrbinary`(command, callback[, maxblocksize[, rest]])

  バイナリ転送モードでファイルを受信します。 command は適切な `RETR` コマンド： `'RETR filename'` でなければなりません。関数 callback は、受信したデータブロックのそれぞれに対して、データブロックを１つの文字列の引数として呼び出されます。省略可能な引数 maxblocksize は、実際の転送を行うのに作られた低レベルのソケットオブジェクトから読み込む最大のチャンクサイズを指定します（これは callback に与えられるデータブロックの最大サイズにもなります）。妥当なデフォルト値が設定されます。 rest は、 `transfercmd()` メソッドと同じものです。

`FTP.``retrlines`(command[, callback])

  ASCII転送モードでファイルとディレクトリのリストを受信します。 command は、適切な `RETR` コマンド(`retrbinary()` を参照)あるいは `LIST`, `NLST`, `MLSD` のようなコマンド(通常は文字列 `'LIST'`)でなければなりません。 `LIST` は、ファイルのリストとそれらのファイルに関する情報を受信します。 `NLST` は、ファイル名のリストを受信します。サーバによっては、 `MLSD` は機械で読めるリストとそれらのファイルに関する情報を受信します。関数 callback は末尾のCRLFを取り除いた各行を引数にして実行されます。デフォルトでは callback は `sys.stdout` に各行を表示します。

`FTP.``set_pasv`(val)

  val が真なら"パッシブモード"をオンにし、そうでないならパッシブモードをオフにします。(Python 2.0以前ではデフォルトでパッシブモードはオフにされていましたが、 Python 2.1以後ではデフォルトでオンになっています。)

`FTP.``storbinary`(command, fp[, blocksize, callback, rest])

  バイナリ転送モードでファイルを転送します。 command は適切な `STOR` コマンド： `"STOR filename"` でなければなりません。 fp は開かれたファイルオブジェクトで、 `read()` メソッドで EOFまで読み込まれ、ブロックサイズ blocksize でデータが転送されます。引数 blocksize のデフォルト値は8192です。 callback はオプションの引数で、引数を1つとる呼び出し可能オブジェクトを渡します。各データブロックが送信された後に、そのブロックを引数にして呼び出されます。 rest は、 `transfercmd()` メソッドにあるものと同じ意味です。

  バージョン 2.1 で変更: blocksize のデフォルト値が追加されました.

  バージョン 2.6 で変更: callback 引数が追加されました。

  バージョン 2.7 で変更: rest パラメタが追加されました。

`FTP.``storlines`(command, fp[, callback])

  ASCII転送モードでファイルを転送します。 command は適切な `STOR` コマンドでなければなりません (`storbinary()` を参照)。 fp は開かれたファイルオブジェクトで、 `readline()` メソッドでEOFまで読み込まれ、各行がデータが転送されます。 callback はオプションの引数で、引数を1つとる呼び出し可能オブジェクトを渡します。各行が送信された後に、その行数を引数にして呼び出されます。

  バージョン 2.6 で変更: callback 引数が追加されました。

`FTP.``transfercmd`(cmd[, rest])

  データ接続中に転送を初期化します。もし転送中なら、`EPRT` あるいは `PORT` コマンドと、cmd で指定したコマンドを送信し、接続を続けます。サーバがパッシブなら、`EPSV` あるいは `PASV` コマンドを送信して接続し、転送コマンドを開始します。どちらの場合も、接続のためのソケットを返します。

  省略可能な rest が与えられたら、 `REST` コマンドがサーバに送信され、 rest を引数として与えます。 rest は普通、要求したファイルのバイトオフセット値で、最初のバイトをとばして指定したオフセット値からファイルのバイト転送を再開するよう伝えます。しかし、RFC 959では rest が印字可能なASCIIコード33から126の範囲の文字列からなることを要求していることに注意して下さい。したがって、 `transfercmd()` メソッドは rest を文字列に変換しますが、文字列の内容についてチェックしません。もし `REST` コマンドをサーバが認識しないなら、例外 `error_re ply` が発生します。この例外が発生したら、引数 rest なしに `transfercmd()` を実行します。

`FTP.``ntransfercmd`(cmd[, rest])

  `transfercmd()` と同様ですが、データと予想されるサイズとのタプルを返します。もしサイズが計算できないなら、サイズの代わりに `None` が返されます。 cmd と rest は `transfercmd()` のものと同じです。

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

  `NLST` コマンドで返されるファイル名のリストを返します。省略可能な argument は、リストアップするディレクトリです（デフォルトではサーバのカレントディレクトリです）。 `NLST` コマンドに非標準である複数の引数を渡すことができます。

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

  `LIST` コマンドで返されるディレクトリ内のリストを作り、標準出力へ出力します。省略可能な argument は、リストアップするディレクトリです（デフォルトではサーバのカレントディレクトリです）。 `LIST` コマンドに非標準である複数の引数を渡すことができます。もし最後の引数が関数なら、 `retrlines()` のように callback として使われます; デフォルトでは `sys.stdout` に印字します。このメソッドは `None` を返します。

`FTP.``rename`(fromname, toname)

  サーバ上のファイルのファイル名 fromname を toname へ変更します。

`FTP.``delete`(filename)

  サーバからファイル filename を削除します。成功したら応答のテキストを返し、そうでないならパーミッションエラーでは `error_perm` を、他のエラーでは `error_reply` を返します。

`FTP.``cwd`(pathname)

  サーバのカレントディレクトリを設定します。

`FTP.``mkd`(pathname)

  サーバ上に新たにディレクトリを作ります。

`FTP.``pwd`()

  サーバ上のカレントディレクトリのパスを返します。

`FTP.``rmd`(dirname)

  サーバ上のディレクトリ dirname を削除します。

`FTP.``size`(filename)

  サーバ上のファイル filename のサイズを尋ねます。成功したらファイルサイズが整数で返され、そうでないなら `None` が返されます。 `SIZE` コマンドは標準化されていませんが、多くの普通のサーバで実装されていることに注意して下さい。

`FTP.``quit`()

  サーバに `QUIT` コマンドを送信し、接続を閉じます。これは接続を閉じるのに"礼儀正しい"方法ですが、 `QUIT` コマンドに反応してサーバの例外が発生するかもしれません。この例外は、 `close()` メソッドによって `FTP` インスタンスに対するその後のコマンド使用が不可になっていることを示しています（下記参照）。

`FTP.``close`()

  接続を一方的に閉じます。既に閉じた接続に対して実行すべきではありません（例えば `quit()` を呼び出して成功した後など）。この実行の後、 `FTP` インスタンスはもう使用すべきではありません（ `close()` あるいは `quit()` を呼び出した後で、 `login()` メソッドをもう一度実行して再び接続を開くことはできません）。

## 20.8.2. FTP_TLS オブジェクト

`FTP_TLS` クラスは `FTP` を継承し、さらにオブジェクトを定義します:

`FTP_TLS.``ssl_version`

  使用する SSL のバージョン (デフォルトは `ssl.PROTOCOL_SSLv23`) です。

`FTP_TLS.``auth`()

  `ssl_version()` 属性で指定されたものに従って、 TLS または SSL を使い、セキュアコントロール接続をセットアップします。

`FTP_TLS.``prot_p`()

  セキュアデータ接続をセットアップします。

`FTP_TLS.``prot_c`()

  平文データ接続をセットアップします。