From 31643ee39c3b08ef2bdeeefcf350f2114a7ee845 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Fri, 21 Mar 2003 21:24:27 +0000 Subject: Backporting docs for email 2.5 --- Doc/lib/email.tex | 7 ++++--- Doc/lib/emailcharsets.tex | 1 + Doc/lib/emailheaders.tex | 18 ++++++++++++++---- Doc/lib/emailiter.tex | 4 +++- Doc/lib/emailmessage.tex | 7 ++++--- Doc/lib/emailmimebase.tex | 3 +-- 6 files changed, 27 insertions(+), 13 deletions(-) diff --git a/Doc/lib/email.tex b/Doc/lib/email.tex index 47bbf5b..debed70 100644 --- a/Doc/lib/email.tex +++ b/Doc/lib/email.tex @@ -323,9 +323,10 @@ family pictures that may be residing in a directory: \verbatiminput{email-mime.py} -Here's an example\footnote{Thanks to Matthew Dixon Cowles for the -original inspiration and examples.} of how to send the entire contents -of a directory as an email message: +Here's an example of how to send the entire contents of a directory as +an email message: +\footnote{Thanks to Matthew Dixon Cowles for the original inspiration + and examples.} \verbatiminput{email-dir.py} diff --git a/Doc/lib/emailcharsets.tex b/Doc/lib/emailcharsets.tex index d654ada..18f2a01 100644 --- a/Doc/lib/emailcharsets.tex +++ b/Doc/lib/emailcharsets.tex @@ -177,6 +177,7 @@ standard operations and built-in functions. \begin{methoddesc}[Charset]{__str__}{} Returns \var{input_charset} as a string coerced to lower case. +\method{__repr__()} is an alias for \method{__str__()}. \end{methoddesc} \begin{methoddesc}[Charset]{__eq__}{other} diff --git a/Doc/lib/emailheaders.tex b/Doc/lib/emailheaders.tex index 66eb716..d4bbeb8 100644 --- a/Doc/lib/emailheaders.tex +++ b/Doc/lib/emailheaders.tex @@ -48,7 +48,8 @@ embedded ISO-8859-1 character. Here is the \class{Header} class description: \begin{classdesc}{Header}{\optional{s\optional{, charset\optional{, - maxlinelen\optional{, header_name\optional{, continuation_ws}}}}}} + maxlinelen\optional{, header_name\optional{, continuation_ws\optional{, + errors}}}}}}} Create a MIME-compliant header that can contain strings in different character sets. @@ -79,7 +80,10 @@ whitespace, and is usually either a space or a hard tab character. This character will be prepended to continuation lines. \end{classdesc} -\begin{methoddesc}[Header]{append}{s\optional{, charset}} +Optional \var{errors} is passed straight through to the +\method{append()} method. + +\begin{methoddesc}[Header]{append}{s\optional{, charset\optional{, errors}}} Append the string \var{s} to the MIME header. Optional \var{charset}, if given, should be a \class{Charset} instance @@ -100,12 +104,18 @@ case, when producing an \rfc{2822}-compliant header using \rfc{2047} rules, the Unicode string will be encoded using the following charsets in order: \code{us-ascii}, the \var{charset} hint, \code{utf-8}. The first character set to not provoke a \exception{UnicodeError} is used. + +Optional \var{errors} is passed through to any \function{unicode()} or +\function{ustr.encode()} call, and defaults to ``strict''. \end{methoddesc} -\begin{methoddesc}[Header]{encode}{} +\begin{methoddesc}[Header]{encode}{\optional{splitchars}} Encode a message header into an RFC-compliant format, possibly wrapping long lines and encapsulating non-\ASCII{} parts in base64 or -quoted-printable encodings. +quoted-printable encodings. Optional \var{splitchars} is a string +containing characters to split long ASCII lines on, in rough support +of \rfc{2822}'s \emph{highest level syntactic breaks}. This doesn't +affect \rfc{2047} encoded lines. \end{methoddesc} The \class{Header} class also provides a number of methods to support diff --git a/Doc/lib/emailiter.tex b/Doc/lib/emailiter.tex index 9180ac2..d1a8f98 100644 --- a/Doc/lib/emailiter.tex +++ b/Doc/lib/emailiter.tex @@ -6,13 +6,15 @@ Iterating over a message object tree is fairly easy with the provides some useful higher level iterations over message object trees. -\begin{funcdesc}{body_line_iterator}{msg} +\begin{funcdesc}{body_line_iterator}{msg\optional{, decode}} This iterates over all the payloads in all the subparts of \var{msg}, returning the string payloads line-by-line. It skips over all the subpart headers, and it skips over any subpart with a payload that isn't a Python string. This is somewhat equivalent to reading the flat text representation of the message from a file using \method{readline()}, skipping over all the intervening headers. + +Optional \var{decode} is passed through to \method{Message.get_payload()}. \end{funcdesc} \begin{funcdesc}{typed_subpart_iterator}{msg\optional{, diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex index 34c152d..61dc74b 100644 --- a/Doc/lib/emailmessage.tex +++ b/Doc/lib/emailmessage.tex @@ -87,9 +87,10 @@ When \code{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 \code{True}, then \code{None} is -returned. The default for \var{decode} is \code{False}. +missing, or if the payload has bogus base64 data, the payload is +returned as-is (undecoded). If the message is a multipart and the +\var{decode} flag is \code{True}, then \code{None} is returned. The +default for \var{decode} is \code{False}. \end{methoddesc} \begin{methoddesc}[Message]{set_payload}{payload\optional{, charset}} diff --git a/Doc/lib/emailmimebase.tex b/Doc/lib/emailmimebase.tex index 6bbd5dd..3318d6a 100644 --- a/Doc/lib/emailmimebase.tex +++ b/Doc/lib/emailmimebase.tex @@ -151,8 +151,7 @@ used to create MIME objects of major type \mimetype{text}. 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{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No -guessing or encoding is performed on the text data, but a newline is -appended to \var{_text} if it doesn't already end with a newline. +guessing or encoding is performed on the text data. \deprecated{2.2.2}{The \var{_encoding} argument has been deprecated. Encoding now happens implicitly based on the \var{_charset} argument.} -- cgit v0.12