mirror of
				https://github.com/python/cpython.git
				synced 2025-11-04 03:44:55 +00:00 
			
		
		
		
	First cut at documentation for imaplib. Based on original documentation by
Piers Lauders.
This commit is contained in:
		
							parent
							
								
									756a9e87b1
								
							
						
					
					
						commit
						89de314cfc
					
				
					 2 changed files with 456 additions and 0 deletions
				
			
		
							
								
								
									
										228
									
								
								Doc/lib/libimaplib.tex
									
										
									
									
									
										Normal file
									
								
							
							
						
						
									
										228
									
								
								Doc/lib/libimaplib.tex
									
										
									
									
									
										Normal file
									
								
							| 
						 | 
					@ -0,0 +1,228 @@
 | 
				
			||||||
 | 
					% Based on HTML documentation by Piers Lauders <piers@staff.cs.usyd.edu.au>;
 | 
				
			||||||
 | 
					% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
 | 
				
			||||||
 | 
					%
 | 
				
			||||||
 | 
					% The imaplib module was written by Piers Lauders.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\section{Standard Module \module{imaplib}}
 | 
				
			||||||
 | 
					\stmodindex{imaplib}
 | 
				
			||||||
 | 
					\label{module-imaplib}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					This module defines a class, \class{IMAP4}, which encapsulates a
 | 
				
			||||||
 | 
					connection to an IMAP4 server and implements 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.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					A single class is provided by the \code{imaplib} module:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\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}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Two 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}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					The following utility functions are defined:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{funcdesc}{Internaldate2tuple}{datestr}
 | 
				
			||||||
 | 
					  Converts an IMAP4 INTERNALDATE string to Coordinated Universal
 | 
				
			||||||
 | 
					  Time. Returns a \module{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 \module{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}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\subsection{IMAP4 Objects}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					All IMAP4rev1 commands are represented by methods of the same name,
 | 
				
			||||||
 | 
					either upper-case or lower-case.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Each command returns a tuple: \code{(}\var{type}, \code{[}\var{data},
 | 
				
			||||||
 | 
					...\code{])} 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.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					An \class{IMAP4} instance has the following methods:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{append}{mailbox, flags, date_time, message}
 | 
				
			||||||
 | 
					  Append message to named mailbox. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{authenticate}{func}
 | 
				
			||||||
 | 
					  Authenticate command --- requires response processing. This is
 | 
				
			||||||
 | 
					  currently unimplemented, and raises an exception. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{check}{}
 | 
				
			||||||
 | 
					  Checkpoint mailbox on server. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{close}{}
 | 
				
			||||||
 | 
					  Close currently selected mailbox. Deleted messages are removed from
 | 
				
			||||||
 | 
					  writable mailbox. This is the recommended command before
 | 
				
			||||||
 | 
					  \samp{LOGOUT}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{copy}{message_set, new_mailbox}
 | 
				
			||||||
 | 
					  Copy \var{message_set} messages onto end of \var{new_mailbox}. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{create}{mailbox}
 | 
				
			||||||
 | 
					  Create new mailbox named \var{mailbox}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{delete}{mailbox}
 | 
				
			||||||
 | 
					  Delete old mailbox named \var{mailbox}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{fetch}{message_set, message_parts}
 | 
				
			||||||
 | 
					  Fetch (parts of) messages. Returned data are tuples of message part
 | 
				
			||||||
 | 
					  envelope and data.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{list}{directory='""', pattern='*'}
 | 
				
			||||||
 | 
					  List mailbox names in directory matching pattern. Returned data contains a
 | 
				
			||||||
 | 
					  list of \samp{LIST} responses.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{login}{user, password}
 | 
				
			||||||
 | 
					  Identify the client using a plaintext password.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{logout}{}
 | 
				
			||||||
 | 
					  Shutdown connection to server. Returns server \samp{BYE} response.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{lsub}{directory='""', pattern='*'}
 | 
				
			||||||
 | 
					  List subscribed mailbox names in directory matching
 | 
				
			||||||
 | 
					  pattern. Returned data are tuples of message part envelope and data.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{rename}{oldmailbox, newmailbox}
 | 
				
			||||||
 | 
					  Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{search}{charset, criteria}
 | 
				
			||||||
 | 
					  Search mailbox for matching messages. Returned data contains a space
 | 
				
			||||||
 | 
					  separated list of matching message numbers.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{status}{mailbox, names}
 | 
				
			||||||
 | 
					  Request named status conditions for \var{mailbox}. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{store}{message_set, command, flag_list}
 | 
				
			||||||
 | 
					  Alters flag dispositions for messages in mailbox.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{subscribe}{mailbox}
 | 
				
			||||||
 | 
					  Subscribe to new mailbox.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{uid}{command, args}
 | 
				
			||||||
 | 
					  Execute command args with messages identified by UID, rather than
 | 
				
			||||||
 | 
					  message number. Returns response appropriate to command.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{unsubscribe}{mailbox}
 | 
				
			||||||
 | 
					  Unsubscribe from old mailbox.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{xatom}{name\optional{, arg1\optional{, arg2}}}
 | 
				
			||||||
 | 
					  Allow simple extension commands notified by server in
 | 
				
			||||||
 | 
					  \samp{CAPABILITY} response.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\class{IMAP4} instances have a variable \member{PROTOCOL_VERSION} that
 | 
				
			||||||
 | 
					is set to the most recent supported protocol in the \samp{CAPABILITY}
 | 
				
			||||||
 | 
					response.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Finally, \class{IMAP4} instances have a variable debug which can be
 | 
				
			||||||
 | 
					set to an integer to turn on debugging.  Values greater than 3 trace
 | 
				
			||||||
 | 
					each command.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\subsection{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, string
 | 
				
			||||||
 | 
					M = imaplib.IMAP4()
 | 
				
			||||||
 | 
					M.LOGIN(getpass.getuser(), getpass.getpass())
 | 
				
			||||||
 | 
					M.SELECT()
 | 
				
			||||||
 | 
					typ, data = M.SEARCH(None, 'ALL')
 | 
				
			||||||
 | 
					for num in string.split(data[0]):
 | 
				
			||||||
 | 
					    typ, data - M.FETCH(num, '(RFC822)')
 | 
				
			||||||
 | 
					    print 'Message %s\n%s\n' % (num, data[0][1])
 | 
				
			||||||
 | 
					M.LOGOUT()
 | 
				
			||||||
 | 
					\end{verbatim}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Note that IMAP4 message numbers change as the mailbox changes, 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}
 | 
				
			||||||
							
								
								
									
										228
									
								
								Doc/libimaplib.tex
									
										
									
									
									
										Normal file
									
								
							
							
						
						
									
										228
									
								
								Doc/libimaplib.tex
									
										
									
									
									
										Normal file
									
								
							| 
						 | 
					@ -0,0 +1,228 @@
 | 
				
			||||||
 | 
					% Based on HTML documentation by Piers Lauders <piers@staff.cs.usyd.edu.au>;
 | 
				
			||||||
 | 
					% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
 | 
				
			||||||
 | 
					%
 | 
				
			||||||
 | 
					% The imaplib module was written by Piers Lauders.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\section{Standard Module \module{imaplib}}
 | 
				
			||||||
 | 
					\stmodindex{imaplib}
 | 
				
			||||||
 | 
					\label{module-imaplib}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					This module defines a class, \class{IMAP4}, which encapsulates a
 | 
				
			||||||
 | 
					connection to an IMAP4 server and implements 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.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					A single class is provided by the \code{imaplib} module:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\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}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Two 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}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					The following utility functions are defined:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{funcdesc}{Internaldate2tuple}{datestr}
 | 
				
			||||||
 | 
					  Converts an IMAP4 INTERNALDATE string to Coordinated Universal
 | 
				
			||||||
 | 
					  Time. Returns a \module{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 \module{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}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\subsection{IMAP4 Objects}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					All IMAP4rev1 commands are represented by methods of the same name,
 | 
				
			||||||
 | 
					either upper-case or lower-case.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Each command returns a tuple: \code{(}\var{type}, \code{[}\var{data},
 | 
				
			||||||
 | 
					...\code{])} 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.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					An \class{IMAP4} instance has the following methods:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{append}{mailbox, flags, date_time, message}
 | 
				
			||||||
 | 
					  Append message to named mailbox. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{authenticate}{func}
 | 
				
			||||||
 | 
					  Authenticate command --- requires response processing. This is
 | 
				
			||||||
 | 
					  currently unimplemented, and raises an exception. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{check}{}
 | 
				
			||||||
 | 
					  Checkpoint mailbox on server. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{close}{}
 | 
				
			||||||
 | 
					  Close currently selected mailbox. Deleted messages are removed from
 | 
				
			||||||
 | 
					  writable mailbox. This is the recommended command before
 | 
				
			||||||
 | 
					  \samp{LOGOUT}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{copy}{message_set, new_mailbox}
 | 
				
			||||||
 | 
					  Copy \var{message_set} messages onto end of \var{new_mailbox}. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{create}{mailbox}
 | 
				
			||||||
 | 
					  Create new mailbox named \var{mailbox}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{delete}{mailbox}
 | 
				
			||||||
 | 
					  Delete old mailbox named \var{mailbox}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{fetch}{message_set, message_parts}
 | 
				
			||||||
 | 
					  Fetch (parts of) messages. Returned data are tuples of message part
 | 
				
			||||||
 | 
					  envelope and data.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{list}{directory='""', pattern='*'}
 | 
				
			||||||
 | 
					  List mailbox names in directory matching pattern. Returned data contains a
 | 
				
			||||||
 | 
					  list of \samp{LIST} responses.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{login}{user, password}
 | 
				
			||||||
 | 
					  Identify the client using a plaintext password.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{logout}{}
 | 
				
			||||||
 | 
					  Shutdown connection to server. Returns server \samp{BYE} response.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{lsub}{directory='""', pattern='*'}
 | 
				
			||||||
 | 
					  List subscribed mailbox names in directory matching
 | 
				
			||||||
 | 
					  pattern. Returned data are tuples of message part envelope and data.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{rename}{oldmailbox, newmailbox}
 | 
				
			||||||
 | 
					  Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{search}{charset, criteria}
 | 
				
			||||||
 | 
					  Search mailbox for matching messages. Returned data contains a space
 | 
				
			||||||
 | 
					  separated list of matching message numbers.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{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}{status}{mailbox, names}
 | 
				
			||||||
 | 
					  Request named status conditions for \var{mailbox}. 
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{store}{message_set, command, flag_list}
 | 
				
			||||||
 | 
					  Alters flag dispositions for messages in mailbox.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{subscribe}{mailbox}
 | 
				
			||||||
 | 
					  Subscribe to new mailbox.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{uid}{command, args}
 | 
				
			||||||
 | 
					  Execute command args with messages identified by UID, rather than
 | 
				
			||||||
 | 
					  message number. Returns response appropriate to command.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{unsubscribe}{mailbox}
 | 
				
			||||||
 | 
					  Unsubscribe from old mailbox.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\begin{methoddesc}{xatom}{name\optional{, arg1\optional{, arg2}}}
 | 
				
			||||||
 | 
					  Allow simple extension commands notified by server in
 | 
				
			||||||
 | 
					  \samp{CAPABILITY} response.
 | 
				
			||||||
 | 
					\end{methoddesc}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\class{IMAP4} instances have a variable \member{PROTOCOL_VERSION} that
 | 
				
			||||||
 | 
					is set to the most recent supported protocol in the \samp{CAPABILITY}
 | 
				
			||||||
 | 
					response.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Finally, \class{IMAP4} instances have a variable debug which can be
 | 
				
			||||||
 | 
					set to an integer to turn on debugging.  Values greater than 3 trace
 | 
				
			||||||
 | 
					each command.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					\subsection{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, string
 | 
				
			||||||
 | 
					M = imaplib.IMAP4()
 | 
				
			||||||
 | 
					M.LOGIN(getpass.getuser(), getpass.getpass())
 | 
				
			||||||
 | 
					M.SELECT()
 | 
				
			||||||
 | 
					typ, data = M.SEARCH(None, 'ALL')
 | 
				
			||||||
 | 
					for num in string.split(data[0]):
 | 
				
			||||||
 | 
					    typ, data - M.FETCH(num, '(RFC822)')
 | 
				
			||||||
 | 
					    print 'Message %s\n%s\n' % (num, data[0][1])
 | 
				
			||||||
 | 
					M.LOGOUT()
 | 
				
			||||||
 | 
					\end{verbatim}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Note that IMAP4 message numbers change as the mailbox changes, 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}
 | 
				
			||||||
		Loading…
	
	Add table
		Add a link
		
	
		Reference in a new issue