[Python-checkins] CVS: python/dist/src/Doc/lib libimaplib.tex,1.14,1.15

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory slayer.i.sourceforge.net:/tmp/cvs-serv5336/Doc/lib

Modified Files:
	libimaplib.tex 
Log Message:

Piers Lauder <piers@cs.su.oz.au>:
I've added an extra comment about quoting arguments to
IMAP4 commands. Also changed the command descriptions
to show optional extra commands where appropriate.

Fred Drake:
Added example usage for the search() method based on comments from
<Lucas.DeJonge@awtpl.com.au>; elaborated error handling information
when arguments are missing from search() and uid().


Index: libimaplib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libimaplib.tex,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -r1.14 -r1.15
*** libimaplib.tex	2000/04/03 20:13:53	1.14
--- libimaplib.tex	2000/05/26 04:08:37	1.15
***************
*** 97,100 ****
--- 97,103 ----
  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},
***************
*** 145,150 ****
  
  \begin{methoddesc}{fetch}{message_set, message_parts}
!   Fetch (parts of) messages. Returned data are tuples of message part
!   envelope and data.
  \end{methoddesc}
  
--- 148,155 ----
  
  \begin{methoddesc}{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}
  
***************
*** 200,206 ****
  \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}
  
--- 205,225 ----
  \end{methoddesc}
  
! \begin{methoddesc}{search}{charset, criterium\optional{, ...}}
!   Search mailbox for matching messages.  Returned data contains a space
!   separated list of matching message numbers.  \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
!   criterium be specified; an exception will be raised when the server
!   returns an error.
! 
!   Example:
! 
! \begin{verbatim}
! # M is a connected IMAP4 instance...
! msgnums = M.search(None, 'FROM', '"LDJ"')
! 
! # or:
! msgnums = M.search(None, '(FROM "LDJ")')
! \end{verbatim}
  \end{methoddesc}
  
***************
*** 228,234 ****
  \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}
  
--- 247,255 ----
  \end{methoddesc}
  
! \begin{methoddesc}{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}
  
***************
*** 237,241 ****
  \end{methoddesc}
  
! \begin{methoddesc}{xatom}{name\optional{, arg1\optional{, arg2}}}
    Allow simple extension commands notified by server in
    \samp{CAPABILITY} response.
--- 258,262 ----
  \end{methoddesc}
  
! \begin{methoddesc}{xatom}{name\optional{, arg\optional{, ...}}}
    Allow simple extension commands notified by server in
    \samp{CAPABILITY} response.