20.8. ftplib — FTPプロトコルクライアント—Pythonドキュメント

20.8。 ftplib —FTPプロトコルクライアント

ソースコード： ：source： `Lib / ftplib.py`

---

このモジュールは、クラス FTP といくつかの関連アイテムを定義します。 FTP クラスは、FTPプロトコルのクライアント側を実装します。 これを使用して、他のFTPサーバーのミラーリングなど、さまざまな自動FTPジョブを実行するPythonプログラムを作成できます。 また、FTPを使用するURLを処理するためにモジュール urllib によって使用されます。 FTP（ファイル転送プロトコル）の詳細については、インターネット 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 は、指定されていない場合、デフォルトで空の文字列になります）。 オプションの timeout パラメーターは、接続試行などのブロック操作のタイムアウトを秒単位で指定します（指定されていない場合は、グローバルなデフォルトのタイムアウト設定が使用されます）。

バージョン2.6で変更： timeout が追加されました。

class ftplib.FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])

RFC 4217 で説明されているように、FTPにTLSサポートを追加する FTP サブクラス。 認証する前に、通常どおりポート21に接続してFTP制御接続を暗黙的に保護します。 データ接続を保護するには、ユーザーが prot_p（）メソッドを呼び出して明示的に要求する必要があります。 context は、 ssl.SSLContext オブジェクトであり、SSL構成オプション、証明書、および秘密鍵を単一の（潜在的に長寿命の）構造にバンドルできます。 ベストプラクティスについては、セキュリティに関する考慮事項をお読みください。

keyfile および certfile は、 context のレガシー代替手段であり、SSL接続用に（それぞれ）PEM形式の秘密鍵および証明書チェーンファイルを指すことができます。

バージョン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

ファイル転送プロトコルの応答仕様に適合しない応答をサーバーから受信した場合に発生する例外。 1〜5の範囲の数字で始まります。

ftplib.all_errors

FTP インスタンスのメソッドが（呼び出し元によるプログラミングエラーとは対照的に）FTP接続の問題の結果として発生する可能性のあるすべての例外のセット（タプルとして）。 このセットには、上記の4つの例外と、 socket.error およびIOErrorが含まれています。

も参照してください

モジュール netrc

.netrcファイル形式のパーサー。 ファイル.netrcは通常、ユーザーにプロンプトを表示する前にユーザー認証情報をロードするためにFTPクライアントによって使用されます。

PythonソースディストリビューションのファイルTools/scripts/ftpmirror.pyは、 ftplib モジュールを使用して、FTPサイトまたはその一部をミラーリングできるスクリプトです。 このモジュールを適用する拡張例として使用できます。

20.8.1。 FTPオブジェクト

いくつかの方法が2つのフレーバーで利用できます。1つはテキストファイルを処理するためのもので、もう1つはバイナリファイルのためのものです。 これらは、使用されるコマンドにちなんで名付けられ、その後にテキストバージョンの場合はlines、バイナリバージョンの場合はbinaryが続きます。

FTP インスタンスには次のメソッドがあります。

FTP.set_debuglevel(level)

インスタンスのデバッグレベルを設定します。 これは、出力されるデバッグ出力の量を制御します。 デフォルトの0は、デバッグ出力を生成しません。 1の値は、適度な量のデバッグ出力を生成します。通常、要求ごとに1行です。 2以上の値は、最大量のデバッグ出力を生成し、制御接続で送受信された各行をログに記録します。

FTP.connect(host[, port[, timeout]])

指定されたホストとポートに接続します。 FTPプロトコル仕様で指定されているように、デフォルトのポート番号は21です。 別のポート番号を指定する必要はほとんどありません。 この関数は、インスタンスごとに1回だけ呼び出す必要があります。 インスタンスの作成時にホストが指定された場合は、まったく呼び出さないでください。 他のすべての方法は、接続が確立された後にのみ使用できます。

オプションの timeout パラメーターは、接続試行のタイムアウトを秒単位で指定します。 timeout が渡されない場合、グローバルなデフォルトのタイムアウト設定が使用されます。

バージョン2.6で変更： timeout が追加されました。

FTP.getwelcome()

最初の接続に応答してサーバーから送信されたウェルカムメッセージを返します。 （このメッセージには、ユーザーに関連する可能性のある免責事項またはヘルプ情報が含まれている場合があります。）

FTP.login([user[, passwd[, acct]]])

指定されたユーザーとしてログインします。 passwd および acct パラメーターはオプションであり、デフォルトで空の文字列になります。 user が指定されていない場合、デフォルトで'anonymous'になります。 user が'anonymous'の場合、デフォルトの passwd は'anonymous@'です。 この関数は、接続が確立された後、インスタンスごとに1回だけ呼び出す必要があります。 インスタンスの作成時にホストとユーザーが指定されている場合は、まったく呼び出さないでください。 ほとんどのFTPコマンドは、クライアントがログインした後にのみ許可されます。 acct パラメーターは、「アカウンティング情報」を提供します。 これを実装しているシステムはほとんどありません。

FTP.abort()

進行中のファイル転送を中止します。 これを使用しても常に機能するとは限りませんが、試してみる価値はあります。

FTP.sendcmd(command)

単純なコマンド文字列をサーバーに送信し、応答文字列を返します。

FTP.voidcmd(command)

簡単なコマンド文字列をサーバーに送信し、応答を処理します。 成功に対応する応答コード（200〜299の範囲のコード）を受信した場合は、何も返しません。 それ以外の場合は、 error_reply を発生させます。

FTP.retrbinary(command, callback[, maxblocksize[, rest]])

バイナリ転送モードでファイルを取得します。 コマンドは適切なRETRコマンドである必要があります：'RETR filename'。 callback 関数は、受信したデータのブロックごとに呼び出され、単一の文字列引数がデータブロックを示します。 オプションの maxblocksize 引数は、実際の転送を行うために作成された低レベルソケットオブジェクトで読み取る最大チャンクサイズを指定します（これは、コールバック[X228Xに渡されるデータブロックの最大サイズでもあります） ]）。 妥当なデフォルトが選択されます。 rest は、 transfercmd（）メソッドと同じ意味です。

FTP.retrlines(command[, callback])

ASCII転送モードでファイルまたはディレクトリのリストを取得します。 コマンドは、適切なRETRコマンド（ retrbinary（）を参照）またはLIST、NLST、[ X133X] （通常は文字列'LIST'のみ）。 LISTは、ファイルのリストとそれらのファイルに関する情報を取得します。 NLSTは、ファイル名のリストを取得します。 一部のサーバーでは、MLSDは、マシンで読み取り可能なファイルのリストとそれらのファイルに関する情報を取得します。 callback 関数は、末尾のCRLFが削除された行を含む文字列引数を使用して各行に対して呼び出されます。 デフォルトの callback は、行をsys.stdoutに出力します。

FTP.set_pasv(val)

val がtrueの場合は「パッシブ」モードを有効にし、それ以外の場合はパッシブモードを無効にします。 （Python 2.0以前では、パッシブモードはデフォルトでオフでした。Python2.1以降では、デフォルトでオンになっています。）

FTP.storbinary(command, fp[, blocksize, callback, rest])

ファイルをバイナリ転送モードで保存します。 コマンドは適切なSTORコマンドである必要があります："STOR filename"。 fp は、保存するデータを提供するために、サイズ blocksize のブロックでread()メソッドを使用してEOFまで読み取られるオープンファイルオブジェクトです。 blocksize 引数のデフォルトは8192です。 callback は、送信後にデータの各ブロックで呼び出されるオプションの単一パラメーターcallableです。 rest は、 transfercmd（）メソッドと同じ意味です。

バージョン2.1で変更：ブロックサイズのデフォルトが追加されました。

バージョン2.6で変更： コールバックパラメーターが追加されました。

バージョン2.7で変更： rest パラメーターが追加されました。

FTP.storlines(command, fp[, callback])

ファイルをASCII転送モードで保存します。 コマンドは適切なSTORコマンドである必要があります（ storbinary（）を参照）。 readline（）メソッドを使用して、開いているファイルオブジェクト fp からEOFまで行が読み取られ、格納されるデータが提供されます。 callback は、送信後に各行で呼び出されるオプションの単一パラメーターcallableです。

バージョン2.6で変更： コールバックパラメーターが追加されました。

FTP.transfercmd(cmd[, rest])

データ接続を介して転送を開始します。 転送がアクティブな場合は、EPRTまたはPORTコマンドと cmd で指定された転送コマンドを送信し、接続を受け入れます。 サーバーがパッシブの場合は、EPSVまたはPASVコマンドを送信してサーバーに接続し、転送コマンドを開始します。 いずれにせよ、接続用のソケットを返却してください。

オプションの rest を指定すると、RESTコマンドがサーバーに送信され、 rest が引数として渡されます。 rest は通常、要求されたファイルへのバイトオフセットであり、最初のバイトをスキップして、要求されたオフセットでファイルのバイトの送信を再開するようサーバーに指示します。 ただし、RFC 959では、 rest がASCIIコード33からASCIIコード126までの印刷可能な範囲の文字を含む文字列である必要があるだけであることに注意してください。 したがって、 transfercmd（）メソッドは、 rest を文字列に変換しますが、文字列の内容はチェックされません。 サーバーがRESTコマンドを認識しない場合、 error_reply 例外が発生します。 これが発生した場合は、 rest 引数なしで transfercmd（）を呼び出すだけです。

FTP.ntransfercmd(cmd[, rest])

transfercmd（）と同様ですが、データ接続のタプルとデータの予想サイズを返します。 予想サイズを計算できなかった場合は、Noneが予想サイズとして返されます。 cmd および rest は、 transfercmd（）と同じ意味です。

FTP.nlst(argument[, ...])

NLSTコマンドによって返されるファイル名のリストを返します。 オプションの argument は、リストするディレクトリです（デフォルトは現在のサーバーディレクトリです）。 複数の引数を使用して、非標準オプションをNLSTコマンドに渡すことができます。

FTP.dir(argument[, ...])

LISTコマンドによって返されるディレクトリリストを作成し、標準出力に出力します。 オプションの argument は、リストするディレクトリです（デフォルトは現在のサーバーディレクトリです）。 複数の引数を使用して、非標準オプションをLISTコマンドに渡すことができます。 最後の引数が関数の場合、 retrlines（）と同様にコールバック関数として使用されます。 デフォルトでは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コマンドは標準化されていませんが、多くの一般的なサーバー実装でサポートされていることに注意してください。

FTP.quit()

QUITコマンドをサーバーに送信し、接続を閉じます。 これは接続を閉じるための「丁寧な」方法ですが、サーバーがQUITコマンドにエラーで応答した場合に例外が発生する可能性があります。 これは、 close（）メソッドの呼び出しを意味し、 FTP インスタンスを後続の呼び出しに使用できなくなります（以下を参照）。

FTP.close()

一方的に接続を閉じます。 これは、 quit（）の呼び出しが成功した後など、すでに閉じられている接続には適用しないでください。 この呼び出しの後、 FTP インスタンスは使用しないでください（ close（）または quit（）の呼び出し後、別のインスタンスを発行して接続を再開することはできません login（）メソッド）。

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()

クリアテキストデータ接続を設定します。