##
11.10.1 IMAP4 オブジェクト

全ての IMAP4rev1 命令は、同じ名前のメソッドで表されており、大文字の ものも小文字のものもあります。

命令に対する引数は全て文字列に変換されます。例外は "`AUTHENTICATE`"の引数と "`APPEND`" の最後の引数で、これは IMAP4 リテラルとして 渡されます。必要に応じて (IMAP4 プロトコルが感知対象としている 文字が文字列に入っており、かつ丸括弧か二重引用符で囲われていなかった 場合) 文字列はクオートされます。しかし、"`LOGIN`" 命令の password 引数は常にクオートされます。文字列がクオートされない ようにしたい (例えば "`STORE`" 命令の flags 引数) 場合、 文字列を丸括弧で囲んでください (例: `r'(\Deleted)'`)。

各命令はタプル: `(type, [data, ...])` を返し、 type は通常 `'OK'` または `'NO'` です。 data は命令に対する応答をテキストにしたものか、命令に対する 実行結果です。各 data は文字列かタプルとなります。タプルの場合、 最初の要素はレスポンスのヘッダで、次の要素にはデータが格納されます。 (ie: 'literal' value)

以下のコマンドにおけるmessage_set オプションは、 コマンドの作用対象となる一つまたは複数のメッセージを指定する 文字列です。この文字列に指定できるのは単なるメッセージ番号 (`'1'`)、メッセージ番号の範囲 (`'2:4'`)、および メッセージ番号の範囲をコンマで区切ったもの(`'1:3,6:9'`) です。範囲にはアスタリスクを使って、最大のメッセージ番号を 指定できます(`'3:*'`)。

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

`append`( | mailbox, flags, date_time, message)

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

`authenticate`( | func)

  認証命令です -- 応答の処理が必要です。現在は実装されておらず、 例外を送出します。

`check`( | )

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

`close`( | )

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

`copy`( | message_set, new_mailbox)

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

`create`( | mailbox)

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

`delete`( | mailbox)

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

`expunge`( | )

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

`fetch`( | message_set, message_parts)

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

`getacl`( | mailbox)

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

`getquota`( | root)

  "`quota`" root により、リソース使用状況と制限値を取得します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン2.3 以降で新規追加された 仕様です。

`getquotaroot`( | mailbox)

  mailbox に対して "`quota`" root を実行した結果のリストを 取得します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン2.3 以降で新規追加された 仕様です。

`list`( | [directory[, pattern]])

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

`login`( | user, password)

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

`login_cram_md5`( | user, password)

  パスワードの保護のため、クライアント認証時に"`CRAM-MD5`"だけを使用します。 これは、"`CAPABILITY`"レスポンスに "`AUTH=CRAM-MD5`" が含まれる場合のみ 有効です。 バージョン2.3 以降で新規追加された 仕様です。

+

`logout`( | )

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

`lsub`( | [directory[, pattern]])

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

`noop`( | )

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

`open`( | host, port)

  host 上の port に対するソケットを開きます。 このメソッドで確立された接続オブジェクトは `read`、 `readline`、`send`、および`shutdown` メソッドで 使われます。このメソッドはオーバライドすることができます。

`partial`( | message_num, message_part, start, length)

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

`proxyauth`( | user)

  userとして認証されたものとします。 認証された管理者がユーザの代理としてメイルボックスにアクセス する際に使用します。 バージョン2.3 以降で新規追加された 仕様です。

+

`read`( | size)

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

`readline`( | )

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

`recent`( | )

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

`rename`( | oldmailbox, newmailbox)

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

`response`( | code)

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

`search`( | charset, criterion[, ...])

  条件に合致するメッセージをメイルボックスから検索します。返される データには合致したメッセージ番号をスペースで分割したリストが入って います。charset は `None` でもよく、この場合にはサーバ への要求内に "`CHARSET`" は指定されません。IMAP プロトコルは 少なくとも一つの条件 (criterion) が指定されるよう要求しています; サーバがエラーを返した場合、例外が送出されます。

  例:

      # M is a connected IMAP4 instance...
      msgnums = M.search(None, 'FROM', '"LDJ"')

      # or:
      msgnums = M.search(None, '(FROM "LDJ")')

`select`( | [mailbox[, readonly]])

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

`send`( | data)

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

`setacl`( | mailbox, who, what)

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

`setquota`( | root, limits)

  "`quota`" root のリソースを limits に設定します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン2.3 以降で新規追加された 仕様です。

`shutdown`( | )

  `open` で確立された接続を閉じます。 このメソッドはオーバライドすることができます。

`socket`( | )

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

`sort`( | sort_criteria, charset, search_criterion[, ...])

  `sort` 命令は `search` に結果の並べ替え (sort) 機能をつけた 変種です。返されるデータには、条件に合致するメッセージ番号をスペースで 分割したリストが入っています。 sort 命令は search_criterium の前に二つの引数を持ちます; sort_criteria のリストを丸括弧で囲ったものと、検索時の charset です。 `search` と違って、検索時の charset は必須です。 `uid sort` 命令もあり、`search` に対する `uid search` と同じように `sort` 命令に対応します。 `sort` 命令はまず、charset 引数の指定に従って searching criteria の文字列を解釈し、メイルボックスから与えられた検索条件に合致する メッセージを探します。次に、合致したメッセージの数を返します。

  "`IMAP4rev1`" 拡張命令です。

`status`( | mailbox, names)

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

`store`( | message_set, command, flag_list)

  メイルボックス内のメッセージ群のフラグ設定を変更します。 RFC 2060 の 6.4.6 節によると、command は "FLAGS", "+FLAGS", "-FLAGS" のいずれかで、サフィクス ".SILENT" をオプションで追加 できます。

  たとえば、全てのメッセージに削除フラグを立てるには 以下のようにします:

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

`subscribe`( | mailbox)

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

`uid`( | command, arg[, ...])

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

`unsubscribe`( | mailbox)

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

`xatom`( | name[, arg[, ...]])

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

`IMAP4_SSL` のインスタンスは追加のメソッドを一つだけ持ちます:

`ssl`( | )

  サーバへの安全な接続に使われる SSLObject インスタンスを返します。

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

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

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