"ftplib" --- FTP プロトコルクライアント
***************************************

**ソースコード:** Lib/ftplib.py

======================================================================

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

デフォルトのエンコーディングは **RFC 2640** に従い UTF-8 です。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは
、WebAssembly プラットフォーム を見てください。

"ftplib" モジュールを使ったセッションの例を示します。

   >>> from ftplib import FTP
   >>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
   >>> ftp.login()                     # user anonymous, passwd anonymous@
   '230 Login successful.'
   >>> ftp.cwd('debian')               # change into "debian" directory
   '250 Directory successfully changed.'
   >>> 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.'
   >>> with open('README', 'wb') as fp:
   ...     ftp.retrbinary('RETR README', fp.write)
   '226 Transfer complete.'
   >>> ftp.quit()
   '221 Goodbye.'


リファレンス
============


FTP オブジェクト
----------------

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

   "FTP" クラスの新しいインスタンスを返します。

   パラメータ:
      * **host** (*str*) -- 接続先のホスト名。 指定した場合、コンスト
        ラクタが暗黙に "connect(host)" を呼び出します。

      * **user** (*str*) -- The username to log in with (default:
        "'anonymous'"). If given, "login(host, passwd, acct)" is
        implicitly called by the constructor.

      * **passwd** (*str*) -- The password to use when logging in. If
        not given, and if *passwd* is the empty string or ""-"", a
        password will be automatically generated.

      * **acct** (*str*) -- Account information to be used for the
        "ACCT" FTP command. Few systems implement this. See RFC-959
        for more details.

      * **timeout** (*float** | **None*) -- "connect()" などのブロック
        する操作のタイムアウトを秒単位で指定します (デフォルト: グロー
        バルなデフォルトのタイムアウト設定)。

      * **source_address** (*tuple** | **None*) -- A 2-tuple "(host,
        port)" for the socket to bind to as its source address before
        connecting.

      * **encoding** (*str*) -- The encoding for directories and
        filenames (default: "'utf-8'").

   "FTP" クラスは "with" 文をサポートしています。例えば:

   >>> from ftplib import FTP
   >>> with FTP("ftp1.at.proftpd.org") as ftp:
   ...     ftp.login()
   ...     ftp.dir()
   ...
   '230 Anonymous login ok, restrictions apply.'
   dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
   dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
   dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
   dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
   >>>

   バージョン 3.2 で変更: "with" 構文のサポートが追加されました。

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

   バージョン 3.9 で変更: *timeout* 引数にゼロを指定すると、非ブロッキ
   ングソケットの作成を防ぐために "ValueError" を送出するようになりま
   した。 *encoding* 引数が追加され、**RFC 2640** に従ってデフォルトが
   Latin-1 から UTF-8 に変更されました。

   "FTP" のいくつかのメソッドには、テキストファイル用とバイナリファイ
   ル用の 2 種類があります。 メソッド名は、使用するコマンドに、テキス
   ト用では "lines"、バイナリ用では "binary" を付けたものです。

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

   set_debuglevel(level)

      インスタンスのデバッグレベルを "int" で設定します。 この値はデバ
      ッグ出力の量を制御します。 デバッグレベルは次のとおりです。

      * "0" (デフォルト): デバッグ出力を行いません。

      * "1": 適度な量のデバッグ出力を行います。 通常はリクエストごとに
        1 行です。

      * "2" 以上: 最大量のデバッグ出力を行い、制御接続で送受信する各行
        を記録します。

   connect(host='', port=0, timeout=None, source_address=None)

      指定したホストとポートに接続します。 この関数はインスタンスごと
      に 1 回だけ呼び出してください。 "FTP" インスタンスの作成時に
      *host* 引数を指定した場合は呼び出さないでください。 ほかのすべて
      の "FTP" メソッドは、接続が成功してから呼び出せます。

      パラメータ:
         * **host** (*str*) -- 接続先のホスト。

         * **port** (*int*) -- 接続先の TCP ポート (デフォルト: FTP プ
           ロトコルの仕様で定められた "21")。 別のポート番号を指定する
           必要はほとんどありません。

         * **timeout** (*float** | **None*) -- 接続試行のタイムアウト
           を秒単位で指定します (デフォルト: グローバルなデフォルトの
           タイムアウト設定)。

         * **source_address** (*tuple** | **None*) -- A 2-tuple
           "(host, port)" for the socket to bind to as its source
           address before connecting.

      引数 "self", "host", "port" を指定して 監査イベント
      "ftplib.connect" を送出します。

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

   getwelcome()

      サーバに最初に接続した際に送信される応答中のウェルカムメッセージ
      を返します。(このメッセージには時に、ユーザにとって重要な免責事
      項や ヘルプ情報が入っています。)

   login(user='anonymous', passwd='', acct='')

      接続中の FTP サーバーにログインします。 この関数は接続が確立した
      後、インスタンスごとに 1 回だけ呼び出してください。 "FTP" インス
      タンスの作成時に *host* と *user* 引数を指定した場合は呼び出さな
      いでください。 ほとんどの FTP コマンドは、クライアントがログイン
      した後でのみ使用できます。

      パラメータ:
         * **user** (*str*) -- The username to log in with (default:
           "'anonymous'").

         * **passwd** (*str*) -- The password to use when logging in.
           If not given, and if *passwd* is the empty string or ""-"",
           a password will be automatically generated.

         * **acct** (*str*) -- Account information to be used for the
           "ACCT" FTP command. Few systems implement this. See RFC-959
           for more details.

   abort()

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

   sendcmd(cmd)

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

      引数 "self", "cmd" を指定して 監査イベント "ftplib.sendcmd" を送
      出します。

   voidcmd(cmd)

      単純なコマンド文字列をサーバーに送信し、応答を処理します。 応答
      コードが成功を表す場合 (200〜299 のコード) は応答文字列を返しま
      す。 それ以外の場合は "error_reply" を送出します。

      引数 "self", "cmd" を指定して 監査イベント "ftplib.sendcmd" を送
      出します。

   retrbinary(cmd, callback, blocksize=8192, rest=None)

      バイナリ転送モードでファイルを取得します。

      パラメータ:
         * **cmd** (*str*) -- 適切な "RETR" コマンド: ""RETR
           *filename*""。

         * **callback** (*callable*) -- 受信したデータのブロックごとに
           呼び出される、引数を 1 つ取る呼び出し可能オブジェクト。 そ
           の引数には "bytes" としてデータが渡されます。

         * **blocksize** (*int*) -- 実際の転送用に作成される低水準の
           "socket" オブジェクトから読み取るチャンクの最大サイズ。
           *callback* に渡すデータの最大サイズでもあります。 デフォル
           トは "8192" です。

         * **rest** (*int*) -- サーバーに送信する "REST" コマンド。
           "transfercmd()" メソッドの *rest* 引数の説明を参照してくだ
           さい。

   retrlines(cmd, callback=None)

      初期化時に *encoding* 引数で指定したエンコーディングで、ファイル
      またはディレクトリ一覧を取得します。 *cmd* には適切な "RETR" コ
      マンド ("retrbinary()" を参照)、または "LIST" や "NLST" などのコ
      マンドを指定してください (通常は単に文字列 "'LIST'")。 "LIST" は
      ファイルの一覧とそれらのファイルに関する情報を取得します。
      "NLST" はファイル名の一覧を取得します。 各行について *callback*
      関数を呼び出し、末尾の CRLF を除いた行を文字列の引数として渡しま
      す。 デフォルトの *callback* は、その行を "sys.stdout" に出力し
      ます。

   set_pasv(val)

      *val* が真の場合 "パッシブ" モードを有効化し、偽の場合は無効化し
      ます。 デフォルトではパッシブモードです。

   storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

      バイナリ転送モードでファイルを保存します。

      パラメータ:
         * **cmd** (*str*) -- 適切な "STOR" コマンド: ""STOR
           *filename*""。

         * **fp** (*file object*) -- バイナリモードで開かれたファイル
           オブジェクト。 "read()" メソッドで *blocksize* サイズのブロ
           ックごとに EOF まで読み取り、保存するデータを供給します。

         * **blocksize** (*int*) -- 読み取るブロックのサイズ。 デフォ
           ルトは "8192" です。

         * **callback** (*callable*) -- データのブロックを送信するたび
           に呼び出される、引数を 1 つ取る呼び出し可能オブジェクト。
           その引数には "bytes" としてデータが渡されます。

         * **rest** (*int*) -- サーバーに送信する "REST" コマンド。
           "transfercmd()" メソッドの *rest* 引数の説明を参照してくだ
           さい。

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

   storlines(cmd, fp, callback=None)

      行モードでファイルを保存します。 *cmd* には適切な "STOR" コマン
      ドを指定してください ("storbinary()" を参照)。 バイナリモードで
      開かれた *file object* *fp* の "readline()" メソッドを使い、EOF
      まで行を読み取って保存するデータを供給します。 *callback* は引数
      を 1 つ取る省略可能な呼び出し可能オブジェクトで、各行の送信後に
      呼び出されます。

   transfercmd(cmd, rest=None)

      データ接続での転送を開始します。 アクティブモードの場合は "EPRT"
      または "PORT" コマンドと、*cmd* で指定された転送コマンドを送信し
      て、接続を受け入れます。 パッシブモードの場合は "EPSV" または
      "PASV" コマンドを送信してサーバーに接続し、転送コマンドを開始し
      ます。 どちらの場合も、その接続のソケットを返します。

      省略可能な *rest* を指定すると、その値を引数として "REST" コマン
      ドをサーバーに送信します。 通常、*rest* は要求するファイル内のバ
      イトオフセットであり、ファイルの先頭部分を飛ばして、指定した位置
      から送信を再開するようサーバーに指示します。 ただし
      "transfercmd()" メソッドは、初期化時の *encoding* 引数を使って
      *rest* を文字列に変換するだけで、その内容は検査しません。 サーバ
      ーが "REST" コマンドを認識しない場合は "error_reply" 例外を送出
      します。 その場合は *rest* 引数を指定せずに "transfercmd()" を呼
      び出してください。

   ntransfercmd(cmd, rest=None)

      "transfercmd()" と同様ですが、データ接続と転送データの予想サイズ
      のタプルを返します。 予想サイズを計算できない場合、その要素は
      "None" になります。 *cmd* と *rest* の意味は "transfercmd()" と
      同じです。

   mlsd(path='', facts=[])

      "MLSD" コマンド (**RFC 3659**) を使い、標準化された形式でディレ
      クトリを一覧表示します。 *path* を省略するとカレントディレクトリ
      を対象とします。 *facts* は必要な情報の種類を表す文字列のリスト
      です (例: "["type", "size", "perm"]")。 "path" に見つかったファ
      イルごとに 2 要素のタプルを yield するジェネレータオブジェクトを
      返します。 最初の要素はファイル名、2 番目の要素はそのファイルの
      情報を含む辞書です。 この辞書の内容は *facts* 引数で制限できる場
      合がありますが、要求したすべての情報をサーバーが返す保証はありま
      せん。

      Added in version 3.3.

   nlst(argument[, ...])

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

      注釈:

        サーバーがこのコマンドをサポートしている場合は、"mlsd()" の方
        が優れた API を提供します。

   dir(argument[, ...])

      "LIST" コマンドが返すディレクトリ一覧を標準出力に表示します。 省
      略可能な *argument* は一覧表示するディレクトリです (デフォルトは
      サーバーのカレントディレクトリ)。 複数の引数を使って、非標準のオ
      プションを "LIST" コマンドに渡せます。 最後の引数が関数の場合は
      、"retrlines()" と同様に *callback* 関数として使います。 デフォ
      ルトでは "sys.stdout" に表示します。 このメソッドは "None" を返
      します。

      注釈:

        サーバーがこのコマンドをサポートしている場合は、"mlsd()" の方
        が優れた API を提供します。

   rename(fromname, toname)

      サーバ上のファイルのファイル名 *fromname* を *toname* へ変更しま
      す。

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


FTP_TLS オブジェクト
--------------------

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')

   **RFC 4217** に従って FTP に TLS サポートを追加する "FTP" のサブク
   ラスです。 ポート 21 に接続し、認証前に FTP の制御接続を暗黙に保護
   します。

   注釈:

     データ接続は、利用者が "prot_p()" メソッドを呼び出して明示的に保
     護する必要があります。

   パラメータ:
      * **host** (*str*) -- 接続先のホスト名。 指定した場合、コンスト
        ラクタが暗黙に "connect(host)" を呼び出します。

      * **user** (*str*) -- The username to log in with (default:
        "'anonymous'"). If given, "login(host, passwd, acct)" is
        implicitly called by the constructor.

      * **passwd** (*str*) -- The password to use when logging in. If
        not given, and if *passwd* is the empty string or ""-"", a
        password will be automatically generated.

      * **acct** (*str*) -- Account information to be used for the
        "ACCT" FTP command. Few systems implement this. See RFC-959
        for more details.

      * **context** ("ssl.SSLContext") -- SSL の設定オプション、証明書
        、秘密鍵を、長期間使用できる単一の構造にまとめる SSL コンテキ
        ストオブジェクトです。 推奨される使用方法については セキュリテ
        ィで考慮すべき点 を参照してください。

      * **timeout** (*float** | **None*) -- "connect()" などのブロック
        する操作のタイムアウトを秒単位で指定します (デフォルト: グロー
        バルなデフォルトのタイムアウト設定)。

      * **source_address** (*tuple** | **None*) -- A 2-tuple "(host,
        port)" for the socket to bind to as its source address before
        connecting.

      * **encoding** (*str*) -- The encoding for directories and
        filenames (default: "'utf-8'").

   Added in version 3.2.

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

   バージョン 3.4 で変更: このクラスは "ssl.SSLContext.check_hostname"
   によるホスト名の検証と *Server Name Indication* ("ssl.HAS_SNI" を参
   照) をサポートするようになりました。

   バージョン 3.9 で変更: *timeout* 引数にゼロを指定すると、非ブロッキ
   ングソケットの作成を防ぐために "ValueError" を送出するようになりま
   した。 *encoding* 引数が追加され、**RFC 2640** に従ってデフォルトが
   Latin-1 から UTF-8 に変更されました。

   バージョン 3.12 で変更: 非推奨の *keyfile* と *certfile* 引数を削除
   しました。

   "FTP_TLS" クラスを使ったセッションの例を示します。

      >>> ftps = FTP_TLS('ftp.pureftpd.org')
      >>> ftps.login()
      '230 Anonymous user logged in'
      >>> ftps.prot_p()
      '200 Data protection level set to "private"'
      >>> ftps.nlst()
      ['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']

   "FTP_TLS" クラスは "FTP" を継承し、次のメソッドと属性を追加で定義し
   ます。

   auth()

      TLS を使って安全な制御接続を確立します。

      バージョン 3.4 で変更: このメソッドは
      "ssl.SSLContext.check_hostname" によるホスト名の検証と *Server
      Name Indication* ("ssl.HAS_SNI" を参照) をサポートするようになり
      ました。

   ccc()

      制御チャネルを平文に戻します。 暗号化されていない FTP の NAT を
      処理できるファイアウォールで、固定ポートを開かずにその機能を利用
      する場合に役立ちます。

      Added in version 3.3.

   prot_p()

      TLS を使って安全なデータ接続を確立します。

   prot_c()

      平文データ接続をセットアップします。


モジュール変数
--------------

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 接続の問題によって送出する可能性
   のある例外を、すべてまとめたタプルです。 呼び出し側のプログラミング
   上の誤りによる例外は含みません。 上記の 4 つの例外に加え、"OSError"
   と "EOFError" も含まれます。

参考:

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