\section{\module{ftplib} ---
FTPプロトコルクライアント}
\declaremodule{standard}{ftplib}
\modulesynopsis{FTPプロトコルクライアント(ソケットを必要とします)。}

\indexii{FTP}{protocol}
\index{FTP!\module{ftplib} (standard module)}

このモジュールでは\class{FTP}クラスと、それに関連するいくつかの項目を定
義しています。
\class{FTP}クラスは、FTPプロトコルのクライアント側の機能を備えています。
このクラスを使うとFTPのいろいろな機能の自動化、例えば他のFTPサーバのミ
ラーリングといったことを実行するPythonプログラムを書くことができます。
また、\refmodule{urllib}モジュールもFTPを使うURLを操作するのにこのクラス
を使っています。
FTP (File Transfer Protocol)についての詳しい情報はInternet \rfc{959}を参
照して下さい。

\module{ftplib}モジュールを使ったサンプルを以下に示します：

\begin{verbatim}
>>> 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()
\end{verbatim}

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

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

\begin{datadesc}{all_errors}
\class{FTP}インスタンスのメソッドの結果、FTP接続で（プログラミングのエ
ラーと考えられるメソッドの実行によって）発生する全ての例外（タプル形
式）。
この例外には以下の４つのエラーはもちろん、\exception{socket.error}と
\exception{IOError}も含まれます。
\end{datadesc}

\begin{excdesc}{error_reply}
サーバから想定外の応答があった時に発生する例外。
\end{excdesc}

\begin{excdesc}{error_temp}
400--499の範囲のエラー応答コードを受け取った時に発生する例外。
\end{excdesc}

\begin{excdesc}{error_perm}
500--599の範囲のエラー応答コードを受け取った時に発生する例外。
\end{excdesc}

\begin{excdesc}{error_proto}
1--5の数字で始まらない応答コードをサーバから受け取った時に発生する例外。
\end{excdesc}

\begin{seealso}
\seemodule{netrc}{\file{.netrc}ファイルフォーマットのパーザ。
\file{.netrc}ファイルは、FTPクライアントがユーザにプロンプトを出す前に、
ユーザ認証情報をロードするのによく使われます。}
\seetext{Pythonのソースディストリビューションの\file{Tools/scripts/ftpmi
rror.py}\index{ftpmirror.py}ファイルは、FTPサイトあるいはその一部をミ
ラーリングするスクリプトで、\module{ftplib}モジュールを使っています。こ
のモジュールを適用した応用例として使うことができます。}
\end{seealso}

\subsection{FTP オブジェクト \label{ftp-objects}}

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

\class{FTP}インスタンスには以下のメソッドがあります：

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

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

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

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

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

\begin{methoddesc}[FTP]{sendcmd}{command}
シンプルなコマンド文字列をサーバに送信して、受信した文字列を返します。
\end{methoddesc}

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

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

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

\begin{methoddesc}[FTP]{set_pasv}{boolean}
\var{boolean}がtrueなら``パッシブモード''をオンにし、そうでないならパッ
シブモードをオフにします。
（Python 2.0以前ではデフォルトでパッシブモードはオフにされていましたが、
Python 2.1以後ではデフォルトでオンになっています。）
\end{methoddesc}

\begin{methoddesc}[FTP]{storbinary}{command, file\optional{, blocksize}}
バイナリ転送モードでファイルを転送します。
\var{command}は適切な\samp{STOR}コマンド：\code{"STOR \var{filename}"}で
なければなりません。
\var{file}は開かれたファイルオブジェクトで、\method{read()}メソッドで
\EOF{}まで読み込まれ、ブロックサイズ\var{blocksize}でデータが転送されま
す。
引数\var{blocksize}のデフォルト値は8192です。
\versionchanged[\var{blocksize}のデフォルト値が追加されました]{2.1}
\end{methoddesc}

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

\begin{methoddesc}[FTP]{transfercmd}{cmd\optional{, rest}}
データ接続中に転送を初期化します。
もし転送中なら、\samp{EPRT}あるいは\samp{PORT}コマンドと、\var{cmd}で指
定したコマンドを送信し、接続を続けます。
サーバがパッシブなら、\samp{EPSV}あるいは\samp{PASV}コマンドを送信して接
続し、転送コマンドを開始します。
どちらの場合も、接続のためのソケットを返します。

省略可能な\var{rest}が与えられたら、\samp{REST}コマンドがサーバに送信さ
れ、\var{rest}を引数として与えます。
\var{rest}は普通、要求したファイルのバイトオフセット値で、最初のバイトを
とばして指定したオフセット値からファイルのバイト転送を再開するよう伝えま
す。
しかし、RFC 959では\var{rest}が印字可能なASCIIコード33から126の範囲の文
字列からなることを要求していることに注意して下さい。
したがって、\method{transfercmd()}メソッドは\var{rest}を文字列に変換しま
すが、文字列の内容についてチェックしません。
もし\samp{REST}コマンドをサーバが認識しないなら、例外\exception{error_re
ply}が発生します。
この例外が発生したら、引数\var{rest}なしに\method{transfercmd()}を実行し
ます。
\end{methoddesc}

\begin{methoddesc}[FTP]{ntransfercmd}{cmd\optional{, rest}}
\method{transfercmd()}と同様ですが、データと予想されるサイズとのタプルを
返します。
もしサイズが計算できないなら、サイズの代わりに\code{None}が返されます。
\var{cmd}と\var{rest}は\method{transfercmd()}のものと同じです。
\end{methoddesc}

\begin{methoddesc}[FTP]{nlst}{argument\optional{, \ldots}}
\samp{NLST}コマンドで返されるファイルのリストを返します。
省略可能な\var{argument}は、リストアップするディレクトリです（デフォルト
ではサーバのカレントディレクトリです）。
\samp{NLST}コマンドに非標準である複数の引数を渡すことができます。
\end{methoddesc}

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

\begin{methoddesc}[FTP]{rename}{fromname, toname}
サーバ上のファイルのファイル名\var{fromname}を\var{toname}へ変更します。
\end{methoddesc}

\begin{methoddesc}[FTP]{delete}{filename}
サーバからファイル\var{filename}を削除します。
成功したら応答のテキストを返し、そうでないならパーミッションエラーでは
\exception{error_perm}を、他のエラーでは\exception{error_reply}を返しま
す。
\end{methoddesc}

\begin{methoddesc}[FTP]{cwd}{pathname}
サーバのカレントディレクトリを設定します。
\end{methoddesc}

\begin{methoddesc}[FTP]{mkd}{pathname}
サーバ上に新たにディレクトリを作ります。
\end{methoddesc}

\begin{methoddesc}[FTP]{pwd}{}
サーバ上のカレントディレクトリのパスを返します。
\end{methoddesc}

\begin{methoddesc}[FTP]{rmd}{dirname}
サーバ上のディレクトリ\var{dirname}を削除します。
\end{methoddesc}

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

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

\begin{methoddesc}[FTP]{close}{}
接続を一方的に閉じます。
既に閉じた接続に対して実行すべきではありません（例えば\method{quit()}を
呼び出して成功した後など）。
この実行の後、\class{FTP}インスタンスはもう使用すべきではありません
（\method{close()}あるいは\method{quit()}を呼び出した後で、
\method{login()}メソッドをもう一度実行して再び接続を開くことはできませ
ん）。
\end{methoddesc}
