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()

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