# `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サーバーは、より良く実装されている傾向があります。

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

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

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

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

  引数 `self`, `line` を指定して 監査イベント `poplib.putline` を送出します。

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

class `poplib.``POP3_SSL`(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)

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

  keyfile と certfile は context のレガシー版です - これらは、SSL 接続のための、 PEM フォーマットの秘密鍵と証明書チェーンファイル名(前者が keyfile 、後者が certfile )を含むことができます。

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

  引数 `self`, `line` を指定して 監査イベント `poplib.putline` を送出します。

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

  バージョン 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 証明書を選んでもらうかしてください。

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

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

exception `poplib.``error_proto`

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

参考

モジュール `imaplib`

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

Frequently Asked Questions About Fetchmail

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

## POP3 オブジェクト

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

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

`POP3.``set_debuglevel`(level)

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

`POP3.``getwelcome`()

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

`POP3.``capa`()

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

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

  メッセージヘッダと howmuch で指定した行数のメッセージを、 which で指定したメッセージ分取り出します。結果は以下のような形式となります。 `(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 で規定されています。

  バージョン 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` を参照してください)。

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

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