From a468404ddae90f66476284269ad87a293145a34f Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Fri, 24 Apr 1998 20:49:02 +0000 Subject: Added a section for the poplib module, contributed by Drew Csillag. --- Doc/lib.tex | 1 + Doc/lib/lib.tex | 1 + Doc/lib/libpoplib.tex | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++ Doc/libpoplib.tex | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 264 insertions(+) create mode 100644 Doc/lib/libpoplib.tex create mode 100644 Doc/libpoplib.tex diff --git a/Doc/lib.tex b/Doc/lib.tex index 13ba617..037d600 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -155,6 +155,7 @@ add new extensions to Python and how to embed it in other applications. \input{libhttplib} \input{libftplib} \input{libgopherlib} +\input{libpoplib} \input{libimaplib} \input{libnntplib} \input{liburlparse} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 13ba617..037d600 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -155,6 +155,7 @@ add new extensions to Python and how to embed it in other applications. \input{libhttplib} \input{libftplib} \input{libgopherlib} +\input{libpoplib} \input{libimaplib} \input{libnntplib} \input{liburlparse} diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex new file mode 100644 index 0000000..12882e9 --- /dev/null +++ b/Doc/lib/libpoplib.tex @@ -0,0 +1,131 @@ +%By Andrew T. Csillag +%Even though I put it into LaTeX, I cannot really claim that I wrote +%it since I just stole most of it from the poplib.py source code and +%the imaplib ``chapter''. + +\section{Standard Module \module{poplib}} +\stmodindex{poplib} +\label{module-poplib} +\indexii{POP3}{protocol} + +This module defines a class, \class{POP3}, which encapsulates a +connection to an POP3 server and implements protocol as defined in +\rfc{1725}. The \class{POP3} class supports both the minmal and +optional command sets. + +A single class is provided by the \module{poplib} module: + +\begin{classdesc}{POP3}{host\optional{, port}} +This class implements the actual POP3 protocol. The connection is +created when the instance is initialized. +If \var{port} is omitted, the standard POP3 port (110) is used. +\end{classdesc} + +One exception is defined as attributes of the \module{poplib} module: + +\begin{excdesc}{error_proto} +Exception raised on any errors. The reason for the exception is +passed to the constructor as a string. +\end{excdesc} + + +\subsection{POP3 Objects} +\label{pop3-objects} + +All POP3 commands are represented by methods of the same name, +in lower-case. + +Most commands return the response text sent by the server. + +An \class{POP3} instance has the following methods: + + +\begin{methoddesc}{getwelcome}{} +Returns the greeting string sent by the POP3 server. +\end{methoddesc} + + +\begin{methoddesc}{user}{username} +Send user commad, response should indicate that a password is required. +\end{methoddesc} + +\begin{methoddesc}{pass_}{password} +Send password, response includes message count and mailbox size. +Note: the mailbox on the server is locked until \method{quit()} is +called. +\end{methoddesc} + +\begin{methoddesc}{apop}{user, secret} +Use the more secure APOP authentication to log into the POP3 server. +\end{methoddesc} + +\begin{methoddesc}{rpop}{user} +Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server. +\end{methoddesc} + +\begin{methoddesc}{stat}{} +Get mailbox status. The result is a tuple of 2 integers: +\code{(\var{message count}, \var{mailbox size})}. +\end{methoddesc} + +\begin{methoddesc}{list}{\optional{which}} +Request message list, result is in the form +\code{['response', ['mesg_num octets', ...]]}. If \var{which} is +set, it is the message to list. +\end{methoddesc} + +\begin{methoddesc}{retr}{which} +Retrieve whole message number \var{which}. Result is in form +\code{['response', ['line', ...], octets]}. +\end{methoddesc} + +\begin{methoddesc}{dele}{which} +Delete message number \var{which}. +\end{methoddesc} + +\begin{methoddesc}{rset}{} +Remove any deletion marks for the mailbox. +\end{methoddesc} + +\begin{methoddesc}{noop}{} +Do nothing. Might be used as a keep-alive. +\end{methoddesc} + +\begin{methoddesc}{quit}{} +Signoff: commit changes, unlock mailbox, drop connection. +\end{methoddesc} + +\begin{methoddesc}{top}{which, howmuch} +Retrieves the message header plus \var{howmuch} lines of the message +after the header of message number \var{which}. Result is in form +\code{['response', ['line', ...], octets]}. +\end{methoddesc} + +\begin{methoddesc}{uidl}{\optional{which}} +Return message digest (unique id) list. +If \var{which} is specified, result contains unique id for that +message, otherwise result is list \code{['response', +['mesgnum uid', ...], octets]}. +\end{methoddesc} + + +\subsection{POP3 Example} +\label{pop3-example} + +Here is a minimal example (without error checking) that opens a +mailbox and retrieves and prints all messages: + +\begin{verbatim} +import getpass, poplib, string + +M = poplib.POP3('localhost') +M.user(getpass.getuser()) +M.pass(getpass.getpass()) +numMessages = len(M.list()[1]) +for i in range(numMessages): + for j in M.retr(i+1)[1]: + sys.stdout.write(j) +\end{verbatim} + +At the end of the module, there is a test section that contains a more +extensive example of usage. diff --git a/Doc/libpoplib.tex b/Doc/libpoplib.tex new file mode 100644 index 0000000..12882e9 --- /dev/null +++ b/Doc/libpoplib.tex @@ -0,0 +1,131 @@ +%By Andrew T. Csillag +%Even though I put it into LaTeX, I cannot really claim that I wrote +%it since I just stole most of it from the poplib.py source code and +%the imaplib ``chapter''. + +\section{Standard Module \module{poplib}} +\stmodindex{poplib} +\label{module-poplib} +\indexii{POP3}{protocol} + +This module defines a class, \class{POP3}, which encapsulates a +connection to an POP3 server and implements protocol as defined in +\rfc{1725}. The \class{POP3} class supports both the minmal and +optional command sets. + +A single class is provided by the \module{poplib} module: + +\begin{classdesc}{POP3}{host\optional{, port}} +This class implements the actual POP3 protocol. The connection is +created when the instance is initialized. +If \var{port} is omitted, the standard POP3 port (110) is used. +\end{classdesc} + +One exception is defined as attributes of the \module{poplib} module: + +\begin{excdesc}{error_proto} +Exception raised on any errors. The reason for the exception is +passed to the constructor as a string. +\end{excdesc} + + +\subsection{POP3 Objects} +\label{pop3-objects} + +All POP3 commands are represented by methods of the same name, +in lower-case. + +Most commands return the response text sent by the server. + +An \class{POP3} instance has the following methods: + + +\begin{methoddesc}{getwelcome}{} +Returns the greeting string sent by the POP3 server. +\end{methoddesc} + + +\begin{methoddesc}{user}{username} +Send user commad, response should indicate that a password is required. +\end{methoddesc} + +\begin{methoddesc}{pass_}{password} +Send password, response includes message count and mailbox size. +Note: the mailbox on the server is locked until \method{quit()} is +called. +\end{methoddesc} + +\begin{methoddesc}{apop}{user, secret} +Use the more secure APOP authentication to log into the POP3 server. +\end{methoddesc} + +\begin{methoddesc}{rpop}{user} +Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server. +\end{methoddesc} + +\begin{methoddesc}{stat}{} +Get mailbox status. The result is a tuple of 2 integers: +\code{(\var{message count}, \var{mailbox size})}. +\end{methoddesc} + +\begin{methoddesc}{list}{\optional{which}} +Request message list, result is in the form +\code{['response', ['mesg_num octets', ...]]}. If \var{which} is +set, it is the message to list. +\end{methoddesc} + +\begin{methoddesc}{retr}{which} +Retrieve whole message number \var{which}. Result is in form +\code{['response', ['line', ...], octets]}. +\end{methoddesc} + +\begin{methoddesc}{dele}{which} +Delete message number \var{which}. +\end{methoddesc} + +\begin{methoddesc}{rset}{} +Remove any deletion marks for the mailbox. +\end{methoddesc} + +\begin{methoddesc}{noop}{} +Do nothing. Might be used as a keep-alive. +\end{methoddesc} + +\begin{methoddesc}{quit}{} +Signoff: commit changes, unlock mailbox, drop connection. +\end{methoddesc} + +\begin{methoddesc}{top}{which, howmuch} +Retrieves the message header plus \var{howmuch} lines of the message +after the header of message number \var{which}. Result is in form +\code{['response', ['line', ...], octets]}. +\end{methoddesc} + +\begin{methoddesc}{uidl}{\optional{which}} +Return message digest (unique id) list. +If \var{which} is specified, result contains unique id for that +message, otherwise result is list \code{['response', +['mesgnum uid', ...], octets]}. +\end{methoddesc} + + +\subsection{POP3 Example} +\label{pop3-example} + +Here is a minimal example (without error checking) that opens a +mailbox and retrieves and prints all messages: + +\begin{verbatim} +import getpass, poplib, string + +M = poplib.POP3('localhost') +M.user(getpass.getuser()) +M.pass(getpass.getpass()) +numMessages = len(M.list()[1]) +for i in range(numMessages): + for j in M.retr(i+1)[1]: + sys.stdout.write(j) +\end{verbatim} + +At the end of the module, there is a test section that contains a more +extensive example of usage. -- cgit v0.12