[Python-checkins] CVS: python/dist/src/Doc/lib email.tex,1.2,1.3 emailencoders.tex,1.1,1.2 emailexc.tex,1.1,1.2 emailgenerator.tex,1.1,1.2 emailiter.tex,1.1,1.2 emailmessage.tex,1.1,1.2 emailparser.tex,1.1,1.2 emailutil.tex,1.1,1.2
Barry Warsaw
bwarsaw@users.sourceforge.net
Wed, 26 Sep 2001 15:21:55 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv23832/Doc/lib
Modified Files:
email.tex emailencoders.tex emailexc.tex emailgenerator.tex
emailiter.tex emailmessage.tex emailparser.tex emailutil.tex
Log Message:
Updates do email package documentation for markup, style, and
organization.
Index: email.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/email.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** email.tex 2001/09/26 16:52:18 1.2
--- email.tex 2001/09/26 22:21:52 1.3
***************
*** 15,20 ****
including MIME and other \rfc{2822}-based message documents. It
subsumes most of the functionality in several older standard modules
! such as \module{rfc822}, \module{mimetools}, \module{multifile}, and
! other non-standard packages such as \module{mimecntl}.
The primary distinguishing feature of the \module{email} package is
--- 15,21 ----
including MIME and other \rfc{2822}-based message documents. It
subsumes most of the functionality in several older standard modules
! such as \refmodule{rfc822}, \refmodule{mimetools},
! \refmodule{multifile}, and other non-standard packages such as
! \module{mimecntl}.
The primary distinguishing feature of the \module{email} package is
***************
*** 39,44 ****
It is perfectly feasible to create the object model out of whole cloth
! -- i.e. completely from scratch. From there, a similar progression can
! be taken as above.
Also included are detailed specifications of all the classes and
--- 40,45 ----
It is perfectly feasible to create the object model out of whole cloth
! --- i.e. completely from scratch. From there, a similar progression
! can be taken as above.
Also included are detailed specifications of all the classes and
***************
*** 50,123 ****
\subsection{Representing an email message}
!
! The primary object in the \module{email} package is the
! \class{Message} class, provided in the \refmodule{email.Message}
! module. \class{Message} is the base class for the \module{email}
! object model. It provides the core functionality for setting and
! querying header fields, and for accessing message bodies.
!
! Conceptually, a \class{Message} object consists of \emph{headers} and
! \emph{payloads}. Headers are \rfc{2822} style field name and
! values where the field name and value are separated by a colon. The
! colon is not part of either the field name or the field value.
!
! Headers are stored and returned in case-preserving form but are
! matched case-insensitively. There may also be a single
! \emph{Unix-From} header, also known as the envelope header or the
! \mailheader{From_} header. The payload is either a string in the case of
! simple message objects, a list of \class{Message} objects for
! multipart MIME documents, or a single \class{Message} instance for
! \mimetype{message/rfc822} type objects.
!
! \class{Message} objects provide a mapping style interface for
! accessing the message headers, and an explicit interface for accessing
! both the headers and the payload. It provides convenience methods for
! generating a flat text representation of the message object tree, for
! accessing commonly used header parameters, and for recursively walking
! over the object tree.
\subsection{Parsing email messages}
! Message object trees can be created in one of two ways: they can be
! created from whole cloth by instantiating \class{Message} objects and
! stringing them together via \method{add_payload()} and
! \method{set_payload()} calls, or they can be created by parsing a flat text
! representation of the email message.
!
! The \module{email} package provides a standard parser that understands
! most email document structures, including MIME documents. You can
! pass the parser a string or a file object, and the parser will return
! to you the root \class{Message} instance of the object tree. For
! simple, non-MIME messages the payload of this root object will likely
! be a string (e.g. containing the text of the message). For MIME
! messages, the root object will return 1 from its
! \method{is_multipart()} method, and the subparts can be accessed via
! the \method{get_payload()} and \method{walk()} methods.
!
! Note that the parser can be extended in limited ways, and of course
! you can implement your own parser completely from scratch. There is
! no magical connection between the \module{email} package's bundled
! parser and the
! \class{Message} class, so your custom parser can create message object
! trees in any way it find necessary. The \module{email} package's
! parser is described in detail in the \refmodule{email.Parser} module
! documentation.
\subsection{Generating MIME documents}
! One of the most common tasks is to generate the flat text of the email
! message represented by a message object tree. You will need to do
! this if you want to send your message via the \refmodule{smtplib}
! module or the \refmodule{nntplib} module, or print the message on the
! console. Taking a message object tree and producing a flat text
! document is the job of the \refmodule{email.Generator} module.
!
! Again, as with the \refmodule{email.Parser} module, you aren't limited
! to the functionality of the bundled generator; you could write one
! from scratch yourself. However the bundled generator knows how to
! generate most email in a standards-compliant way, should handle MIME
! and non-MIME email messages just fine, and is designed so that the
! transformation from flat text, to an object tree via the
! \class{Parser} class,
! and back to flat text, be idempotent (the input is identical to the
! output).
\subsection{Creating email and MIME objects from scratch}
--- 51,61 ----
\subsection{Representing an email message}
! \input{emailmessage}
\subsection{Parsing email messages}
! \input{emailparser}
\subsection{Generating MIME documents}
! \input{emailgenerator}
\subsection{Creating email and MIME objects from scratch}
***************
*** 157,163 ****
subclasses.
! \var{_maintype} is the \code{Content-Type:} major type (e.g. \code{text} or
! \code{image}), and \var{_subtype} is the \code{Content-Type:} minor type
! (e.g. \code{plain} or \code{gif}). \var{_params} is a parameter
key/value dictionary and is passed directly to
\method{Message.add_header()}.
--- 95,102 ----
subclasses.
! \var{_maintype} is the \mailheader{Content-Type} major type
! (e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the
! \mailheader{Content-Type} minor type
! (e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameter
key/value dictionary and is passed directly to
\method{Message.add_header()}.
***************
*** 196,203 ****
\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
_charset\optional{, _encoder}}}}
A subclass of \class{MIMEBase}, the \class{MIMEText} class is used to
! create MIME objects of major type \mimetype{text}. \var{_text} is the string
! for the payload. \var{_subtype} is the minor type and defaults to
! \mimetype{plain}. \var{_charset} is the character set of the text and is
passed as a parameter to the \class{MIMEBase} constructor; it defaults
to \code{us-ascii}. No guessing or encoding is performed on the text
--- 135,143 ----
\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
_charset\optional{, _encoder}}}}
+
A subclass of \class{MIMEBase}, the \class{MIMEText} class is used to
! create MIME objects of major type \mimetype{text}. \var{_text} is the
! string for the payload. \var{_subtype} is the minor type and defaults
! to \mimetype{plain}. \var{_charset} is the character set of the text and is
passed as a parameter to the \class{MIMEBase} constructor; it defaults
to \code{us-ascii}. No guessing or encoding is performed on the text
***************
*** 221,246 ****
to \mimetype{rfc822}.
\end{classdesc}
-
- \subsection{Encoders, Exceptions, Utilities, and Iterators}
! The \module{email} package provides various encoders for safe
! transport of binary payloads in \class{MIMEImage} and \class{MIMEText}
! instances. See the \refmodule{email.Encoders} module for more
! details.
! All of the class exceptions that the \module{email} package can raise
! are available in the \refmodule{email.Errors} module.
! Some miscellaneous utility functions are available in the
! \refmodule{email.Utils} module.
! Iterating over a message object tree is easy with the
! \method{Message.walk()} method; some additional helper iterators are
! available in the \refmodule{email.Iterators} module.
\subsection{Differences from \module{mimelib}}
The \module{email} package was originally prototyped as a separate
! library called \module{mimelib}. Changes have been made so that
method names are more consistent, and some methods or modules have
either been added or removed. The semantics of some of the methods
--- 161,183 ----
to \mimetype{rfc822}.
\end{classdesc}
! \subsection{Encoders}
! \input{emailencoders}
! \subsection{Exception classes}
! \input{emailexc}
! \subsection{Miscellaneous utilities}
! \input{emailutil}
! \subsection{Iterators}
! \input{emailiter}
\subsection{Differences from \module{mimelib}}
The \module{email} package was originally prototyped as a separate
! library called
! \ulink{\module{mimelib}}{http://mimelib.sf.net/}.
! Changes have been made so that
method names are more consistent, and some methods or modules have
either been added or removed. The semantics of some of the methods
***************
*** 283,287 ****
Also, whereas \method{getparams()} returned a list of strings,
\method{get_params()} returns a list of 2-tuples, effectively
! the key/value pairs of the parameters, split on the \samp{=}
sign.
\item The method \method{getparam()} was renamed to \method{get_param()}.
--- 220,224 ----
Also, whereas \method{getparams()} returned a list of strings,
\method{get_params()} returns a list of 2-tuples, effectively
! the key/value pairs of the parameters, split on the \character{=}
sign.
\item The method \method{getparam()} was renamed to \method{get_param()}.
***************
*** 356,358 ****
Coming soon...
-
--- 293,294 ----
Index: emailencoders.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/emailencoders.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** emailencoders.tex 2001/09/26 05:23:47 1.1
--- emailencoders.tex 2001/09/26 22:21:52 1.2
***************
*** 1,15 ****
- \section{\module{email.Encoders} ---
- Email message payload encoders}
-
\declaremodule{standard}{email.Encoders}
\modulesynopsis{Encoders for email message payloads.}
- \sectionauthor{Barry A. Warsaw}{barry@zope.com}
- \versionadded{2.2}
-
When creating \class{Message} objects from scratch, you often need to
encode the payloads for transport through compliant mail servers.
! This is especially true for \code{image/*} and \code{text/*} type
! messages containing binary data.
The \module{email} package provides some convenient encodings in its
--- 1,9 ----
\declaremodule{standard}{email.Encoders}
\modulesynopsis{Encoders for email message payloads.}
When creating \class{Message} objects from scratch, you often need to
encode the payloads for transport through compliant mail servers.
! This is especially true for \mimetype{image/*} and \mimetype{text/*}
! type messages containing binary data.
The \module{email} package provides some convenient encodings in its
***************
*** 19,23 ****
message object to encode. They usually extract the payload, encode
it, and reset the payload to this newly encoded value. They should also
! set the \code{Content-Transfer-Encoding:} header as appropriate.
Here are the encoding functions provided:
--- 13,17 ----
message object to encode. They usually extract the payload, encode
it, and reset the payload to this newly encoded value. They should also
! set the \mailheader{Content-Transfer-Encoding} header as appropriate.
Here are the encoding functions provided:
***************
*** 35,39 ****
\begin{funcdesc}{encode_base64}{msg}
Encodes the payload into \emph{Base64} form and sets the
! \code{Content-Transfer-Encoding:} header to
\code{base64}. This is a good encoding to use when most of your payload
is unprintable data since it is a more compact form than
--- 29,33 ----
\begin{funcdesc}{encode_base64}{msg}
Encodes the payload into \emph{Base64} form and sets the
! \mailheader{Content-Transfer-Encoding} header to
\code{base64}. This is a good encoding to use when most of your payload
is unprintable data since it is a more compact form than
***************
*** 44,48 ****
\begin{funcdesc}{encode_7or8bit}{msg}
This doesn't actually modify the message's payload, but it does set
! the \code{Content-Transfer-Encoding:} header to either \code{7bit} or
\code{8bit} as appropriate, based on the payload data.
\end{funcdesc}
--- 38,42 ----
\begin{funcdesc}{encode_7or8bit}{msg}
This doesn't actually modify the message's payload, but it does set
! the \mailheader{Content-Transfer-Encoding} header to either \code{7bit} or
\code{8bit} as appropriate, based on the payload data.
\end{funcdesc}
***************
*** 50,53 ****
\begin{funcdesc}{encode_noop}{msg}
This does nothing; it doesn't even set the
! \code{Content-Transfer-Encoding:} header.
\end{funcdesc}
--- 44,47 ----
\begin{funcdesc}{encode_noop}{msg}
This does nothing; it doesn't even set the
! \mailheader{Content-Transfer-Encoding} header.
\end{funcdesc}
Index: emailexc.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/emailexc.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** emailexc.tex 2001/09/26 05:23:47 1.1
--- emailexc.tex 2001/09/26 22:21:52 1.2
***************
*** 1,10 ****
! \section{\module{email.Errors} ---
! email package exception classes}
!
! \declaremodule{standard}{email.Exceptions}
\modulesynopsis{The exception classes used by the email package.}
- \sectionauthor{Barry A. Warsaw}{barry@zope.com}
-
- \versionadded{2.2}
The following exception classes are defined in the
--- 1,4 ----
! \declaremodule{standard}{email.Errors}
\modulesynopsis{The exception classes used by the email package.}
The following exception classes are defined in the
***************
*** 42,46 ****
Situations where it can be raised include not being able to find the
! starting or terminating boundary in a \code{multipart/*} message.
\end{excclassdesc}
--- 36,40 ----
Situations where it can be raised include not being able to find the
! starting or terminating boundary in a \mimetype{multipart/*} message.
\end{excclassdesc}
***************
*** 48,53 ****
Raised when a payload is added to a \class{Message} object using
\method{add_payload()}, but the payload is already a scalar and the
! message's \code{Content-Type:} main type is not either \code{multipart}
! or missing. \exception{MultipartConversionError} multiply inherits
! from \exception{MessageError} and the built-in \exception{TypeError}.
\end{excclassdesc}
--- 42,48 ----
Raised when a payload is added to a \class{Message} object using
\method{add_payload()}, but the payload is already a scalar and the
! message's \mailheader{Content-Type} main type is not either
! \mimetype{multipart} or missing. \exception{MultipartConversionError}
! multiply inherits from \exception{MessageError} and the built-in
! \exception{TypeError}.
\end{excclassdesc}
Index: emailgenerator.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/emailgenerator.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** emailgenerator.tex 2001/09/26 05:23:47 1.1
--- emailgenerator.tex 2001/09/26 22:21:52 1.2
***************
*** 1,16 ****
- \section{\module{email.Generator} ---
- Generating flat text from an email message object tree}
-
\declaremodule{standard}{email.Generator}
! \modulesynopsis{Generate flat text email messages to from a message
! object tree.}
! \sectionauthor{Barry A. Warsaw}{barry@zope.com}
! \versionadded{2.2}
! The \class{Generator} class is used to render a message object model
! into its flat text representation, including MIME encoding any
! sub-messages, generating the correct \rfc{2822} headers, etc. Here
! are the public methods of the \class{Generator} class.
\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
--- 1,23 ----
\declaremodule{standard}{email.Generator}
! \modulesynopsis{Generate flat text email messages from a message object tree.}
! One of the most common tasks is to generate the flat text of the email
! message represented by a message object tree. You will need to do
! this if you want to send your message via the \refmodule{smtplib}
! module or the \refmodule{nntplib} module, or print the message on the
! console. Taking a message object tree and producing a flat text
! document is the job of the \class{Generator} class.
! Again, as with the \refmodule{email.Parser} module, you aren't limited
! to the functionality of the bundled generator; you could write one
! from scratch yourself. However the bundled generator knows how to
! generate most email in a standards-compliant way, should handle MIME
! and non-MIME email messages just fine, and is designed so that the
! transformation from flat text, to an object tree via the
! \class{Parser} class,
! and back to flat text, be idempotent (the input is identical to the
! output).
!
! Here are the public methods of the \class{Generator} class:
\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
***************
*** 26,31 ****
line). This is the only guaranteed portable way to avoid having such
lines be mistaken for \emph{Unix-From} headers (see
! \url{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
! for details).
Optional \var{maxheaderlen} specifies the longest length for a
--- 33,39 ----
line). This is the only guaranteed portable way to avoid having such
lines be mistaken for \emph{Unix-From} headers (see
! \ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
! {http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
! for details).
Optional \var{maxheaderlen} specifies the longest length for a
Index: emailiter.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/emailiter.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** emailiter.tex 2001/09/26 05:23:47 1.1
--- emailiter.tex 2001/09/26 22:21:52 1.2
***************
*** 1,10 ****
- \section{\module{email.Iterators} ---
- Message object tree iterators}
-
\declaremodule{standard}{email.Iterators}
\modulesynopsis{Iterate over a message object tree.}
- \sectionauthor{Barry A. Warsaw}{barry@zope.com}
-
- \versionadded{2.2}
Iterating over a message object tree is fairly easy with the
--- 1,4 ----
***************
*** 30,37 ****
Note that \var{subtype} is optional; if omitted, then subpart MIME
type matching is done only with the main type. \var{maintype} is
! optional too; it defaults to \code{text}.
Thus, by default \function{typed_subpart_iterator()} returns each
! subpart that has a MIME type of \code{text/*}.
\end{funcdesc}
--- 24,31 ----
Note that \var{subtype} is optional; if omitted, then subpart MIME
type matching is done only with the main type. \var{maintype} is
! optional too; it defaults to \mimetype{text}.
Thus, by default \function{typed_subpart_iterator()} returns each
! subpart that has a MIME type of \mimetype{text/*}.
\end{funcdesc}
Index: emailmessage.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/emailmessage.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** emailmessage.tex 2001/09/26 05:23:47 1.1
--- emailmessage.tex 2001/09/26 22:21:52 1.2
***************
*** 1,29 ****
- \section{\module{email.Message} ---
- The Message class}
-
\declaremodule{standard}{email.Message}
\modulesynopsis{The base class representing email messages.}
- \sectionauthor{Barry A. Warsaw}{barry@zope.com}
! \versionadded{2.2}
! The \module{Message} module provides a single class, the
! \class{Message} class. This class is the base class for the
! \module{email} package object model. It has a fairly extensive set of
! methods to get and set email headers and email payloads. For an
! introduction of the \module{email} package, please read the
! \refmodule{email} package overview.
! \class{Message} instances can be created either directly, or
! indirectly by using a \refmodule{email.Parser}. \class{Message}
! objects provide a mapping style interface for accessing the message
! headers, and an explicit interface for accessing both the headers and
! the payload. It provides convenience methods for generating a flat
! text representation of the message object tree, for accessing commonly
! used header parameters, and for recursively walking over the object
! tree.
Here are the methods of the \class{Message} class:
\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
Return the entire formatted message as a string. Optional
--- 1,36 ----
\declaremodule{standard}{email.Message}
\modulesynopsis{The base class representing email messages.}
! The central class in the \module{email} package is the
! \class{Message} class; it is the base class for the \module{email}
! object model. \class{Message} provides the core functionality for
! setting and querying header fields, and for accessing message bodies.
! Conceptually, a \class{Message} object consists of \emph{headers} and
! \emph{payloads}. Headers are \rfc{2822} style field names and
! values where the field name and value are separated by a colon. The
! colon is not part of either the field name or the field value.
! Headers are stored and returned in case-preserving form but are
! matched case-insensitively. There may also be a single
! \emph{Unix-From} header, also known as the envelope header or the
! \code{From_} header. The payload is either a string in the case of
! simple message objects, a list of \class{Message} objects for
! multipart MIME documents, or a single \class{Message} instance for
! \mimetype{message/rfc822} type objects.
!
! \class{Message} objects provide a mapping style interface for
! accessing the message headers, and an explicit interface for accessing
! both the headers and the payload. It provides convenience methods for
! generating a flat text representation of the message object tree, for
! accessing commonly used header parameters, and for recursively walking
! over the object tree.
Here are the methods of the \class{Message} class:
+ \begin{classdesc}{Message}{}
+ The constructor takes no arguments.
+ \end{classdesc}
+
\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
Return the entire formatted message as a string. Optional
***************
*** 67,72 ****
and \var{payload}, but only if the document is already a MIME
multipart document. This condition is satisfied if the message's
! \code{Content-Type:} header's main type is either \var{multipart}, or
! there is no \code{Content-Type:} header. In any other situation,
\exception{MultipartConversionError} is raised.
\end{methoddesc}
--- 74,80 ----
and \var{payload}, but only if the document is already a MIME
multipart document. This condition is satisfied if the message's
! \mailheader{Content-Type} header's main type is either
! \mimetype{multipart}, or there is no \mailheader{Content-Type}
! header. In any other situation,
\exception{MultipartConversionError} is raised.
\end{methoddesc}
***************
*** 84,99 ****
With optional \var{i}, \method{get_payload()} will return the
\var{i}-th element of the payload, counting from zero, if
! \method{is_multipart()} returns 1. An \code{IndexError} will be raised
if \var{i} is less than 0 or greater than or equal to the number of
items in the payload. If the payload is scalar
(i.e. \method{is_multipart()} returns 0) and \var{i} is given, a
! \code{TypeError} is raised.
Optional \var{decode} is a flag indicating whether the payload should be
! decoded or not, according to the \code{Content-Transfer-Encoding:} header.
When true and the message is not a multipart, the payload will be
decoded if this header's value is \samp{quoted-printable} or
\samp{base64}. If some other encoding is used, or
! \code{Content-Transfer-Encoding:} header is
missing, the payload is returned as-is (undecoded). If the message is
a multipart and the \var{decode} flag is true, then \code{None} is
--- 92,107 ----
With optional \var{i}, \method{get_payload()} will return the
\var{i}-th element of the payload, counting from zero, if
! \method{is_multipart()} returns 1. An \exception{IndexError} will be raised
if \var{i} is less than 0 or greater than or equal to the number of
items in the payload. If the payload is scalar
(i.e. \method{is_multipart()} returns 0) and \var{i} is given, a
! \exception{TypeError} is raised.
Optional \var{decode} is a flag indicating whether the payload should be
! decoded or not, according to the \mailheader{Content-Transfer-Encoding} header.
When true and the message is not a multipart, the payload will be
decoded if this header's value is \samp{quoted-printable} or
\samp{base64}. If some other encoding is used, or
! \mailheader{Content-Transfer-Encoding} header is
missing, the payload is returned as-is (undecoded). If the message is
a multipart and the \var{decode} flag is true, then \code{None} is
***************
*** 138,142 ****
Return the value of the named header field. \var{name} should not
include the colon field separator. If the header is missing,
! \code{None} is returned; a \code{KeyError} is never raised.
Note that if the named field appears more than once in the message's
--- 146,150 ----
Return the value of the named header field. \var{name} should not
include the colon field separator. If the header is missing,
! \code{None} is returned; a \exception{KeyError} is never raised.
Note that if the named field appears more than once in the message's
***************
*** 244,251 ****
\begin{methoddesc}[Message]{get_type}{\optional{failobj}}
Return the message's content type, as a string of the form
! ``maintype/subtype'' as taken from the \code{Content-Type:} header.
The returned string is coerced to lowercase.
! If there is no \code{Content-Type:} header in the message,
\var{failobj} is returned (defaults to \code{None}).
\end{methoddesc}
--- 252,260 ----
\begin{methoddesc}[Message]{get_type}{\optional{failobj}}
Return the message's content type, as a string of the form
! \mimetype{maintype/subtype} as taken from the
! \mailheader{Content-Type} header.
The returned string is coerced to lowercase.
! If there is no \mailheader{Content-Type} header in the message,
\var{failobj} is returned (defaults to \code{None}).
\end{methoddesc}
***************
*** 264,301 ****
\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{, header}}}
! Return the message's \code{Content-Type:} parameters, as a list. The
elements of the returned list are 2-tuples of key/value pairs, as
! split on the \samp{=} sign. The left hand side of the \samp{=} is the
! key, while the right hand side is the value. If there is no \samp{=}
! sign in the parameter the value is the empty string. The value is
! always unquoted with \method{Utils.unquote()}.
Optional \var{failobj} is the object to return if there is no
! \code{Content-Type:} header. Optional \var{header} is the header to
! search instead of \code{Content-Type:}.
\end{methoddesc}
\begin{methoddesc}[Message]{get_param}{param\optional{,
failobj\optional{, header}}}
! Return the value of the \code{Content-Type:} header's parameter
! \var{param} as a string. If the message has no \code{Content-Type:}
header or if there is no such parameter, then \var{failobj} is
returned (defaults to \code{None}).
Optional \var{header} if given, specifies the message header to use
! instead of \code{Content-Type:}.
\end{methoddesc}
\begin{methoddesc}[Message]{get_charsets}{\optional{failobj}}
Return a list containing the character set names in the message. If
! the message is a \code{multipart}, then the list will contain one
element for each subpart in the payload, otherwise, it will be a list
of length 1.
Each item in the list will be a string which is the value of the
! \code{charset} parameter in the \code{Content-Type:} header for the
represented subpart. However, if the subpart has no
! \code{Content-Type:} header, no \code{charset} parameter, or is not of
! the \code{text} main MIME type, then that item in the returned list
will be \var{failobj}.
\end{methoddesc}
--- 273,310 ----
\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{, header}}}
! Return the message's \mailheader{Content-Type} parameters, as a list. The
elements of the returned list are 2-tuples of key/value pairs, as
! split on the \character{=} sign. The left hand side of the
! \character{=} is the key, while the right hand side is the value. If
! there is no \character{=} sign in the parameter the value is the empty
! string. The value is always unquoted with \method{Utils.unquote()}.
Optional \var{failobj} is the object to return if there is no
! \mailheader{Content-Type} header. Optional \var{header} is the header to
! search instead of \mailheader{Content-Type}.
\end{methoddesc}
\begin{methoddesc}[Message]{get_param}{param\optional{,
failobj\optional{, header}}}
! Return the value of the \mailheader{Content-Type} header's parameter
! \var{param} as a string. If the message has no \mailheader{Content-Type}
header or if there is no such parameter, then \var{failobj} is
returned (defaults to \code{None}).
Optional \var{header} if given, specifies the message header to use
! instead of \mailheader{Content-Type}.
\end{methoddesc}
\begin{methoddesc}[Message]{get_charsets}{\optional{failobj}}
Return a list containing the character set names in the message. If
! the message is a \mimetype{multipart}, then the list will contain one
element for each subpart in the payload, otherwise, it will be a list
of length 1.
Each item in the list will be a string which is the value of the
! \code{charset} parameter in the \mailheader{Content-Type} header for the
represented subpart. However, if the subpart has no
! \mailheader{Content-Type} header, no \code{charset} parameter, or is not of
! the \mimetype{text} main MIME type, then that item in the returned list
will be \var{failobj}.
\end{methoddesc}
***************
*** 303,307 ****
\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
Return the value of the \code{filename} parameter of the
! \code{Content-Disposition:} header of the message, or \var{failobj} if
either the header is missing, or has no \code{filename} parameter.
The returned string will always be unquoted as per
--- 312,316 ----
\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
Return the value of the \code{filename} parameter of the
! \mailheader{Content-Disposition} header of the message, or \var{failobj} if
either the header is missing, or has no \code{filename} parameter.
The returned string will always be unquoted as per
***************
*** 311,315 ****
\begin{methoddesc}[Message]{get_boundary}{\optional{failobj}}
Return the value of the \code{boundary} parameter of the
! \code{Content-Type:} header of the message, or \var{failobj} if either
the header is missing, or has no \code{boundary} parameter. The
returned string will always be unquoted as per
--- 320,324 ----
\begin{methoddesc}[Message]{get_boundary}{\optional{failobj}}
Return the value of the \code{boundary} parameter of the
! \mailheader{Content-Type} header of the message, or \var{failobj} if either
the header is missing, or has no \code{boundary} parameter. The
returned string will always be unquoted as per
***************
*** 318,333 ****
\begin{methoddesc}[Message]{set_boundary}{boundary}
! Set the \code{boundary} parameter of the \code{Content-Type:} header
to \var{boundary}. \method{set_boundary()} will always quote
\var{boundary} so you should not quote it yourself. A
! \code{HeaderParseError} is raised if the message object has no
! \code{Content-Type:} header.
Note that using this method is subtly different than deleting the old
! \code{Content-Type:} header and adding a new one with the new boundary
via \method{add_header()}, because \method{set_boundary()} preserves the
! order of the \code{Content-Type:} header in the list of headers.
However, it does \emph{not} preserve any continuation lines which may
! have been present in the original \code{Content-Type:} header.
\end{methoddesc}
--- 327,342 ----
\begin{methoddesc}[Message]{set_boundary}{boundary}
! Set the \code{boundary} parameter of the \mailheader{Content-Type} header
to \var{boundary}. \method{set_boundary()} will always quote
\var{boundary} so you should not quote it yourself. A
! \exception{HeaderParseError} is raised if the message object has no
! \mailheader{Content-Type} header.
Note that using this method is subtly different than deleting the old
! \mailheader{Content-Type} header and adding a new one with the new boundary
via \method{add_header()}, because \method{set_boundary()} preserves the
! order of the \mailheader{Content-Type} header in the list of headers.
However, it does \emph{not} preserve any continuation lines which may
! have been present in the original \mailheader{Content-Type} header.
\end{methoddesc}
Index: emailparser.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/emailparser.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** emailparser.tex 2001/09/26 05:23:47 1.1
--- emailparser.tex 2001/09/26 22:21:52 1.2
***************
*** 1,23 ****
- \section{\module{email.Parser} ---
- Parsing flat text email messages}
-
\declaremodule{standard}{email.Parser}
\modulesynopsis{Parse flat text email messages to produce a message
object tree.}
- \sectionauthor{Barry A. Warsaw}{barry@zope.com}
! \versionadded{2.2}
! The \module{Parser} module provides a single class, the \class{Parser}
! class, which is used to take a message in flat text form and create
! the associated object model. The resulting object tree can then be
! manipulated using the \class{Message} class interface as described in
! \refmodule{email.Message}, and turned over
! to a generator (as described in \refmodule{emamil.Generator}) to
! return the textual representation of the message. It is intended that
! the \class{Parser} to \class{Generator} path be idempotent if the
! object model isn't modified in between.
! \subsection{Parser class API}
\begin{classdesc}{Parser}{\optional{_class}}
--- 1,29 ----
\declaremodule{standard}{email.Parser}
\modulesynopsis{Parse flat text email messages to produce a message
object tree.}
! Message object trees can be created in one of two ways: they can be
! created from whole cloth by instantiating \class{Message} objects and
! stringing them together via \method{add_payload()} and
! \method{set_payload()} calls, or they can be created by parsing a flat text
! representation of the email message.
! The \module{email} package provides a standard parser that understands
! most email document structures, including MIME documents. You can
! pass the parser a string or a file object, and the parser will return
! to you the root \class{Message} instance of the object tree. For
! simple, non-MIME messages the payload of this root object will likely
! be a string (e.g. containing the text of the message). For MIME
! messages, the root object will return 1 from its
! \method{is_multipart()} method, and the subparts can be accessed via
! the \method{get_payload()} and \method{walk()} methods.
! Note that the parser can be extended in limited ways, and of course
! you can implement your own parser completely from scratch. There is
! no magical connection between the \module{email} package's bundled
! parser and the \class{Message} class, so your custom parser can create
! message object trees in any way it find necessary.
!
! \subsubsection{Parser class API}
\begin{classdesc}{Parser}{\optional{_class}}
***************
*** 76,95 ****
\end{verbatim}
! \subsection{Additional notes}
Here are some notes on the parsing semantics:
\begin{itemize}
! \item Most non-\code{multipart} type messages are parsed as a single
message object with a string payload. These objects will return
0 for \method{is_multipart()}.
! \item One exception is for \code{message/delivery-status} type
! messages. Because such the body of such messages consist of
blocks of headers, \class{Parser} will create a non-multipart
object containing non-multipart subobjects for each header
block.
! \item Another exception is for \code{message/*} types (i.e. more
! general than \code{message/delivery-status}. These are
! typically \code{message/rfc822} type messages, represented as a
non-multipart object containing a singleton payload, another
non-multipart \class{Message} instance.
--- 82,101 ----
\end{verbatim}
! \subsubsection{Additional notes}
Here are some notes on the parsing semantics:
\begin{itemize}
! \item Most non-\mimetype{multipart} type messages are parsed as a single
message object with a string payload. These objects will return
0 for \method{is_multipart()}.
! \item One exception is for \mimetype{message/delivery-status} type
! messages. Because the body of such messages consist of
blocks of headers, \class{Parser} will create a non-multipart
object containing non-multipart subobjects for each header
block.
! \item Another exception is for \mimetype{message/*} types (i.e. more
! general than \mimetype{message/delivery-status}). These are
! typically \mimetype{message/rfc822} type messages, represented as a
non-multipart object containing a singleton payload, another
non-multipart \class{Message} instance.
Index: emailutil.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/emailutil.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** emailutil.tex 2001/09/26 05:23:47 1.1
--- emailutil.tex 2001/09/26 22:21:52 1.2
***************
*** 1,11 ****
- \section{\module{email.Utils} ---
- Miscellaneous email package utilities}
-
\declaremodule{standard}{email.Utils}
\modulesynopsis{Miscellaneous email package utilities.}
- \sectionauthor{Barry A. Warsaw}{barry@zope.com}
- \versionadded{2.2}
-
There are several useful utilities provided with the \module{email}
package.
--- 1,5 ----
***************
*** 25,30 ****
\begin{funcdesc}{parseaddr}{address}
Parse address -- which should be the value of some address-containing
! field such as \code{To:} or \code{Cc:} -- into its constituent
! ``realname'' and ``email address'' parts. Returns a tuple of that
information, unless the parse fails, in which case a 2-tuple of
\code{(None, None)} is returned.
--- 19,24 ----
\begin{funcdesc}{parseaddr}{address}
Parse address -- which should be the value of some address-containing
! field such as \mailheader{To} or \mailheader{Cc} -- into its constituent
! \emph{realname} and \emph{email address} parts. Returns a tuple of that
information, unless the parse fails, in which case a 2-tuple of
\code{(None, None)} is returned.
***************
*** 34,38 ****
The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
\code{(realname, email_address)} and returns the string value suitable
! for a \code{To:} or \code{Cc:} header. If the first element of
\var{pair} is false, then the second element is returned unmodified.
\end{funcdesc}
--- 28,32 ----
The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
\code{(realname, email_address)} and returns the string value suitable
! for a \mailheader{To} or \mailheader{Cc} header. If the first element of
\var{pair} is false, then the second element is returned unmodified.
\end{funcdesc}
***************
*** 69,75 ****
\var{charset} is \samp{iso-8859-1}.
! \var{encoding} must be either the letter \samp{q} for
! Quoted-Printable or \samp{b} for Base64 encoding. If
! neither, a \code{ValueError} is raised. Both the \var{charset} and
the \var{encoding} strings are case-insensitive, and coerced to lower
case in the returned string.
--- 63,69 ----
\var{charset} is \samp{iso-8859-1}.
! \var{encoding} must be either the letter \character{q} for
! Quoted-Printable or \character{b} for Base64 encoding. If
! neither, a \exception{ValueError} is raised. Both the \var{charset} and
the \var{encoding} strings are case-insensitive, and coerced to lower
case in the returned string.