18.8.1 FTP オブジェクト

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

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

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

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

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

login( [user[, passwd[, ac ct]]])
与えられたuserでログインします。 passwdacctのパラメータは省略可能で、デフォルトでは空文字列 です。 もしuserが指定されないなら、デフォルトで'anonymous'になりま す。 もしuser'anonymous'なら、デフォルトのpasswd 'anonymous@'になります。 このfunctionは各インスタンスについて一度だけ、接続が確立した後に呼び出さ なければなりません; インスタンスが作られた時にホスト名とユーザ名が与えられていたら、このメ ソッドを実行すべきではありません。 ほとんどのFTPコマンドはクライアントがログインした後に実行可能になりま す。

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

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

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

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

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

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

storbinary( command, file[, blocksize])
バイナリ転送モードでファイルを転送します。 commandは適切な"STOR"コマンド:"STOR filename"で なければなりません。 fileは開かれたファイルオブジェクトで、read()メソッドで EOFまで読み込まれ、ブロックサイズblocksizeでデータが転送されま す。 引数blocksizeのデフォルト値は8192です。 バージョン 2.1 で 変更 された仕様: blocksizeのデフォルト値が追加されました

storlines( command, file)
ASCII転送モードでファイルを転送します。 commandは適切な"STOR"コマンドでなければなりません(st orbinary()を参照)。 fileは開かれたファイルオブジェクトで、readline()メソッド でEOFまで読み込まれ、各行がデータが転送されます。

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()を実行し ます。

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

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

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

rename( fromname, toname)
サーバ上のファイルのファイル名fromnametonameへ変更します。

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

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

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

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

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

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

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

close( )
接続を一方的に閉じます。 既に閉じた接続に対して実行すべきではありません(例えばquit()を 呼び出して成功した後など)。 この実行の後、FTPインスタンスはもう使用すべきではありません (close()あるいはquit()を呼び出した後で、 login()メソッドをもう一度実行して再び接続を開くことはできませ ん)。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。