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クライアントがユーザにプロンプトを出す前に、ユーザ認証情報をロードするのによく使われます。