"imaplib" --- IMAP4 プロトコルクライアント
******************************************

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

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

このモジュールは、IMAP4 サーバへの接続をカプセル化する "IMAP4"、
"IMAP4_SSL"、"IMAP4_stream" の 3 クラスを定義します。 これらは **RFC
3501** で定義された IMAP4rev1 クライアントプロトコルの大部分を実装して
います。 IMAP4 (**RFC 1730**) サーバとの後方互換性もありますが、IMAP4
は "STATUS" コマンドをサポートしていないことに注意してください。

利用可能な環境: not WASI.

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

"imaplib" モジュールには 3 つのクラスがあり、"IMAP4" が基底クラスです
。

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

   このクラスは IMAP4 プロトコルの実際の処理を実装します。 インスタン
   スの初期化時に接続を作成し、プロトコルのバージョン (IMAP4 または
   IMAP4rev1) を決定します。 *host* を指定しない場合は、"''" (ローカル
   ホスト) を使います。 *port* を省略すると、標準の IMAP4 ポート (143)
   を使います。 オプションの *timeout* 引数は、接続を試みる際のタイム
   アウトを秒単位で指定します。 "timeout" を指定しない場合や "None" の
   場合は、ソケットのグローバルなデフォルトのタイムアウトを使います。

   "IMAP4" クラスは "with" 文をサポートしています。 このように使うと、
   "with" 文を抜けるときに IMAP4 の "LOGOUT" コマンドが自動的に発行さ
   れます。 例えば次のように使います。

      >>> from imaplib import IMAP4
      >>> with IMAP4("domain.org") as M:
      ...     M.noop()
      ...
      ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

   バージョン 3.5 で変更: "with" 構文のサポートが追加されました。

   バージョン 3.9 で変更: オプションの *timeout* 引数が追加されました
   。

例外は "IMAP4" クラスの属性として定義されています:

exception IMAP4.error

   何らかのエラー発生の際に送出される例外です。例外の理由は文字列とし
   てコンストラクタに渡されます。

exception IMAP4.abort

   IMAP4 サーバのエラーが生じると、この例外が送出されます。この例外は
   "IMAP4.error" のサブクラスです。通常、インスタンスを閉じ、新たなイ
   ンスタンスを再び生成することで、この例外から復旧できます。

exception IMAP4.readonly

   この例外は書き込み可能なメールボックスの状態がサーバによって変更さ
   れた際に送出されます。この例外は "IMAP4.error" のサブクラスです。他
   の何らかのクライアントが現在書き込み権限を獲得しており、メールボッ
   クスを開きなおして書き込み権限を再獲得する必要があります。

このモジュールではもう一つ、安全 (secure) な接続を使ったサブクラスがあ
ります:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

   SSL で暗号化されたソケットを介して接続する、"IMAP4" のサブクラスで
   す (このクラスを使うには、SSL サポート付きでコンパイルされた socket
   モジュールが必要です)。 *host* を指定しない場合は、"''" (ローカルホ
   スト) を使います。 *port* を省略すると、標準の IMAP4-over-SSL ポー
   ト (993) を使います。 *ssl_context* は "ssl.SSLContext" オブジェク
   トで、SSL の設定オプション、証明書、秘密鍵を 1 つの構造にまとめられ
   ます。 この構造は長期間使い続けることもできます。 推奨される方法に
   ついては セキュリティで考慮すべき点 を読んでください。

   注釈:

     デフォルトの *ssl_context* では接続は暗号化されますが、サーバ証明
     書とホスト名は検証されません。 これらを検証するには、
     "ssl.create_default_context()" で作成したコンテキストを渡してくだ
     さい。

   オプションの *timeout* 引数は、接続を試みる際のタイムアウトを秒単位
   で指定します。 "timeout" を指定しない場合や "None" の場合は、ソケッ
   トのグローバルなデフォルトのタイムアウトを使います。

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

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

   バージョン 3.9 で変更: オプションの *timeout* 引数が追加されました
   。

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

さらにもう一つのサブクラスは、子プロセスで確立した接続を使用する場合に
使用します:

class imaplib.IMAP4_stream(command)

   "IMAP4" から派生したサブクラスで、 *command* を
   "subprocess.Popen()" に渡して作成される "stdin/stdout" ディスクリプ
   タと接続します。

以下のユーティリティ関数が定義されています:

imaplib.Internaldate2tuple(resp)

   IMAP4 の "INTERNALDATE" 応答を含む *bytes-like object* を解析し、対
   応するローカル時刻を返します。 戻り値は "time.struct_time" タプルで
   すが、入力の形式が正しくなければ "None" です。

imaplib.Int2AP(num)

   整数を ["A" .. "P"] からなる文字集合を用いて表現した bytes に変換し
   ます。

imaplib.ParseFlags(resp)

   IMAP4 の "FLAGS" 応答を含む *bytes-like object* を、各フラグを
   "bytes" で表したタプルに変換します。 入力の形式が正しくなければ空の
   タプルを返します。

imaplib.Time2Internaldate(date_time)

   *date_time* を IMAP4 の "INTERNALDATE" 表現に変換します。 戻り値は
   ""DD-Mmm-YYYY HH:MM:SS +HHMM"" 形式の文字列です (ダブルクォートも含
   みます)。 *date_time* 引数には、エポックからの秒数を表す数値 (int
   または float、"time.time()" の戻り値)、ローカル時刻を表す 9 要素の
   タプル、"time.struct_time" のインスタンス ("time.localtime()" の戻
   り値)、"datetime.datetime" の aware なインスタンス、またはダブルク
   ォートで囲んだ文字列を指定できます。 最後の場合、文字列はすでに正し
   い形式であるとみなされます。

IMAP4 メッセージ番号は、メールボックスに対する変更が行われた後には変化
します; 特に、"EXPUNGE" 命令はメッセージの削除を行いますが、残ったメッ
セージには再度番号を振りなおします。従って、メッセージ番号ではなく、
UID 命令を使い、その UID を利用するよう強く勧めます。

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

参考:

  ワシントン大学の IMAP Information Center によるプロトコルの説明文書
  や、そのプロトコルを実装したサーバのソースは、(**ソースコード**)
  https://github.com/uw-imap/imap にあります (**メンテナンスされていま
  せん**)。


IMAP4 オブジェクト
==================

IMAP4rev1 のすべてのコマンドに、大文字または小文字の同名のメソッドが対
応しています。

"AUTHENTICATE" の引数と、IMAP4 リテラルとして渡される "APPEND" の最後
の引数を除き、コマンドの引数はすべて文字列に変換されます。 必要であれ
ば、各文字列は引用符で囲まれます (IMAP4 プロトコル上で特別な意味を持つ
文字が含まれていて、丸括弧でもダブルクォートでも囲まれていない場合)。
ただし、"LOGIN" コマンドの *password* 引数は常に引用符で囲まれます。
引数の文字列が引用符で囲まれるのを避けるには (例えば "STORE" の
*flags* 引数)、文字列を丸括弧で囲んでください (例えば "r'(\Deleted)'")
。 通常は引数を引用符で囲まずに渡し、必要に応じてモジュールに引用符を
付けさせてください。 すでにダブルクォートで囲まれた引数は変更されない
ため、引用符を自ら付けるコードも引き続き動作します。

ほとんどのコマンドは "(type, [data, ...])" というタプルを返します。
*type* は通常 "'OK'" または "'NO'" で、*data* はコマンド応答のテキスト
か、コマンドで定められた結果です。 各 *data* は "bytes" またはタプルで
す。 タプルの場合、最初の部分は応答のヘッダで、2 番目の部分にはデータ
(リテラル値) が含まれます。

以下のコマンドにおける *message_set* オプションは、操作の対象となるひ
とつあるいは複数のメッセージを指す文字列です。単一のメッセージ番号
("'1'") かメッセージ番号の範囲 ("'2:4'")、あるいは連続していないメッセ
ージをカンマでつなげたもの ("'1:3,6:9'") となります。範囲指定でアスタ
リスクを使用すると、上限を無限とすることができます ("'3:*'")。

"IMAP4" のインスタンスは以下のメソッドを持っています:

IMAP4.append(mailbox, flags, date_time, message)

   指定された名前のメールボックスに *message* を追加します。

   *flags* は "None" または IMAP フラグのトークンを含む文字列です。 複
   数のフラグは "r'\Seen \Answered'" のようにスペースで区切ります。
   *flags* が丸括弧で囲まれていなければ、自動的に丸括弧を付けます。

IMAP4.authenticate(mechanism, authobject)

   認証命令です --- 応答の処理が必要です。

   *mechanism* は利用する認証メカニズムを与えます。認証メカニズムはイ
   ンスタンス変数 "capabilities" の中に "AUTH=mechanism" という形式で
   現れる必要があります。

   *authobject* は呼び出し可能なオブジェクトである必要があります:

      data = authobject(response)

   サーバからの継続応答を処理するために呼び出され、渡される *response*
   引数は "bytes" です。 base64 エンコードしてサーバに送信する *data*
   を "bytes" で返す必要があります。 代わりにクライアントの中止応答
   "*" を送信する場合は、"None" を返してください。

   バージョン 3.5 で変更: 文字列のユーザ名とパスワードは ASCII に制限
   されず、"utf-8" にエンコードされるようになりました。

IMAP4.check()

   サーバ上のメールボックスにチェックポイントを設定します。

IMAP4.close()

   現在選択されているメールボックスを閉じます。削除されたメッセージは
   書き込み可能メールボックスから除去されます。"LOGOUT" 前に実行するこ
   とを勧めます。

IMAP4.copy(message_set, new_mailbox)

   *message_set* で指定したメッセージ群を *new_mailbox* の末尾にコピー
   します。

IMAP4.create(mailbox)

   *mailbox* と名づけられた新たなメールボックスを生成します。

IMAP4.delete(mailbox)

   *mailbox* と名づけられた古いメールボックスを削除します。

IMAP4.deleteacl(mailbox, who)

   mailbox における who についてのACLを削除(権限を削除)します。

IMAP4.enable(capability)

   *capability* を有効にします (**RFC 5161** を参照)。 ほとんどの
   capability は有効にする必要がありません。 現在サポートされているの
   は "UTF8=ACCEPT" capability だけです (**RFC 6855** を参照)。

   Added in version 3.5: "enable()" メソッドと **RFC 6855** のサポート
   を追加しました。

IMAP4.expunge()

   選択されたメールボックスから削除された要素を永久に除去します。各々
   の削除されたメッセージに対して、"EXPUNGE" 応答を生成します。返され
   るデータには "EXPUNGE" メッセージ番号を受信した順番に並べたリストが
   入っています。

IMAP4.fetch(message_set, message_parts)

   メッセージ (の一部) を取りよせます。*message_parts* はメッセージパ
   ートの名前を表す文字列を丸括弧で囲ったもので、例えば: ""(UID
   BODY[TEXT])"" のようになります。返されるデータはメッセージパートの
   エンベロープ情報とデータからなるタプルです。

IMAP4.getacl(mailbox)

   *mailbox* に対する "ACL" を取得します。このメソッドは非標準ですが、
   "Cyrus" サーバでサポートされています。

IMAP4.getannotation(mailbox, entry, attribute)

   *mailbox* に対する "ANNOTATION" を取得します。このメソッドは非標準
   ですが、"Cyrus" サーバでサポートされています。

IMAP4.getquota(root)

   "quota" *root* により、リソース使用状況と制限値を取得します。このメ
   ソッドは **RFC 2087** で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.getquotaroot(mailbox)

   指定した *mailbox* の "quota" "roots" のリストを取得します。 このメ
   ソッドは rfc2087 で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.idle(duration=None)

   "Idler" を返します。 これは **RFC 2177** で定義された IMAP4 の
   "IDLE" コマンドを実装する、イテラブルなコンテキストマネージャです。

   返されたオブジェクトは、"with" 文で有効になると "IDLE" コマンドを送
   信し、*iterator* プロトコルを通じてタグなしの IMAP 応答を生成し、コ
   ンテキストを抜けるときに "DONE" を送信します。

   "IDLE" コマンドの送信後に届いたタグなし応答はすべて、イテレーション
   で取得できます (サーバがコマンドを確認する前に届いた応答も含みます)
   。 残った応答 ("with" コンテキスト内のイテレーションで取得しなかっ
   た応答) は、"IDLE" の終了後に "IMAP4.response()" を使って通常どおり
   取得できます。

   応答は IMAP4 オブジェクト で説明した "(type, [data, ...])" タプルで
   表されます。

   *duration* 引数はアイドル状態を続ける最大時間を秒単位で設定し、この
   時間が過ぎると進行中のイテレーションは停止します。 "int"、"float"、
   または時間制限なしを表す "None" を指定できます。 操作がない場合にタ
   イムアウトするサーバでタイムアウトを避けるには、29 分 (1740 秒) 以
   下にしてください。 ソケット接続が必要です。 "IMAP4_stream" 接続では
   *duration* を "None" にする必要があります。

      >>> with M.idle(duration=29 * 60) as idler:
      ...     for typ, data in idler:
      ...         print(typ, data)
      ...
      EXISTS [b'1']
      RECENT [b'1']

   Idler.burst(interval=0.1)

      *interval* 秒以内の間隔で連続して届く応答を yield します
      ("interval" は "int" または "float" で表します)。

      この *generator* は、1 つずつ応答を取り出すイテレーションに代わ
      るもので、効率的な一括処理を支援します。 次の応答に加えて、その
      直後に取得できる後続の応答も取得します (例えば、一括削除の後に相
      次いで届く "EXPUNGE" 応答)。

      ソケット接続が必要です。 "IMAP4_stream" 接続では動作しません。

         >>> with M.idle() as idler:
         ...     # 応答と、0.1 秒未満の間隔で続く応答を取得する
         ...     batch = list(idler.burst())
         ...     print(f'processing {len(batch)} responses...')
         ...     print(batch)
         ...
         processing 3 responses...
         [('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

      Tip:

        ひとまとまりの応答の最初の応答を待つ際には、"IMAP4.idle()" に
        渡した "IDLE" コンテキストの最大時間が考慮されます。 そのため
        、"Idler" がすでに時間切れであれば、このジェネレータは何も生成
        せず直ちに終了します。 ループで使う場合はこの点に注意してくだ
        さい。

   注釈:

     "IMAP4.idle()" が返すイテレータは、"with" 文の中でのみ使えます。
     そのコンテキストの前後では、要求していない応答はコマンドが完了す
     るたびに内部で収集され、"IMAP4.response()" で取得できます。

   注釈:

     "Idler" のクラス名や構造は内部インターフェースであり、変更される
     可能性があります。 呼び出し側のコードは、コンテキスト管理、イテレ
     ーション、公開メソッドの安定性を前提にできますが、このクラスのサ
     ブクラス化、インスタンス化、比較など、クラスの直接の参照は避けて
     ください。

   Added in version 3.14.

IMAP4.list(directory='', pattern='*')

   *pattern* にマッチする *directory* メールボックス名を列挙します。
   *directory* の標準の設定値は最上レベルのメールフォルダで、*pattern*
   は標準の設定では全てにマッチします。返されるデータには "LIST" 応答
   のリストが入っています。

IMAP4.login(user, password)

   平文パスワードを使ってクライアントを照合します。*password* はクオー
   トされます。

IMAP4.login_cram_md5(user, password)

   パスワードの保護のため、クライアント認証時に "CRAM-MD5" だけを使用
   します。これは、"CAPABILITY" レスポンスに "AUTH=CRAM-MD5" が含まれ
   る場合のみ有効です。

   バージョン 3.15 で変更: MD5 のサポートが利用できない場合、
   "IMAP4.error" を送出します。

IMAP4.logout()

   サーバへの接続を遮断します。サーバからの "BYE" 応答を返します。

   バージョン 3.8 で変更: このメソッドは、任意の例外を黙って無視するこ
   とがなくなりました。

IMAP4.lsub(directory='', pattern='*')

   購読しているメールボックス名のうち、ディレクトリ内でパターンにマッ
   チするものを列挙します。*directory* の標準の設定値は最上レベルのメ
   ールフォルダで、*pattern* は標準の設定では全てにマッチします。返さ
   れるデータには返されるデータはメッセージパートエンベロープ情報とデ
   ータからなるタプルです。

IMAP4.myrights(mailbox)

   mailboxにおける自分のACLを返します (すなわち自分がmailboxで持ってい
   る権限を返します)。

IMAP4.namespace()

   **RFC 2342** で定義されるIMAP名前空間を返します。

IMAP4.noop()

   サーバに "NOOP" を送信します。

IMAP4.open(host, port, timeout=None)

   *host* の *port* へのソケットを開きます。 オプションの *timeout* 引
   数は、接続を試みる際のタイムアウトを秒単位で指定します。 "timeout"
   を指定しない場合や "None" の場合は、ソケットのグローバルなデフォル
   トのタイムアウトを使います。 また、*timeout* 引数がゼロの場合は、非
   ブロッキングソケットの作成を拒否するために "ValueError" を送出しま
   す。 このメソッドは "IMAP4" コンストラクタから暗黙的に呼び出されま
   す。 このメソッドで確立した接続オブジェクトは、"IMAP4.read()"、
   "IMAP4.readline()"、"IMAP4.send()"、"IMAP4.shutdown()" メソッドで使
   われます。 このメソッドはオーバーライドできます。

   引数 "self", "host", "port" を指定して 監査イベント "imaplib.open"
   を送出します。

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

IMAP4.partial(message_num, message_part, start, length)

   メッセージの一部を取り寄せます。 返されるデータはメッセージパートエ
   ンベロープ情報とデータからなるタプルです。

IMAP4.proxyauth(user)

   *user* として認証されたものとします。認証された管理者がユーザの代理
   としてメールボックスにアクセスする際に使用します。

IMAP4.read(size)

   遠隔のサーバから *size* バイト読み出します。このメソッドはオーバラ
   イドすることができます。

IMAP4.readline()

   遠隔のサーバから一行読み出します。このメソッドはオーバライドするこ
   とができます。

IMAP4.recent()

   サーバに更新を促します。新たなメッセージがない場合応答は "None" に
   なり、そうでない場合 "RECENT" 応答の値になります。

IMAP4.rename(oldmailbox, newmailbox)

   *oldmailbox* という名前のメールボックスを *newmailbox* に名称変更し
   ます。

IMAP4.response(code)

   応答 *code* を受信していれば、そのデータを返し、そうでなければ
   "None" を返します。通常の形式 (usual type) ではなく指定したコードを
   返します。

IMAP4.search(charset, criterion[, ...])

   メールボックスから条件に合うメッセージを検索します。 *charset* は
   "None" でもよく、その場合はサーバへの要求で "CHARSET" を指定しませ
   ん。 IMAP プロトコルでは少なくとも 1 つの条件を指定する必要があり、
   サーバがエラーを返すと例外が送出されます。 "enable()" コマンドで
   "UTF8=ACCEPT" capability を有効にしている場合、*charset* は "None"
   にする必要があります。

   以下はプログラム例です:

      # M は接続済みの IMAP4 インスタンス...
      typ, msgnums = M.search(None, 'FROM', '"LDJ"')

      # または:
      typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select(mailbox='INBOX', readonly=False)

   メールボックスを選択します。返されるデータは *mailbox* 内のメッセー
   ジ数 ("EXISTS" 応答) です。標準の設定では *mailbox* は "'INBOX'" で
   す。*readonly* が設定された場合、メールボックスに対する変更はできま
   せん。

IMAP4.send(data)

   遠隔のサーバに "data" を送信します。このメソッドはオーバライドする
   ことができます。

   引数 "self", "data" を指定して 監査イベント "imaplib.send" を送出し
   ます。

IMAP4.setacl(mailbox, who, what)

   "ACL" を *mailbox* に設定します。このメソッドは非標準ですが、
   "Cyrus" サーバでサポートされています。

IMAP4.setannotation(mailbox, entry, attribute[, ...])

   "ANNOTATION" を *mailbox* に設定します。このメソッドは非標準ですが
   、"Cyrus" サーバでサポートされています。

IMAP4.setquota(root, limits)

   "quota" *root* のリソースの制限値を *limits* に設定します。 このメ
   ソッドは rfc2087 で定義されている IMAP4 QUOTA 拡張の一部です。

IMAP4.shutdown()

   "open" で確立された接続を閉じます。 "IMAP4.logout()" は暗黙的にこの
   メソッドを呼び出します。このメソッドはオーバライドすることができま
   す。

IMAP4.socket()

   サーバへの接続に使われているソケットインスタンスを返します。

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

   "sort" 命令は "search" に結果の並べ替え (sort) 機能をつけた変種です
   。返されるデータには、条件に合致するメッセージ番号をスペースで分割
   したリストが入っています。

   sort 命令は *search_criterion* の前に二つの引数を持ちます;
   *sort_criteria* のリストを丸括弧で囲ったものと、検索時の *charset*
   です。 "search" と違って、検索時の *charset* は必須です。 "uid
   sort" 命令もあり、"search" に対する "uid search" と同じように
   "sort" 命令に対応します。 "sort" 命令はまず、"charset" 引数の指定に
   従って 検索条件の文字列を解釈し、メールボックスから与えられた検索条
   件に合致するメッセージを探します。 次に、合致したメッセージの番号を
   返します。

   "IMAP4rev1" 拡張命令です。

IMAP4.starttls(ssl_context=None)

   "STARTTLS" コマンドを送信します。 *ssl_context* 引数は省略可能で、
   指定する場合は "ssl.SSLContext" オブジェクトでなければなりません。
   これにより IMAP 接続の暗号化が有効になります。 推奨される方法につい
   ては セキュリティで考慮すべき点 を読んでください。

   注釈:

     デフォルトの *ssl_context* では接続は暗号化されますが、サーバ証明
     書とホスト名は検証されません。 これらを検証するには、
     "ssl.create_default_context()" で作成したコンテキストを渡してくだ
     さい。

   Added in version 3.2.

   バージョン 3.4 で変更: このメソッドは
   "ssl.SSLContext.check_hostname" によるホスト名の検証と、*Server
   Name Indication* ("ssl.HAS_SNI" を参照) をサポートするようになりま
   した。

IMAP4.status(mailbox, names)

   *mailbox* の指定ステータス名の状態情報を要求します。

IMAP4.store(message_set, command, flag_list)

   メールボックス内のメッセージのフラグ設定を変更します。 *command* は
   **RFC 3501** の 6.4.6 節に従い、"FLAGS"、"+FLAGS"、"-FLAGS" のいず
   れかで、必要に応じて末尾に ".SILENT" を付けます。

   たとえば、すべてのメッセージに削除フラグを設定するには次のようにし
   ます:

      typ, data = M.search(None, 'ALL')
      for num in data[0].split():
         M.store(num, '+FLAGS', '\\Deleted')
      M.expunge()

   注釈:

     ']' を含むフラグ (例えば "[test]") の作成は **RFC 3501** (IMAP プ
     ロトコル) に違反します。 しかし、imaplib は以前からこのようなフラ
     グの作成を許可しており、Gmail などの広く使われている IMAP サーバ
     も受け入れたり生成したりします。 Python 以外にも、このようなフラ
     グを作成するプログラムがあります。 RFC 違反であり、IMAP クライア
     ントとサーバは厳格であるべきですが、後方互換性のため、imaplib は
     引き続きこのようなフラグの作成を許可しています。 さらに、実際の互
     換性を高めるため、Python 3.6 以降はサーバから送られてきた場合も処
     理します。

IMAP4.subscribe(mailbox)

   新たなメールボックスを購読 (subscribe) します。

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

   "thread" コマンドは "search" にスレッドの概念を加えた変形版です。返
   されるデータは空白で区切られたスレッドメンバのリストを含んでいます
   。

   各スレッドメンバは0以上のメッセージ番号からなり、空白で区切られてお
   り、親子関係を示しています。

   "thread" コマンドは *search_criterion* 引数より前に、
   *threading_algorithm* と検索用の *charset* という 2 つの引数を取り
   ます。 "search" と異なり、検索用の *charset* 引数は必須です。 "uid
   thread" コマンドもあり、"uid search" が "search" に対応するのと同様
   に "thread" に対応します。 "thread" コマンドはまず、*charset* 引数
   を使って検索条件の文字列を解釈し、指定した条件に合うメッセージをメ
   ールボックスから検索します。 次に、指定したスレッド化アルゴリズムに
   従ってスレッドにまとめたメッセージを返します。

   "IMAP4rev1" 拡張命令です。

IMAP4.uid(command, arg[, ...])

   command args を、メッセージ番号ではなく UID で指定されたメッセージ
   群に対して実行します。命令内容に応じた応答を返します。少なくとも一
   つの引数を与えなくてはなりません; 何も与えない場合、サーバはエラー
   を返し、例外が送出されます。

IMAP4.unsubscribe(mailbox)

   古いメールボックスの購読を解除 (unsubscribe) します。

IMAP4.unselect()

   "imaplib.IMAP4.unselect()" は、選択されたメールボックスに関連するサ
   ーバのリソースを解放し、サーバを認証済みの状態に戻します。 このコマ
   ンドは "imaplib.IMAP4.close()" と同じ処理を行いますが、現在選択され
   ているメールボックスのメッセージを永久に削除することはありません。

   Added in version 3.9.

IMAP4.xatom(name[, ...])

   サーバから "CAPABILITY" 応答で通知された単純な拡張命令を許容
   (allow) します。

以下の属性が "IMAP4" のインスタンス上で定義されています:

IMAP4.capabilities

   サーバが通知した capability を大文字で格納するタプルです。

   接続の確立時に設定され、"login()"、"authenticate()"、"starttls()"
   の成功後に更新されます。 接続の状態によって、サーバが異なる
   capability を通知する場合があるためです。

   バージョン 3.14.7 で変更: "login()" と "authenticate()" の後で更新
   されるようになりました。

IMAP4.PROTOCOL_VERSION

   サーバから返された "CAPABILITY" 応答にある、サポートされている最新
   のプロトコルです。

IMAP4.debug

   デバッグ出力を制御するための整数値です。 初期値はモジュール変数
   "Debug" から取られます。 3 より大きい値にすると各命令をトレースしま
   す。

IMAP4.utf8_enabled

   通常は "False" の真偽値ですが、"UTF8=ACCEPT" capability に対する
   "enable()" コマンドが成功すると "True" になります。

   Added in version 3.5.

property IMAP4.file

   基になるソケットに関連付けられた内部の "BufferedReader" です。 従来
   の利用のために説明していますが、公開インターフェースの一部ではあり
   ません。 変更する前に現在のファイルが閉じられていることを確認するの
   は、呼び出し側の責任です。

   バージョン 3.15 で非推奨、バージョン 3.19 で削除予定.


IMAP4 の使用例
==============

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

   import getpass, imaplib

   M = imaplib.IMAP4(host='example.org')
   M.login(getpass.getuser(), getpass.getpass())
   M.select()
   typ, data = M.search(None, 'ALL')
   for num in data[0].split():
       typ, data = M.fetch(num, '(RFC822)')
       print('Message %s\n%s\n' % (num, data[0][1]))
   M.close()
   M.logout()

注釈:

  "FETCH" 応答には、追加のデータや要求していないデータが含まれる場合が
  あるため (**RFC 3501** の 7.4.2 節を参照)、実運用のコードでは
  "data[0][1]" に頼らず応答全体を調べてください。
