このモジュールでは FTP クラスと、それに関連するいくつかの項目を定義しています。 FTP クラスは、FTPプロトコルのクライアント側の機能を備えています。このクラスを使うとFTPのいろいろな機能の自動化、例えば他のFTPサーバのミラーリングといったことを実行するPythonプログラムを書くことができます。また、 urllib モジュールもFTPを使うURLを操作するのにこのクラスを使っています。 FTP (File Transfer Protocol)についての詳しい情報はInternet RFC 959 を参照して下さい。
ftplib モジュールを使ったサンプルを以下に示します:
>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # ホストのデフォルトポートへ接続
>>> ftp.login() # ユーザ名 anonymous、パスワード anonyumou
s@
>>> ftp.retrlines('LIST') # ディレクトリの内容をリストアップ
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()
このモジュールは以下の項目を定義しています。
FTP クラスの新しいインスタンスを返します。 host が与えられると、 connect(host) メソッドが実行されます。 user が与えられると、さらに login(user, passwd, acct) メソッドが実行されます(この passwd と acct は指定されなければデフォルトでは空文字列です)。
オプションの timeout 引数は、コネクションの接続時など、ブロックする操作におけるタイムアウト時間を秒数で指定します。 (指定されなかった場合、グローバルのデフォルトタイムアウト設定が利用されます。)
バージョン 2.6 で変更: timeout が追加されました。
RFC 4217 に記述されている TLS サポートを FTP に加えた FTP のサブクラスです。認証の前に FTP コントロール接続を暗示的にセキュアにし、通常通りに port 21 に接続します。データ接続をセキュアにするには、ユーザが prot_p() メソッドを呼び出してそれを明示的に要求しなければなりません。 keyfile と certfile は省略可できます – これらは、SSL 接続のための、 PEM フォーマットの秘密鍵と証明書チェーンファイル名を含むことができます。
バージョン 2.7 で追加.
FTP_TLS クラスを使ったサンプルセッションはこちらです:
>>> from ftplib import FTP_TLS
>>> ftps = FTP_TLS('ftp.python.org')
>>> ftps.login() # 制御チャネルをセキュアにする前に匿名でログインする
>>> ftps.prot_p() # セキュアなデータ接続に移行する
>>> ftps.retrlines('LIST') # ディレクトリの内容をセキュアに列挙する
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()
>>>
サーバから想定外の応答があった時に発生する例外。
一時的エラーを表すエラーコード(400–499の範囲の応答コード)を受け取った時に発生する例外。
永久エラーを表すエラーコード(500–599の範囲の応答コード)を受け取った時に発生する例外。
File Transfer Protocol の応答仕様に適合しない、すなわち1–5の数字で始まらない応答コードをサーバから受け取った時に発生する例外。
FTP インスタンスのメソッド実行時、FTP接続で(プログラミングのエラーと考えられるメソッドの実行によって)発生する全ての例外(タプル形式)。この例外には以上の4つのエラーはもちろん、 socket.error と IOError も含まれます。
参考
Pythonのソースディストリビューションの Tools/scripts/ftpmi rror.py ファイルは、FTPサイトあるいはその一部をミラーリングするスクリプトで、 ftplib モジュールを使っています。このモジュールを適用した応用例として使うことができます。
いくつかのコマンドは2つのタイプについて実行します:1つはテキストファイルで、もう1つはバイナリファイルを扱います。これらのメソッドのテキストバージョンでは lines 、バイナリバージョンでは binary の語がメソッド名の終わりについています。
FTP インスタンスには以下のメソッドがあります:
インスタンスのデバッグレベルを設定します。この設定によってデバッグ時に出力される量を調節します。デフォルトは 0 で、何も出力されません。 1 なら、一般的に1つのコマンドあたり1行の適当な量のデバッグ出力を行います。 2 以上なら、コントロール接続で受信した各行を出力して、最大のデバッグ出力をします。
指定されたホストとポートに接続します。ポート番号のデフォルト値はFTPプロトコルの仕様で定められた 21 です。他のポート番号を指定する必要はめったにありません。この関数はひとつのインスタンスに対して一度だけ実行すべきです;インスタンスが作られた時にホスト名が与えられていたら、呼び出すべきではありません。これ以外の他の全てのメソッドは接続された後で実行可能となります。
The optional timeout parameter specifies a timeout in seconds for the connection attempt. If no timeout is passed, the global default timeout setting will be used.
オプションの timeout 引数は、コネクションの接続におけるタイムアウト時間を秒数で指定します。 timeout が渡されなかった場合、グローバルのデフォルトタイムアウト設定が利用されます。
バージョン 2.6 で変更: timeout が追加されました
接続して最初にサーバから送られてくるウェルカムメッセージを返します。(このメッセージには、ユーザにとって適切な注意書きやヘルプ情報が含まれることがあります。)
与えられた user でログインします。 passwd と acct のパラメータは省略可能で、デフォルトでは空文字列です。もし user が指定されないなら、デフォルトで 'anonymous' になります。もし user が 'anonymous' なら、デフォルトの passwd は 'anonymous@' になります。この関数は各インスタンスについて一度だけ、接続が確立した後に呼び出さなければなりません。インスタンスが作られた時にホスト名とユーザ名が与えられていたら、このメソッドを実行すべきではありません。ほとんどのFTPコマンドはクライアントがログインした後に実行可能になります。 acct 引数は “accounting information” を提供します。ほとんどのシステムはこれを実装していません。
実行中のファイル転送を中止します。これはいつも機能するわけではありませんが、やってみる価値はあります。
シンプルなコマンド文字列をサーバに送信して、受信した文字列を返します。
シンプルなコマンド文字列をサーバに送信して、その応答を扱います。応答コードが成功に関係するもの(200–299の範囲にあるコード)なら何も返しません。それ以外は error_reply を発生します。
バイナリ転送モードでファイルを受信します。 command は適切な RETR コマンド: 'RETR filename' でなければなりません。関数 callback は、受信したデータブロックのそれぞれに対して、データブロックを1つの文字列の引数として呼び出されます。省略可能な引数 maxblocksize は、実際の転送を行うのに作られた低レベルのソケットオブジェクトから読み込む最大のチャンクサイズを指定します(これは callback に与えられるデータブロックの最大サイズにもなります)。妥当なデフォルト値が設定されます。 rest は、 transfercmd() メソッドと同じものです。
ASCII転送モードでファイルとディレクトリのリストを受信します。 command は、適切な RETR コマンド(retrbinary() を参照)あるいは LIST, NLST, MLSD のようなコマンド(通常は文字列 'LIST')でなければなりません。 LIST は、ファイルのリストとそれらのファイルに関する情報を受信します。 NLST は、ファイル名のリストを受信します。サーバによっては、 MLSD は機械で読めるリストとそれらのファイルに関する情報を受信します。関数 callback は末尾のCRLFを取り除いた各行を引数にして実行されます。デフォルトでは callback は sys.stdout に各行を表示します。
boolean がtrueなら”パッシブモード”をオンにし、そうでないならパッシブモードをオフにします。(Python 2.0以前ではデフォルトでパッシブモードはオフにされていましたが、 Python 2.1以後ではデフォルトでオンになっています。)
バイナリ転送モードでファイルを転送します。 command は適切な STOR コマンド: "STOR filename" でなければなりません。 file は開かれたファイルオブジェクトで、 read() メソッドで EOFまで読み込まれ、ブロックサイズ blocksize でデータが転送されます。引数 blocksize のデフォルト値は8192です。 callback はオプションの引数で、引数を1つとる呼び出し可能オブジェクトを渡します。各データブロックが送信された後に、そのブロックを引数にして呼び出されます。 rest は、 transfercmd() メソッドにあるものと同じ意味です。
バージョン 2.1 で変更: blocksize のデフォルト値が追加されました.
バージョン 2.6 で変更: callback 引数が追加されました。
バージョン 2.7 で変更: rest パラメタが追加されました。
ASCII転送モードでファイルを転送します。 command は適切な STOR コマンドでなければなりません (storbinary() を参照)。 file は開かれたファイルオブジェクトで、 readline() メソッドでEOFまで読み込まれ、各行がデータが転送されます。 callback はオプションの引数で、引数を1つとる呼び出し可能オブジェクトを渡します。各行が送信された後に、その行数を引数にして呼び出されます。
バージョン 2.6 で変更: callback 引数が追加されました。
データ接続中に転送を初期化します。もし転送中なら、 EPRT あるいは PORT コマンドと、 cmd で指定したコマンドを送信し、接続を続けます。サーバがパッシブなら、 EPSV あるいは PASV コマンドを送信して接続し、転送コマンドを開始します。どちらの場合も、接続のためのソケットを返します。
省略可能な rest が与えられたら、 REST コマンドがサーバに送信され、 rest を引数として与えます。 rest は普通、要求したファイルのバイトオフセット値で、最初のバイトをとばして指定したオフセット値からファイルのバイト転送を再開するよう伝えます。しかし、RFC 959では rest が印字可能なASCIIコード33から126の範囲の文字列からなることを要求していることに注意して下さい。したがって、 transfercmd() メソッドは rest を文字列に変換しますが、文字列の内容についてチェックしません。もし REST コマンドをサーバが認識しないなら、例外 error_re ply が発生します。この例外が発生したら、引数 rest なしに transfercmd() を実行します。
transfercmd() と同様ですが、データと予想されるサイズとのタプルを返します。もしサイズが計算できないなら、サイズの代わりに None が返されます。 cmd と rest は transfercmd() のものと同じです。
NLST コマンドで返されるファイル名のリストを返します。省略可能な argument は、リストアップするディレクトリです(デフォルトではサーバのカレントディレクトリです)。 NLST コマンドに非標準である複数の引数を渡すことができます。
LIST コマンドで返されるディレクトリ内のリストを作り、標準出力へ出力します。省略可能な argument は、リストアップするディレクトリです(デフォルトではサーバのカレントディレクトリです)。 LIST コマンドに非標準である複数の引数を渡すことができます。もし最後の引数が関数なら、 retrlines() のように callback として使われます;デフォルトでは sys.stdout に印字します。このメソッドは None を返します。
サーバ上のファイルのファイル名 fromname を toname へ変更します。
サーバからファイル filename を削除します。成功したら応答のテキストを返し、そうでないならパーミッションエラーでは error_perm を、他のエラーでは error_reply を返します。
サーバのカレントディレクトリを設定します。
サーバ上に新たにディレクトリを作ります。
サーバ上のカレントディレクトリのパスを返します。
サーバ上のディレクトリ dirname を削除します。
サーバ上のファイル filename のサイズを尋ねます。成功したらファイルサイズが整数で返され、そうでないなら None が返されます。 SIZE コマンドは標準化されていませんが、多くの普通のサーバで実装されていることに注意して下さい。