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コマンドは標準化されていませんが、多くの普通のサーバで実装されていることに注意して下さい。
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()¶ 平文データ接続をセットアップします。