Changeset 240:ca209b0b5f0c

Show
Ignore:
Timestamp:
19/02/11 23:19:50 (15 months ago)
Author:
Menno Smits <menno@…>
Branch:
default
Message:

merged changes from another documentation working copy

Files:
2 modified

Legend:

Unmodified
Added
Removed

  • doc-src/index.rst

    r239 r240  
    1 .. IMAPClient documentation master file, created by 
    2    sphinx-quickstart on Fri Oct  1 12:26:06 2010. 
    3    You can adapt this file completely to your liking, but it should at least 
    4    contain the root `toctree` directive. 
    5  
    61IMAPClient 
    72========== 
    … …  
    127Introduction 
    138------------ 
    14 A Pythonic, easy-to-use IMAP client class. 
     9A Pythonic, easy-to-use IMAP client package. 
    1510 
    16 Unlike imaplib, arguments and returns values are Pythonic and readily 
    17 usable. Exceptions are raised when problems occur (no error checking 
    18 of return values is required). 
     11Although IMAPClient actually uses the imaplib module from the Python 
     12standard library under the hood, it provides a different API. Instead 
     13of requiring that the caller performs extra parsing work, return 
     14values are full parsed, readily usable and use sensible Python 
     15types. Exceptions are raised when problems occur (no error checking of 
     16return values is required). 
     17 
     18MAPClient is straight forward it use, but it can be useful to have at 
     19least a general understanding of the IMAP protocol. `RFC3501 
     20<http://www.faqs.org/rfcs/rfc3501.html>`_ explains IMAP in 
     21detail. Other RFCs also apply to various extensions to the base 
     22protocol. These are referred to in the documentation below where 
     23relevant. 
    1924 
    2025A Simple Example 
    … …  
    2429XXX include some simple output 
    2530 
     31Concepts 
     32-------- 
     33 
     34Message Identifiers 
     35~~~~~~~~~~~~~~~~~~~ 
     36There are two ways to refer to messages using the IMAP protocol.  
     37 
     38One way is by message sequence number where the messages in a mailbox 
     39are numbered from 1 to N where N is the number of messages. These 
     40numbers don't persist between sessions and may be reassigned after 
     41some operations such as a folder expunge. 
     42 
     43XXX explain UIDs 
     44 
     45XXX rework below 
     46Message unique identifiers (UID) can be used with any call. The use_uid 
     47argument to the constructor and the use_uid attribute control whether UIDs 
     48are used. 
     49 
     50Any method that accepts message id's takes either a sequence containing 
     51message IDs (eg. [1,2,3]) or a single message ID as an integer. 
     52 
     53Message Flags 
     54~~~~~~~~~~~~~ 
     55Any method that accepts message flags takes either a sequence containing 
     56message flags (eg. [DELETED, 'foo', 'Bar']) or a single message flag (eg. 
     57'Foo'). See the constants at the top of this file for commonly used flags. 
     58 
     59Folder Name Encoding 
     60~~~~~~~~~~~~~~~~~~~~ 
     61XXX  
     62Any method that takes a folder name will accept a standard string or a 
     63unicode string. Unicode strings will be transparently encoded using 
     64modified UTF-7 as specified by RFC-2060. Such folder names will be returned 
     65as unicode strings by methods that return folder names. 
     66 
     67Transparent folder name encoding can be enabled or disabled with the 
     68folder_encode attribute. It defaults to True. 
     69 
     70XXX check FPNP for more ideas on what should go in here 
     71 
     72Exceptions 
     73~~~~~~~~~~ 
     74The IMAP related exceptions that will be raised by this class are: 
     75 
     76* IMAPClient.Error 
     77* IMAPClient.AbortError 
     78* IMAPClient.ReadOnlyError 
     79 
     80These are aliases for the imaplib.IMAP4 exceptions of the same name. Socket 
     81errors may also be raised in the case of network errors. 
     82 
    2683IMAPClient Class Reference 
    2784-------------------------- 
     85The primary class used by the imapclient package is the IMAPClient 
     86class. All interaction with a remote IMAP server is performed via an 
     87IMAPClient instance. 
     88 
    2889.. autoclass:: imapclient.IMAPClient 
    2990   :members: 

  • imapclient/imapclient.py

    r239 r240  
    3232 
    3333class IMAPClient(object): 
    34     #XXX concepts to cover: UIDs, message lists, folder encoding, exceptions 
    3534    """ 
    36     Message unique identifiers (UID) can be used with any call. The use_uid 
    37     argument to the constructor and the use_uid attribute control whether UIDs 
    38     are used. 
    39  
    40     Any method that accepts message id's takes either a sequence containing 
    41     message IDs (eg. [1,2,3]) or a single message ID as an integer. 
    42  
    43     Any method that accepts message flags takes either a sequence containing 
    44     message flags (eg. [DELETED, 'foo', 'Bar']) or a single message flag (eg. 
    45     'Foo'). See the constants at the top of this file for commonly used flags. 
    46  
    47     Any method that takes a folder name will accept a standard string or a 
    48     unicode string. Unicode strings will be transparently encoded using 
    49     modified UTF-7 as specified by RFC-2060. Such folder names will be returned 
    50     as unicode strings by methods that return folder names. 
    51  
    52     Transparent folder name encoding can be enabled or disabled with the 
    53     folder_encode attribute. It defaults to True. 
    54  
    55     The IMAP related exceptions that will be raised by this class are: 
    56         IMAPClient.Error 
    57         IMAPClient.AbortError 
    58         IMAPClient.ReadOnlyError 
    59     These are aliases for the imaplib.IMAP4 exceptions of the same name. Socket 
    60     errors may also be raised in the case of network errors. 
     35    A connection to the IMAP server specified by *host* is made when 
     36    the class is instantiated. 
     37 
     38    *port* defaults to 143, or 993 if *ssl* is ``True``. 
     39 
     40    If *use_uid* is ``True`` unique message UIDs be used for all calls 
     41    that accept message ids (defaults to ``True``). 
     42 
     43    If *ssl* is ``True`` an SSL connection will be made (defaults to 
     44    ``False``). 
    6145    """ 
    6246 
    … …  
    7054 
    7155    def __init__(self, host, port=None, use_uid=True, ssl=False): 
    72         """Initialise object instance and connect to the remote IMAP server. 
    73  
    74         @param host: The IMAP server address/hostname to connect to. 
    75         @param port: The port number to use (default is 143, 993 for SSL). 
    76         @param use_uid: Should message UIDs be used (default is True). 
    77         @param ssl: Make an SSL connection (default is False) 
    78         """ 
    7956        if ssl: 
    8057            ImapClass = imaplib.IMAP4_SSL 
    … …  
    11693 
    11794    def has_capability(self, capability): 
    118         """Return True if the server has the *capability* specified. 
     95        """Return ``True`` if the IMAP server has the given *capability*. 
    11996        """ 
    12097        # FIXME: this will not detect capabilities that are backwards