--- rest25/library/imaplib.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/imaplib.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,35 +1,30 @@
-
 :mod:`imaplib` --- IMAP4 protocol client
 ========================================
 
 .. module:: imaplib
    :synopsis: IMAP4 protocol client (requires sockets).
 .. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
 .. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
+.. revised by ESR, January 2000
+.. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
+.. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
+   November 2002
 
 
 .. index::
    pair: IMAP4; protocol
    pair: IMAP4_SSL; protocol
    pair: IMAP4_stream; protocol
 
-.. % Based on HTML documentation by Piers Lauder
-.. % <piers@communitysolutions.com.au>;
-.. % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
-.. % Revised by ESR, January 2000.
-.. % Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
-.. % Changes for IMAP4_stream by Piers Lauder
-.. % <piers@communitysolutions.com.au>, November 2002
-
 This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
 :class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
 implement a large subset of the IMAP4rev1 client protocol as defined in
 :rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
 note that the ``STATUS`` command is not supported in IMAP4.
 
 Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
 base class:
 
 
 .. class:: IMAP4([host[, port]])
 
@@ -113,25 +108,25 @@
 Note that IMAP4 message numbers change as the mailbox changes; in particular,
 after an ``EXPUNGE`` command performs deletions the remaining messages are
 renumbered. So it is highly advisable to use UIDs instead, with the UID command.
 
 At the end of the module, there is a test section that contains a more extensive
 example of usage.
 
 
 .. seealso::
 
    Documents describing the protocol, and sources and binaries  for servers
    implementing it, can all be found at the University of Washington's *IMAP
-   Information Center* (`<http://www.cac.washington.edu/imap/>`_).
+   Information Center* (http://www.washington.edu/imap/).
 
 
 .. _imap4-objects:
 
 IMAP4 Objects
 -------------
 
 All IMAP4rev1 commands are represented by methods of the same name, either
 upper-case or lower-case.
 
 All arguments to commands are converted to strings, except for ``AUTHENTICATE``,
 and the last argument to ``APPEND`` which is passed as an IMAP4 literal.  If
@@ -147,381 +142,381 @@
 tuple. If a tuple, then the first part is the header of the response, and the
 second part contains the data (ie: 'literal' value).
 
 The *message_set* options to commands below is a string specifying one or more
 messages to be acted upon.  It may be a simple message number (``'1'``), a range
 of message numbers (``'2:4'``), or a group of non-contiguous ranges separated by
 commas (``'1:3,6:9'``).  A range can contain an asterisk to indicate an infinite
 upper bound (``'3:*'``).
 
 An :class:`IMAP4` instance has the following methods:
 
 
-.. method:: XXX Class.append(mailbox, flags, date_time, message)
+.. method:: IMAP4.append(mailbox, flags, date_time, message)
 
    Append *message* to named mailbox.
 
 
-.. method:: XXX Class.authenticate(mechanism, authobject)
+.. method:: IMAP4.authenticate(mechanism, authobject)
 
    Authenticate command --- requires response processing.
 
    *mechanism* specifies which authentication mechanism is to be used - it should
    appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``.
 
    *authobject* must be a callable object::
 
       data = authobject(response)
 
    It will be called to process server continuation responses. It should return
    ``data`` that will be encoded and sent to server. It should return ``None`` if
    the client abort response ``*`` should be sent instead.
 
 
-.. method:: XXX Class.check()
+.. method:: IMAP4.check()
 
    Checkpoint mailbox on server.
 
 
-.. method:: XXX Class.close()
+.. method:: IMAP4.close()
 
    Close currently selected mailbox. Deleted messages are removed from writable
    mailbox. This is the recommended command before ``LOGOUT``.
 
 
-.. method:: XXX Class.copy(message_set, new_mailbox)
+.. method:: IMAP4.copy(message_set, new_mailbox)
 
    Copy *message_set* messages onto end of *new_mailbox*.
 
 
-.. method:: XXX Class.create(mailbox)
+.. method:: IMAP4.create(mailbox)
 
    Create new mailbox named *mailbox*.
 
 
-.. method:: XXX Class.delete(mailbox)
+.. method:: IMAP4.delete(mailbox)
 
    Delete old mailbox named *mailbox*.
 
 
-.. method:: XXX Class.deleteacl(mailbox, who)
+.. method:: IMAP4.deleteacl(mailbox, who)
 
    Delete the ACLs (remove any rights) set for who on mailbox.
 
    .. versionadded:: 2.4
 
 
-.. method:: XXX Class.expunge()
+.. method:: IMAP4.expunge()
 
    Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE``
    response for each deleted message. Returned data contains a list of ``EXPUNGE``
    message numbers in order received.
 
 
-.. method:: XXX Class.fetch(message_set, message_parts)
+.. method:: IMAP4.fetch(message_set, message_parts)
 
    Fetch (parts of) messages.  *message_parts* should be a string of message part
    names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``.  Returned data
    are tuples of message part envelope and data.
 
 
-.. method:: XXX Class.getacl(mailbox)
+.. method:: IMAP4.getacl(mailbox)
 
    Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported
    by the ``Cyrus`` server.
 
 
-.. method:: XXX Class.getannotation(mailbox, entry, attribute)
+.. method:: IMAP4.getannotation(mailbox, entry, attribute)
 
-   Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is non-
-   standard, but is supported by the ``Cyrus`` server.
+   Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is
+   non-standard, but is supported by the ``Cyrus`` server.
 
    .. versionadded:: 2.5
 
 
-.. method:: XXX Class.getquota(root)
+.. method:: IMAP4.getquota(root)
 
    Get the ``quota`` *root*'s resource usage and limits. This method is part of the
    IMAP4 QUOTA extension defined in rfc2087.
 
    .. versionadded:: 2.3
 
 
-.. method:: XXX Class.getquotaroot(mailbox)
+.. method:: IMAP4.getquotaroot(mailbox)
 
    Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part
    of the IMAP4 QUOTA extension defined in rfc2087.
 
    .. versionadded:: 2.3
 
 
-.. method:: XXX Class.list([directory[, pattern]])
+.. method:: IMAP4.list([directory[, pattern]])
 
    List mailbox names in *directory* matching *pattern*.  *directory* defaults to
    the top-level mail folder, and *pattern* defaults to match anything.  Returned
    data contains a list of ``LIST`` responses.
 
 
-.. method:: XXX Class.login(user, password)
+.. method:: IMAP4.login(user, password)
 
    Identify the client using a plaintext password. The *password* will be quoted.
 
 
-.. method:: XXX Class.login_cram_md5(user, password)
+.. method:: IMAP4.login_cram_md5(user, password)
 
    Force use of ``CRAM-MD5`` authentication when identifying the client to protect
    the password.  Will only work if the server ``CAPABILITY`` response includes the
    phrase ``AUTH=CRAM-MD5``.
 
    .. versionadded:: 2.3
 
 
-.. method:: XXX Class.logout()
+.. method:: IMAP4.logout()
 
    Shutdown connection to server. Returns server ``BYE`` response.
 
 
-.. method:: XXX Class.lsub([directory[, pattern]])
+.. method:: IMAP4.lsub([directory[, pattern]])
 
    List subscribed mailbox names in directory matching pattern. *directory*
    defaults to the top level directory and *pattern* defaults to match any mailbox.
    Returned data are tuples of message part envelope and data.
 
 
-.. method:: XXX Class.myrights(mailbox)
+.. method:: IMAP4.myrights(mailbox)
 
    Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
 
    .. versionadded:: 2.4
 
 
-.. method:: XXX Class.namespace()
+.. method:: IMAP4.namespace()
 
    Returns IMAP namespaces as defined in RFC2342.
 
    .. versionadded:: 2.3
 
 
-.. method:: XXX Class.noop()
+.. method:: IMAP4.noop()
 
    Send ``NOOP`` to server.
 
 
-.. method:: XXX Class.open(host, port)
+.. method:: IMAP4.open(host, port)
 
    Opens socket to *port* at *host*. The connection objects established by this
    method will be used in the ``read``, ``readline``, ``send``, and ``shutdown``
    methods. You may override this method.
 
 
-.. method:: XXX Class.partial(message_num, message_part, start, length)
+.. method:: IMAP4.partial(message_num, message_part, start, length)
 
    Fetch truncated part of a message. Returned data is a tuple of message part
    envelope and data.
 
 
-.. method:: XXX Class.proxyauth(user)
+.. method:: IMAP4.proxyauth(user)
 
    Assume authentication as *user*. Allows an authorised administrator to proxy
    into any user's mailbox.
 
    .. versionadded:: 2.3
 
 
-.. method:: XXX Class.read(size)
+.. method:: IMAP4.read(size)
 
    Reads *size* bytes from the remote server. You may override this method.
 
 
-.. method:: XXX Class.readline()
+.. method:: IMAP4.readline()
 
    Reads one line from the remote server. You may override this method.
 
 
-.. method:: XXX Class.recent()
+.. method:: IMAP4.recent()
 
    Prompt server for an update. Returned data is ``None`` if no new messages, else
    value of ``RECENT`` response.
 
 
-.. method:: XXX Class.rename(oldmailbox, newmailbox)
+.. method:: IMAP4.rename(oldmailbox, newmailbox)
 
    Rename mailbox named *oldmailbox* to *newmailbox*.
 
 
-.. method:: XXX Class.response(code)
+.. method:: IMAP4.response(code)
 
    Return data for response *code* if received, or ``None``. Returns the given
    code, instead of the usual type.
 
 
-.. method:: XXX Class.search(charset, criterion[, ...])
+.. method:: IMAP4.search(charset, criterion[, ...])
 
    Search mailbox for matching messages.  *charset* may be ``None``, in which case
    no ``CHARSET`` will be specified in the request to the server.  The IMAP
    protocol requires that at least one criterion be specified; an exception will be
    raised when the server returns an error.
 
    Example::
 
       # M is a connected IMAP4 instance...
       typ, msgnums = M.search(None, 'FROM', '"LDJ"')
 
       # or:
       typ, msgnums = M.search(None, '(FROM "LDJ")')
 
 
-.. method:: XXX Class.select([mailbox[, readonly]])
+.. method:: IMAP4.select([mailbox[, readonly]])
 
    Select a mailbox. Returned data is the count of messages in *mailbox*
    (``EXISTS`` response).  The default *mailbox* is ``'INBOX'``.  If the *readonly*
    flag is set, modifications to the mailbox are not allowed.
 
 
-.. method:: XXX Class.send(data)
+.. method:: IMAP4.send(data)
 
    Sends ``data`` to the remote server. You may override this method.
 
 
-.. method:: XXX Class.setacl(mailbox, who, what)
+.. method:: IMAP4.setacl(mailbox, who, what)
 
    Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by
    the ``Cyrus`` server.
 
 
-.. method:: XXX Class.setannotation(mailbox, entry, attribute[, ...])
+.. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...])
 
    Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is
    supported by the ``Cyrus`` server.
 
    .. versionadded:: 2.5
 
 
-.. method:: XXX Class.setquota(root, limits)
+.. method:: IMAP4.setquota(root, limits)
 
    Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4
    QUOTA extension defined in rfc2087.
 
    .. versionadded:: 2.3
 
 
-.. method:: XXX Class.shutdown()
+.. method:: IMAP4.shutdown()
 
    Close connection established in ``open``. You may override this method.
 
 
-.. method:: XXX Class.socket()
+.. method:: IMAP4.socket()
 
    Returns socket instance used to connect to server.
 
 
-.. method:: XXX Class.sort(sort_criteria, charset, search_criterion[, ...])
+.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])
 
    The ``sort`` command is a variant of ``search`` with sorting semantics for the
    results.  Returned data contains a space separated list of matching message
    numbers.
 
    Sort has two arguments before the *search_criterion* argument(s); a
    parenthesized list of *sort_criteria*, and the searching *charset*.  Note that
    unlike ``search``, the searching *charset* argument is mandatory.  There is also
    a ``uid sort`` command which corresponds to ``sort`` the way that ``uid search``
    corresponds to ``search``.  The ``sort`` command first searches the mailbox for
    messages that match the given searching criteria using the charset argument for
    the interpretation of strings in the searching criteria.  It then returns the
    numbers of matching messages.
 
    This is an ``IMAP4rev1`` extension command.
 
 
-.. method:: XXX Class.status(mailbox, names)
+.. method:: IMAP4.status(mailbox, names)
 
    Request named status conditions for *mailbox*.
 
 
-.. method:: XXX Class.store(message_set, command, flag_list)
+.. method:: IMAP4.store(message_set, command, flag_list)
 
    Alters flag dispositions for messages in mailbox.  *command* is specified by
    section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
    optionally with a suffix of ".SILENT".
 
    For example, to set the delete flag on all messages::
 
       typ, data = M.search(None, 'ALL')
       for num in data[0].split():
          M.store(num, '+FLAGS', '\\Deleted')
       M.expunge()
 
 
-.. method:: XXX Class.subscribe(mailbox)
+.. method:: IMAP4.subscribe(mailbox)
 
    Subscribe to new mailbox.
 
 
-.. method:: XXX Class.thread(threading_algorithm, charset, search_criterion[, ...])
+.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])
 
    The ``thread`` command is a variant of ``search`` with threading semantics for
    the results.  Returned data contains a space separated list of thread members.
 
    Thread members consist of zero or more messages numbers, delimited by spaces,
    indicating successive parent and child.
 
    Thread has two arguments before the *search_criterion* argument(s); a
    *threading_algorithm*, and the searching *charset*.  Note that unlike
    ``search``, the searching *charset* argument is mandatory.  There is also a
    ``uid thread`` command which corresponds to ``thread`` the way that ``uid
    search`` corresponds to ``search``.  The ``thread`` command first searches the
    mailbox for messages that match the given searching criteria using the charset
    argument for the interpretation of strings in the searching criteria. It then
    returns the matching messages threaded according to the specified threading
    algorithm.
 
    This is an ``IMAP4rev1`` extension command.
 
    .. versionadded:: 2.4
 
 
-.. method:: XXX Class.uid(command, arg[, ...])
+.. method:: IMAP4.uid(command, arg[, ...])
 
    Execute command args with messages identified by UID, rather than message
    number.  Returns response appropriate to command.  At least one argument must be
    supplied; if none are provided, the server will return an error and an exception
    will be raised.
 
 
-.. method:: XXX Class.unsubscribe(mailbox)
+.. method:: IMAP4.unsubscribe(mailbox)
 
    Unsubscribe from old mailbox.
 
 
-.. method:: XXX Class.xatom(name[, arg[, ...]])
+.. method:: IMAP4.xatom(name[, arg[, ...]])
 
    Allow simple extension commands notified by server in ``CAPABILITY`` response.
 
 Instances of :class:`IMAP4_SSL` have just one additional method:
 
 
-.. method:: XXX Class.ssl()
+.. method:: IMAP4_SSL.ssl()
 
    Returns SSLObject instance used for the secure connection with the server.
 
 The following attributes are defined on instances of :class:`IMAP4`:
 
 
-.. attribute:: XXX Class.PROTOCOL_VERSION
+.. attribute:: IMAP4.PROTOCOL_VERSION
 
    The most recent supported protocol in the ``CAPABILITY`` response from the
    server.
 
 
-.. attribute:: XXX Class.debug
+.. attribute:: IMAP4.debug
 
    Integer value to control debugging output.  The initialize value is taken from
    the module variable ``Debug``.  Values greater than three trace each command.
 
 
 .. _imap4-example:
 
 IMAP4 Example
 -------------
 
 Here is a minimal example (without error checking) that opens a mailbox and
 retrieves and prints all messages::
