diff options
Diffstat (limited to 'Doc/lib/libimaplib.tex')
| -rw-r--r-- | Doc/lib/libimaplib.tex | 507 |
1 files changed, 0 insertions, 507 deletions
diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex deleted file mode 100644 index e34caaa..0000000 --- a/Doc/lib/libimaplib.tex +++ /dev/null @@ -1,507 +0,0 @@ -\section{\module{imaplib} --- - IMAP4 protocol client} - -\declaremodule{standard}{imaplib} -\modulesynopsis{IMAP4 protocol client (requires sockets).} -\moduleauthor{Piers Lauder}{piers@communitysolutions.com.au} -\sectionauthor{Piers Lauder}{piers@communitysolutions.com.au} - -% 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 - -\indexii{IMAP4}{protocol} -\indexii{IMAP4_SSL}{protocol} -\indexii{IMAP4_stream}{protocol} - -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 -\samp{STATUS} command is not supported in IMAP4. - -Three classes are provided by the \module{imaplib} module, -\class{IMAP4} is the base class: - -\begin{classdesc}{IMAP4}{\optional{host\optional{, port}}} -This class implements the actual IMAP4 protocol. The connection is -created and protocol version (IMAP4 or IMAP4rev1) is determined when -the instance is initialized. -If \var{host} is not specified, \code{''} (the local host) is used. -If \var{port} is omitted, the standard IMAP4 port (143) is used. -\end{classdesc} - -Three exceptions are defined as attributes of the \class{IMAP4} class: - -\begin{excdesc}{IMAP4.error} -Exception raised on any errors. The reason for the exception is -passed to the constructor as a string. -\end{excdesc} - -\begin{excdesc}{IMAP4.abort} -IMAP4 server errors cause this exception to be raised. This is a -sub-class of \exception{IMAP4.error}. Note that closing the instance -and instantiating a new one will usually allow recovery from this -exception. -\end{excdesc} - -\begin{excdesc}{IMAP4.readonly} -This exception is raised when a writable mailbox has its status -changed by the server. This is a sub-class of -\exception{IMAP4.error}. Some other client now has write permission, -and the mailbox will need to be re-opened to re-obtain write -permission. -\end{excdesc} - -There's also a subclass for secure connections: - -\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{, - keyfile\optional{, certfile}}}}} -This is a subclass derived from \class{IMAP4} that connects over an -SSL encrypted socket (to use this class you need a socket module that -was compiled with SSL support). If \var{host} is not specified, -\code{''} (the local host) is used. If \var{port} is omitted, the -standard IMAP4-over-SSL port (993) is used. \var{keyfile} and -\var{certfile} are also optional - they can contain a PEM formatted -private key and certificate chain file for the SSL connection. -\end{classdesc} - -The second subclass allows for connections created by a child process: - -\begin{classdesc}{IMAP4_stream}{command} -This is a subclass derived from \class{IMAP4} that connects -to the \code{stdin/stdout} file descriptors created by passing -\var{command} to \code{os.popen2()}. -\versionadded{2.3} -\end{classdesc} - -The following utility functions are defined: - -\begin{funcdesc}{Internaldate2tuple}{datestr} - Converts an IMAP4 INTERNALDATE string to Coordinated Universal - Time. Returns a \refmodule{time} module tuple. -\end{funcdesc} - -\begin{funcdesc}{Int2AP}{num} - Converts an integer into a string representation using characters - from the set [\code{A} .. \code{P}]. -\end{funcdesc} - -\begin{funcdesc}{ParseFlags}{flagstr} - Converts an IMAP4 \samp{FLAGS} response to a tuple of individual - flags. -\end{funcdesc} - -\begin{funcdesc}{Time2Internaldate}{date_time} - Converts a \refmodule{time} module tuple to an IMAP4 - \samp{INTERNALDATE} representation. Returns a string in the form: - \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes). -\end{funcdesc} - - -Note that IMAP4 message numbers change as the mailbox changes; in -particular, after an \samp{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. - -\begin{seealso} - \seetext{Documents describing the protocol, and sources and binaries - for servers implementing it, can all be found at the - University of Washington's \emph{IMAP Information Center} - (\url{http://www.cac.washington.edu/imap/}).} -\end{seealso} - - -\subsection{IMAP4 Objects \label{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 -\samp{AUTHENTICATE}, and the last argument to \samp{APPEND} which is -passed as an IMAP4 literal. If necessary (the string contains IMAP4 -protocol-sensitive characters and isn't enclosed with either -parentheses or double quotes) each string is quoted. However, the -\var{password} argument to the \samp{LOGIN} command is always quoted. -If you want to avoid having an argument string quoted -(eg: the \var{flags} argument to \samp{STORE}) then enclose the string in -parentheses (eg: \code{r'(\e Deleted)'}). - -Each command returns a tuple: \code{(\var{type}, [\var{data}, -...])} where \var{type} is usually \code{'OK'} or \code{'NO'}, -and \var{data} is either the text from the command response, or -mandated results from the command. Each \var{data} -is either a string, or a 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 \var{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 -(\code{'1'}), a range of message numbers (\code{'2:4'}), or a group of -non-contiguous ranges separated by commas (\code{'1:3,6:9'}). A range -can contain an asterisk to indicate an infinite upper bound -(\code{'3:*'}). - -An \class{IMAP4} instance has the following methods: - - -\begin{methoddesc}[IMAP4]{append}{mailbox, flags, date_time, message} - Append \var{message} to named mailbox. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{authenticate}{mechanism, authobject} - Authenticate command --- requires response processing. - - \var{mechanism} specifies which authentication mechanism is to be - used - it should appear in the instance variable \code{capabilities} - in the form \code{AUTH=mechanism}. - - \var{authobject} must be a callable object: - -\begin{verbatim} -data = authobject(response) -\end{verbatim} - - It will be called to process server continuation responses. - It should return \code{data} that will be encoded and sent to server. - It should return \code{None} if the client abort response \samp{*} should - be sent instead. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{check}{} - Checkpoint mailbox on server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{close}{} - Close currently selected mailbox. Deleted messages are removed from - writable mailbox. This is the recommended command before - \samp{LOGOUT}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{copy}{message_set, new_mailbox} - Copy \var{message_set} messages onto end of \var{new_mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{create}{mailbox} - Create new mailbox named \var{mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{delete}{mailbox} - Delete old mailbox named \var{mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{deleteacl}{mailbox, who} - Delete the ACLs (remove any rights) set for who on mailbox. -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{expunge}{} - Permanently remove deleted items from selected mailbox. Generates an - \samp{EXPUNGE} response for each deleted message. Returned data - contains a list of \samp{EXPUNGE} message numbers in order - received. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{fetch}{message_set, message_parts} - Fetch (parts of) messages. \var{message_parts} should be - a string of message part names enclosed within parentheses, - eg: \samp{"(UID BODY[TEXT])"}. Returned data are tuples - of message part envelope and data. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getacl}{mailbox} - Get the \samp{ACL}s for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getannotation}{mailbox, entry, attribute} - Retrieve the specified \samp{ANNOTATION}s for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getquota}{root} - Get the \samp{quota} \var{root}'s resource usage and limits. - This method is part of the IMAP4 QUOTA extension defined in rfc2087. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getquotaroot}{mailbox} - Get the list of \samp{quota} \samp{roots} for the named \var{mailbox}. - This method is part of the IMAP4 QUOTA extension defined in rfc2087. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{list}{\optional{directory\optional{, pattern}}} - List mailbox names in \var{directory} matching - \var{pattern}. \var{directory} defaults to the top-level mail - folder, and \var{pattern} defaults to match anything. Returned data - contains a list of \samp{LIST} responses. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{login}{user, password} - Identify the client using a plaintext password. - The \var{password} will be quoted. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{login_cram_md5}{user, password} - Force use of \samp{CRAM-MD5} authentication when identifying the - client to protect the password. Will only work if the server - \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{logout}{} - Shutdown connection to server. Returns server \samp{BYE} response. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{lsub}{\optional{directory\optional{, pattern}}} - List subscribed mailbox names in directory matching pattern. - \var{directory} defaults to the top level directory and - \var{pattern} defaults to match any mailbox. - Returned data are tuples of message part envelope and data. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{myrights}{mailbox} - Show my ACLs for a mailbox (i.e. the rights that I have on mailbox). -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{namespace}{} - Returns IMAP namespaces as defined in RFC2342. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{noop}{} - Send \samp{NOOP} to server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{open}{host, port} - Opens socket to \var{port} at \var{host}. - The connection objects established by this method - will be used in the \code{read}, \code{readline}, \code{send}, and - \code{shutdown} methods. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[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. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{proxyauth}{user} - Assume authentication as \var{user}. - Allows an authorised administrator to proxy into any user's mailbox. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{read}{size} - Reads \var{size} bytes from the remote server. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{readline}{} - Reads one line from the remote server. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{recent}{} - Prompt server for an update. Returned data is \code{None} if no new - messages, else value of \samp{RECENT} response. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{rename}{oldmailbox, newmailbox} - Rename mailbox named \var{oldmailbox} to \var{newmailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{response}{code} - Return data for response \var{code} if received, or - \code{None}. Returns the given code, instead of the usual type. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{search}{charset, criterion\optional{, ...}} - Search mailbox for matching messages. \var{charset} may be - \code{None}, in which case no \samp{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: - -\begin{verbatim} -# M is a connected IMAP4 instance... -typ, msgnums = M.search(None, 'FROM', '"LDJ"') - -# or: -typ, msgnums = M.search(None, '(FROM "LDJ")') -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{select}{\optional{mailbox\optional{, readonly}}} - Select a mailbox. Returned data is the count of messages in - \var{mailbox} (\samp{EXISTS} response). The default \var{mailbox} - is \code{'INBOX'}. If the \var{readonly} flag is set, modifications - to the mailbox are not allowed. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{send}{data} - Sends \code{data} to the remote server. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{setacl}{mailbox, who, what} - Set an \samp{ACL} for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{setannotation}{mailbox, entry, attribute\optional{, ...}} - Set \samp{ANNOTATION}s for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{setquota}{root, limits} - Set the \samp{quota} \var{root}'s resource \var{limits}. - This method is part of the IMAP4 QUOTA extension defined in rfc2087. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{shutdown}{} - Close connection established in \code{open}. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{socket}{} - Returns socket instance used to connect to server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{sort}{sort_criteria, charset, search_criterion\optional{, ...}} - The \code{sort} command is a variant of \code{search} with sorting - semantics for the results. Returned data contains a space separated - list of matching message numbers. - - Sort has two arguments before the \var{search_criterion} - argument(s); a parenthesized list of \var{sort_criteria}, and the - searching \var{charset}. Note that unlike \code{search}, the - searching \var{charset} argument is mandatory. There is also a - \code{uid sort} command which corresponds to \code{sort} the way - that \code{uid search} corresponds to \code{search}. The - \code{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 \samp{IMAP4rev1} extension command. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{status}{mailbox, names} - Request named status conditions for \var{mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{store}{message_set, command, flag_list} - Alters flag dispositions for messages in mailbox. \var{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: - -\begin{verbatim} -typ, data = M.search(None, 'ALL') -for num in data[0].split(): - M.store(num, '+FLAGS', '\\Deleted') -M.expunge() -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{subscribe}{mailbox} - Subscribe to new mailbox. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{thread}{threading_algorithm, charset, - search_criterion\optional{, ...}} - The \code{thread} command is a variant of \code{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 \var{search_criterion} - argument(s); a \var{threading_algorithm}, and the searching - \var{charset}. Note that unlike \code{search}, the searching - \var{charset} argument is mandatory. There is also a \code{uid - thread} command which corresponds to \code{thread} the way that - \code{uid search} corresponds to \code{search}. The \code{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 \samp{IMAP4rev1} extension command. \versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{uid}{command, arg\optional{, ...}} - 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. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{unsubscribe}{mailbox} - Unsubscribe from old mailbox. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{xatom}{name\optional{, arg\optional{, ...}}} - Allow simple extension commands notified by server in - \samp{CAPABILITY} response. -\end{methoddesc} - - -Instances of \class{IMAP4_SSL} have just one additional method: - -\begin{methoddesc}[IMAP4_SSL]{ssl}{} - Returns SSLObject instance used for the secure connection with the server. -\end{methoddesc} - - -The following attributes are defined on instances of \class{IMAP4}: - - -\begin{memberdesc}[IMAP4]{PROTOCOL_VERSION} -The most recent supported protocol in the -\samp{CAPABILITY} response from the server. -\end{memberdesc} - -\begin{memberdesc}[IMAP4]{debug} -Integer value to control debugging output. The initialize value is -taken from the module variable \code{Debug}. Values greater than -three trace each command. -\end{memberdesc} - - -\subsection{IMAP4 Example \label{imap4-example}} - -Here is a minimal example (without error checking) that opens a -mailbox and retrieves and prints all messages: - -\begin{verbatim} -import getpass, imaplib - -M = imaplib.IMAP4() -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() -\end{verbatim} |