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

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

このモジュールは、クラス FTP といくつかの関連アイテムを定義します。 FTP クラスは、FTPプロトコルのクライアント側を実装します。これを使用して、他のFTPサーバーのミラーリングなど、さまざまな自動FTPジョブを実行するPythonプログラムを作成できます。また、FTPを使用するURLを処理するために、モジュール urllib.request によって使用されます。 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.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()

このモジュールは、次の項目を定義します。

class ftplib.FTP(host=, user=, passwd=, acct=, timeout=None, source_address=None)

FTP クラスの新しいインスタンスを返します。 host を指定すると、メソッド呼び出しconnect(host)が行われます。 user が指定されると、さらにlogin(user, passwd, acct)メソッド呼び出しが行われます（ passwd および acct は、指定されていない場合、デフォルトで空の文字列になります）。オプションの timeout パラメーターは、接続試行などのブロック操作のタイムアウトを秒単位で指定します（指定されていない場合は、グローバルなデフォルトのタイムアウト設定が使用されます）。 source_address は、接続する前にソケットが送信元アドレスとしてバインドするための2タプル(host, port)です。

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 パラメーターが追加されました。

class ftplib.FTP_TLS(host=, user=, passwd=, acct=, keyfile=None, certfile=None, context=None, timeout=None, source_address=None)

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

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

バージョン3.2の新機能。

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

バージョン3.4で変更：クラスは ssl.SSLContext.check_hostname および Server Name Indication によるホスト名チェックをサポートするようになりました（ ssl.HAS_SNI を参照））。

バージョン3.6以降非推奨： keyfile および certfile は非推奨になり、 context が優先されます。代わりに ssl.SSLContext.load_cert_chain（）を使用するか、 ssl.create_default_context（）にシステムの信頼できるCA証明書を選択させてください。

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']

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つの例外と、 OSError および EOFError が含まれています。

も参照してください

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

FTPオブジェクト

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

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

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

FTP.connect(host=, port=0, timeout=None, source_address=None): 指定されたホストとポートに接続します。 FTPプロトコル仕様で指定されているように、デフォルトのポート番号は21です。別のポート番号を指定する必要はほとんどありません。この関数は、インスタンスごとに1回だけ呼び出す必要があります。インスタンスの作成時にホストが指定された場合は、まったく呼び出さないでください。他のすべての方法は、接続が確立された後にのみ使用できます。オプションの timeout パラメーターは、接続試行のタイムアウトを秒単位で指定します。 timeout が渡されない場合、グローバルなデフォルトのタイムアウト設定が使用されます。 source_address は、接続する前にソケットが送信元アドレスとしてバインドするための2タプル(host, port)です。

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

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

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

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

FTP.sendcmd(cmd): 単純なコマンド文字列をサーバーに送信し、応答文字列を返します。

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

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

FTP.retrlines(cmd, callback=None): ASCII転送モードでファイルまたはディレクトリのリストを取得します。 cmd は、適切なRETRコマンド（ retrbinary（）を参照）またはLISTやNLSTなどのコマンド（通常は文字列'LIST'）のみ。 LISTは、ファイルのリストとそれらのファイルに関する情報を取得します。 NLSTは、ファイル名のリストを取得します。 callback 関数は、末尾のCRLFが削除された行を含む文字列引数を使用して各行に対して呼び出されます。デフォルトの callback は、行をsys.stdoutに出力します。

FTP.set_pasv(val): val がtrueの場合は「パッシブ」モードを有効にし、それ以外の場合はパッシブモードを無効にします。パッシブモードはデフォルトでオンになっています。

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

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

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

FTP.transfercmd(cmd, rest=None)

データ接続を介して転送を開始します。転送がアクティブな場合は、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=None): transfercmd（）と同様ですが、データ接続のタプルとデータの予想サイズを返します。予想サイズを計算できなかった場合は、Noneが予想サイズとして返されます。 cmd および rest は、 transfercmd（）と同じ意味です。

FTP.mlsd(path=, facts=[]): MLSDコマンド（ RFC 3659 ）を使用して、標準化された形式でディレクトリを一覧表示します。 path を省略すると、現在のディレクトリが想定されます。 facts は、必要な情報のタイプを表す文字列のリストです（例： ["type", "size", "perm"]）。パスで見つかったすべてのファイルに対して2つの要素のタプルを生成するジェネレータオブジェクトを返します。最初の要素はファイル名であり、2番目の要素はファイル名に関する事実を含む辞書です。この辞書の内容は facts 引数によって制限される可能性がありますが、サーバーは要求されたすべてのファクトを返すことが保証されていません。

バージョン3.3の新機能。

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

ノート

サーバーがコマンドをサポートしている場合、 mlsd（）はより優れたAPIを提供します。

FTP.dir(argument[, ...]): LISTコマンドによって返されるディレクトリリストを作成し、標準出力に出力します。オプションの argument は、リストするディレクトリです（デフォルトは現在のサーバーディレクトリです）。複数の引数を使用して、非標準オプションをLISTコマンドに渡すことができます。最後の引数が関数の場合、 retrlines（）と同様にコールバック関数として使用されます。デフォルトではsys.stdoutに出力されます。このメソッドはNoneを返します。

ノート

サーバーがコマンドをサポートしている場合、 mlsd（）はより優れたAPIを提供します。

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（）メソッド）。

FTP_TLSオブジェクト

FTP_TLS クラスは FTP を継承し、次の追加オブジェクトを定義します。

FTP_TLS.ssl_version: 使用するSSLバージョン（デフォルトは ssl.PROTOCOL_SSLv23 ）。

FTP_TLS.auth(): ssl_version 属性で指定されている内容に応じて、TLSまたはSSLを使用して安全な制御接続をセットアップします。

バージョン3.4で変更：このメソッドは、 ssl.SSLContext.check_hostname および Server Name Indication によるホスト名チェックをサポートするようになりました（ ssl.HAS_SNI を参照））。

FTP_TLS.ccc(): 制御チャネルを平文に戻します。これは、固定ポートを開かずに非セキュアFTPでNATを処理する方法を知っているファイアウォールを利用するのに役立ちます。

バージョン3.3の新機能。

FTP_TLS.prot_p(): 安全なデータ接続を設定します。

FTP_TLS.prot_c(): クリアテキストデータ接続を設定します。

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

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

FTPオブジェクト

FTP_TLSオブジェクト