20.9. "poplib" --- POP3 プロトコルクライアント
**********************************************

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

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

このモジュールは、 "POP3" クラスを定義します。これはPOP3サーバへの接続
と、 **RFC 1725** に定められたプロトコルを実装します。 "POP3" クラスは
minimalとoptinalという2つのコマンドセットをサポートします。モジュール
は "POP3_SSL" クラスも提供します。このクラスは下位のプロトコルレイヤー
にSSLを使ったPOP3サーバへの接続を提供します。

POP3についての注意事項は、それが広くサポートされているにもかかわらず、
既に時代遅れだということです。幾つも実装されているPOP3サーバーの品質は
、貧弱なものが多数を占めています。もし、お使いのメールサーバーがIMAPを
サポートしているなら、 "imaplib.IMAP4" クラスが使えます。 IMAPサーバー
は、より良く実装されている傾向があります。

"poplib" モジュールは二つのクラスを提供します:

class poplib.POP3(host[, port[, timeout]])

   このクラスが、実際にPOP3プロトコルを実装します。インスタンスが初期
   化されるときに、コネクションが作成されます。 *port* が省略されると
   、POP3標準のポート(110)が使われます。オプションの *timeout* 引数は
   、接続時のタイムアウト時間を秒数で指定します (指定されなかった場合
   は、グローバルのデフォルトタイムアウト設定が利用されます)。

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

class poplib.POP3_SSL(host[, port[, keyfile[, certfile]]])

   "POP3" クラスのサブクラスで、SSL でカプセル化されたソケットによる
   POP サーバへの接続を提供します。 *port* が指定されていない場合、
   POP3-over-SSL 標準の 995 番ポートが使われます。 *keyfile* と
   *certfile* もオプションです - SSL 接続に使われる PEM フォーマットの
   秘密鍵と証明書チェインを指定出来ます。

   バージョン 2.4 で追加.

1つの例外が、 "poplib" モジュールのアトリビュートとして定義されていま
す:

exception poplib.error_proto

   例外は、このモジュール内で起こったすべてのエラーで発生します。
   ("socket" モジュールからのエラーは捕まえず、そのまま伝播します) 例
   外の理由は文字列としてコンストラクタに渡されます。

参考:

  モジュール "imaplib"
     The standard Python IMAP module.

  Frequently Asked Questions About Fetchmail
     POP/IMAPクライアント **fetchmail** のFAQ。POPプロトコルをベースに
     したアプリケーションを書くときに有用な、POP3サーバの種類や RFCへ
     の適合度といった情報を収集しています。


20.9.1. POP3 オブジェクト
=========================

POP3コマンドはすべて、それと同じ名前のメソッドとしてlower-caseで表現さ
れます。そしてそのほとんどは、サーバからのレスポンスとなるテキストを返
します。

"POP3" クラスのインスタンスは以下のメソッドを持ちます:

POP3.set_debuglevel(level)

   インスタンスのデバッグレベルを設定します。この設定によってデバッグ
   時に出力される量を調節します。デフォルトは "0" で、何も出力されませ
   ん。"1" なら、一般的に１つのコマンドあたり１行の適当な量のデバッグ
   出力を行います。"2" 以上なら、コントロール接続で受信した各行を出力
   して、最大のデバッグ出力をします。

POP3.getwelcome()

   POP3サーバーから送られるグリーティングメッセージを返します。

POP3.user(username)

   userコマンドを送出します。応答はパスワード要求を表示します。

POP3.pass_(password)

   パスワードを送出します。応答は、メッセージ数とメールボックスのサイ
   ズを含みます。注意：サーバー上のメールボックスは "quit()" が呼ばれ
   るまでロックされます。

POP3.apop(user, secret)

   POP3サーバーにログオンするのに、よりセキュアなAPOP認証を使用します
   。

POP3.rpop(user)

   POP3サーバーにログオンするのに、（UNIXのr-コマンドと同様の）RPOP認
   証を使用します。

POP3.stat()

   メールボックスの状態を得ます。結果は2つのintegerからなるタプルとな
   ります。 "(message count, mailbox size)".

POP3.list([which])

   メッセージのリストを要求します。結果は "(response, ['mesg_num
   octets', ...], octets)" という形式で表されます。 *which* が与えられ
   ると、それによりメッセージを指定します。

POP3.retr(which)

   *which* 番のメッセージ全体を取り出し、そのメッセージに既読フラグを
   立てます。結果は "(response, ['line', ...], octets)" という形式で表
   されます。

POP3.dele(which)

   *which* 番のメッセージに削除のためのフラグを立てます。ほとんどのサ
   ーバで、QUITコマンドが実行されるまでは実際の削除は行われません（も
   っとも良く知られた例外は Eudora QPOPで、その配送メカニズムはRFCに違
   反しており、どんな切断状況でも削除操作を未解決にしています）。

POP3.rset()

   メールボックスの削除マークすべてを取り消します。

POP3.noop()

   何もしません。接続保持のために使われます。

POP3.quit()

   Signoff:  commit changes, unlock mailbox, drop connection. サインオ
   フ: 変更をコミットし、メールボックスをアンロックして、接続を破棄し
   ます。

POP3.top(which, howmuch)

   メッセージヘッダと *howmuch* で指定した行数のメッセージを、 *which*
   で指定したメッセージ分取り出します。結果は以下のような形式となりま
   す。 "(response, ['line', ...], octets)".

   このメソッドはPOP3のTOPコマンドを利用し、RETRコマンドのように、メッ
   セージに既読フラグをセットしません。残念ながら、TOPコマンドはRFCで
   は貧弱な仕様しか定義されておらず、しばしばノーブランドのサーバーで
   は（その仕様が）守られていません。このメソッドを信用してしまう前に
   、実際に使用するPOPサーバーでテストをしてください。

POP3.uidl([which])

   （ユニークIDによる）メッセージダイジェストのリストを返します。
   *which* が設定されている場合、結果はユニークIDを含みます。それは
   "'response mesgnum uid" という形式のメッセージ、または "(response,
   ['mesgnum uid', ...], octets)" という形式のリストとなります。

"POP3_SSL" クラスのインスタンスは追加のメソッドを持ちません。このサブ
クラスのインターフェイスは親クラスと同じです。


20.9.2. POP3 の例
=================

以下にメールボックスを開き、全てのメッセージを取得して印刷する最小の (
エラーチェックをしない) 使用例を示します:

   import getpass, poplib

   M = poplib.POP3('localhost')
   M.user(getpass.getuser())
   M.pass_(getpass.getpass())
   numMessages = len(M.list()[1])
   for i in range(numMessages):
       for j in M.retr(i+1)[1]:
           print j

モジュールの末尾に、より拡張的な使用例が収められたテストセクションがあ
ります。
