ftplib.FTP.set_debuglevel(): FTPデバッグの基本と応用
このメソッドを使用すると、FTP接続中に発生する通信の詳細をより詳細に表示させることができます。デバッグレベルは整数値で指定し、値が大きいほど詳細な情報が出力されます。
具体的な引数とその意味は以下の通りです。
debuglevel(整数):0: デバッグ情報を出力しません。1: クライアントとサーバー間のFTPコマンドと応答を出力します。これは最も一般的に使用されるデバッグレベルで、接続がどのように確立され、どのようなコマンドが送信されているかを確認するのに役立ちます。2以上: さらに詳細な情報（データ転送に関する情報など）が出力されることがありますが、通常はレベル1で十分です。
使用例
from ftplib import FTP
try:
# FTPクラスのインスタンスを作成
ftp = FTP('your_ftp_server.com')
# デバッグレベルを1に設定
ftp.set_debuglevel(1)
# ログイン
ftp.login('your_username', 'your_password')
# 何らかの操作（例: ファイルリストの取得）
ftp.dir()
# ログアウト
ftp.quit()
except Exception as e:
print(f"エラーが発生しました: {e}")
上記の例では、ftp.set_debuglevel(1) を呼び出すことで、FTPサーバーとの間でやり取りされるコマンドと応答がコンソールに出力されます。これにより、FTP接続に関する問題を特定したり、接続の動作を理解したりするのに非常に役立ちます。
- 動作の理解
FTPプロトコルの動作に慣れていない場合、デバッグ出力を確認することで、FTPクライアントとサーバーがどのように通信しているかを学ぶことができます。 - 問題の診断
FTP接続がうまくいかない場合（例: ログインできない、ファイル転送が失敗する）、set_debuglevel(1)を使用して、サーバーからの応答や送信されたコマンドを確認することで、問題の原因を特定しやすくなります。
ftplib.FTP.set_debuglevel() に関する一般的なエラーとトラブルシューティング
-
- エラー/問題
set_debuglevel(1)を設定しても、期待する情報が得られない、またはset_debuglevel(2)以上を設定したら出力が多すぎて読み解けない。 - トラブルシューティング
set_debuglevel(1)が最も一般的で、FTPコマンドとサーバー応答が表示されます。これが最も問題解決に役立つ情報量であることが多いです。- より詳細な情報が必要な場合は
set_debuglevel(2)を試しますが、通常はデータ接続の詳細などが含まれ、非常に冗長になります。 - 特定の情報だけが欲しい場合は、
ftplibのソースコードを読んで、どのデバッグレベルで何が出力されるかを確認するのも手です。
- エラー/問題
-
デバッグ出力が表示されない
- エラー/問題
set_debuglevel()を呼び出しているのに、何も出力されない。 - トラブルシューティング
-
標準出力がリダイレクトされている
プログラムの実行環境によっては、標準出力（sys.stdout）がファイルや他のストリームにリダイレクトされている可能性があります。ターミナルに直接出力させたい場合は、リダイレクトを解除するか、明示的にsys.stdoutに出力されるように設定されているか確認してください。 -
例外が発生して処理が中断している
set_debuglevel()を呼び出した後に、FTP接続や操作で例外が発生し、デバッグ出力が表示される前にプログラムが終了している可能性があります。try...exceptブロックで全体を囲み、例外が発生した際に何が起きているかを確認してください。 -
インスタンスの作成前に設定している
set_debuglevel()はFTPインスタンスのメソッドです。FTPインスタンスを作成する前に呼び出すと、エラーになります。# 間違い # ftplib.set_debuglevel(1) # これはエラーになる from ftplib import FTP ftp = FTP('your_ftp_server.com') ftp.set_debuglevel(1) # 正しい
-
- エラー/問題
-
デバッグ出力に具体的なエラーメッセージがない
- エラー/問題
set_debuglevel(1)でコマンドと応答は表示されるが、具体的なエラーの原因が読み取れない。例えば、「550 Failed to open file」のようなメッセージは出るが、なぜ失敗したのかが不明。 - トラブルシューティング
- FTPサーバーのログを確認する
ftplibのデバッグ出力はクライアント側の視点です。サーバー側で何が起きているかを確認するには、FTPサーバー自体のログ（通常は/var/log/vsftpd.logや/var/log/proftpd/proftpd.logなど）を確認するのが最も有効です。 - 権限の問題
「550 Permission denied」のようなエラーは、FTPユーザーがファイルやディレクトリに対する適切な書き込み/読み取り権限を持っていないことを示唆しています。サーバー側の設定を確認してください。 - パスの問題
ファイルのパスが正しくない場合も「550」エラーが出ることがあります。絶対パスを使用しているか、または現在のFTPディレクトリが意図した場所になっているか (ftp.pwd()で確認) を確認してください。 - ファイアウォール/ネットワークの問題
FTPはコントロールチャネルとデータチャネルを使用するため、ファイアウォールが適切に設定されていないと接続が中断されることがあります。特にパッシブモード (PASV) が機能しない場合、データ転送ができません。デバッグ出力でPASVコマンドとその応答（IPアドレスとポート番号）を確認し、それらの情報が正しく、アクセス可能であることを確認してください。
- FTPサーバーのログを確認する
- エラー/問題
-
ftplib以外の原因- エラー/問題
デバッグレベルを上げても、Pythonスクリプトがハングアップしたり、タイムアウトしたりする。 - トラブルシューティング
-
タイムアウト設定
ftplib.FTPのインスタンス作成時にtimeout引数を指定して、ネットワーク操作のタイムアウトを設定できます。短すぎるタイムアウトは、接続が確立される前に切断される原因となることがあります。ftp = FTP('your_ftp_server.com', timeout=30) # 30秒のタイムアウトを設定 -
ネットワークの不安定さ
ネットワーク接続が不安定な場合、FTPコマンドの応答が遅延したり、データ転送が中断されたりすることがあります。これはset_debuglevel()で詳細なログを確認することで、コマンドの送受信がどの時点で途切れているかを確認する手がかりになります。 -
サーバー側の問題
FTPサーバー自体が過負荷であったり、設定に問題があったりする場合、クライアント側では解決できない問題が発生します。サーバー管理者に問い合わせるのが最も確実な方法です。
-
- エラー/問題
- 例外処理と組み合わせる
set_debuglevel()はあくまでデバッグ情報の出力です。実際の運用では、ftplibが発生させる様々な例外（ftplib.all_errorsの派生クラスなど）を適切にキャッチし、エラーハンドリングを行うことが重要です。デバッグ出力と例外メッセージを組み合わせることで、より効果的な問題解決が可能です。 - 成功時のログと比較する
もし可能であれば、同じFTPサーバーで正常に動作する別のクライアント（例えば、FileZillaのようなGUIクライアント）のログや、以前成功したPythonスクリプトのデバッグ出力と比較することで、問題の切り分けがしやすくなります。 - 出力を注意深く観察する
特に重要なのは、クライアントが送信したコマンド (*cmd*や*put*で表示されることが多い) と、サーバーからの応答 (*resp*や*get*で表示されることが多い) です。エラーコード（例:550,421など）や、サーバーからの具体的なエラーメッセージに注目してください。 - 段階的にデバッグレベルを上げる
最初は0で通常実行し、問題が発生した場合に1に上げて詳細なログを確認します。それでも解決しない場合に限り、より高いレベルを試すことを検討します。
基本的な接続とデバッグレベル1の設定
これは最も一般的で、FTPコマンドとサーバー応答を確認する際に非常に役立ちます。
from ftplib import FTP
FTP_HOST = 'ftp.example.com' # 適切なFTPホスト名に置き換えてください
FTP_USER = 'your_username' # 適切なユーザー名に置き換えてください
FTP_PASS = 'your_password' # 適切なパスワードに置き換えてください
print("--- デバッグレベル1でFTP接続と操作 ---")
try:
ftp = FTP(FTP_HOST)
# デバッグレベルを1に設定
# これにより、クライアントとサーバー間の全てのFTPコマンドと応答が出力されます。
ftp.set_debuglevel(1)
ftp.login(FTP_USER, FTP_PASS)
print(f"ログイン成功: {FTP_USER}")
# 現在の作業ディレクトリを表示
current_dir = ftp.pwd()
print(f"現在のディレクトリ: {current_dir}")
# ディレクトリの一覧を取得
print("\nディレクトリ一覧:")
ftp.dir()
ftp.quit()
print("FTPセッションを終了しました。")
except Exception as e:
print(f"\nエラーが発生しました: {e}")
# エラー発生時でも、それまでのデバッグ出力は表示されます。
出力の例 (デバッグレベル1)
--- デバッグレベル1でFTP接続と操作 ---
*cmd* 'USER your_username'
*get* '331 Please specify the password.'
*cmd* 'PASS your_password'
*get* '230 Login successful.'
ログイン成功: your_username
*cmd* 'PWD'
*get* '257 "/" is the current directory.'
現在のディレクトリ: /
ディレクトリ一覧:
*cmd* 'TYPE I'
*get* '200 Switching to Binary mode.'
*cmd* 'PASV'
*get* '227 Entering Passive Mode (192,168,1,100,200,5).'
*cmd* 'LIST'
*get* '150 Ok to send data.'
-rw-r--r-- 1 ftpuser ftpuser 1234 May 20 10:00 file1.txt
drwxr-xr-x 2 ftpuser ftpuser 4096 Apr 15 08:30 my_folder
*get* '226 Transfer complete.'
*cmd* 'QUIT'
*get* '221 Goodbye.'
FTPセッションを終了しました。
上記のように、*cmd* はクライアント（Pythonスクリプト）がサーバーに送信したコマンド、*get* はサーバーから受信した応答を示します。各行にはFTPプロトコルで使用されるステータスコード（例: 230 Login successful.）が含まれています。
ファイルのアップロードとデバッグレベル1の活用
ファイルのアップロード時に問題が発生した場合、デバッグレベル1の出力は非常に役立ちます。
from ftplib import FTP
import io
FTP_HOST = 'ftp.example.com'
FTP_USER = 'your_username'
FTP_PASS = 'your_password'
UPLOAD_FILE_NAME = 'test_upload.txt'
UPLOAD_CONTENT = b"This is a test file to upload.\nIt contains multiple lines of text."
print(f"--- {UPLOAD_FILE_NAME} のアップロードとデバッグ ---")
try:
ftp = FTP(FTP_HOST)
ftp.set_debuglevel(1) # デバッグレベル1を設定
ftp.login(FTP_USER, FTP_PASS)
print(f"ログイン成功: {FTP_USER}")
# メモリ上のファイルをアップロード
# ftplibはファイルライクオブジェクトを受け取る
# 'wb' モードでバイナリデータとして書き込む
file_in_memory = io.BytesIO(UPLOAD_CONTENT)
print(f"ファイルをアップロード中: {UPLOAD_FILE_NAME}")
ftp.storbinary(f'STOR {UPLOAD_FILE_NAME}', file_in_memory)
print(f"ファイル {UPLOAD_FILE_NAME} のアップロードが完了しました。")
ftp.quit()
print("FTPセッションを終了しました。")
except Exception as e:
print(f"\nエラーが発生しました: {e}")
出力の例 (アップロード時のデバッグレベル1)
--- test_upload.txt のアップロードとデバッグ ---
*cmd* 'USER your_username'
*get* '331 Please specify the password.'
*cmd* 'PASS your_password'
*get* '230 Login successful.'
ログイン成功: your_username
ファイルをアップロード中: test_upload.txt
*cmd* 'TYPE I'
*get* '200 Switching to Binary mode.'
*cmd* 'PASV'
*get* '227 Entering Passive Mode (192,168,1,100,200,6).'
*cmd* 'STOR test_upload.txt'
*get* '150 Ok to send data.'
# ここでデータ転送が行われる (デバッグレベル1ではデータの内容は表示されない)
*get* '226 Transfer complete.'
ファイル test_upload.txt のアップロードが完了しました。
*cmd* 'QUIT'
*get* '221 Goodbye.'
FTPセッションを終了しました。
もしアップロードが失敗した場合、例えばディスク容量不足や権限の問題などがあると、STOR コマンドに対するサーバーからの応答が「550 Permission denied.」や「553 Could not create file.」のようなエラーメッセージになるでしょう。これらのメッセージから、何が問題であるか手がかりを得ることができます。
デバッグレベル0（デバッグなし）
デバッグが不要になった場合、または本番環境で余計な出力を避けたい場合に設定します。
from ftplib import FTP
FTP_HOST = 'ftp.example.com'
FTP_USER = 'your_username'
FTP_PASS = 'your_password'
print("--- デバッグレベル0（デバッグなし）でFTP接続と操作 ---")
try:
ftp = FTP(FTP_HOST)
ftp.set_debuglevel(0) # デバッグレベルを0に設定 - 出力なし
ftp.login(FTP_USER, FTP_PASS)
print(f"ログイン成功: {FTP_USER}")
# 何らかのFTP操作
ftp.cwd('/public_html') # ディレクトリ変更
print(f"ディレクトリを {ftp.pwd()} に変更しました。")
ftp.quit()
print("FTPセッションを終了しました。")
except Exception as e:
print(f"\nエラーが発生しました: {e}")
この場合、set_debuglevel(0) の行以外にFTP通信に関するデバッグ出力は一切表示されません。
デバッグレベルは、プログラムの途中で変更することも可能です。また、エラーが発生した場合でも、それまでのデバッグ出力は表示されます。
from ftplib import FTP
FTP_HOST = 'ftp.example.com'
FTP_USER = 'your_username'
FTP_PASS = 'your_password'
NON_EXISTENT_DIR = '/non_existent_folder_xyz' # 存在しないディレクトリ
print("--- デバッグレベルを途中で変更し、エラーをシミュレート ---")
try:
ftp = FTP(FTP_HOST)
ftp.set_debuglevel(1) # 最初はレベル1
ftp.login(FTP_USER, FTP_PASS)
print(f"ログイン成功: {FTP_USER}")
print("\n--- デバッグレベルを0に変更 ---")
ftp.set_debuglevel(0) # デバッグレベルを0に変更
# 存在しないディレクトリへの変更を試みる (エラー発生を期待)
print(f"ディレクトリ '{NON_EXISTENT_DIR}' へ変更を試みます...")
ftp.cwd(NON_EXISTENT_DIR) # ここでエラーが発生するはず
# エラーが発生しない場合は、この行は表示されない
print(f"ディレクトリを {ftp.pwd()} に変更しました。")
print("\n--- デバッグレベルを1に戻してログアウト ---")
ftp.set_debuglevel(1) # デバッグレベルを1に戻す (この後のQUITコマンドは表示される)
ftp.quit()
print("FTPセッションを終了しました。")
except Exception as e:
print(f"\nエラーが発生しました: {e}")
# エラーが発生した場合でも、それまでのデバッグ出力はコンソールに表示されます。
# 最後のquit()が実行されないため、QUITコマンドのデバッグ出力は出ないかもしれません。
# 閉じる必要がある場合はfinallyブロックで対応します。
try:
if 'ftp' in locals() and ftp:
ftp.quit() # エラー発生時でも接続を閉じる試み
print("エラー発生後、FTPセッションを閉じました。")
except Exception as quit_e:
print(f"FTPセッションを閉じる際にエラー: {quit_e}")
出力の例 (エラー発生時)
--- デバッグレベルを途中で変更し、エラーをシミュレート ---
*cmd* 'USER your_username'
*get* '331 Please specify the password.'
*cmd* 'PASS your_password'
*get* '230 Login successful.'
ログイン成功: your_username
--- デバッグレベルを0に変更 ---
ディレクトリ '/non_existent_folder_xyz' へ変更を試みます...
エラーが発生しました: 550 Failed to change directory.
この例では、set_debuglevel(0) に切り替えた後に cwd() でエラーが発生しているため、CWD コマンドとそのエラー応答は表示されません。しかし、set_debuglevel(1) でログインした際のコマンドと応答は表示されています。エラーの発生箇所を特定するために、エラーが起こりそうなコードの直前でデバッグレベルを上げるなどの工夫ができます。
ftplib.FTP.set_debuglevel() は手軽で便利ですが、より柔軟なログ記録やデバッグを行いたい場合、いくつかの代替手段があります。
Python の標準ロギングモジュール (logging) の活用
Pythonの標準ロギングモジュールは、より高度なログ管理を可能にします。ログレベル（DEBUG, INFO, WARNING, ERROR, CRITICAL）の設定、ログの出力先（コンソール、ファイル、ネットワークなど）の指定、ログフォーマットのカスタマイズが可能です。
ftplib モジュール自体も、内部的にPythonの標準ロギングを使用しています。ftplib のログは、ftplib という名前のロガーを通じて出力されます。したがって、このロガーを設定することで、set_debuglevel() と同じ、またはそれ以上のデバッグ情報を取得できます。
import logging
from ftplib import FTP
# ロギング設定
# DEBUGレベルのメッセージも出力するように設定
logging.basicConfig(level=logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
# ftplibのロガーを取得
# デフォルトではftplibのログはWARNINGレベル以上しか出力されないため、DEBUGに設定し直す
ftplib_logger = logging.getLogger('ftplib')
ftplib_logger.setLevel(logging.DEBUG) # ftplibのログレベルをDEBUGに設定
# --- FTP操作 ---
FTP_HOST = 'ftp.example.com' # 適切なFTPホスト名に置き換えてください
FTP_USER = 'your_username' # 適切なユーザー名に置き換えてください
FTP_PASS = 'your_password' # 適切なパスワードに置き換えてください
print("--- ロギングモジュールでFTPデバッグ ---")
try:
ftp = FTP(FTP_HOST)
# set_debuglevel() は不要
# ftp.set_debuglevel(1)
ftp.login(FTP_USER, FTP_PASS)
logging.info(f"ログイン成功: {FTP_USER}")
current_dir = ftp.pwd()
logging.info(f"現在のディレクトリ: {current_dir}")
logging.info("ディレクトリ一覧:")
ftp.dir()
ftp.quit()
logging.info("FTPセッションを終了しました。")
except Exception as e:
logging.error(f"エラーが発生しました: {e}", exc_info=True) # 例外情報も出力
この方法の利点
- 詳細な情報
set_debuglevel(1)と同等のFTPコマンドと応答に加えて、ftplib内部の他のDEBUGレベルのメッセージも取得できる場合があります。 - 集中管理
アプリケーション全体のログを同じ仕組みで管理できるため、ログの一貫性が保たれます。 - ログレベルの制御
特定の種類のメッセージ（エラーのみ、情報のみなど）に絞って出力できます。 - 柔軟なログ出力
ログをファイルに保存したり、特定のフォーマットで出力したりできます。
カスタムコールバック関数を使用したデバッグ
ftplib.FTP オブジェクトには、内部のデバッグ出力ロジックを置き換えるためのset_pasv や set_debuglevel のようなメソッドはありませんが、FTPコマンドの送受信を直接監視するための標準的なフックも提供されていません。
しかし、もしFTPコマンドの送受信をより細かく制御したり、カスタムの処理を挟んだりしたい場合、ftplib モジュールを直接拡張したり、別のFTPライブラリを検討したりする必要があります。
現実的には、set_debuglevel() や標準の logging モジュールで出力される情報で十分な場合がほとんどです。それでもカスタム処理を行いたい場合は、以下のようなアプローチが考えられますが、これらはより高度なプログラミングを伴います。
- ネットワークトラフィックをキャプチャする
Wiresharkのようなツールを使用して、実際のネットワークパケットをキャプチャする方法です。これはFTPプロトコルがどのように動作しているかを低レベルで確認する究極のデバッグ方法ですが、プログラミングとは直接関係ありません。 - ftplib のソースコードを読んで改造する
これは推奨される方法ではありませんが、デバッグ目的であれば、ftplibの内部メソッド（putcmdやgetrespなど）にカスタムのログ記録ロジックを追加することで、詳細なトレースが可能です。ただし、モジュールを直接改造すると、バージョンアップ時に問題が発生する可能性があります。
手動での出力（非推奨だが理解のため）
set_debuglevel() を使わずに、FTPコマンドの実行前後に手動で情報を出力する方法です。これは、特定の操作に絞ってデバッグしたい場合や、カスタムメッセージを追加したい場合に考えられますが、非常に手間がかかり、ほとんどの場合にset_debuglevel()やloggingモジュールの方が優れています。
from ftplib import FTP
FTP_HOST = 'ftp.example.com'
FTP_USER = 'your_username'
FTP_PASS = 'your_password'
print("--- 手動でFTP操作をログ ---")
try:
ftp = FTP(FTP_HOST)
# set_debuglevel() は呼び出さない
# ftp.set_debuglevel(1)
print(f"DEBUG: 接続開始 {FTP_HOST}")
# loginメソッドの内部で何が起きているか、この方法では見えない
ftp.login(FTP_USER, FTP_PASS)
print(f"INFO: ログイン成功: {FTP_USER}")
print("DEBUG: PWDコマンド送信前")
current_dir = ftp.pwd()
print(f"INFO: 現在のディレクトリ: {current_dir}")
print("DEBUG: DIRコマンド送信前")
ftp.dir()
print("INFO: ディレクトリ一覧表示完了")
print("DEBUG: QUITコマンド送信前")
ftp.quit()
print("INFO: FTPセッションを終了しました。")
except Exception as e:
print(f"ERROR: エラーが発生しました: {e}")
- エラー処理の複雑化
エラーが発生した場合、どこまで処理が進んだか、どのコマンドで失敗したかを正確に把握するのが難しいです。 - 不完全な情報
ftplib内部で自動的に送信されるコマンド（例:TYPE IやPASV）やサーバー応答は捕捉できません。 - 冗長性
全てのFTPコマンドや応答に対して手動でprint()を追加するのは非効率的です。