目次

前のトピックへ

20.7. httplib — HTTP プロトコルクライアント

次のトピックへ

20.9. poplib — POP3 プロトコルクライアント

このページ

20.8. ftplib — FTPプロトコルクライアント

このモジュールでは 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()

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

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

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

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

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

exception ftplib.error_reply

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

exception ftplib.error_temp

400–499の範囲のエラー応答コードを受け取った時に発生する例外。

exception ftplib.error_perm

500–599の範囲のエラー応答コードを受け取った時に発生する例外。

exception ftplib.error_proto

1–5の数字で始まらない応答コードをサーバから受け取った時に発生する例外。

ftplib.all_errors

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

参考

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

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

20.8.1. FTP オブジェクト

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

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

FTP.set_debuglevel(level)

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

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

指定されたホストとポートに接続します。ポート番号のデフォルト値は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 が追加されました

FTP.getwelcome()

接続して最初にサーバから送られてくるウェルカムメッセージを返します。(このメッセージには、ユーザにとって適切な注意書きやヘルプ情報が含まれることがあります。)

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

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

FTP.abort()

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

FTP.sendcmd(command)

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

FTP.voidcmd(command)

シンプルなコマンド文字列をサーバに送信して、その応答を扱います。応答コードが200–299の範囲にあれば何も返しません。それ以外は例外を発生します。

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

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

FTP.retrlines(command[, callback])

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

FTP.set_pasv(boolean)

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

FTP.storbinary(command, file[, blocksize, callback])

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

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

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

FTP.storlines(command, file[, callback])

ASCII転送モードでファイルを転送します。 command は適切な STOR コマンドでなければなりません (storbinary() を参照)。 file は開かれたファイルオブジェクトで、 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 が返されます。 cmdresttransfercmd() のものと同じです。

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

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

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

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

FTP.rename(fromname, toname)

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

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() メソッドをもう一度実行して再び接続を開くことはできません)。