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

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

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

このモジュールはクラス "POP3" を定義しています。 "POP3" はPOP3 サーバ
への接続をカプセル化し、**RFC 1939** で定義されているプロトコルを実装
しています。 "POP3" クラスは **RFC 1939** の最小限のコマンドセットとオ
プションのコマンドセットをサポートしています。 既に確立されている接続
で暗号化された通信を行うために、**RFC 2595** で導入された "STLS" コマ
ンドもサポートされています。

加えて、このモジュールはクラス "POP3_SSL" を提供しています。
"POP3_SSL"  は SSL を下層のプロトコルレイヤーとして使う POP3 サーバへ
の接続をサポートしています。

POP3 は広くサポートされていますが、時代遅れになりつつあることに注意し
てください。 POP3 サーバの実装の品質には大きなばらつきがあり、低品質な
ものが多すぎるほどあります。 メールサーバが IMAP に対応している場合は
、"imaplib.IMAP4" クラスを使う方がよいでしょう。 IMAP サーバの方が、よ
り適切に実装されている傾向があります。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは
、WebAssembly プラットフォーム を見てください。

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

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

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

   引数 "self", "host", "port" 付きで 監査イベント "poplib.connect" を
   送出します。

   全てのコマンドは引数 "self" と "line" を指定して auditing event
   "poplib.putline" を送出します。 ここで "line" はリモートホストに送
   信されるバイト列です。

   バージョン 3.9 で変更: *timeout* パラメータが0に設定されている場合
   、非ブロッキングソケットの作成を防ぐために "ValueError" を送出しま
   す。

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, *, timeout=None, context=None)

   "POP3" クラスのサブクラスで、SSL でカプセル化されたソケットによる
   POP サーバへの接続を提供します。 *port* が指定されていない場合、
   POP3-over-SSL 標準の 995 番ポートが使われます。*timeout* については
   "POP3" クラスのコンストラクタの引数と同じです。 *context* は SSL の
   設定、証明書、秘密鍵を一つの (POP3_SSL オブジェクトよりも長く存在し
   続けうる) 構造にまとめた "ssl.SSLContext" オブジェクトで、省略可能
   です。ベストプラクティスについては セキュリティで考慮すべき点 を参
   照してください。

   引数 "self", "host", "port" 付きで 監査イベント "poplib.connect" を
   送出します。

   全てのコマンドは引数 "self" と "line" を指定して auditing event
   "poplib.putline" を送出します。 ここで "line" はリモートホストに送
   信されるバイト列です。

   バージョン 3.2 で変更: *context* 引数が追加されました。

   バージョン 3.4 で変更: このクラスは "ssl.SSLContext.check_hostname"
   によるホスト名の検証と、*Server Name Indication* ("ssl.HAS_SNI" を
   参照) をサポートしています。

   バージョン 3.9 で変更: *timeout* パラメータが0に設定されている場合
   、非ブロッキングソケットの作成を防ぐために "ValueError" を送出しま
   す。

   バージョン 3.12 で変更: 非推奨の *keyfile* と *certfile* 引数を削除
   しました。

"poplib" モジュールの属性として、次の例外が定義されています。

exception poplib.error_proto

   このモジュール内で起こったあらゆるエラーで送出される例外です
   ("socket" モジュールからのエラーは捕捉されません)。例外の理由は文字
   列としてコンストラクタに渡されます。

参考:

  モジュール "imaplib"
     標準 Python IMAP モジュールです。

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


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

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

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

POP3.set_debuglevel(level)

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

POP3.getwelcome()

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

POP3.capa()

   **RFC 2449** で規定されている機能についてサーバに問い合わせます。
   "{'name': ['param'...]}" という形の辞書を返します。

   Added in version 3.4.

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

   サインオフ: 変更をコミットし、メールボックスをアンロックして、接続
   を破棄します。

POP3.top(which, howmuch)

   *which* 番のメッセージから、ヘッダーとその直後の本文 *howmuch* 行を
   取得します。 結果は "(response, ['line', ...], octets)" という形式
   です。

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

POP3.uidl(which=None)

   メッセージダイジェスト (一意な ID) のリストを返します。 *which* を
   指定した場合、そのメッセージの一意な ID を含む "'response mesgnum
   uid" 形式の結果を返します。 省略した場合は "(response, ['mesgnum
   uid', ...], octets)" 形式のリストを返します。

POP3.utf8()

   UTF-8 モードへの切り替えを試行します。成功した場合はサーバの応答を
   返し、失敗した場合は "error_proto" を送出します。**RFC 6856** で規
   定されています。

   Added in version 3.5.

POP3.stls(context=None)

   アクティブな接続にて **RFC 2595** で定められた方法で TLS セッション
   を開始します。TLS セッションはユーザ認証を行う前に開始する必要があ
   ります。

   *context* は SSL の設定、証明書、秘密鍵を一つの (POP3 オブジェクト
   よりも長く存在し続けうる) 構造にまとめた "ssl.SSLContext" オブジェ
   クトです。ベストプラクティスについては セキュリティで考慮すべき点
   を参照してください。

   このメソッドは "ssl.SSLContext.check_hostname" によるホスト名の検証
   と、*Server Name Indication* ("ssl.HAS_SNI" を参照) をサポートして
   います。

   Added in version 3.4.

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


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)

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