[Python-checkins] r42533 - in sandbox/trunk/emailpkg/3.1: MANIFEST NEWS README docs docs/about.html docs/blank.png docs/contents.png docs/email-dir.txt docs/email-mime.txt docs/email-simple.txt docs/email-unpack.txt docs/index.html docs/index.png docs/mimelib.css docs/mimelib.html docs/module-email.charset.html docs/module-email.encoders.html docs/module-email.errors.html docs/module-email.generator.html docs/module-email.header.html docs/module-email.html docs/module-email.iterators.html docs/module-email.message.html docs/module-email.mime.text.html docs/module-email.parser.html docs/module-email.utils.html docs/modules.png docs/next.png docs/node1.html docs/node16.html docs/node17.html docs/node18.html docs/node5.html docs/node6.html docs/node7.html docs/previous.png docs/pyfav.png docs/up.png email/__init__.py email/base64mime.py email/charset.py email/encoders.py email/errors.py email/feedparser.py email/generator.py email/header.py email/iterators.py email/message.py email/mime/audio.py email/mime/base.py email/mime/image.py email/mime/message.py email/mime/multipart.py email/mime/nonmultipart.py email/mime/text.py email/parser.py email/quoprimime.py email/test/test_email.py email/test/test_email_codecs.py email/test/test_email_codecs_renamed.py email/test/test_email_renamed.py email/utils.py moredata setup.py
barry.warsaw
python-checkins at python.org
Tue Feb 21 04:03:32 CET 2006
Author: barry.warsaw
Date: Tue Feb 21 04:03:07 2006
New Revision: 42533
Added:
sandbox/trunk/emailpkg/3.1/docs/
sandbox/trunk/emailpkg/3.1/docs/about.html
sandbox/trunk/emailpkg/3.1/docs/blank.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/docs/contents.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/docs/email-dir.txt
sandbox/trunk/emailpkg/3.1/docs/email-mime.txt
sandbox/trunk/emailpkg/3.1/docs/email-simple.txt
sandbox/trunk/emailpkg/3.1/docs/email-unpack.txt
sandbox/trunk/emailpkg/3.1/docs/index.html
sandbox/trunk/emailpkg/3.1/docs/index.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/docs/mimelib.css
sandbox/trunk/emailpkg/3.1/docs/mimelib.html
sandbox/trunk/emailpkg/3.1/docs/module-email.charset.html
sandbox/trunk/emailpkg/3.1/docs/module-email.encoders.html
sandbox/trunk/emailpkg/3.1/docs/module-email.errors.html
sandbox/trunk/emailpkg/3.1/docs/module-email.generator.html
sandbox/trunk/emailpkg/3.1/docs/module-email.header.html
sandbox/trunk/emailpkg/3.1/docs/module-email.html
sandbox/trunk/emailpkg/3.1/docs/module-email.iterators.html
sandbox/trunk/emailpkg/3.1/docs/module-email.message.html
sandbox/trunk/emailpkg/3.1/docs/module-email.mime.text.html
sandbox/trunk/emailpkg/3.1/docs/module-email.parser.html
sandbox/trunk/emailpkg/3.1/docs/module-email.utils.html
sandbox/trunk/emailpkg/3.1/docs/modules.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/docs/next.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/docs/node1.html
sandbox/trunk/emailpkg/3.1/docs/node16.html
sandbox/trunk/emailpkg/3.1/docs/node17.html
sandbox/trunk/emailpkg/3.1/docs/node18.html
sandbox/trunk/emailpkg/3.1/docs/node5.html
sandbox/trunk/emailpkg/3.1/docs/node6.html
sandbox/trunk/emailpkg/3.1/docs/node7.html
sandbox/trunk/emailpkg/3.1/docs/previous.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/docs/pyfav.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/docs/up.png (contents, props changed)
sandbox/trunk/emailpkg/3.1/moredata/
- copied from r42421, sandbox/trunk/emailpkg/2.5/moredata/
Removed:
sandbox/trunk/emailpkg/3.1/NEWS
Modified:
sandbox/trunk/emailpkg/3.1/ (props changed)
sandbox/trunk/emailpkg/3.1/MANIFEST
sandbox/trunk/emailpkg/3.1/README
sandbox/trunk/emailpkg/3.1/email/__init__.py
sandbox/trunk/emailpkg/3.1/email/base64mime.py
sandbox/trunk/emailpkg/3.1/email/charset.py
sandbox/trunk/emailpkg/3.1/email/encoders.py
sandbox/trunk/emailpkg/3.1/email/errors.py
sandbox/trunk/emailpkg/3.1/email/feedparser.py
sandbox/trunk/emailpkg/3.1/email/generator.py
sandbox/trunk/emailpkg/3.1/email/header.py
sandbox/trunk/emailpkg/3.1/email/iterators.py
sandbox/trunk/emailpkg/3.1/email/message.py
sandbox/trunk/emailpkg/3.1/email/mime/audio.py
sandbox/trunk/emailpkg/3.1/email/mime/base.py
sandbox/trunk/emailpkg/3.1/email/mime/image.py
sandbox/trunk/emailpkg/3.1/email/mime/message.py
sandbox/trunk/emailpkg/3.1/email/mime/multipart.py
sandbox/trunk/emailpkg/3.1/email/mime/nonmultipart.py
sandbox/trunk/emailpkg/3.1/email/mime/text.py
sandbox/trunk/emailpkg/3.1/email/parser.py
sandbox/trunk/emailpkg/3.1/email/quoprimime.py
sandbox/trunk/emailpkg/3.1/email/test/test_email.py
sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs.py
sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs_renamed.py
sandbox/trunk/emailpkg/3.1/email/test/test_email_renamed.py
sandbox/trunk/emailpkg/3.1/email/utils.py
sandbox/trunk/emailpkg/3.1/setup.py
Log:
Many updates in preparation for bumping version to 4.0, releasing a new
standalone package, and merging back into the Python 2.5 trunk.
Change all internal imports to use the PEP 9 lower case names.
Fix Python 2.3 compatibility by checking for the euc-jp encoding before tyring
to run the test_email_codecs*.py tests. Also, we can't use sorted() in the
tests as that's a Python 2.4 function.
Remove previously deprecated methods Message.get_type(),
Message.get_main_type(), Message.get_subtype(), and Generator.__call__().
Remove DeprecationWarnings filter from the tests. Update all tests which used
.get_type() to use .get_content_type().
Add a new test for an issue found by Tokio: Instantiating a Charset with a
Unicode argument (which is legal as long as the string contains only ASCII).
Add CharsetError which gets raised if the Charset ctor argument is illegal.
Fix setup.py to include the email.mime subpackage.
Remove the NEWS file; all major changes are described in the documentation
now. Update the README.
Commit a major update of the documentation.
Modified: sandbox/trunk/emailpkg/3.1/MANIFEST
==============================================================================
--- sandbox/trunk/emailpkg/3.1/MANIFEST (original)
+++ sandbox/trunk/emailpkg/3.1/MANIFEST Tue Feb 21 04:03:07 2006
@@ -1,34 +1,33 @@
setup.py
testall.py
-NEWS
README
-LICENSE.txt
-email/_compat21.py
-email/_compat22.py
-email/Charset.py
-email/Encoders.py
-email/Errors.py
-email/FeedParser.py
-email/Generator.py
-email/Header.py
-email/Iterators.py
-email/MIMEAudio.py
-email/MIMEBase.py
-email/MIMEImage.py
-email/MIMEMessage.py
-email/MIMEMultipart.py
-email/MIMENonMultipart.py
-email/MIMEText.py
-email/Message.py
-email/Parser.py
-email/Utils.py
email/__init__.py
email/_parseaddr.py
-email/base64MIME.py
-email/quopriMIME.py
+email/base64mime.py
+email/charset.py
+email/encoders.py
+email/errors.py
+email/feedparser.py
+email/generator.py
+email/header.py
+email/iterators.py
+email/message.py
+email/parser.py
+email/quoprimime.py
+email/utils.py
+email/mime/__init__.py
+email/mime/audio.py
+email/mime/base.py
+email/mime/image.py
+email/mime/message.py
+email/mime/multipart.py
+email/mime/nonmultipart.py
+email/mime/text.py
email/test/__init__.py
email/test/test_email.py
email/test/test_email_codecs.py
+email/test/test_email_renamed.py
+email/test/test_email_codecs_renamed.py
email/test/test_email_torture.py
email/test/data/PyBanner048.gif
email/test/data/audiotest.au
@@ -75,6 +74,8 @@
email/test/data/msg_40.txt
email/test/data/msg_41.txt
email/test/data/msg_42.txt
+email/test/data/msg_43.txt
+email/test/data/msg_44.txt
moredata/crispin-torture.txt
docs/about.html
docs/blank.png
@@ -87,27 +88,26 @@
docs/index.png
docs/mimelib.css
docs/mimelib.html
-docs/module-email.Charset.html
-docs/module-email.Encoders.html
-docs/module-email.Errors.html
-docs/module-email.Generator.html
-docs/module-email.Header.html
-docs/module-email.Iterators.html
-docs/module-email.Message.html
-docs/module-email.Parser.html
-docs/module-email.Utils.html
+docs/module-email.charset.html
+docs/module-email.encoders.html
+docs/module-email.errors.html
+docs/module-email.generator.html
+docs/module-email.header.html
docs/module-email.html
+docs/module-email.iterators.html
+docs/module-email.message.html
+docs/module-email.mime.text.html
+docs/module-email.parser.html
+docs/module-email.utils.html
docs/modules.png
docs/next.png
docs/node1.html
-docs/node10.html
-docs/node11.html
+docs/node16.html
+docs/node17.html
docs/node18.html
-docs/node19.html
-docs/node20.html
-docs/node4.html
+docs/node5.html
docs/node6.html
docs/node7.html
-docs/node8.html
docs/previous.png
+docs/pyfav.png
docs/up.png
Deleted: /sandbox/trunk/emailpkg/3.1/NEWS
==============================================================================
--- /sandbox/trunk/emailpkg/3.1/NEWS Tue Feb 21 04:03:07 2006
+++ (empty file)
@@ -1,594 +0,0 @@
-Copyright (C) 2001-2004 Python Software Foundation
-
-Here is a history of user visible changes to this software.
-
-2.5.5 (13-May-2004)
-2.5.4
-2.5.3
-2.5.2
-
- Lots of bug fixes.
-
-2.5.1 (30-Mar-2003)
-
- Bug fixes and improved compatibility for Python 2.2.0.
-
-2.5 (21-Mar-2003)
-
- A few other minor bug fixes.
-
-2.5b1 (11-Mar-2003)
-
- - Message.get_payload() now recognizes various uuencoded
- Content-Transfer-Encodings (e.g. x-uuencode).
-
- When passing decode=True to Message.get_payload() and a
- low-level decoding error occurs, the payload is returned as-is
- instead of raising an exception.
-
- - Header.__init__() and Header.append() now accept an optional
- argument `errors' which is passed through to the unicode() and
- ustr.encode() calls. You can use this to prevent conversion
- errors by e.g. passing 'replace' or 'ignore'.
-
- RFC 2822 specifies that long headers should be split at the
- "highest level syntactic break" possible. This can only really
- be determined by the application, and the current API doesn't
- support arbitrary break points. As a compromise,
- Header.encode() grew a `splitchars' argument which provides some
- control over splitting at higher level syntactic breaks.
-
- Header.decode_header() now transforms binascii.Errors into
- email.Errors.HeaderParseErrors when bogus base64 data appears in
- the header.
-
- The header splitting and folding algorithms were completely
- reimplemented, especially when dealing with ASCII headers.
-
- We now preserve spaces between encoded and non-encode parts in
- RFC 2047 headers when converting the header to Unicode. While
- the RFC is technically ambiguous on this point, this is the
- behavior most people expect.
-
- - email.Iterators.body_line_iterator() now takes an optional
- decode argument, which is passed through to Message.get_payload().
-
- - The MIMEText constructor used to append a newline to the _text
- argument if it didn't already end in a newline. Now it doesn't.
- This could theoretically break code so it should be considered
- experimental for 2.5 beta 1. But it's the right fix, so we'll
- keep it unless there are howls of derision.
-
- - The quopriMIME.header_encode() maxlinelen argument now accepts
- None, which inhibits line breaking.
-
- - Support for Korean charsets was added to Charset.py. Also the
- Charset class grew a __repr__() method.
-
- - Various and sundry bug fixes, improved RFC conformance, and
- improved lax parsing.
-
-2.4.3 (14-Oct-2002)
-2.4.2 (10-Oct-2002)
-2.4.1 (07-Oct-2002)
-
- Last minute patches for the Python 2.2.2 backport. This includes
- case insensitivity of character set names, patches for Windows,
- and some fixes for non-splitting of unspecified 8bit header data.
-
-2.4 (01-Oct-2002)
-
- - Updated all the documentation.
-
- - Clarification to the semantics of Header.__init__() and
- Header.append() when it gets byte strings and Unicode strings as
- its first argument. When a byte string is used, the charset
- must be the encoding of the string, such that unicode(s,charset)
- succeeds. When a Unicode string is used, the charset is a hint,
- and the first of the following to succeed is used: us-ascii, the
- charset hint, utf-8.
-
- - A new header encoding flag has been added to the Charset
- module. SHORTEST (which cannot be used for body encodings)
- returns the string either quoted-printable or base64 encoding,
- whichever is shortest in terms of characters. This is a good
- heuristic for providing the most human readable value possible.
- The utf-8 charset uses SHORTEST encoding by default now.
-
- - Message.get_content_charset() is a new method that returns the
- charset parameter on the Content-Type header, unquoted and RFC
- 2231 decoded if necessary.
-
- - "import email" no longer imports some sub-modules by side-effect.
-
- - Fixed some problems related to RFC 2231 encoding of boundary and
- charset parameters on Content-Type headers. Document that
- get_param() and get_params() may return values that are strings
- or 3-tuples.
-
- - The signature of the non-public function _structure() has
- changed.
-
-2.3.1 (13-Sep-2002)
-
- - Minor update to the distutils package. A file was missing in
- the email-2.3.tar.gz file.
-
-2.3 (10-Sep-2002)
-
- - Added support for RFC 2231 encoding. Patch by Oleg Broytmann
- (previous patch was for RFC 2231 decoding only).
-
- - New method Message.replace_header() which replaces the first
- occurrence of a header with a new value, preserving header order
- and header name case. Patch by Skip Montanaro.
-
- - RFC 2045, section 5.2 states that if the Content-Type: header is
- invalid, it defaults to text/plain. Implement simple checks for
- this in get_content_type(), get_content_maintype(), and
- get_content_subtype(). These will no longer raise ValueErrors.
-
- - In non-strict parsing, if no start boundary can be found for a
- multipart message, the entire body of the message is set as the
- payload. Strict parsing such a message will still raise a
- BoundaryError.
-
-2.2 (23-Jul-2002)
-
- - Better support for default content types has been added.
- Specifically:
-
- o The following methods have been silently deprecated. At some
- future release they may be unsilently deprecated:
- Message.get_type(), Message.get_main_type(),
- Message.get_subtype().
-
- o The following methods have been added as a consistent way of
- getting a message's content type: Message.get_content_type(),
- Message.get_content_maintype(), Message.get_content_subtype().
-
- Note that none of these methods take a `failobj' argument
- because messages always have a default content type. Usually
- this type is text/plain, but for messages inside a
- multipart/digest container, it's message/rfc822.
-
- Also note that .get_content_maintype() and
- .get_content_subtype() can raise ValueError exceptions if the
- default content type doesn't include exactly one slash.
-
- - The Parser constructor's `strict' flag is exposed to
- email.message_from_file() and email.message_from_string().
- Also, non-strict parsing is now the default, since that seems to
- be the most useful behavior.
-
- - email.Header.Header.append() now allows the charset argument to
- be a string, naming a character set. It will convert these to a
- Charset instance automatically.
-
- - The test procedure has changed. See the README for details.
- Also, a new torture test has been added.
-
- - The non-public function email.Iterators._structure() can now
- take an output file object (which must be suitable for print>>).
-
-2.1 (09-Jul-2002)
-
- - Support for RFC 2231 by Oleg Broytmann was added.
-
- - Fixed some representational, parsing, and generation bugs with
- multipart/digest and message/rfc822 messages. Now we guarantee
- that the structure of such messages is something like:
-
- multipart/digest
- message/rfc822
- text/plain (or whatever the subpart's type is)
- message/rfc822
- text/plain (ditto)
-
- The encapsulating message/rfc822 object is a multipart of
- exactly length 1.
-
- To preserve idempotency, the concept of a "default type" is
- added to Message objects. For most messages the default type is
- text/plain, except for messages at the first level inside a
- multipart/digest which are message/rfc822. This default type is
- not described in the Content-Type: header of the container.
-
- Message objects thus have new methods get_default_type() and
- set_default_type(), the latter of which takes a string argument
- that must be either 'text/plain' or 'message/rfc822'.
-
- (Some changes were also made to the non-public interface for the
- Generator class.)
-
- - The Header class now knows how to split long non-RFC 2047
- encoded headers (i.e. us-ascii charset) in the RFC 2822
- recommended way. Splits are attempted at the "highest-level
- syntactic breaks" which we define as on parameter semicolons,
- followed by folding whitespace. No errors are raised if long
- headers still exceed the maximum RFC 2822 header length of 998
- characters after splitting.
-
- - Other Header class API changes:
- o All __init__() arguments have default values now. Also, a
- new argument continuation_ws has been added (defaults to a
- single ASCII space).
- o Rich comparison __eq__ and __ne__ operators are defined
- o __unicode__() for Python 2.2 by Mikhail Zabaluev
- o guess_maxlinelen() method has been removed
- o encode_chunks() is no longer public
-
- - The email.Header module has grown a function make_header() which
- takes the output of decode_header() and returns a Header
- instance.
-
- - A non-public function email.Iterators._structure() has been
- added for debugging purposes.
-
- - MIMEMultipart.__init__() doesn't attach the subparts of the
- tuple is empty (i.e. there are no subparts). Fixed a bug
- related to passing in explicit boundary.
-
- - Anthony Baxter's patches for non-strict parsing have been added
- to the Parser class. There are currently no test cases for
- non-strict parsing yet. Other Parser class API changes:
- o Parser.__init__() grew a strict argument, defaulting to
- true for backwards compatibility.
- o parse() and parsestr() both grew a headersonly argument
- which tells them to stop parsing once the header block is
- parsed. The file pointer is left at the start of the body.
-
- - For RFC 2231 support, added the following functions to the
- email.Utils module: decode_rfc2231(), encode_rfc2231(),
- decode_params().
-
-2.0.5 (02-Jun-2002)
-
- - Two new class/modules MIMEMultipart and MIMENonMultipart have
- been added. The former is useful as a concrete class for
- creating multipart/* parts. The latter is mostly useful as a
- base class for other MIME non-multipart subparts. For example,
- the MIMEAudio, MIMEImage, and MIMEText clases now derive from
- MIMENonMultipart. Note also that MIMENonMultipart.attach()
- raises a MultipartConversionError.
-
- - The message structure for message/rfc822 subparts has been
- changed to be more consistent. Now message/rfc822 payloads are
- defined as a list containing exactly one element, the
- sub-Message object.
-
- - The callable interface to the Generator class is now silently
- deprecated in favor of the Generator.flatten() method.
- __call__() can be 2-3 times slower than the equivalent normal
- method.
-
-2.0.4 (21-May-2002)
-
- - Fixed a bug in email.Utils.getaddresses().
-
-2.0.3 (19-May-2002)
-
- - Fixed some limitations that caused the Parser to not work with
- CRLF style line-endings. The parser should now be able to parse
- any email message with consistent line endings of \r, \n, \r\n.
-
- - Fixed a bug related to the semantics of the Header class
- constructor. If neither maxlinelen or header_name is given, the
- maximum line length is 76 by default. If maxlinelen is given,
- it is always honored. If maxlinelen is not given, but
- header_name is given, then a suitable default line length is
- calculated.
-
- - Implemented a simpler testing framework. Now you just need to
- run "python test.py" in the source directory.
-
- - Merged with the standard Python cvs tree, with compatibility
- modules for working in Python 2.1 and Python 2.2.
-
-2.0.2 (26-Apr-2002)
-
- - Fix a Python 2.1.3 incompatibility in Iterators.py,
- body_line_iterator().
-
-2.0.1 (10-Apr-2002)
-
- - Minor bug fixes in the test suite.
-
- - One minor API change: in Header.append(), the charset is
- optional, and used to default to the empty Charset(). It now
- defaults to the charset given in the Header constructor.
-
-2.0 (08-Apr-2002)
-
- - Message.add_payload() is now deprecated. Instead use
- Message.attach() and Message.set_payload(). The former always
- ensures that the message's payload is a list object, while the
- latter is used only for scalar payloads (i.e. a string or a
- single Message object in the case of message/rfc822 types).
-
- - email.Utils.formataddr(): New function which is the inverse of
- .parseaddr(); i.e. it glues a realname and an email address
- together. This replaces email.Utils.dump_address_pair() which
- is deprecated.
-
- - class Charset now has a __str__() method, and implements rich
- comparison operators for comparison to lower case charset
- names.
-
- - encode_7or8bit(): If there is no payload, set the
- Content-Transfer-Encoding: value to 7bit.
-
- - Fixes for bugs in generating multipart messages that had exactly
- zero or one subparts.
-
-1.2 (18-Mar-2002)
-
- - In the MIMEText class's constructor, the _encoder argument is
- deprecated. You will get a DeprecationWarning if you try to use
- it. This is because there is a fundamental conflict between
- _encoder and the fact that _charset is passed to the underlying
- set_payload() method. _encoder really makes no sense any more.
-
- - When Message.set_type() is used to set the Content-Type: header,
- the MIME-Version: header is always set (overriding any existing
- MIME-Version: header).
-
- - More liberal acceptance of parameter formatting, e.g. this is
- now accepted: Content-Type: multipart/mixed; boundary = "FOO"
- I.e. spaces around the = sign.
-
- - Bug fix in Generator related to splitting long lines in a
- multiline header.
-
- - In class Charset, __str__() method added, as were __eq__() and
- __ne__().
-
- - Charset.get_body_encoding() may now return a function as well as
- a string character set name. The function takes a single
- argument, which is a Message instance, and may change the
- Content-Transfer-Encoding: header (or do any other manipulations
- on the message).
-
- - Charset.from_splittable() added argument to_output which is used
- to specify whether the input_codec or the output_codec is used
- for the conversion (by default, the output codec is used).
-
-1.1 (unreleased)
-
- - No changes since 0.97. Only the version number has changed.
-
-0.97 (unreleased)
-
- - Message.set_charset() can now take a string naming a character
- set in addition to a Charset instance. In the former case, a
- Charset is instantiated by passing the string to its
- constructor.
-
- - The MIMEText constructor now passes the _charset argument to the
- underlying set_charset() method. This makes things consistent
- at the cost of a minor semantic change: the resulting instance
- will have a Content-Transfer-Encoding: header where previously
- it did not.
-
- - A fix for a crash when quopriMIME.encode() tried to encode a
- multiline string containing a blank line.
-
- - New module Header.py which provides a higher level interface for
- encoded email headers, such as Subject:, From:, and To:. This
- module provides an abstraction for composing such headers out of
- charset encoded parts, and for decoding such headers. It
- properly splits lines on character boundaries even for multibyte
- character sets.
-
- - New RFC compliant base64 and quoted-printable modules, called
- base64MIME.py and quopriMIME.py. These are intended to replace
- the Python standard base64.py and quopri.py modules, but are
- geared toward their use conformant to the various MIME email
- standards.
-
- - The Message class is much more character set aware and RFC
- compliant:
-
- + set_payload() now takes a new optional charset argument
- + New methods set_charset(), get_charset(), set_param(),
- del_param(), set_type()
- + Header parameter quoting is more RFC compliant
- + get_param() and get_params() now take a new optional unquote
- argument
-
- - The Charset module now knows about utf-8, gb2132, and big5
- codecs, the latter two of which are available independently of
- Python (see the comments in this module for downloading Chinese,
- Japanese, and Korean codecs).
-
- New Charset methods get_body_encoding(), get_output_charset(),
- encoded_header_len(), header_encode(), and body_encode().
-
- - The Generator now handles encoding the body, if the message
- object has a character set.
-
- - The Utils module has new functions fix_eols() and make_msgid().
- It also includes a workaround for bugs in parseaddr() when used
- with Python versions before 2.2.
-
- - A fix for a Parser bug when parsing multipart/* parts that
- contain only a single subpart.
-
-0.96 (19-Nov-2001)
-
- - A fix for email.Utils.formatdate() for "uneven" timezones like
- Australia/Adelaide and America/St_Johns.
-
-0.95 (09-Nov-2001)
-
- - A new implementation of email.Utils.formatdate() which makes it
- more RFC 2822 compliant.
-
-0.94 (25-Oct-2001)
-
- - A fix for SF bug #472560, extra newlines returned by get_param()
- when the separating semi-colon shows up on a continuation line
- (legal, but weird).
-
-0.93 (17-Oct-2001)
-
- - Fix for SF bug #471918, generator splitting long headers
- produces dupliaction. Bug report and fix contributed by Matthew
- Cowles.
-
- - If a line could not be split on semicolons in order to produce
- shorter lines, an attempt is made to split the header on folding
- white space. One deficiency still: it won't try to split on
- both semis and folding whitespace. Oh well.
-
-0.92 (14-Oct-2001)
-
- - Iterators.typed_subpart_iterator() should use a 'text/plain'
- failobj in its get_main_type() call.
-
- - Added class Parser.HeaderParser which just parses headers and
- leaves the message as a string payload; it does not recursively
- parse the body.
-
-0.91 (09-Oct-2001)
-
- - Added the MIMEAudio class/module for audio/* MIME types.
- Contributed by Anthony Baxter.
-
- - Fixed a bug in Message.get_all() where failobj was never
- returned if no matching fields were found.
-
-0.90 (01-Oct-2001)
-
- - mimelib has been integrated with Python 2.2. A compatibility
- package called email 0.90 is being made available here. It is
- significantly different in API from the mimelib package. See
- the README for details. mimelib as a separate package is no
- longer being supported.
-
-0.6 (17-Sep-2001)
-
- - Last minute bug fixes.
-
-0.5 (17-Sep-2001)
-
- - New methods in the top-level mimelib package namespace:
- + messageFromString() to create an object tree from a string.
- + messageFromFile() to create an object tree from an open file.
-
- - New methods in the address.py module:
- + encode() for encoding to RFC 2047 headers
- + decode() for decoding from RFC 2047 headers
-
- - New methods in the Message class:
- + asString() to get a flat text representation of the object
- tree.
- + __str__() same as asString() but includes the Unix-From
- envelope header in the output.
- + __contains__() for use with the `in' operator.
- + attach() is a synonym for add_payload()
- + getcharsets()
- + getfilename()
- + getboundary()
- + setboundary()
- + getdecodedpayload()
- + getpayloadastext()
- + getbodyastext()
-
- - Message.preamble and Message.epilogue default to None (they used
- to not exist by default).
-
- - Changes to the Generator class:
- + New optional argument `maxheaderlen' for __init__() controls
- the maximum length in characters of any header line.
- + write() isn't the entry point for doing the text generation
- any more. This lets us make this method compatible with
- file-like objects. Use __call__() semantics instead.
- + Calling a Generator instance creates the plain text
- message. This is the same as the old write() interface
- except that the optional `unixfrom' argument now defaults to
- 0.
- + There is a new, undocumented semi-private interface for
- extending the MIME types Generator can handle. UTSL.
-
- - New Encoders.py module contains some useful encoders for Image
- and Text instances.
-
- - Text.__init__() has a new _encoder optional argument, which has
- the same semantics as _encoder for Image.__init__().
-
- - StringableMixin.py module has been removed, and its
- functionality merged back into the Message class.
-
- - MessageParseError doesn't contain line numbers any more.
-
- - Lots of bug fixes; lots more unit tests.
-
-0.4 (09-Jul-2001)
-
- - New module/class called RFC822 which represents message/rfc822
- MIME types. This takes a single Message instance.
-
- - Message.getmaintype() and Message.getsubtype() will now return
- failobj when the Content-Type: header doesn't have enough
- information.
-
-0.3 (20-Apr-2001)
-
- - In the Image class, the _encoding argument has been changed to
- _encoder. Also ImageTypeError is removed; if Image.__init__()
- can't guess the image's minor type, a TypeError is raised
- instead.
-
- - Message.getparam() and Message.getparams() have grown a new
- optional argument `header'.
-
- - MsgReader class has grown a new method readlines() for
- compatibility with Python 2.1's xreadline module.
-
- - The ReprMixin module and class have been renamed to
- StringableMixin
-
- - New exception MultipartConversionError can be raised by
- Message.add_payload()
-
- - Bug fixes
-
- - mimelib has been moved to SourceForge. See
- http://mimelib.sourceforge.net
-
-0.2 (14-Feb-2001)
-
- - Generator constructor has a new optional argument `mangle_from_'
- which is a flag. If true, the generated flat text has From_
- lines mangled in the body of messages by prepending a `>' in
- front of the line. This assures that such lines are not
- mistaken for Unix mailbox separators.
-
- - Added a new class ReprMixin for adding convenience methods
- get_text() and __str__() to Message subclasses.
-
- - RFC 1341 (MIME) calls the blob between the closing boundary and
- the end of the message, the `epilogue'. Change `postamble' to
- `epilogue' in Message and Generator classes.
-
- - Much better conformance to RFC 1341 in the Generator.
-
- - Added __all__ support for "from mimelib import *"
-
- - Added LICENSE file, currently BSD-ish. The copyright will
- eventually be transferred to the Python Software Foundation when
- it is activated.
-
- - Bug fixes.
-
-0.1 (24-Jan-2001)
-
- Initial beta release.
-
-
-
-Local Variables:
-mode: indented-text
-indent-tabs-mode: nil
-End:
Modified: sandbox/trunk/emailpkg/3.1/README
==============================================================================
--- sandbox/trunk/emailpkg/3.1/README (original)
+++ sandbox/trunk/emailpkg/3.1/README Tue Feb 21 04:03:07 2006
@@ -1,5 +1,5 @@
email -- a mail and MIME handling package
-Copyright (C) 2001-2004 Python Software Foundation
+Copyright (C) 2001-2006 Python Software Foundation
Introduction
@@ -11,7 +11,7 @@
non-standard packages such as mimecntl. It is compliant with most of the
email related RFCs such as 2045-2047 (the MIME RFCs) and 2231.
- This version is identical to the package available in Python 2.4. It is
+ This version is identical to the package available in Python 2.5. It is
being made available as a standalone distutils package for use in older
Python releases. A minimum of Python 2.3 is required. Because the email
package is part of Python, it is covered by the PSF license for Python, as
@@ -34,7 +34,8 @@
Documentation and Examples
- The documentation can be found in the docs directory:
+ The documentation, including the major changes in the package over time,
+ can be found in the docs directory:
docs/index.html
@@ -49,17 +50,11 @@
% python setup.py install
- If you're using Python 2.4, you've already got the latest version.
-
Acknowledgements
- A big thanks goes to Ben Gertzfield who implemented the bulk of the
- multibyte support in version 1.1, as well as the RFC compliant base64 and
- quoted-printable modules.
-
- Many thanks to these other fine folks for providing code contributions or
- examples, suggestions, bug reports, feedback, encouragement, etc.
+ Here is a list of folks who have contributed code, examples, suggestions,
+ bug reports, feedback, and encouragement:
Anthony Baxter
Martin Bless
@@ -67,14 +62,17 @@
Matthew Dixon Cowles
Jeff Dairiki
Quinn Dunkan
+ Ben Gertzfield
David Given
Phil Hunt
+ Tokio Kikuchi
Sheila King
Martin Koch
Jason Mastaler
Andrew McNamara
Skip Montanaro
Guido van Rossum
+ Barry Warsaw
Thomas Wouters
Apologies to anybody I've left out (let me know!).
Added: sandbox/trunk/emailpkg/3.1/docs/about.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/about.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,108 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="prev" href="module-email.html" />
+<link rel="parent" href="mimelib.html" />
+<meta name='aesop' content='information' />
+<title>About this document ...</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.13 Examples"
+ href="node18.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="email Package Reference"
+ href="mimelib.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node18.html">2.13 Examples</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="mimelib.html">email Package Reference</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H1><A NAME="SECTION000300000000000000000">
+About this document ...</A>
+</H1>
+ <strong>email Package Reference</strong>,
+February 17, 2006, Release 4.0
+<p> This document was generated using the <a
+ href="http://saftsack.fs.uni-bayreuth.de/~latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> translator.
+</p>
+
+<p> <a
+ href="http://saftsack.fs.uni-bayreuth.de/~latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> is Copyright ©
+ 1993, 1994, 1995, 1996, 1997, <a
+ href="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos
+ Drakos</a>, Computer Based Learning Unit, University of
+ Leeds, and Copyright © 1997, 1998, <a
+ href="http://www.maths.mq.edu.au/~ross/">Ross
+ Moore</a>, Mathematics Department, Macquarie University,
+ Sydney.
+</p>
+
+<p> The application of <a
+ href="http://saftsack.fs.uni-bayreuth.de/~latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> to the Python
+ documentation has been heavily tailored by Fred L. Drake,
+ Jr. Original navigation icons were contributed by Christopher
+ Petrilli.
+</p>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.13 Examples"
+ href="node18.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="email Package Reference"
+ href="mimelib.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node18.html">2.13 Examples</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="mimelib.html">email Package Reference</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/blank.png
==============================================================================
Binary file. No diff available.
Added: sandbox/trunk/emailpkg/3.1/docs/contents.png
==============================================================================
Binary file. No diff available.
Added: sandbox/trunk/emailpkg/3.1/docs/email-dir.txt
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/email-dir.txt Tue Feb 21 04:03:07 2006
@@ -0,0 +1,115 @@
+#!/usr/bin/env python
+
+"""Send the contents of a directory as a MIME message."""
+
+import os
+import sys
+import smtplib
+# For guessing MIME type based on file name extension
+import mimetypes
+
+from optparse import OptionParser
+
+from email import encoders
+from email.message import Message
+from email.mime.audio import MIMEAudio
+from email.mime.base import MIMEBase
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+COMMASPACE = ', '
+
+
+def main():
+ parser = OptionParser(usage="""\
+Send the contents of a directory as a MIME message.
+
+Usage: %prog [options]
+
+Unless the -o option is given, the email is sent by forwarding to your local
+SMTP server, which then does the normal delivery process. Your local machine
+must be running an SMTP server.
+""")
+ parser.add_option('-d', '--directory',
+ type='string', action='store',
+ help="""Mail the contents of the specified directory,
+ otherwise use the current directory. Only the regular
+ files in the directory are sent, and we don't recurse to
+ subdirectories.""")
+ parser.add_option('-o', '--output',
+ type='string', action='store', metavar='FILE',
+ help="""Print the composed message to FILE instead of
+ sending the message to the SMTP server.""")
+ parser.add_option('-s', '--sender',
+ type='string', action='store', metavar='SENDER',
+ help='The value of the From: header (required)')
+ parser.add_option('-r', '--recipient',
+ type='string', action='append', metavar='RECIPIENT',
+ default=[], dest='recipients',
+ help='A To: header value (at least one required)')
+ opts, args = parser.parse_args()
+ if not opts.sender or not opts.recipients:
+ parser.print_help()
+ sys.exit(1)
+ directory = opts.directory
+ if not directory:
+ directory = '.'
+ # Create the enclosing (outer) message
+ outer = MIMEMultipart()
+ outer['Subject'] = 'Contents of directory %s' % os.path.abspath(directory)
+ outer['To'] = COMMASPACE.join(opts.recipients)
+ outer['From'] = opts.sender
+ outer.preamble = 'You will not see this in a MIME-aware mail reader.\n'
+
+ for filename in os.listdir(directory):
+ path = os.path.join(directory, filename)
+ if not os.path.isfile(path):
+ continue
+ # Guess the content type based on the file's extension. Encoding
+ # will be ignored, although we should check for simple things like
+ # gzip'd or compressed files.
+ ctype, encoding = mimetypes.guess_type(path)
+ if ctype is None or encoding is not None:
+ # No guess could be made, or the file is encoded (compressed), so
+ # use a generic bag-of-bits type.
+ ctype = 'application/octet-stream'
+ maintype, subtype = ctype.split('/', 1)
+ if maintype == 'text':
+ fp = open(path)
+ # Note: we should handle calculating the charset
+ msg = MIMEText(fp.read(), _subtype=subtype)
+ fp.close()
+ elif maintype == 'image':
+ fp = open(path, 'rb')
+ msg = MIMEImage(fp.read(), _subtype=subtype)
+ fp.close()
+ elif maintype == 'audio':
+ fp = open(path, 'rb')
+ msg = MIMEAudio(fp.read(), _subtype=subtype)
+ fp.close()
+ else:
+ fp = open(path, 'rb')
+ msg = MIMEBase(maintype, subtype)
+ msg.set_payload(fp.read())
+ fp.close()
+ # Encode the payload using Base64
+ encoders.encode_base64(msg)
+ # Set the filename parameter
+ msg.add_header('Content-Disposition', 'attachment', filename=filename)
+ outer.attach(msg)
+ # Now send or store the message
+ composed = outer.as_string()
+ if opts.output:
+ fp = open(opts.output, 'w')
+ fp.write(composed)
+ fp.close()
+ else:
+ s = smtplib.SMTP()
+ s.connect()
+ s.sendmail(opts.sender, opts.recipients, composed)
+ s.close()
+
+
+if __name__ == '__main__':
+ main()
Added: sandbox/trunk/emailpkg/3.1/docs/email-mime.txt
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/email-mime.txt Tue Feb 21 04:03:07 2006
@@ -0,0 +1,32 @@
+# Import smtplib for the actual sending function
+import smtplib
+
+# Here are the email package modules we'll need
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
+
+COMMASPACE = ', '
+
+# Create the container (outer) email message.
+msg = MIMEMultipart()
+msg['Subject'] = 'Our family reunion'
+# me == the sender's email address
+# family = the list of all recipients' email addresses
+msg['From'] = me
+msg['To'] = COMMASPACE.join(family)
+msg.preamble = 'Our family reunion'
+
+# Assume we know that the image files are all in PNG format
+for file in pngfiles:
+ # Open the files in binary mode. Let the MIMEImage class automatically
+ # guess the specific image type.
+ fp = open(file, 'rb')
+ img = MIMEImage(fp.read())
+ fp.close()
+ msg.attach(img)
+
+# Send the email via our own SMTP server.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, family, msg.as_string())
+s.close()
Added: sandbox/trunk/emailpkg/3.1/docs/email-simple.txt
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/email-simple.txt Tue Feb 21 04:03:07 2006
@@ -0,0 +1,25 @@
+# Import smtplib for the actual sending function
+import smtplib
+
+# Import the email modules we'll need
+from email.mime.text import MIMEText
+
+# Open a plain text file for reading. For this example, assume that
+# the text file contains only ASCII characters.
+fp = open(textfile, 'rb')
+# Create a text/plain message
+msg = MIMEText(fp.read())
+fp.close()
+
+# me == the sender's email address
+# you == the recipient's email address
+msg['Subject'] = 'The contents of %s' % textfile
+msg['From'] = me
+msg['To'] = you
+
+# Send the message via our own SMTP server, but don't include the
+# envelope header.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, [you], msg.as_string())
+s.close()
Added: sandbox/trunk/emailpkg/3.1/docs/email-unpack.txt
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/email-unpack.txt Tue Feb 21 04:03:07 2006
@@ -0,0 +1,68 @@
+#!/usr/bin/env python
+
+"""Unpack a MIME message into a directory of files."""
+
+import os
+import sys
+import email
+import errno
+import mimetypes
+
+from optparse import OptionParser
+
+
+def main():
+ parser = OptionParser(usage="""\
+Unpack a MIME message into a directory of files.
+
+Usage: %prog [options] msgfile
+""")
+ parser.add_option('-d', '--directory',
+ type='string', action='store',
+ help="""Unpack the MIME message into the named
+ directory, which will be created if it doesn't already
+ exist.""")
+ opts, args = parser.parse_args()
+ if not opts.directory:
+ parser.print_help()
+ sys.exit(1)
+
+ try:
+ msgfile = args[0]
+ except IndexError:
+ parser.print_help()
+ sys.exit(1)
+
+ try:
+ os.mkdir(opts.directory)
+ except OSError, e:
+ # Ignore directory exists error
+ if e.errno <> errno.EEXIST:
+ raise
+
+ fp = open(msgfile)
+ msg = email.message_from_file(fp)
+ fp.close()
+
+ counter = 1
+ for part in msg.walk():
+ # multipart/* are just containers
+ if part.get_content_maintype() == 'multipart':
+ continue
+ # Applications should really sanitize the given filename so that an
+ # email message can't be used to overwrite important files
+ filename = part.get_filename()
+ if not filename:
+ ext = mimetypes.guess_extension(part.get_type())
+ if not ext:
+ # Use a generic bag-of-bits extension
+ ext = '.bin'
+ filename = 'part-%03d%s' % (counter, ext)
+ counter += 1
+ fp = open(os.path.join(opts.directory, filename), 'wb')
+ fp.write(part.get_payload(decode=True))
+ fp.close()
+
+
+if __name__ == '__main__':
+ main()
Added: sandbox/trunk/emailpkg/3.1/docs/index.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/index.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,130 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="node1.html" />
+<meta name='aesop' content='information' />
+<title>email Package Reference</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></td>
+<td class='online-navigation'><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></td>
+<td class='online-navigation'><a rel="next" title="1 Introduction"
+ href="node1.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node1.html">1 Introduction</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<P>
+
+<div class="titlepage">
+<div class='center'>
+<h1>email Package Reference</h1>
+<p><b><font size="+2">Barry Warsaw</font></b></p>
+<p><span class="email">barry at python.org</span></p>
+<p><strong>Release 4.0</strong><br />
+<strong>February 17, 2006</strong></p>
+<p></p>
+</div>
+</div>
+
+<P>
+
+<H3>Abstract:</H3>
+<DIV CLASS="ABSTRACT">
+ The <tt class="module">email</tt> package provides classes and utilities to create,
+ parse, generate, and modify email messages, conforming to all the
+ relevant email and MIME related RFCs.
+</DIV>
+<P>
+
+<P>
+
+<p><br /></p><hr class='online-navigation' />
+<div class='online-navigation'>
+<!--Table of Child-Links-->
+<A NAME="CHILD_LINKS"></a>
+
+<UL CLASS="ChildLinks">
+<LI><A href="node1.html">1 Introduction</a>
+<LI><A href="module-email.html">2 <tt class="module">email</tt> --
+ An email and MIME handling package</a>
+<UL>
+<LI><A href="module-email.message.html">2.1 Representing an email message</a>
+<LI><A href="module-email.parser.html">2.2 Parsing email messages</a>
+<UL>
+<LI><A href="node5.html">2.2.1 FeedParser API</a>
+<LI><A href="node6.html">2.2.2 Parser class API</a>
+<LI><A href="node7.html">2.2.3 Additional notes</a>
+</ul>
+<LI><A href="module-email.generator.html">2.3 Generating MIME documents</a>
+<LI><A href="module-email.mime.text.html">2.4 Creating email and MIME objects from scratch</a>
+<LI><A href="module-email.header.html">2.5 Internationalized headers</a>
+<LI><A href="module-email.charset.html">2.6 Representing character sets</a>
+<LI><A href="module-email.encoders.html">2.7 Encoders</a>
+<LI><A href="module-email.errors.html">2.8 Exception and Defect classes</a>
+<LI><A href="module-email.utils.html">2.9 Miscellaneous utilities</a>
+<LI><A href="module-email.iterators.html">2.10 Iterators</a>
+<LI><A href="node16.html">2.11 Package History</a>
+<LI><A href="node17.html">2.12 Differences from <tt class="module">mimelib</tt></a>
+<LI><A href="node18.html">2.13 Examples</a>
+</ul>
+<LI><A href="about.html">About this document ...</a>
+</ul>
+<!--End of Table of Child-Links-->
+</div>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></td>
+<td class='online-navigation'><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></td>
+<td class='online-navigation'><a rel="next" title="1 Introduction"
+ href="node1.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node1.html">1 Introduction</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/index.png
==============================================================================
Binary file. No diff available.
Added: sandbox/trunk/emailpkg/3.1/docs/mimelib.css
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/mimelib.css Tue Feb 21 04:03:07 2006
@@ -0,0 +1,243 @@
+/*
+ * The first part of this is the standard CSS generated by LaTeX2HTML,
+ * with the "empty" declarations removed.
+ */
+
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.math { font-family: "Century Schoolbook", serif; }
+.math i { font-family: "Century Schoolbook", serif;
+ font-weight: bold }
+.boldmath { font-family: "Century Schoolbook", serif;
+ font-weight: bold }
+
+/*
+ * Implement both fixed-size and relative sizes.
+ *
+ * I think these can be safely removed, as it doesn't appear that
+ * LaTeX2HTML ever generates these, even though these are carried
+ * over from the LaTeX2HTML stylesheet.
+ */
+small.xtiny { font-size : xx-small; }
+small.tiny { font-size : x-small; }
+small.scriptsize { font-size : smaller; }
+small.footnotesize { font-size : small; }
+big.xlarge { font-size : large; }
+big.xxlarge { font-size : x-large; }
+big.huge { font-size : larger; }
+big.xhuge { font-size : xx-large; }
+
+/*
+ * Document-specific styles come next;
+ * these are added for the Python documentation.
+ *
+ * Note that the size specifications for the H* elements are because
+ * Netscape on Solaris otherwise doesn't get it right; they all end up
+ * the normal text size.
+ */
+
+body { color: #000000;
+ background-color: #ffffff; }
+
+a:link:active { color: #ff0000; }
+a:link:hover { background-color: #bbeeff; }
+a:visited:hover { background-color: #bbeeff; }
+a:visited { color: #551a8b; }
+a:link { color: #0000bb; }
+
+h1, h2, h3, h4, h5, h6 { font-family: avantgarde, sans-serif;
+ font-weight: bold; }
+h1 { font-size: 180%; }
+h2 { font-size: 150%; }
+h3, h4 { font-size: 120%; }
+
+/* These are section titles used in navigation links, so make sure we
+ * match the section header font here, even it not the weight.
+ */
+.sectref { font-family: avantgarde, sans-serif; }
+/* And the label before the titles in navigation: */
+.navlabel { font-size: 85%; }
+
+
+/* LaTeX2HTML insists on inserting <br> elements into headers which
+ * are marked with \label. This little bit of CSS magic ensures that
+ * these elements don't cause spurious whitespace to be added.
+ */
+h1>br, h2>br, h3>br,
+h4>br, h5>br, h6>br { display: none; }
+
+code, tt { font-family: "lucida typewriter", lucidatypewriter,
+ monospace; }
+var { font-family: times, serif;
+ font-style: italic;
+ font-weight: normal; }
+
+.Unix { font-variant: small-caps; }
+
+.typelabel { font-family: lucida, sans-serif; }
+
+.navigation td { background-color: #99ccff;
+ font-weight: bold;
+ font-family: avantgarde, sans-serif;
+ font-size: 110%; }
+
+div.warning { background-color: #fffaf0;
+ border: thin solid black;
+ padding: 1em;
+ margin-left: 2em;
+ margin-right: 2em; }
+
+div.warning .label { font-family: sans-serif;
+ font-size: 110%;
+ margin-right: 0.5em; }
+
+div.note { background-color: #fffaf0;
+ border: thin solid black;
+ padding: 1em;
+ margin-left: 2em;
+ margin-right: 2em; }
+
+div.note .label { margin-right: 0.5em;
+ font-family: sans-serif; }
+
+address { font-size: 80%; }
+.release-info { font-style: italic;
+ font-size: 80%; }
+
+.titlegraphic { vertical-align: top; }
+
+.verbatim pre { color: #00008b;
+ font-family: "lucida typewriter", lucidatypewriter,
+ monospace;
+ font-size: 90%; }
+.verbatim { margin-left: 2em; }
+.verbatim .footer { padding: 0.05in;
+ font-size: 85%;
+ background-color: #99ccff;
+ margin-right: 0.5in; }
+
+.grammar { background-color: #99ccff;
+ margin-right: 0.5in;
+ padding: 0.05in; }
+.grammar-footer { padding: 0.05in;
+ font-size: 85%; }
+.grammartoken { font-family: "lucida typewriter", lucidatypewriter,
+ monospace; }
+
+.productions { background-color: #bbeeff; }
+.productions a:active { color: #ff0000; }
+.productions a:link:hover { background-color: #99ccff; }
+.productions a:visited:hover { background-color: #99ccff; }
+.productions a:visited { color: #551a8b; }
+.productions a:link { color: #0000bb; }
+.productions table { vertical-align: baseline;
+ empty-cells: show; }
+.productions > table td,
+.productions > table th { padding: 2px; }
+.productions > table td:first-child,
+.productions > table td:last-child {
+ font-family: "lucida typewriter",
+ lucidatypewriter,
+ monospace;
+ }
+/* same as the second selector above, but expressed differently for Opera */
+.productions > table td:first-child + td + td {
+ font-family: "lucida typewriter",
+ lucidatypewriter,
+ monospace;
+ vertical-align: baseline;
+ }
+.productions > table td:first-child + td {
+ padding-left: 1em;
+ padding-right: 1em;
+ }
+.productions > table tr { vertical-align: baseline; }
+
+.email { font-family: avantgarde, sans-serif; }
+.mailheader { font-family: avantgarde, sans-serif; }
+.mimetype { font-family: avantgarde, sans-serif; }
+.newsgroup { font-family: avantgarde, sans-serif; }
+.url { font-family: avantgarde, sans-serif; }
+.file { font-family: avantgarde, sans-serif; }
+.guilabel { font-family: avantgarde, sans-serif; }
+
+.realtable { border-collapse: collapse;
+ border-color: black;
+ border-style: solid;
+ border-width: 0px 0px 2px 0px;
+ empty-cells: show;
+ margin-left: auto;
+ margin-right: auto;
+ padding-left: 0.4em;
+ padding-right: 0.4em;
+ }
+.realtable tbody { vertical-align: baseline; }
+.realtable tfoot { display: table-footer-group; }
+.realtable thead { background-color: #99ccff;
+ border-width: 0px 0px 2px 1px;
+ display: table-header-group;
+ font-family: avantgarde, sans-serif;
+ font-weight: bold;
+ vertical-align: baseline;
+ }
+.realtable thead :first-child {
+ border-width: 0px 0px 2px 0px;
+ }
+.realtable thead th { border-width: 0px 0px 2px 1px }
+.realtable td,
+.realtable th { border-color: black;
+ border-style: solid;
+ border-width: 0px 0px 1px 1px;
+ padding-left: 0.4em;
+ padding-right: 0.4em;
+ }
+.realtable td:first-child,
+.realtable th:first-child {
+ border-left-width: 0px;
+ vertical-align: baseline;
+ }
+.center { text-align: center; }
+.left { text-align: left; }
+.right { text-align: right; }
+
+.refcount-info { font-style: italic; }
+.refcount-info .value { font-weight: bold;
+ color: #006600; }
+
+/*
+ * Some decoration for the "See also:" blocks, in part inspired by some of
+ * the styling on Lars Marius Garshol's XSA pages.
+ * (The blue in the navigation bars is #99CCFF.)
+ */
+.seealso { background-color: #fffaf0;
+ border: thin solid black;
+ padding: 0pt 1em 4pt 1em; }
+
+.seealso > .heading { font-size: 110%;
+ font-weight: bold; }
+
+/*
+ * Class 'availability' is used for module availability statements at
+ * the top of modules.
+ */
+.availability .platform { font-weight: bold; }
+
+
+/*
+ * Additional styles for the distutils package.
+ */
+.du-command { font-family: monospace; }
+.du-option { font-family: avantgarde, sans-serif; }
+.du-filevar { font-family: avantgarde, sans-serif;
+ font-style: italic; }
+.du-xxx:before { content: "** ";
+ font-weight: bold; }
+.du-xxx:after { content: " **";
+ font-weight: bold; }
+
+
+/*
+ * Some specialization for printed output.
+ */
+ at media print {
+ .online-navigation { display: none; }
+ }
Added: sandbox/trunk/emailpkg/3.1/docs/mimelib.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/mimelib.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,130 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="node1.html" />
+<meta name='aesop' content='information' />
+<title>email Package Reference</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></td>
+<td class='online-navigation'><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></td>
+<td class='online-navigation'><a rel="next" title="1 Introduction"
+ href="node1.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node1.html">1 Introduction</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<P>
+
+<div class="titlepage">
+<div class='center'>
+<h1>email Package Reference</h1>
+<p><b><font size="+2">Barry Warsaw</font></b></p>
+<p><span class="email">barry at python.org</span></p>
+<p><strong>Release 4.0</strong><br />
+<strong>February 17, 2006</strong></p>
+<p></p>
+</div>
+</div>
+
+<P>
+
+<H3>Abstract:</H3>
+<DIV CLASS="ABSTRACT">
+ The <tt class="module">email</tt> package provides classes and utilities to create,
+ parse, generate, and modify email messages, conforming to all the
+ relevant email and MIME related RFCs.
+</DIV>
+<P>
+
+<P>
+
+<p><br /></p><hr class='online-navigation' />
+<div class='online-navigation'>
+<!--Table of Child-Links-->
+<A NAME="CHILD_LINKS"></a>
+
+<UL CLASS="ChildLinks">
+<LI><A href="node1.html">1 Introduction</a>
+<LI><A href="module-email.html">2 <tt class="module">email</tt> --
+ An email and MIME handling package</a>
+<UL>
+<LI><A href="module-email.message.html">2.1 Representing an email message</a>
+<LI><A href="module-email.parser.html">2.2 Parsing email messages</a>
+<UL>
+<LI><A href="node5.html">2.2.1 FeedParser API</a>
+<LI><A href="node6.html">2.2.2 Parser class API</a>
+<LI><A href="node7.html">2.2.3 Additional notes</a>
+</ul>
+<LI><A href="module-email.generator.html">2.3 Generating MIME documents</a>
+<LI><A href="module-email.mime.text.html">2.4 Creating email and MIME objects from scratch</a>
+<LI><A href="module-email.header.html">2.5 Internationalized headers</a>
+<LI><A href="module-email.charset.html">2.6 Representing character sets</a>
+<LI><A href="module-email.encoders.html">2.7 Encoders</a>
+<LI><A href="module-email.errors.html">2.8 Exception and Defect classes</a>
+<LI><A href="module-email.utils.html">2.9 Miscellaneous utilities</a>
+<LI><A href="module-email.iterators.html">2.10 Iterators</a>
+<LI><A href="node16.html">2.11 Package History</a>
+<LI><A href="node17.html">2.12 Differences from <tt class="module">mimelib</tt></a>
+<LI><A href="node18.html">2.13 Examples</a>
+</ul>
+<LI><A href="about.html">About this document ...</a>
+</ul>
+<!--End of Table of Child-Links-->
+</div>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></td>
+<td class='online-navigation'><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></td>
+<td class='online-navigation'><a rel="next" title="1 Introduction"
+ href="node1.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node1.html">1 Introduction</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.charset.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.charset.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,437 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.encoders.html" />
+<link rel="prev" href="module-email.header.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.encoders.html" />
+<meta name='aesop' content='information' />
+<title>2.6 Representing character sets</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.5 Internationalized headers"
+ href="module-email.header.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.7 Encoders"
+ href="module-email.encoders.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.header.html">2.5 Internationalized headers</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.encoders.html">2.7 Encoders</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000260000000000000000">
+2.6 Representing character sets</A>
+</H2>
+<A NAME="module-email.charset"></A>
+
+<P>
+This module provides a class <tt class="class">Charset</tt> for representing
+character sets and character set conversions in email messages, as
+well as a character set registry and several convenience methods for
+manipulating this registry. Instances of <tt class="class">Charset</tt> are used in
+several other modules within the <tt class="module">email</tt> package.
+
+<P>
+Import this class from the <tt class="module">email.charset</tt> module.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-87' xml:id='l2h-87' class="class">Charset</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>input_charset</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Map character sets to their email properties.
+
+<P>
+This class provides information about the requirements imposed on
+email for a specific character set. It also provides convenience
+routines for converting between character sets, given the availability
+of the applicable codecs. Given a character set, it will do its best
+to provide information on how to use that character set in an email
+message in an RFC-compliant way.
+
+<P>
+Certain character sets must be encoded with quoted-printable or base64
+when used in email headers or bodies. Certain character sets must be
+converted outright, and are not allowed in email.
+
+<P>
+Optional <var>input_charset</var> is as described below; it is always
+coerced to lower case. After being alias normalized it is also used
+as a lookup into the registry of character sets to find out the header
+encoding, body encoding, and output conversion codec to be used for
+the character set. For example, if
+<var>input_charset</var> is <code>iso-8859-1</code>, then headers and bodies will
+be encoded using quoted-printable and no output conversion codec is
+necessary. If <var>input_charset</var> is <code>euc-jp</code>, then headers will
+be encoded with base64, bodies will not be encoded, but output text
+will be converted from the <code>euc-jp</code> character set to the
+<code>iso-2022-jp</code> character set.
+</dl>
+
+<P>
+<tt class="class">Charset</tt> instances have the following data attributes:
+
+<P>
+<dl><dt><b><tt id='l2h-88' xml:id='l2h-88'>input_charset</tt></b></dt>
+<dd>
+The initial character set specified. Common aliases are converted to
+their <em>official</em> email names (e.g. <code>latin_1</code> is converted to
+<code>iso-8859-1</code>). Defaults to 7-bit <code>us-ascii</code>.
+</dd></dl>
+
+<P>
+<dl><dt><b><tt id='l2h-89' xml:id='l2h-89'>header_encoding</tt></b></dt>
+<dd>
+If the character set must be encoded before it can be used in an
+email header, this attribute will be set to <code>Charset.QP</code> (for
+quoted-printable), <code>Charset.BASE64</code> (for base64 encoding), or
+<code>Charset.SHORTEST</code> for the shortest of QP or BASE64 encoding.
+Otherwise, it will be <code>None</code>.
+</dd></dl>
+
+<P>
+<dl><dt><b><tt id='l2h-90' xml:id='l2h-90'>body_encoding</tt></b></dt>
+<dd>
+Same as <var>header_encoding</var>, but describes the encoding for the
+mail message's body, which indeed may be different than the header
+encoding. <code>Charset.SHORTEST</code> is not allowed for
+<var>body_encoding</var>.
+</dd></dl>
+
+<P>
+<dl><dt><b><tt id='l2h-91' xml:id='l2h-91'>output_charset</tt></b></dt>
+<dd>
+Some character sets must be converted before they can be used in
+email headers or bodies. If the <var>input_charset</var> is one of
+them, this attribute will contain the name of the character set
+output will be converted to. Otherwise, it will be <code>None</code>.
+</dd></dl>
+
+<P>
+<dl><dt><b><tt id='l2h-92' xml:id='l2h-92'>input_codec</tt></b></dt>
+<dd>
+The name of the Python codec used to convert the <var>input_charset</var> to
+Unicode. If no conversion codec is necessary, this attribute will be
+<code>None</code>.
+</dd></dl>
+
+<P>
+<dl><dt><b><tt id='l2h-93' xml:id='l2h-93'>output_codec</tt></b></dt>
+<dd>
+The name of the Python codec used to convert Unicode to the
+<var>output_charset</var>. If no conversion codec is necessary, this
+attribute will have the same value as the <var>input_codec</var>.
+</dd></dl>
+
+<P>
+<tt class="class">Charset</tt> instances also have the following methods:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-94' xml:id='l2h-94' class="method">get_body_encoding</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the content transfer encoding used for body encoding.
+
+<P>
+This is either the string "<tt class="samp">quoted-printable</tt>" or "<tt class="samp">base64</tt>"depending on the encoding used, or it is a function, in which case you
+should call the function with a single argument, the Message object
+being encoded. The function should then set the
+<span class="mailheader">Content-Transfer-Encoding:</span> header itself to whatever is
+appropriate.
+
+<P>
+Returns the string "<tt class="samp">quoted-printable</tt>" if
+<var>body_encoding</var> is <code>QP</code>, returns the string
+"<tt class="samp">base64</tt>" if <var>body_encoding</var> is <code>BASE64</code>, and returns the
+string "<tt class="samp">7bit</tt>" otherwise.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-95' xml:id='l2h-95' class="method">convert</tt></b>(</nobr></td>
+ <td><var>s</var>)</td></tr></table></dt>
+<dd>
+Convert the string <var>s</var> from the <var>input_codec</var> to the
+<var>output_codec</var>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-96' xml:id='l2h-96' class="method">to_splittable</tt></b>(</nobr></td>
+ <td><var>s</var>)</td></tr></table></dt>
+<dd>
+Convert a possibly multibyte string to a safely splittable format.
+<var>s</var> is the string to split.
+
+<P>
+Uses the <var>input_codec</var> to try and convert the string to Unicode,
+so it can be safely split on character boundaries (even for multibyte
+characters).
+
+<P>
+Returns the string as-is if it isn't known how to convert <var>s</var> to
+Unicode with the <var>input_charset</var>.
+
+<P>
+Characters that could not be converted to Unicode will be replaced
+with the Unicode replacement character "<tt class="character">U+FFFD</tt>".
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-97' xml:id='l2h-97' class="method">from_splittable</tt></b>(</nobr></td>
+ <td><var>ustr</var><big>[</big><var>, to_output</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Convert a splittable string back into an encoded string. <var>ustr</var>
+is a Unicode string to ``unsplit''.
+
+<P>
+This method uses the proper codec to try and convert the string from
+Unicode back into an encoded format. Return the string as-is if it is
+not Unicode, or if it could not be converted from Unicode.
+
+<P>
+Characters that could not be converted from Unicode will be replaced
+with an appropriate character (usually "<tt class="character">?</tt>").
+
+<P>
+If <var>to_output</var> is <code>True</code> (the default), uses
+<var>output_codec</var> to convert to an
+encoded format. If <var>to_output</var> is <code>False</code>, it uses
+<var>input_codec</var>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-98' xml:id='l2h-98' class="method">get_output_charset</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the output character set.
+
+<P>
+This is the <var>output_charset</var> attribute if that is not <code>None</code>,
+otherwise it is <var>input_charset</var>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-99' xml:id='l2h-99' class="method">encoded_header_len</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the length of the encoded header string, properly calculating
+for quoted-printable or base64 encoding.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-100' xml:id='l2h-100' class="method">header_encode</tt></b>(</nobr></td>
+ <td><var>s</var><big>[</big><var>, convert</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Header-encode the string <var>s</var>.
+
+<P>
+If <var>convert</var> is <code>True</code>, the string will be converted from the
+input charset to the output charset automatically. This is not useful
+for multibyte character sets, which have line length issues (multibyte
+characters must be split on a character, not a byte boundary); use the
+higher-level <tt class="class">Header</tt> class to deal with these issues (see
+<tt class="module"><a href="module-email.header.html">email.header</a></tt>). <var>convert</var> defaults to <code>False</code>.
+
+<P>
+The type of encoding (base64 or quoted-printable) will be based on
+the <var>header_encoding</var> attribute.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-101' xml:id='l2h-101' class="method">body_encode</tt></b>(</nobr></td>
+ <td><var>s</var><big>[</big><var>, convert</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Body-encode the string <var>s</var>.
+
+<P>
+If <var>convert</var> is <code>True</code> (the default), the string will be
+converted from the input charset to output charset automatically.
+Unlike <tt class="method">header_encode()</tt>, there are no issues with byte
+boundaries and multibyte charsets in email bodies, so this is usually
+pretty safe.
+
+<P>
+The type of encoding (base64 or quoted-printable) will be based on
+the <var>body_encoding</var> attribute.
+</dl>
+
+<P>
+The <tt class="class">Charset</tt> class also provides a number of methods to support
+standard operations and built-in functions.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-102' xml:id='l2h-102' class="method">__str__</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Returns <var>input_charset</var> as a string coerced to lower case.
+<tt class="method">__repr__()</tt> is an alias for <tt class="method">__str__()</tt>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-103' xml:id='l2h-103' class="method">__eq__</tt></b>(</nobr></td>
+ <td><var>other</var>)</td></tr></table></dt>
+<dd>
+This method allows you to compare two <tt class="class">Charset</tt> instances for equality.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-104' xml:id='l2h-104' class="method">__ne__</tt></b>(</nobr></td>
+ <td><var>other</var>)</td></tr></table></dt>
+<dd>
+This method allows you to compare two <tt class="class">Charset</tt> instances for inequality.
+</dl>
+
+<P>
+The <tt class="module">email.charset</tt> module also provides the following
+functions for adding new entries to the global character set, alias,
+and codec registries:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-105' xml:id='l2h-105' class="function">add_charset</tt></b>(</nobr></td>
+ <td><var>charset</var><big>[</big><var>, header_enc</var><big>[</big><var>,
+ body_enc</var><big>[</big><var>, output_charset</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Add character properties to the global registry.
+
+<P>
+<var>charset</var> is the input character set, and must be the canonical
+name of a character set.
+
+<P>
+Optional <var>header_enc</var> and <var>body_enc</var> is either
+<code>Charset.QP</code> for quoted-printable, <code>Charset.BASE64</code> for
+base64 encoding, <code>Charset.SHORTEST</code> for the shortest of
+quoted-printable or base64 encoding, or <code>None</code> for no encoding.
+<code>SHORTEST</code> is only valid for <var>header_enc</var>. The default is
+<code>None</code> for no encoding.
+
+<P>
+Optional <var>output_charset</var> is the character set that the output
+should be in. Conversions will proceed from input charset, to
+Unicode, to the output charset when the method
+<tt class="method">Charset.convert()</tt> is called. The default is to output in the
+same character set as the input.
+
+<P>
+Both <var>input_charset</var> and <var>output_charset</var> must have Unicode
+codec entries in the module's character set-to-codec mapping; use
+<tt class="function">add_codec()</tt> to add codecs the module does
+not know about. See the <tt class="module"><a href="module-codecs.html">codecs</a></tt> module's documentation for
+more information.
+
+<P>
+The global character set registry is kept in the module global
+dictionary <code>CHARSETS</code>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-106' xml:id='l2h-106' class="function">add_alias</tt></b>(</nobr></td>
+ <td><var>alias, canonical</var>)</td></tr></table></dt>
+<dd>
+Add a character set alias. <var>alias</var> is the alias name,
+e.g. <code>latin-1</code>. <var>canonical</var> is the character set's canonical
+name, e.g. <code>iso-8859-1</code>.
+
+<P>
+The global charset alias registry is kept in the module global
+dictionary <code>ALIASES</code>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-107' xml:id='l2h-107' class="function">add_codec</tt></b>(</nobr></td>
+ <td><var>charset, codecname</var>)</td></tr></table></dt>
+<dd>
+Add a codec that map characters in the given character set to and from
+Unicode.
+
+<P>
+<var>charset</var> is the canonical name of a character set.
+<var>codecname</var> is the name of a Python codec, as appropriate for the
+second argument to the <tt class="function">unicode()</tt> built-in, or to the
+<tt class="method">encode()</tt> method of a Unicode string.
+</dl>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.5 Internationalized headers"
+ href="module-email.header.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.7 Encoders"
+ href="module-email.encoders.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.header.html">2.5 Internationalized headers</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.encoders.html">2.7 Encoders</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.encoders.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.encoders.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,165 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.errors.html" />
+<link rel="prev" href="module-email.charset.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.errors.html" />
+<meta name='aesop' content='information' />
+<title>2.7 Encoders</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.6 Representing character sets"
+ href="module-email.charset.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.8 Exception and Defect"
+ href="module-email.errors.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.charset.html">2.6 Representing character sets</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.errors.html">2.8 Exception and Defect</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000270000000000000000">
+2.7 Encoders</A>
+</H2>
+<A NAME="module-email.encoders"></A>
+
+<P>
+When creating <tt class="class">Message</tt> objects from scratch, you often need to
+encode the payloads for transport through compliant mail servers.
+This is especially true for <span class="mimetype">image/*</span> and <span class="mimetype">text/*</span>
+type messages containing binary data.
+
+<P>
+The <tt class="module">email</tt> package provides some convenient encodings in its
+<tt class="module">encoders</tt> module. These encoders are actually used by the
+<tt class="class">MIMEAudio</tt> and <tt class="class">MIMEImage</tt> class constructors to provide default
+encodings. All encoder functions take exactly one argument, the 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
+<span class="mailheader">Content-Transfer-Encoding:</span> header as appropriate.
+
+<P>
+Here are the encoding functions provided:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-109' xml:id='l2h-109' class="function">encode_quopri</tt></b>(</nobr></td>
+ <td><var>msg</var>)</td></tr></table></dt>
+<dd>
+Encodes the payload into quoted-printable form and sets the
+<span class="mailheader">Content-Transfer-Encoding:</span> header to
+<code>quoted-printable</code><A NAME="tex2html35"
+ HREF="#foot2068"><SUP>2</SUP></A>.
+This is a good encoding to use when most of your payload is normal
+printable data, but contains a few unprintable characters.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-110' xml:id='l2h-110' class="function">encode_base64</tt></b>(</nobr></td>
+ <td><var>msg</var>)</td></tr></table></dt>
+<dd>
+Encodes the payload into base64 form and sets the
+<span class="mailheader">Content-Transfer-Encoding:</span> header to
+<code>base64</code>. This is a good encoding to use when most of your payload
+is unprintable data since it is a more compact form than
+quoted-printable. The drawback of base64 encoding is that it
+renders the text non-human readable.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-111' xml:id='l2h-111' class="function">encode_7or8bit</tt></b>(</nobr></td>
+ <td><var>msg</var>)</td></tr></table></dt>
+<dd>
+This doesn't actually modify the message's payload, but it does set
+the <span class="mailheader">Content-Transfer-Encoding:</span> header to either <code>7bit</code> or
+<code>8bit</code> as appropriate, based on the payload data.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-112' xml:id='l2h-112' class="function">encode_noop</tt></b>(</nobr></td>
+ <td><var>msg</var>)</td></tr></table></dt>
+<dd>
+This does nothing; it doesn't even set the
+<span class="mailheader">Content-Transfer-Encoding:</span> header.
+</dl>
+
+<P>
+<BR><HR><H4>Footnotes</H4>
+<DL>
+<DT><A NAME="foot2068">...quoted-printable</A><A
+ href="module-email.encoders.html#tex2html35"><SUP>2</SUP></A></DT>
+<DD>Note that encoding with
+<tt class="method">encode_quopri()</tt> also encodes all tabs and space characters in
+the data.
+
+</DD>
+</DL>
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.6 Representing character sets"
+ href="module-email.charset.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.8 Exception and Defect"
+ href="module-email.errors.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.charset.html">2.6 Representing character sets</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.errors.html">2.8 Exception and Defect</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.errors.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.errors.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,224 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.utils.html" />
+<link rel="prev" href="module-email.encoders.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.utils.html" />
+<meta name='aesop' content='information' />
+<title>2.8 Exception and Defect classes</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.7 Encoders"
+ href="module-email.encoders.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.9 Miscellaneous utilities"
+ href="module-email.utils.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.encoders.html">2.7 Encoders</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.utils.html">2.9 Miscellaneous utilities</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000280000000000000000">
+2.8 Exception and Defect classes</A>
+</H2>
+<A NAME="module-email.errors"></A>
+
+<P>
+The following exception classes are defined in the
+<tt class="module">email.errors</tt> module:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">exception</span> <tt id='l2h-114' xml:id='l2h-114' class="exception">MessageError</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+This is the base class for all exceptions that the <tt class="module">email</tt>
+package can raise. It is derived from the standard
+<tt class="exception">Exception</tt> class and defines no additional methods.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">exception</span> <tt id='l2h-115' xml:id='l2h-115' class="exception">MessageParseError</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+This is the base class for exceptions thrown by the <tt class="class">Parser</tt>
+class. It is derived from <tt class="exception">MessageError</tt>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">exception</span> <tt id='l2h-116' xml:id='l2h-116' class="exception">HeaderParseError</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Raised under some error conditions when parsing the <a class="rfc" id='rfcref-3231' xml:id='rfcref-3231'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> headers of
+a message, this class is derived from <tt class="exception">MessageParseError</tt>.
+It can be raised from the <tt class="method">Parser.parse()</tt> or
+<tt class="method">Parser.parsestr()</tt> methods.
+
+<P>
+Situations where it can be raised include finding an envelope
+header after the first <a class="rfc" id='rfcref-3233' xml:id='rfcref-3233'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> header of the message, finding a
+continuation line before the first <a class="rfc" id='rfcref-3235' xml:id='rfcref-3235'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> header is found, or finding
+a line in the headers which is neither a header or a continuation
+line.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">exception</span> <tt id='l2h-117' xml:id='l2h-117' class="exception">BoundaryError</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Raised under some error conditions when parsing the <a class="rfc" id='rfcref-3237' xml:id='rfcref-3237'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> headers of
+a message, this class is derived from <tt class="exception">MessageParseError</tt>.
+It can be raised from the <tt class="method">Parser.parse()</tt> or
+<tt class="method">Parser.parsestr()</tt> methods.
+
+<P>
+Situations where it can be raised include not being able to find the
+starting or terminating boundary in a <span class="mimetype">multipart/*</span> message
+when strict parsing is used.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">exception</span> <tt id='l2h-118' xml:id='l2h-118' class="exception">MultipartConversionError</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Raised when a payload is added to a <tt class="class">Message</tt> object using
+<tt class="method">add_payload()</tt>, but the payload is already a scalar and the
+message's <span class="mailheader">Content-Type:</span> main type is not either
+<span class="mimetype">multipart</span> or missing. <tt class="exception">MultipartConversionError</tt>
+multiply inherits from <tt class="exception">MessageError</tt> and the built-in
+<tt class="exception">TypeError</tt>.
+
+<P>
+Since <tt class="method">Message.add_payload()</tt> is deprecated, this exception is
+rarely raised in practice. However the exception may also be raised
+if the <tt class="method">attach()</tt> method is called on an instance of a class
+derived from <tt class="class">MIMENonMultipart</tt> (e.g. <tt class="class">MIMEImage</tt>).
+</dl>
+
+<P>
+Here's the list of the defects that the <tt class="class">FeedParser</tt> can find while
+parsing messages. Note that the defects are added to the message where the
+problem was found, so for example, if a message nested inside a
+<span class="mimetype">multipart/alternative</span> had a malformed header, that nested message
+object would have a defect, but the containing messages would not.
+
+<P>
+All defect classes are subclassed from <tt class="class">email.errors.MessageDefect</tt>, but
+this class is <em>not</em> an exception!
+
+<P>
+
+<span class="versionnote">New in version 2.4:
+All the defect classes were added.</span>
+
+<P>
+
+<UL>
+<LI><tt class="class">NoBoundaryInMultipartDefect</tt> - A message claimed to be a
+ multipart, but had no <span class="mimetype">boundary</span> parameter.
+
+<P>
+</LI>
+<LI><tt class="class">StartBoundaryNotFoundDefect</tt> - The start boundary claimed in the
+ <span class="mailheader">Content-Type:</span> header was never found.
+
+<P>
+</LI>
+<LI><tt class="class">FirstHeaderLineIsContinuationDefect</tt> - The message had a
+ continuation line as its first header line.
+
+<P>
+</LI>
+<LI><tt class="class">MisplacedEnvelopeHeaderDefect</tt> - A ``Unix From'' header was found
+ in the middle of a header block.
+
+<P>
+</LI>
+<LI><tt class="class">MalformedHeaderDefect</tt> - A header was found that was missing a
+ colon, or was otherwise malformed.
+
+<P>
+</LI>
+<LI><tt class="class">MultipartInvariantViolationDefect</tt> - A message claimed to be a
+ <span class="mimetype">multipart</span>, but no subparts were found. Note that when a
+ message has this defect, its <tt class="method">is_multipart()</tt> method may return
+ false even though its content type claims to be <span class="mimetype">multipart</span>.
+</LI>
+</UL>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.7 Encoders"
+ href="module-email.encoders.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.9 Miscellaneous utilities"
+ href="module-email.utils.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.encoders.html">2.7 Encoders</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.utils.html">2.9 Miscellaneous utilities</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.generator.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.generator.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,286 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.mime.text.html" />
+<link rel="prev" href="module-email.parser.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.mime.text.html" />
+<meta name='aesop' content='information' />
+<title>2.3 Generating MIME documents</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2.3 Additional notes"
+ href="node7.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.4 Creating email and"
+ href="module-email.mime.text.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node7.html">2.2.3 Additional notes</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.mime.text.html">2.4 Creating email and</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000230000000000000000">
+2.3 Generating MIME documents</A>
+</H2>
+<A NAME="module-email.generator"></A>
+
+<P>
+One of the most common tasks is to generate the flat text of the email
+message represented by a message object structure. You will need to do
+this if you want to send your message via the <tt class="module"><a href="module-smtplib.html">smtplib</a></tt>
+module or the <tt class="module"><a href="module-nntplib.html">nntplib</a></tt> module, or print the message on the
+console. Taking a message object structure and producing a flat text
+document is the job of the <tt class="class">Generator</tt> class.
+
+<P>
+Again, as with the <tt class="module"><a href="module-email.parser.html">email.parser</a></tt> 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 a message structure via the
+<tt class="class">Parser</tt> class, and back to flat text, is idempotent (the input
+is identical to the output).
+
+<P>
+Here are the public methods of the <tt class="class">Generator</tt> class, imported from the
+<tt class="module">email.generator</tt> module:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-56' xml:id='l2h-56' class="class">Generator</tt></b>(</nobr></td>
+ <td><var>outfp</var><big>[</big><var>, mangle_from_</var><big>[</big><var>,
+ maxheaderlen</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+The constructor for the <tt class="class">Generator</tt> class takes a file-like
+object called <var>outfp</var> for an argument. <var>outfp</var> must support
+the <tt class="method">write()</tt> method and be usable as the output file in a
+Python extended print statement.
+
+<P>
+Optional <var>mangle_from_</var> is a flag that, when <code>True</code>, puts a
+"<tt class="samp">></tt>" character in front of any line in the body that starts exactly as
+"<tt class="samp">From </tt>", i.e. <code>From</code> followed by a space at the beginning of the
+line. This is the only guaranteed portable way to avoid having such
+lines be mistaken for a Unix mailbox format envelope header separator (see
+<a class="ulink" href="http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html"
+ >WHY THE CONTENT-LENGTH FORMAT IS BAD</a>
+for details). <var>mangle_from_</var> defaults to <code>True</code>, but you
+might want to set this to <code>False</code> if you are not writing Unix
+mailbox format files.
+
+<P>
+Optional <var>maxheaderlen</var> specifies the longest length for a
+non-continued header. When a header line is longer than
+<var>maxheaderlen</var> (in characters, with tabs expanded to 8 spaces),
+the header will be split as defined in the <tt class="module">email.header.Header</tt>
+class. Set to zero to disable header wrapping. The default is 78, as
+recommended (but not required) by <a class="rfc" id='rfcref-3133' xml:id='rfcref-3133'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>.
+</dl>
+
+<P>
+The other public <tt class="class">Generator</tt> methods are:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-57' xml:id='l2h-57' class="method">flatten</tt></b>(</nobr></td>
+ <td><var>msg</var><big>[</big><var>, unixfrom</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Print the textual representation of the message object structure rooted at
+<var>msg</var> to the output file specified when the <tt class="class">Generator</tt>
+instance was created. Subparts are visited depth-first and the
+resulting text will be properly MIME encoded.
+
+<P>
+Optional <var>unixfrom</var> is a flag that forces the printing of the
+envelope header delimiter before the first <a class="rfc" id='rfcref-3135' xml:id='rfcref-3135'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> header of the
+root message object. If the root object has no envelope header, a
+standard one is crafted. By default, this is set to <code>False</code> to
+inhibit the printing of the envelope delimiter.
+
+<P>
+Note that for subparts, no envelope header is ever printed.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-58' xml:id='l2h-58' class="method">clone</tt></b>(</nobr></td>
+ <td><var>fp</var>)</td></tr></table></dt>
+<dd>
+Return an independent clone of this <tt class="class">Generator</tt> instance with
+the exact same options.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-59' xml:id='l2h-59' class="method">write</tt></b>(</nobr></td>
+ <td><var>s</var>)</td></tr></table></dt>
+<dd>
+Write the string <var>s</var> to the underlying file object,
+i.e. <var>outfp</var> passed to <tt class="class">Generator</tt>'s constructor. This
+provides just enough file-like API for <tt class="class">Generator</tt> instances to
+be used in extended print statements.
+</dl>
+
+<P>
+As a convenience, see the methods <tt class="method">Message.as_string()</tt> and
+<code>str(aMessage)</code>, a.k.a. <tt class="method">Message.__str__()</tt>, which
+simplify the generation of a formatted string representation of a
+message object. For more detail, see <tt class="module"><a href="module-email.message.html">email.message</a></tt>.
+
+<P>
+The <tt class="module">email.generator</tt> module also provides a derived class,
+called <tt class="class">DecodedGenerator</tt> which is like the <tt class="class">Generator</tt>
+base class, except that non-<span class="mimetype">text</span> parts are substituted with
+a format string representing the part.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-60' xml:id='l2h-60' class="class">DecodedGenerator</tt></b>(</nobr></td>
+ <td><var>outfp</var><big>[</big><var>, mangle_from_</var><big>[</big><var>,
+ maxheaderlen</var><big>[</big><var>, fmt</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+
+<P>
+This class, derived from <tt class="class">Generator</tt> walks through all the
+subparts of a message. If the subpart is of main type
+<span class="mimetype">text</span>, then it prints the decoded payload of the subpart.
+Optional <var>_mangle_from_</var> and <var>maxheaderlen</var> are as with the
+<tt class="class">Generator</tt> base class.
+
+<P>
+If the subpart is not of main type <span class="mimetype">text</span>, optional <var>fmt</var>
+is a format string that is used instead of the message payload.
+<var>fmt</var> is expanded with the following keywords, "<tt class="samp">%(keyword)s</tt>"format:
+
+<P>
+
+<UL>
+<LI><code>type</code> - Full MIME type of the non-<span class="mimetype">text</span> part
+
+<P>
+</LI>
+<LI><code>maintype</code> - Main MIME type of the non-<span class="mimetype">text</span> part
+
+<P>
+</LI>
+<LI><code>subtype</code> - Sub-MIME type of the non-<span class="mimetype">text</span> part
+
+<P>
+</LI>
+<LI><code>filename</code> - Filename of the non-<span class="mimetype">text</span> part
+
+<P>
+</LI>
+<LI><code>description</code> - Description associated with the
+ non-<span class="mimetype">text</span> part
+
+<P>
+</LI>
+<LI><code>encoding</code> - Content transfer encoding of the
+ non-<span class="mimetype">text</span> part
+
+<P>
+</LI>
+</UL>
+
+<P>
+The default value for <var>fmt</var> is <code>None</code>, meaning
+
+<P>
+<div class="verbatim"><pre>
+[Non-text (%(type)s) part of message omitted, filename %(filename)s]
+</pre></div>
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+
+<span class="versionnote">Changed in version 2.5:
+The previously deprecated method <tt class="method">__call__()</tt> was
+removed.</span>
+
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2.3 Additional notes"
+ href="node7.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.4 Creating email and"
+ href="module-email.mime.text.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node7.html">2.2.3 Additional notes</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.mime.text.html">2.4 Creating email and</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.header.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.header.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,341 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.charset.html" />
+<link rel="prev" href="module-email.mime.text.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.charset.html" />
+<meta name='aesop' content='information' />
+<title>2.5 Internationalized headers</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.4 Creating email and"
+ href="module-email.mime.text.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.6 Representing character sets"
+ href="module-email.charset.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.mime.text.html">2.4 Creating email and</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.charset.html">2.6 Representing character sets</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000250000000000000000">
+2.5 Internationalized headers</A>
+</H2>
+<A NAME="module-email.header"></A>
+
+<P>
+<a class="rfc" id='rfcref-3164' xml:id='rfcref-3164'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> is the base standard that describes the format of email
+messages. It derives from the older <a class="rfc" id='rfcref-3166' xml:id='rfcref-3166'
+href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> standard which came
+into widespread use at a time when most email was composed of ASCII
+characters only. <a class="rfc" id='rfcref-3168' xml:id='rfcref-3168'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> is a specification written assuming email
+contains only 7-bit ASCII characters.
+
+<P>
+Of course, as email has been deployed worldwide, it has become
+internationalized, such that language specific character sets can now
+be used in email messages. The base standard still requires email
+messages to be transferred using only 7-bit ASCII characters, so a
+slew of RFCs have been written describing how to encode email
+containing non-ASCII characters into <a class="rfc" id='rfcref-3170' xml:id='rfcref-3170'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant format.
+These RFCs include <a class="rfc" id='rfcref-3172' xml:id='rfcref-3172'
+href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, <a class="rfc" id='rfcref-3174' xml:id='rfcref-3174'
+href="http://www.faqs.org/rfcs/rfc2046.html">RFC 2046</a>, <a class="rfc" id='rfcref-3176' xml:id='rfcref-3176'
+href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>, and <a class="rfc" id='rfcref-3178' xml:id='rfcref-3178'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>.
+The <tt class="module">email</tt> package supports these standards in its
+<tt class="module">email.header</tt> and <tt class="module">email.charset</tt> modules.
+
+<P>
+If you want to include non-ASCII characters in your email headers,
+say in the <span class="mailheader">Subject:</span> or <span class="mailheader">To:</span> fields, you should
+use the <tt class="class">Header</tt> class and assign the field in the
+<tt class="class">Message</tt> object to an instance of <tt class="class">Header</tt> instead of
+using a string for the header value. Import the <tt class="class">Header</tt> class from the
+<tt class="module">email.header</tt> module. For example:
+
+<P>
+<div class="verbatim"><pre>
+>>> from email.message import Message
+>>> from email.header import Header
+>>> msg = Message()
+>>> h = Header('p\xf6stal', 'iso-8859-1')
+>>> msg['Subject'] = h
+>>> print msg.as_string()
+Subject: =?iso-8859-1?q?p=F6stal?=
+</pre></div>
+
+<P>
+Notice here how we wanted the <span class="mailheader">Subject:</span> field to contain a
+non-ASCII character? We did this by creating a <tt class="class">Header</tt>
+instance and passing in the character set that the byte string was
+encoded in. When the subsequent <tt class="class">Message</tt> instance was
+flattened, the <span class="mailheader">Subject:</span> field was properly <a class="rfc" id='rfcref-3180' xml:id='rfcref-3180'
+href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>
+encoded. MIME-aware mail readers would show this header using the
+embedded ISO-8859-1 character.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+<P>
+Here is the <tt class="class">Header</tt> class description:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-77' xml:id='l2h-77' class="class">Header</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>s</var><big>[</big><var>, charset</var><big>[</big><var>,
+ maxlinelen</var><big>[</big><var>, header_name</var><big>[</big><var>, continuation_ws</var><big>[</big><var>,
+ errors</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Create a MIME-compliant header that can contain strings in different
+character sets.
+
+<P>
+Optional <var>s</var> is the initial header value. If <code>None</code> (the
+default), the initial header value is not set. You can later append
+to the header with <tt class="method">append()</tt> method calls. <var>s</var> may be a
+byte string or a Unicode string, but see the <tt class="method">append()</tt>
+documentation for semantics.
+
+<P>
+Optional <var>charset</var> serves two purposes: it has the same meaning as
+the <var>charset</var> argument to the <tt class="method">append()</tt> method. It also
+sets the default character set for all subsequent <tt class="method">append()</tt>
+calls that omit the <var>charset</var> argument. If <var>charset</var> is not
+provided in the constructor (the default), the <code>us-ascii</code>
+character set is used both as <var>s</var>'s initial charset and as the
+default for subsequent <tt class="method">append()</tt> calls.
+
+<P>
+The maximum line length can be specified explicit via
+<var>maxlinelen</var>. For splitting the first line to a shorter value (to
+account for the field header which isn't included in <var>s</var>,
+e.g. <span class="mailheader">Subject:</span>) pass in the name of the field in
+<var>header_name</var>. The default <var>maxlinelen</var> is 76, and the
+default value for <var>header_name</var> is <code>None</code>, meaning it is not
+taken into account for the first line of a long, split header.
+
+<P>
+Optional <var>continuation_ws</var> must be <a class="rfc" id='rfcref-3182' xml:id='rfcref-3182'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant folding
+whitespace, and is usually either a space or a hard tab character.
+This character will be prepended to continuation lines.
+</dl>
+
+<P>
+Optional <var>errors</var> is passed straight through to the
+<tt class="method">append()</tt> method.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-78' xml:id='l2h-78' class="method">append</tt></b>(</nobr></td>
+ <td><var>s</var><big>[</big><var>, charset</var><big>[</big><var>, errors</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Append the string <var>s</var> to the MIME header.
+
+<P>
+Optional <var>charset</var>, if given, should be a <tt class="class">Charset</tt> instance
+(see <tt class="module"><a href="module-email.charset.html">email.charset</a></tt>) or the name of a character set, which
+will be converted to a <tt class="class">Charset</tt> instance. A value of
+<code>None</code> (the default) means that the <var>charset</var> given in the
+constructor is used.
+
+<P>
+<var>s</var> may be a byte string or a Unicode string. If it is a byte
+string (i.e. <code>isinstance(s, str)</code> is true), then
+<var>charset</var> is the encoding of that byte string, and a
+<tt class="exception">UnicodeError</tt> will be raised if the string cannot be
+decoded with that character set.
+
+<P>
+If <var>s</var> is a Unicode string, then <var>charset</var> is a hint
+specifying the character set of the characters in the string. In this
+case, when producing an <a class="rfc" id='rfcref-3184' xml:id='rfcref-3184'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant header using <a class="rfc" id='rfcref-3186' xml:id='rfcref-3186'
+href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>
+rules, the Unicode string will be encoded using the following charsets
+in order: <code>us-ascii</code>, the <var>charset</var> hint, <code>utf-8</code>. The
+first character set to not provoke a <tt class="exception">UnicodeError</tt> is used.
+
+<P>
+Optional <var>errors</var> is passed through to any <tt class="function">unicode()</tt> or
+<tt class="function">ustr.encode()</tt> call, and defaults to ``strict''.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-79' xml:id='l2h-79' class="method">encode</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>splitchars</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Encode a message header into an RFC-compliant format, possibly
+wrapping long lines and encapsulating non-ASCII parts in base64 or
+quoted-printable encodings. Optional <var>splitchars</var> is a string
+containing characters to split long ASCII lines on, in rough support
+of <a class="rfc" id='rfcref-3188' xml:id='rfcref-3188'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>'s <em>highest level syntactic breaks</em>. This doesn't
+affect <a class="rfc" id='rfcref-3190' xml:id='rfcref-3190'
+href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a> encoded lines.
+</dl>
+
+<P>
+The <tt class="class">Header</tt> class also provides a number of methods to support
+standard operators and built-in functions.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-80' xml:id='l2h-80' class="method">__str__</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+A synonym for <tt class="method">Header.encode()</tt>. Useful for
+<code>str(aHeader)</code>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-81' xml:id='l2h-81' class="method">__unicode__</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+A helper for the built-in <tt class="function">unicode()</tt> function. Returns the
+header as a Unicode string.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-82' xml:id='l2h-82' class="method">__eq__</tt></b>(</nobr></td>
+ <td><var>other</var>)</td></tr></table></dt>
+<dd>
+This method allows you to compare two <tt class="class">Header</tt> instances for equality.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-83' xml:id='l2h-83' class="method">__ne__</tt></b>(</nobr></td>
+ <td><var>other</var>)</td></tr></table></dt>
+<dd>
+This method allows you to compare two <tt class="class">Header</tt> instances for inequality.
+</dl>
+
+<P>
+The <tt class="module">email.header</tt> module also provides the following
+convenient functions.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-84' xml:id='l2h-84' class="function">decode_header</tt></b>(</nobr></td>
+ <td><var>header</var>)</td></tr></table></dt>
+<dd>
+Decode a message header value without converting the character set.
+The header value is in <var>header</var>.
+
+<P>
+This function returns a list of <code>(decoded_string, charset)</code> pairs
+containing each of the decoded parts of the header. <var>charset</var> is
+<code>None</code> for non-encoded parts of the header, otherwise a lower
+case string containing the name of the character set specified in the
+encoded string.
+
+<P>
+Here's an example:
+
+<P>
+<div class="verbatim"><pre>
+>>> from email.header import decode_header
+>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
+[('p\xf6stal', 'iso-8859-1')]
+</pre></div>
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-85' xml:id='l2h-85' class="function">make_header</tt></b>(</nobr></td>
+ <td><var>decoded_seq</var><big>[</big><var>, maxlinelen</var><big>[</big><var>,
+ header_name</var><big>[</big><var>, continuation_ws</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Create a <tt class="class">Header</tt> instance from a sequence of pairs as returned
+by <tt class="function">decode_header()</tt>.
+
+<P>
+<tt class="function">decode_header()</tt> takes a header value string and returns a
+sequence of pairs of the format <code>(decoded_string, charset)</code> where
+<var>charset</var> is the name of the character set.
+
+<P>
+This function takes one of those sequence of pairs and returns a
+<tt class="class">Header</tt> instance. Optional <var>maxlinelen</var>,
+<var>header_name</var>, and <var>continuation_ws</var> are as in the
+<tt class="class">Header</tt> constructor.
+</dl>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.4 Creating email and"
+ href="module-email.mime.text.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.6 Representing character sets"
+ href="module-email.charset.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.mime.text.html">2.4 Creating email and</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.charset.html">2.6 Representing character sets</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,196 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="about.html" />
+<link rel="prev" href="node1.html" />
+<link rel="parent" href="mimelib.html" />
+<link rel="next" href="module-email.message.html" />
+<meta name='aesop' content='information' />
+<title>2 email -- An email and MIME handling package</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="1 Introduction"
+ href="node1.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="email Package Reference"
+ href="mimelib.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.1 Representing an email"
+ href="module-email.message.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node1.html">1 Introduction</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="mimelib.html">email Package Reference</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.message.html">2.1 Representing an email</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H1><A NAME="SECTION000200000000000000000">
+2 <tt class="module">email</tt> --
+ An email and MIME handling package</A>
+</H1>
+
+<P>
+<A NAME="module-email"></A>
+
+<P>
+
+<span class="versionnote">New in version 2.2.</span>
+
+<P>
+The <tt class="module">email</tt> package is a library for managing email messages,
+including MIME and other <a class="rfc" id='rfcref-3031' xml:id='rfcref-3031'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-based message documents. It
+subsumes most of the functionality in several older standard modules
+such as <tt class="module"><a href="module-rfc822.html">rfc822</a></tt>, <tt class="module"><a href="module-mimetools.html">mimetools</a></tt>,
+<tt class="module"><a href="module-multifile.html">multifile</a></tt>, and other non-standard packages such as
+<tt class="module">mimecntl</tt>. It is specifically <em>not</em> designed to do any
+sending of email messages to SMTP (<a class="rfc" id='rfcref-3033' xml:id='rfcref-3033'
+href="http://www.faqs.org/rfcs/rfc2821.html">RFC 2821</a>), NNTP, or other servers; those
+are functions of modules such as <tt class="module"><a href="module-smtplib.html">smtplib</a></tt> and <tt class="module"><a href="module-nntplib.html">nntplib</a></tt>.
+The <tt class="module">email</tt> package attempts to be as RFC-compliant as possible,
+supporting in addition to <a class="rfc" id='rfcref-3035' xml:id='rfcref-3035'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>, such MIME-related RFCs as
+<a class="rfc" id='rfcref-3037' xml:id='rfcref-3037'
+href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, <a class="rfc" id='rfcref-3039' xml:id='rfcref-3039'
+href="http://www.faqs.org/rfcs/rfc2046.html">RFC 2046</a>, <a class="rfc" id='rfcref-3041' xml:id='rfcref-3041'
+href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>, and <a class="rfc" id='rfcref-3043' xml:id='rfcref-3043'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>.
+
+<P>
+The primary distinguishing feature of the <tt class="module">email</tt> package is
+that it splits the parsing and generating of email messages from the
+internal <em>object model</em> representation of email. Applications
+using the <tt class="module">email</tt> package deal primarily with objects; you can
+add sub-objects to messages, remove sub-objects from messages,
+completely re-arrange the contents, etc. There is a separate parser
+and a separate generator which handles the transformation from flat
+text to the object model, and then back to flat text again. There
+are also handy subclasses for some common MIME object types, and a few
+miscellaneous utilities that help with such common tasks as extracting
+and parsing message field values, creating RFC-compliant dates, etc.
+
+<P>
+The following sections describe the functionality of the
+<tt class="module">email</tt> package. The ordering follows a progression that
+should be common in applications: an email message is read as flat
+text from a file or other source, the text is parsed to produce the
+object structure of the email message, this structure is manipulated,
+and finally, the object tree is rendered back into flat text.
+
+<P>
+It is perfectly feasible to create the object structure out of whole
+cloth -- i.e. completely from scratch. From there, a similar
+progression can be taken as above.
+
+<P>
+Also included are detailed specifications of all the classes and
+modules that the <tt class="module">email</tt> package provides, the exception
+classes you might encounter while using the <tt class="module">email</tt> package,
+some auxiliary utilities, and a few examples. For users of the older
+<tt class="module">mimelib</tt> package, or previous versions of the <tt class="module">email</tt>
+package, a section on differences and porting is provided.
+
+<P>
+<div class="seealso">
+ <p class="heading">See Also:</p>
+
+ <dl compact="compact" class="seemodule">
+ <dt>Module <b><tt class="module"><a href="module-smtplib.html">smtplib</a></tt>:</b>
+ <dd>SMTP protocol client.
+ </dl>
+ <dl compact="compact" class="seemodule">
+ <dt>Module <b><tt class="module"><a href="module-nntplib.html">nntplib</a></tt>:</b>
+ <dd>NNTP protocol client.
+ </dl>
+</div>
+
+<P>
+
+<p><br /></p><hr class='online-navigation' />
+<div class='online-navigation'>
+<!--Table of Child-Links-->
+<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
+
+<UL CLASS="ChildLinks">
+<LI><A href="module-email.message.html">2.1 Representing an email message</a>
+<LI><A href="module-email.parser.html">2.2 Parsing email messages</a>
+<UL>
+<LI><A href="node5.html">2.2.1 FeedParser API</a>
+<LI><A href="node6.html">2.2.2 Parser class API</a>
+<LI><A href="node7.html">2.2.3 Additional notes</a>
+</ul>
+<LI><A href="module-email.generator.html">2.3 Generating MIME documents</a>
+<LI><A href="module-email.mime.text.html">2.4 Creating email and MIME objects from scratch</a>
+<LI><A href="module-email.header.html">2.5 Internationalized headers</a>
+<LI><A href="module-email.charset.html">2.6 Representing character sets</a>
+<LI><A href="module-email.encoders.html">2.7 Encoders</a>
+<LI><A href="module-email.errors.html">2.8 Exception and Defect classes</a>
+<LI><A href="module-email.utils.html">2.9 Miscellaneous utilities</a>
+<LI><A href="module-email.iterators.html">2.10 Iterators</a>
+<LI><A href="node16.html">2.11 Package History</a>
+<LI><A href="node17.html">2.12 Differences from <tt class="module">mimelib</tt></a>
+<LI><A href="node18.html">2.13 Examples</a>
+</ul>
+<!--End of Table of Child-Links-->
+</div>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="1 Introduction"
+ href="node1.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="email Package Reference"
+ href="mimelib.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.1 Representing an email"
+ href="module-email.message.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node1.html">1 Introduction</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="mimelib.html">email Package Reference</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.message.html">2.1 Representing an email</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.iterators.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.iterators.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,175 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="node16.html" />
+<link rel="prev" href="module-email.utils.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="node16.html" />
+<meta name='aesop' content='information' />
+<title>2.10 Iterators</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.9 Miscellaneous utilities"
+ href="module-email.utils.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.11 Package History"
+ href="node16.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.utils.html">2.9 Miscellaneous utilities</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node16.html">2.11 Package History</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION0002100000000000000000">
+2.10 Iterators</A>
+</H2>
+<A NAME="module-email.iterators"></A>
+
+<P>
+Iterating over a message object tree is fairly easy with the
+<tt class="method">Message.walk()</tt> method. The <tt class="module">email.iterators</tt> module
+provides some useful higher level iterations over message object
+trees.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-135' xml:id='l2h-135' class="function">body_line_iterator</tt></b>(</nobr></td>
+ <td><var>msg</var><big>[</big><var>, decode</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+This iterates over all the payloads in all the subparts of <var>msg</var>,
+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
+<tt class="method">readline()</tt>, skipping over all the intervening headers.
+
+<P>
+Optional <var>decode</var> is passed through to <tt class="method">Message.get_payload()</tt>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-136' xml:id='l2h-136' class="function">typed_subpart_iterator</tt></b>(</nobr></td>
+ <td><var>msg</var><big>[</big><var>,
+ maintype</var><big>[</big><var>, subtype</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+This iterates over all the subparts of <var>msg</var>, returning only those
+subparts that match the MIME type specified by <var>maintype</var> and
+<var>subtype</var>.
+
+<P>
+Note that <var>subtype</var> is optional; if omitted, then subpart MIME
+type matching is done only with the main type. <var>maintype</var> is
+optional too; it defaults to <span class="mimetype">text</span>.
+
+<P>
+Thus, by default <tt class="function">typed_subpart_iterator()</tt> returns each
+subpart that has a MIME type of <span class="mimetype">text/*</span>.
+</dl>
+
+<P>
+The following function has been added as a useful debugging tool. It
+should <em>not</em> be considered part of the supported public interface
+for the package.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-137' xml:id='l2h-137' class="function">_structure</tt></b>(</nobr></td>
+ <td><var>msg</var><big>[</big><var>, fp</var><big>[</big><var>, level</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Prints an indented representation of the content types of the
+message object structure. For example:
+
+<P>
+<div class="verbatim"><pre>
+>>> msg = email.message_from_file(somefile)
+>>> _structure(msg)
+multipart/mixed
+ text/plain
+ text/plain
+ multipart/digest
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ text/plain
+</pre></div>
+
+<P>
+Optional <var>fp</var> is a file-like object to print the output to. It
+must be suitable for Python's extended print statement. <var>level</var>
+is used internally.
+</dl>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.9 Miscellaneous utilities"
+ href="module-email.utils.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.11 Package History"
+ href="node16.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.utils.html">2.9 Miscellaneous utilities</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node16.html">2.11 Package History</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.message.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.message.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,927 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.parser.html" />
+<link rel="prev" href="module-email.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.parser.html" />
+<meta name='aesop' content='information' />
+<title>2.1 Representing an email message</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2 email "
+ href="module-email.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.html">2 email </A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.parser.html">2.2 Parsing email messages</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000210000000000000000">
+2.1 Representing an email message</A>
+</H2>
+<A NAME="module-email.message"></A>
+
+<P>
+The central class in the <tt class="module">email</tt> package is the
+<tt class="class">Message</tt> class, imported from the <tt class="module">email.message</tt> module. It is
+the base class for the <tt class="module">email</tt> object model. <tt class="class">Message</tt> provides
+the core functionality for setting and querying header fields, and for
+accessing message bodies.
+
+<P>
+Conceptually, a <tt class="class">Message</tt> object consists of <em>headers</em> and
+<em>payloads</em>. Headers are <a class="rfc" id='rfcref-3090' xml:id='rfcref-3090'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> 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.
+
+<P>
+Headers are stored and returned in case-preserving form but are
+matched case-insensitively. There may also be a single envelope
+header, also known as the <em>Unix-From</em> header or the
+<code>From_</code> header. The payload is either a string in the case of
+simple message objects or a list of <tt class="class">Message</tt> objects for
+MIME container documents (e.g. <span class="mimetype">multipart/*</span> and
+<span class="mimetype">message/rfc822</span>).
+
+<P>
+<tt class="class">Message</tt> 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.
+
+<P>
+Here are the methods of the <tt class="class">Message</tt> class:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3' xml:id='l2h-3' class="class">Message</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+The constructor takes no arguments.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-4' xml:id='l2h-4' class="method">as_string</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>unixfrom</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return the entire message flatten as a string. When optional
+<var>unixfrom</var> is <code>True</code>, the envelope header is included in the
+returned string. <var>unixfrom</var> defaults to <code>False</code>.
+
+<P>
+Note that this method is provided as a convenience and may not always format
+the message the way you want. For example, by default it mangles lines that
+begin with <code>From </code>. For more flexibility, instantiate a
+<tt class="class">Generator</tt> instance and use its
+<tt class="method">flatten()</tt> method directly. For example:
+
+<P>
+<div class="verbatim"><pre>
+from cStringIO import StringIO
+from email.generator import Generator
+fp = StringIO()
+g = Generator(fp, mangle_from_=False, maxheaderlen=60)
+g.flatten(msg)
+text = fp.getvalue()
+</pre></div>
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-5' xml:id='l2h-5' class="method">__str__</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Equivalent to <tt class="method">as_string(unixfrom=True)</tt>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-6' xml:id='l2h-6' class="method">is_multipart</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return <code>True</code> if the message's payload is a list of
+sub-<tt class="class">Message</tt> objects, otherwise return <code>False</code>. When
+<tt class="method">is_multipart()</tt> returns False, the payload should be a string
+object.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-7' xml:id='l2h-7' class="method">set_unixfrom</tt></b>(</nobr></td>
+ <td><var>unixfrom</var>)</td></tr></table></dt>
+<dd>
+Set the message's envelope header to <var>unixfrom</var>, which should be a string.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-8' xml:id='l2h-8' class="method">get_unixfrom</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the message's envelope header. Defaults to <code>None</code> if the
+envelope header was never set.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-9' xml:id='l2h-9' class="method">attach</tt></b>(</nobr></td>
+ <td><var>payload</var>)</td></tr></table></dt>
+<dd>
+Add the given <var>payload</var> to the current payload, which must be
+<code>None</code> or a list of <tt class="class">Message</tt> objects before the call.
+After the call, the payload will always be a list of <tt class="class">Message</tt>
+objects. If you want to set the payload to a scalar object (e.g. a
+string), use <tt class="method">set_payload()</tt> instead.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-10' xml:id='l2h-10' class="method">get_payload</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>i</var><big>[</big><var>, decode</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return a reference the current payload, which will be a list of
+<tt class="class">Message</tt> objects when <tt class="method">is_multipart()</tt> is <code>True</code>, or a
+string when <tt class="method">is_multipart()</tt> is <code>False</code>. If the
+payload is a list and you mutate the list object, you modify the
+message's payload in place.
+
+<P>
+With optional argument <var>i</var>, <tt class="method">get_payload()</tt> will return the
+<var>i</var>-th element of the payload, counting from zero, if
+<tt class="method">is_multipart()</tt> is <code>True</code>. An <tt class="exception">IndexError</tt>
+will be raised if <var>i</var> is less than 0 or greater than or equal to
+the number of items in the payload. If the payload is a string
+(i.e. <tt class="method">is_multipart()</tt> is <code>False</code>) and <var>i</var> is given, a
+<tt class="exception">TypeError</tt> is raised.
+
+<P>
+Optional <var>decode</var> is a flag indicating whether the payload should be
+decoded or not, according to the <span class="mailheader">Content-Transfer-Encoding:</span> header.
+When <code>True</code> and the message is not a multipart, the payload will be
+decoded if this header's value is "<tt class="samp">quoted-printable</tt>" or
+"<tt class="samp">base64</tt>". If some other encoding is used, or
+<span class="mailheader">Content-Transfer-Encoding:</span> header is
+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</var> flag is <code>True</code>, then <code>None</code> is returned. The
+default for <var>decode</var> is <code>False</code>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-11' xml:id='l2h-11' class="method">set_payload</tt></b>(</nobr></td>
+ <td><var>payload</var><big>[</big><var>, charset</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Set the entire message object's payload to <var>payload</var>. It is the
+client's responsibility to ensure the payload invariants. Optional
+<var>charset</var> sets the message's default character set; see
+<tt class="method">set_charset()</tt> for details.
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+<var>charset</var> argument added.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-12' xml:id='l2h-12' class="method">set_charset</tt></b>(</nobr></td>
+ <td><var>charset</var>)</td></tr></table></dt>
+<dd>
+Set the character set of the payload to <var>charset</var>, which can
+either be a <tt class="class">Charset</tt> instance (see <tt class="module"><a href="module-email.charset.html">email.charset</a></tt>), a
+string naming a character set,
+or <code>None</code>. If it is a string, it will be converted to a
+<tt class="class">Charset</tt> instance. If <var>charset</var> is <code>None</code>, the
+<code>charset</code> parameter will be removed from the
+<span class="mailheader">Content-Type:</span> header. Anything else will generate a
+<tt class="exception">TypeError</tt>.
+
+<P>
+The message will be assumed to be of type <span class="mimetype">text/*</span> encoded with
+<var>charset.input_charset</var>. It will be converted to
+<var>charset.output_charset</var>
+and encoded properly, if needed, when generating the plain text
+representation of the message. MIME headers
+(<span class="mailheader">MIME-Version:</span>, <span class="mailheader">Content-Type:</span>,
+<span class="mailheader">Content-Transfer-Encoding:</span>) will be added as needed.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-13' xml:id='l2h-13' class="method">get_charset</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the <tt class="class">Charset</tt> instance associated with the message's payload.
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+The following methods implement a mapping-like interface for accessing
+the message's <a class="rfc" id='rfcref-3092' xml:id='rfcref-3092'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> headers. Note that there are some
+semantic differences between these methods and a normal mapping
+(i.e. dictionary) interface. For example, in a dictionary there are
+no duplicate keys, but here there may be duplicate message headers. Also,
+in dictionaries there is no guaranteed order to the keys returned by
+<tt class="method">keys()</tt>, but in a <tt class="class">Message</tt> object, headers are always
+returned in the order they appeared in the original message, or were
+added to the message later. Any header deleted and then re-added are
+always appended to the end of the header list.
+
+<P>
+These semantic differences are intentional and are biased toward
+maximal convenience.
+
+<P>
+Note that in all cases, any envelope header present in the message is
+not included in the mapping interface.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-14' xml:id='l2h-14' class="method">__len__</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the total number of headers, including duplicates.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-15' xml:id='l2h-15' class="method">__contains__</tt></b>(</nobr></td>
+ <td><var>name</var>)</td></tr></table></dt>
+<dd>
+Return true if the message object has a field named <var>name</var>.
+Matching is done case-insensitively and <var>name</var> should not include the
+trailing colon. Used for the <code>in</code> operator,
+e.g.:
+
+<P>
+<div class="verbatim"><pre>
+if 'message-id' in myMessage:
+ print 'Message-ID:', myMessage['message-id']
+</pre></div>
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-16' xml:id='l2h-16' class="method">__getitem__</tt></b>(</nobr></td>
+ <td><var>name</var>)</td></tr></table></dt>
+<dd>
+Return the value of the named header field. <var>name</var> should not
+include the colon field separator. If the header is missing,
+<code>None</code> is returned; a <tt class="exception">KeyError</tt> is never raised.
+
+<P>
+Note that if the named field appears more than once in the message's
+headers, exactly which of those field values will be returned is
+undefined. Use the <tt class="method">get_all()</tt> method to get the values of all
+the extant named headers.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-17' xml:id='l2h-17' class="method">__setitem__</tt></b>(</nobr></td>
+ <td><var>name, val</var>)</td></tr></table></dt>
+<dd>
+Add a header to the message with field name <var>name</var> and value
+<var>val</var>. The field is appended to the end of the message's existing
+fields.
+
+<P>
+Note that this does <em>not</em> overwrite or delete any existing header
+with the same name. If you want to ensure that the new header is the
+only one present in the message with field name
+<var>name</var>, delete the field first, e.g.:
+
+<P>
+<div class="verbatim"><pre>
+del msg['subject']
+msg['subject'] = 'Python roolz!'
+</pre></div>
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-18' xml:id='l2h-18' class="method">__delitem__</tt></b>(</nobr></td>
+ <td><var>name</var>)</td></tr></table></dt>
+<dd>
+Delete all occurrences of the field with name <var>name</var> from the
+message's headers. No exception is raised if the named field isn't
+present in the headers.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-19' xml:id='l2h-19' class="method">has_key</tt></b>(</nobr></td>
+ <td><var>name</var>)</td></tr></table></dt>
+<dd>
+Return true if the message contains a header field named <var>name</var>,
+otherwise return false.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-20' xml:id='l2h-20' class="method">keys</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return a list of all the message's header field names.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-21' xml:id='l2h-21' class="method">values</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return a list of all the message's field values.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-22' xml:id='l2h-22' class="method">items</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return a list of 2-tuples containing all the message's field headers
+and values.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-23' xml:id='l2h-23' class="method">get</tt></b>(</nobr></td>
+ <td><var>name</var><big>[</big><var>, failobj</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return the value of the named header field. This is identical to
+<tt class="method">__getitem__()</tt> except that optional <var>failobj</var> is returned
+if the named header is missing (defaults to <code>None</code>).
+</dl>
+
+<P>
+Here are some additional useful methods:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-24' xml:id='l2h-24' class="method">get_all</tt></b>(</nobr></td>
+ <td><var>name</var><big>[</big><var>, failobj</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return a list of all the values for the field named <var>name</var>.
+If there are no such named headers in the message, <var>failobj</var> is
+returned (defaults to <code>None</code>).
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-25' xml:id='l2h-25' class="method">add_header</tt></b>(</nobr></td>
+ <td><var>_name, _value, **_params</var>)</td></tr></table></dt>
+<dd>
+Extended header setting. This method is similar to
+<tt class="method">__setitem__()</tt> except that additional header parameters can be
+provided as keyword arguments. <var>_name</var> is the header field to add
+and <var>_value</var> is the <em>primary</em> value for the header.
+
+<P>
+For each item in the keyword argument dictionary <var>_params</var>, the
+key is taken as the parameter name, with underscores converted to
+dashes (since dashes are illegal in Python identifiers). Normally,
+the parameter will be added as <code>key="value"</code> unless the value is
+<code>None</code>, in which case only the key will be added.
+
+<P>
+Here's an example:
+
+<P>
+<div class="verbatim"><pre>
+msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+</pre></div>
+
+<P>
+This will add a header that looks like
+
+<P>
+<div class="verbatim"><pre>
+Content-Disposition: attachment; filename="bud.gif"
+</pre></div>
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-26' xml:id='l2h-26' class="method">replace_header</tt></b>(</nobr></td>
+ <td><var>_name, _value</var>)</td></tr></table></dt>
+<dd>
+Replace a header. Replace the first header found in the message that
+matches <var>_name</var>, retaining header order and field name case. If
+no matching header was found, a <tt class="exception">KeyError</tt> is raised.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-27' xml:id='l2h-27' class="method">get_content_type</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the message's content type. The returned string is coerced to
+lower case of the form <span class="mimetype">maintype/subtype</span>. If there was no
+<span class="mailheader">Content-Type:</span> header in the message the default type as
+given by <tt class="method">get_default_type()</tt> will be returned. Since
+according to <a class="rfc" id='rfcref-3094' xml:id='rfcref-3094'
+href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, messages always have a default type,
+<tt class="method">get_content_type()</tt> will always return a value.
+
+<P>
+<a class="rfc" id='rfcref-3096' xml:id='rfcref-3096'
+href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a> defines a message's default type to be
+<span class="mimetype">text/plain</span> unless it appears inside a
+<span class="mimetype">multipart/digest</span> container, in which case it would be
+<span class="mimetype">message/rfc822</span>. If the <span class="mailheader">Content-Type:</span> header
+has an invalid type specification, <a class="rfc" id='rfcref-3098' xml:id='rfcref-3098'
+href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a> mandates that the
+default type be <span class="mimetype">text/plain</span>.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-28' xml:id='l2h-28' class="method">get_content_maintype</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the message's main content type. This is the
+<span class="mimetype">maintype</span> part of the string returned by
+<tt class="method">get_content_type()</tt>.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-29' xml:id='l2h-29' class="method">get_content_subtype</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the message's sub-content type. This is the <span class="mimetype">subtype</span>
+part of the string returned by <tt class="method">get_content_type()</tt>.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-30' xml:id='l2h-30' class="method">get_default_type</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the default content type. Most messages have a default content
+type of <span class="mimetype">text/plain</span>, except for messages that are subparts
+of <span class="mimetype">multipart/digest</span> containers. Such subparts have a
+default content type of <span class="mimetype">message/rfc822</span>.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-31' xml:id='l2h-31' class="method">set_default_type</tt></b>(</nobr></td>
+ <td><var>ctype</var>)</td></tr></table></dt>
+<dd>
+Set the default content type. <var>ctype</var> should either be
+<span class="mimetype">text/plain</span> or <span class="mimetype">message/rfc822</span>, although this is
+not enforced. The default content type is not stored in the
+<span class="mailheader">Content-Type:</span> header.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-32' xml:id='l2h-32' class="method">get_params</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>failobj</var><big>[</big><var>,
+ header</var><big>[</big><var>, unquote</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return the message's <span class="mailheader">Content-Type:</span> parameters, as a list. The
+elements of the returned list are 2-tuples of key/value pairs, as
+split on the "<tt class="character">=</tt>" sign. The left hand side of the
+"<tt class="character">=</tt>" is the key, while the right hand side is the value. If
+there is no "<tt class="character">=</tt>" sign in the parameter the value is the empty
+string, otherwise the value is as described in <tt class="method">get_param()</tt> and is
+unquoted if optional <var>unquote</var> is <code>True</code> (the default).
+
+<P>
+Optional <var>failobj</var> is the object to return if there is no
+<span class="mailheader">Content-Type:</span> header. Optional <var>header</var> is the header to
+search instead of <span class="mailheader">Content-Type:</span>.
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+<var>unquote</var> argument added.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-33' xml:id='l2h-33' class="method">get_param</tt></b>(</nobr></td>
+ <td><var>param</var><big>[</big><var>,
+ failobj</var><big>[</big><var>, header</var><big>[</big><var>, unquote</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return the value of the <span class="mailheader">Content-Type:</span> header's parameter
+<var>param</var> as a string. If the message has no <span class="mailheader">Content-Type:</span>
+header or if there is no such parameter, then <var>failobj</var> is
+returned (defaults to <code>None</code>).
+
+<P>
+Optional <var>header</var> if given, specifies the message header to use
+instead of <span class="mailheader">Content-Type:</span>.
+
+<P>
+Parameter keys are always compared case insensitively. The return
+value can either be a string, or a 3-tuple if the parameter was
+<a class="rfc" id='rfcref-3100' xml:id='rfcref-3100'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a> encoded. When it's a 3-tuple, the elements of the value are of
+the form <code>(CHARSET, LANGUAGE, VALUE)</code>. Note that both <code>CHARSET</code> and
+<code>LANGUAGE</code> can be <code>None</code>, in which case you should consider
+<code>VALUE</code> to be encoded in the <code>us-ascii</code> charset. You can
+usually ignore <code>LANGUAGE</code>.
+
+<P>
+If your application doesn't care whether the parameter was encoded as in
+<a class="rfc" id='rfcref-3102' xml:id='rfcref-3102'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>, you can collapse the parameter value by calling
+<tt class="function">email.Utils.collapse_rfc2231_value()</tt>, passing in the return value
+from <tt class="method">get_param()</tt>. This will return a suitably decoded Unicode string
+whn the value is a tuple, or the original string unquoted if it isn't. For
+example:
+
+<P>
+<div class="verbatim"><pre>
+rawparam = msg.get_param('foo')
+param = email.Utils.collapse_rfc2231_value(rawparam)
+</pre></div>
+
+<P>
+In any case, the parameter value (either the returned string, or the
+<code>VALUE</code> item in the 3-tuple) is always unquoted, unless
+<var>unquote</var> is set to <code>False</code>.
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+<var>unquote</var> argument added, and 3-tuple return value
+possible.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-34' xml:id='l2h-34' class="method">set_param</tt></b>(</nobr></td>
+ <td><var>param, value</var><big>[</big><var>,
+ header</var><big>[</big><var>, requote</var><big>[</big><var>, charset</var><big>[</big><var>, language</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+
+<P>
+Set a parameter in the <span class="mailheader">Content-Type:</span> header. If the
+parameter already exists in the header, its value will be replaced
+with <var>value</var>. If the <span class="mailheader">Content-Type:</span> header as not yet
+been defined for this message, it will be set to <span class="mimetype">text/plain</span>
+and the new parameter value will be appended as per <a class="rfc" id='rfcref-3104' xml:id='rfcref-3104'
+href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>.
+
+<P>
+Optional <var>header</var> specifies an alternative header to
+<span class="mailheader">Content-Type:</span>, and all parameters will be quoted as
+necessary unless optional <var>requote</var> is <code>False</code> (the default
+is <code>True</code>).
+
+<P>
+If optional <var>charset</var> is specified, the parameter will be encoded
+according to <a class="rfc" id='rfcref-3106' xml:id='rfcref-3106'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. Optional <var>language</var> specifies the RFC
+2231 language, defaulting to the empty string. Both <var>charset</var> and
+<var>language</var> should be strings.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-35' xml:id='l2h-35' class="method">del_param</tt></b>(</nobr></td>
+ <td><var>param</var><big>[</big><var>, header</var><big>[</big><var>,
+ requote</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Remove the given parameter completely from the
+<span class="mailheader">Content-Type:</span> header. The header will be re-written in
+place without the parameter or its value. All values will be quoted
+as necessary unless <var>requote</var> is <code>False</code> (the default is
+<code>True</code>). Optional <var>header</var> specifies an alternative to
+<span class="mailheader">Content-Type:</span>.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-36' xml:id='l2h-36' class="method">set_type</tt></b>(</nobr></td>
+ <td><var>type</var><big>[</big><var>, header</var><big>]</big><var></var><big>[</big><var>,
+ requote</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Set the main type and subtype for the <span class="mailheader">Content-Type:</span>
+header. <var>type</var> must be a string in the form
+<span class="mimetype">maintype/subtype</span>, otherwise a <tt class="exception">ValueError</tt> is
+raised.
+
+<P>
+This method replaces the <span class="mailheader">Content-Type:</span> header, keeping all
+the parameters in place. If <var>requote</var> is <code>False</code>, this
+leaves the existing header's quoting as is, otherwise the parameters
+will be quoted (the default).
+
+<P>
+An alternative header can be specified in the <var>header</var> argument.
+When the <span class="mailheader">Content-Type:</span> header is set a
+<span class="mailheader">MIME-Version:</span> header is also added.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-37' xml:id='l2h-37' class="method">get_filename</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return the value of the <code>filename</code> parameter of the
+<span class="mailheader">Content-Disposition:</span> header of the message. If the header does
+not have a <code>filename</code> parameter, this method falls back to looking for
+the <code>name</code> parameter. If neither is found, or the header is missing,
+then <var>failobj</var> is returned. The returned string will always be unquoted
+as per <tt class="method">Utils.unquote()</tt>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-38' xml:id='l2h-38' class="method">get_boundary</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return the value of the <code>boundary</code> parameter of the
+<span class="mailheader">Content-Type:</span> header of the message, or <var>failobj</var> if either
+the header is missing, or has no <code>boundary</code> parameter. The
+returned string will always be unquoted as per
+<tt class="method">Utils.unquote()</tt>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-39' xml:id='l2h-39' class="method">set_boundary</tt></b>(</nobr></td>
+ <td><var>boundary</var>)</td></tr></table></dt>
+<dd>
+Set the <code>boundary</code> parameter of the <span class="mailheader">Content-Type:</span>
+header to <var>boundary</var>. <tt class="method">set_boundary()</tt> will always quote
+<var>boundary</var> if necessary. A <tt class="exception">HeaderParseError</tt> is raised
+if the message object has no <span class="mailheader">Content-Type:</span> header.
+
+<P>
+Note that using this method is subtly different than deleting the old
+<span class="mailheader">Content-Type:</span> header and adding a new one with the new boundary
+via <tt class="method">add_header()</tt>, because <tt class="method">set_boundary()</tt> preserves the
+order of the <span class="mailheader">Content-Type:</span> header in the list of headers.
+However, it does <em>not</em> preserve any continuation lines which may
+have been present in the original <span class="mailheader">Content-Type:</span> header.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-40' xml:id='l2h-40' class="method">get_content_charset</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return the <code>charset</code> parameter of the <span class="mailheader">Content-Type:</span>
+header, coerced to lower case. If there is no
+<span class="mailheader">Content-Type:</span> header, or if that header has no
+<code>charset</code> parameter, <var>failobj</var> is returned.
+
+<P>
+Note that this method differs from <tt class="method">get_charset()</tt> which
+returns the <tt class="class">Charset</tt> instance for the default encoding of the
+message body.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-41' xml:id='l2h-41' class="method">get_charsets</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return a list containing the character set names in the message. If
+the message is a <span class="mimetype">multipart</span>, then the list will contain one
+element for each subpart in the payload, otherwise, it will be a list
+of length 1.
+
+<P>
+Each item in the list will be a string which is the value of the
+<code>charset</code> parameter in the <span class="mailheader">Content-Type:</span> header for the
+represented subpart. However, if the subpart has no
+<span class="mailheader">Content-Type:</span> header, no <code>charset</code> parameter, or is not of
+the <span class="mimetype">text</span> main MIME type, then that item in the returned list
+will be <var>failobj</var>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-42' xml:id='l2h-42' class="method">walk</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+The <tt class="method">walk()</tt> method is an all-purpose generator which can be
+used to iterate over all the parts and subparts of a message object
+tree, in depth-first traversal order. You will typically use
+<tt class="method">walk()</tt> as the iterator in a <code>for</code> loop; each
+iteration returns the next subpart.
+
+<P>
+Here's an example that prints the MIME type of every part of a
+multipart message structure:
+
+<P>
+<div class="verbatim"><pre>
+>>> for part in msg.walk():
+... print part.get_content_type()
+multipart/report
+text/plain
+message/delivery-status
+text/plain
+text/plain
+message/rfc822
+</pre></div>
+</dl>
+
+<P>
+
+<span class="versionnote">Changed in version 2.5:
+The previously deprecated methods <tt class="method">get_type()</tt>,
+<tt class="method">get_main_type()</tt>, and <tt class="method">get_subtype()</tt> were removed.</span>
+
+<P>
+<tt class="class">Message</tt> objects can also optionally contain two instance
+attributes, which can be used when generating the plain text of a MIME
+message.
+
+<P>
+<dl><dt><b><tt id='l2h-43' xml:id='l2h-43'>preamble</tt></b></dt>
+<dd>
+The format of a MIME document allows for some text between the blank
+line following the headers, and the first multipart boundary string.
+Normally, this text is never visible in a MIME-aware mail reader
+because it falls outside the standard MIME armor. However, when
+viewing the raw text of the message, or when viewing the message in a
+non-MIME aware reader, this text can become visible.
+
+<P>
+The <var>preamble</var> attribute contains this leading extra-armor text
+for MIME documents. When the <tt class="class">Parser</tt> discovers some text after
+the headers but before the first boundary string, it assigns this text
+to the message's <var>preamble</var> attribute. When the <tt class="class">Generator</tt>
+is writing out the plain text representation of a MIME message, and it
+finds the message has a <var>preamble</var> attribute, it will write this
+text in the area between the headers and the first boundary. See
+<tt class="module"><a href="module-email.parser.html">email.parser</a></tt> and <tt class="module"><a href="module-email.generator.html">email.generator</a></tt> for details.
+
+<P>
+Note that if the message object has no preamble, the
+<var>preamble</var> attribute will be <code>None</code>.
+</dd></dl>
+
+<P>
+<dl><dt><b><tt id='l2h-44' xml:id='l2h-44'>epilogue</tt></b></dt>
+<dd>
+The <var>epilogue</var> attribute acts the same way as the <var>preamble</var>
+attribute, except that it contains text that appears between the last
+boundary and the end of the message.
+
+<P>
+
+<span class="versionnote">Changed in version 2.5:
+You do not need to set the epilogue to the empty string in
+order for the <tt class="class">Generator</tt> to print a newline at the end of the
+file.</span>
+
+</dd></dl>
+
+<P>
+<dl><dt><b><tt id='l2h-45' xml:id='l2h-45'>defects</tt></b></dt>
+<dd>
+The <var>defects</var> attribute contains a list of all the problems found when
+parsing this message. See <tt class="module"><a href="module-email.errors.html">email.errors</a></tt> for a detailed description
+of the possible parsing defects.
+
+<P>
+
+<span class="versionnote">New in version 2.4.</span>
+
+</dd></dl>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2 email "
+ href="module-email.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.html">2 email </A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.parser.html">2.2 Parsing email messages</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.mime.text.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.mime.text.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,305 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.header.html" />
+<link rel="prev" href="module-email.generator.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.header.html" />
+<meta name='aesop' content='information' />
+<title>2.4 Creating email and MIME objects from scratch</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.3 Generating MIME documents"
+ href="module-email.generator.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.5 Internationalized headers"
+ href="module-email.header.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.generator.html">2.3 Generating MIME documents</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.header.html">2.5 Internationalized headers</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000240000000000000000">
+2.4 Creating email and MIME objects from scratch</A>
+</H2>
+<A NAME="module-email.mime"></A><A NAME="module-email.mime.base"></A><A NAME="module-email.mime.nonmultipart"></A><A NAME="module-email.mime.multipart"></A><A NAME="module-email.mime.audio"></A><A NAME="module-email.mime.image"></A><A NAME="module-email.mime.message"></A><A NAME="module-email.mime.text"></A>Ordinarily, you get a message object structure by passing a file or
+some text to a parser, which parses the text and returns the root
+message object. However you can also build a complete message
+structure from scratch, or even individual <tt class="class">Message</tt> objects by
+hand. In fact, you can also take an existing structure and add new
+<tt class="class">Message</tt> objects, move them around, etc. This makes a very
+convenient interface for slicing-and-dicing MIME messages.
+
+<P>
+You can create a new object structure by creating <tt class="class">Message</tt> instances,
+adding attachments and all the appropriate headers manually. For MIME
+messages though, the <tt class="module">email</tt> package provides some convenient
+subclasses to make things easier.
+
+<P>
+Here are the classes:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-69' xml:id='l2h-69' class="class">MIMEBase</tt></b>(</nobr></td>
+ <td><var>_maintype, _subtype, **_params</var>)</td></tr></table></dt>
+<dd>
+Module: <tt class="module">email.mime.base</tt>
+
+<P>
+This is the base class for all the MIME-specific subclasses of
+<tt class="class">Message</tt>. Ordinarily you won't create instances specifically
+of <tt class="class">MIMEBase</tt>, although you could. <tt class="class">MIMEBase</tt> is provided
+primarily as a convenient base class for more specific MIME-aware
+subclasses.
+
+<P>
+<var>_maintype</var> is the <span class="mailheader">Content-Type:</span> major type
+(e.g. <span class="mimetype">text</span> or <span class="mimetype">image</span>), and <var>_subtype</var> is the
+<span class="mailheader">Content-Type:</span> minor type
+(e.g. <span class="mimetype">plain</span> or <span class="mimetype">gif</span>). <var>_params</var> is a parameter
+key/value dictionary and is passed directly to
+<tt class="method">Message.add_header()</tt>.
+
+<P>
+The <tt class="class">MIMEBase</tt> class always adds a <span class="mailheader">Content-Type:</span> header
+(based on <var>_maintype</var>, <var>_subtype</var>, and <var>_params</var>), and a
+<span class="mailheader">MIME-Version:</span> header (always set to <code>1.0</code>).
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-70' xml:id='l2h-70' class="class">MIMENonMultipart</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Module: <tt class="module">email.mime.nonmultipart</tt>
+
+<P>
+A subclass of <tt class="class">MIMEBase</tt>, this is an intermediate base class for
+MIME messages that are not <span class="mimetype">multipart</span>. The primary purpose
+of this class is to prevent the use of the <tt class="method">attach()</tt> method,
+which only makes sense for <span class="mimetype">multipart</span> messages. If
+<tt class="method">attach()</tt> is called, a <tt class="exception">MultipartConversionError</tt>
+exception is raised.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-71' xml:id='l2h-71' class="class">MIMEMultipart</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>subtype</var><big>[</big><var>,
+ boundary</var><big>[</big><var>, _subparts</var><big>[</big><var>, _params</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Module: <tt class="module">email.mmime.multipart</tt>
+
+<P>
+A subclass of <tt class="class">MIMEBase</tt>, this is an intermediate base class for
+MIME messages that are <span class="mimetype">multipart</span>. Optional <var>_subtype</var>
+defaults to <span class="mimetype">mixed</span>, but can be used to specify the subtype
+of the message. A <span class="mailheader">Content-Type:</span> header of
+<span class="mimetype">multipart/</span><var>_subtype</var> will be added to the message
+object. A <span class="mailheader">MIME-Version:</span> header will also be added.
+
+<P>
+Optional <var>boundary</var> is the multipart boundary string. When
+<code>None</code> (the default), the boundary is calculated when needed.
+
+<P>
+<var>_subparts</var> is a sequence of initial subparts for the payload. It
+must be possible to convert this sequence to a list. You can always
+attach new subparts to the message by using the
+<tt class="method">Message.attach()</tt> method.
+
+<P>
+Additional parameters for the <span class="mailheader">Content-Type:</span> header are
+taken from the keyword arguments, or passed into the <var>_params</var>
+argument, which is a keyword dictionary.
+
+<P>
+
+<span class="versionnote">New in version 2.2.2.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-72' xml:id='l2h-72' class="class">MIMEAudio</tt></b>(</nobr></td>
+ <td><var>_audiodata</var><big>[</big><var>, _subtype</var><big>[</big><var>,
+ _encoder</var><big>[</big><var>, **_params</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Module: <tt class="module">email.mime.audio</tt>
+
+<P>
+A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEAudio</tt> class
+is used to create MIME message objects of major type <span class="mimetype">audio</span>.
+<var>_audiodata</var> is a string containing the raw audio data. If this
+data can be decoded by the standard Python module <tt class="module"><a href="module-sndhdr.html">sndhdr</a></tt>,
+then the subtype will be automatically included in the
+<span class="mailheader">Content-Type:</span> header. Otherwise you can explicitly specify the
+audio subtype via the <var>_subtype</var> parameter. If the minor type could
+not be guessed and <var>_subtype</var> was not given, then <tt class="exception">TypeError</tt>
+is raised.
+
+<P>
+Optional <var>_encoder</var> is a callable (i.e. function) which will
+perform the actual encoding of the audio data for transport. This
+callable takes one argument, which is the <tt class="class">MIMEAudio</tt> instance.
+It should use <tt class="method">get_payload()</tt> and <tt class="method">set_payload()</tt> to
+change the payload to encoded form. It should also add any
+<span class="mailheader">Content-Transfer-Encoding:</span> or other headers to the message
+object as necessary. The default encoding is base64. See the
+<tt class="module"><a href="module-email.encoders.html">email.encoders</a></tt> module for a list of the built-in encoders.
+
+<P>
+<var>_params</var> are passed straight through to the base class constructor.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-73' xml:id='l2h-73' class="class">MIMEImage</tt></b>(</nobr></td>
+ <td><var>_imagedata</var><big>[</big><var>, _subtype</var><big>[</big><var>,
+ _encoder</var><big>[</big><var>, **_params</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Module: <tt class="module">email.mime.image</tt>
+
+<P>
+A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEImage</tt> class is
+used to create MIME message objects of major type <span class="mimetype">image</span>.
+<var>_imagedata</var> is a string containing the raw image data. If this
+data can be decoded by the standard Python module <tt class="module"><a href="module-imghdr.html">imghdr</a></tt>,
+then the subtype will be automatically included in the
+<span class="mailheader">Content-Type:</span> header. Otherwise you can explicitly specify the
+image subtype via the <var>_subtype</var> parameter. If the minor type could
+not be guessed and <var>_subtype</var> was not given, then <tt class="exception">TypeError</tt>
+is raised.
+
+<P>
+Optional <var>_encoder</var> is a callable (i.e. function) which will
+perform the actual encoding of the image data for transport. This
+callable takes one argument, which is the <tt class="class">MIMEImage</tt> instance.
+It should use <tt class="method">get_payload()</tt> and <tt class="method">set_payload()</tt> to
+change the payload to encoded form. It should also add any
+<span class="mailheader">Content-Transfer-Encoding:</span> or other headers to the message
+object as necessary. The default encoding is base64. See the
+<tt class="module"><a href="module-email.encoders.html">email.encoders</a></tt> module for a list of the built-in encoders.
+
+<P>
+<var>_params</var> are passed straight through to the <tt class="class">MIMEBase</tt>
+constructor.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-74' xml:id='l2h-74' class="class">MIMEMessage</tt></b>(</nobr></td>
+ <td><var>_msg</var><big>[</big><var>, _subtype</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Module: <tt class="module">email.mime.message</tt>
+
+<P>
+A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEMessage</tt> class
+is used to create MIME objects of main type <span class="mimetype">message</span>.
+<var>_msg</var> is used as the payload, and must be an instance of class
+<tt class="class">Message</tt> (or a subclass thereof), otherwise a
+<tt class="exception">TypeError</tt> is raised.
+
+<P>
+Optional <var>_subtype</var> sets the subtype of the message; it defaults
+to <span class="mimetype">rfc822</span>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-75' xml:id='l2h-75' class="class">MIMEText</tt></b>(</nobr></td>
+ <td><var>_text</var><big>[</big><var>, _subtype</var><big>[</big><var>, _charset</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Module: <tt class="module">email.mime.text</tt>
+
+<P>
+A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEText</tt> class is
+used to create MIME objects of major type <span class="mimetype">text</span>.
+<var>_text</var> is the string for the payload. <var>_subtype</var> is the
+minor type and defaults to <span class="mimetype">plain</span>. <var>_charset</var> is the
+character set of the text and is passed as a parameter to the
+<tt class="class">MIMENonMultipart</tt> constructor; it defaults to <code>us-ascii</code>. No
+guessing or encoding is performed on the text data.
+
+<P>
+
+<span class="versionnote">Changed in version 2.4:
+The previously deprecated <var>_encoding</var> argument has
+been removed. Encoding happens implicitly based on the <var>_charset</var>
+argument.</span>
+
+</dl>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.3 Generating MIME documents"
+ href="module-email.generator.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.5 Internationalized headers"
+ href="module-email.header.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.generator.html">2.3 Generating MIME documents</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.header.html">2.5 Internationalized headers</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.parser.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.parser.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,154 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.generator.html" />
+<link rel="prev" href="module-email.message.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="node5.html" />
+<meta name='aesop' content='information' />
+<title>2.2 Parsing email messages</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.1 Representing an email"
+ href="module-email.message.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2.1 FeedParser API"
+ href="node5.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.message.html">2.1 Representing an email</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node5.html">2.2.1 FeedParser API</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000220000000000000000">
+2.2 Parsing email messages</A>
+</H2>
+<A NAME="module-email.parser"></A>
+
+<P>
+Message object structures can be created in one of two ways: they can be
+created from whole cloth by instantiating <tt class="class">Message</tt> objects and
+stringing them together via <tt class="method">attach()</tt> and
+<tt class="method">set_payload()</tt> calls, or they can be created by parsing a flat text
+representation of the email message.
+
+<P>
+The <tt class="module">email</tt> 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 <tt class="class">Message</tt> instance of the object structure. For
+simple, non-MIME messages the payload of this root object will likely
+be a string containing the text of the message. For MIME
+messages, the root object will return <code>True</code> from its
+<tt class="method">is_multipart()</tt> method, and the subparts can be accessed via
+the <tt class="method">get_payload()</tt> and <tt class="method">walk()</tt> methods.
+
+<P>
+There are actually two parser interfaces available for use, the classic
+<tt class="class">Parser</tt> API and the incremental <tt class="class">FeedParser</tt> API. The classic
+<tt class="class">Parser</tt> API is fine if you have the entire text of the message in
+memory as a string, or if the entire message lives in a file on the file
+system. <tt class="class">FeedParser</tt> is more appropriate for when you're reading the
+message from a stream which might block waiting for more input (e.g. reading
+an email message from a socket). The <tt class="class">FeedParser</tt> can consume and parse
+the message incrementally, and only returns the root object when you close the
+parser<A NAME="tex2html17"
+ HREF="#foot976"><SUP>1</SUP></A>.
+
+<P>
+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 <tt class="module">email</tt> package's bundled
+parser and the <tt class="class">Message</tt> class, so your custom parser can create
+message object trees any way it finds necessary.
+
+<P>
+<BR><HR><H4>Footnotes</H4>
+<DL>
+<DT><A NAME="foot976">...
+parser</A><A
+ href="module-email.parser.html#tex2html17"><SUP>1</SUP></A></DT>
+<DD>As of email package version 3.0, introduced in
+Python 2.4, the classic <tt class="class">Parser</tt> was re-implemented in terms of the
+<tt class="class">FeedParser</tt>, so the semantics and results are identical between the two
+parsers.
+
+</DD>
+</DL>
+<p><br /></p><hr class='online-navigation' />
+<div class='online-navigation'>
+<!--Table of Child-Links-->
+<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
+
+<UL CLASS="ChildLinks">
+<LI><A href="node5.html">2.2.1 FeedParser API</a>
+<LI><A href="node6.html">2.2.2 Parser class API</a>
+<LI><A href="node7.html">2.2.3 Additional notes</a>
+</ul>
+<!--End of Table of Child-Links-->
+</div>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.1 Representing an email"
+ href="module-email.message.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2.1 FeedParser API"
+ href="node5.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.message.html">2.1 Representing an email</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node5.html">2.2.1 FeedParser API</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/module-email.utils.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/module-email.utils.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,341 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.iterators.html" />
+<link rel="prev" href="module-email.errors.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="module-email.iterators.html" />
+<meta name='aesop' content='information' />
+<title>2.9 Miscellaneous utilities</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.8 Exception and Defect"
+ href="module-email.errors.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.10 Iterators"
+ href="module-email.iterators.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.errors.html">2.8 Exception and Defect</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.iterators.html">2.10 Iterators</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION000290000000000000000">
+2.9 Miscellaneous utilities</A>
+</H2>
+<A NAME="module-email.utils"></A>
+
+<P>
+There are several useful utilities provided in the <tt class="module">email.utils</tt>
+module:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-120' xml:id='l2h-120' class="function">quote</tt></b>(</nobr></td>
+ <td><var>str</var>)</td></tr></table></dt>
+<dd>
+Return a new string with backslashes in <var>str</var> replaced by two
+backslashes, and double quotes replaced by backslash-double quote.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-121' xml:id='l2h-121' class="function">unquote</tt></b>(</nobr></td>
+ <td><var>str</var>)</td></tr></table></dt>
+<dd>
+Return a new string which is an <em>unquoted</em> version of <var>str</var>.
+If <var>str</var> ends and begins with double quotes, they are stripped
+off. Likewise if <var>str</var> ends and begins with angle brackets, they
+are stripped off.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-122' xml:id='l2h-122' class="function">parseaddr</tt></b>(</nobr></td>
+ <td><var>address</var>)</td></tr></table></dt>
+<dd>
+Parse address - which should be the value of some address-containing
+field such as <span class="mailheader">To:</span> or <span class="mailheader">Cc:</span> - into its constituent
+<em>realname</em> and <em>email address</em> parts. Returns a tuple of that
+information, unless the parse fails, in which case a 2-tuple of
+<code>('', '')</code> is returned.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-123' xml:id='l2h-123' class="function">formataddr</tt></b>(</nobr></td>
+ <td><var>pair</var>)</td></tr></table></dt>
+<dd>
+The inverse of <tt class="method">parseaddr()</tt>, this takes a 2-tuple of the form
+<code>(realname, email_address)</code> and returns the string value suitable
+for a <span class="mailheader">To:</span> or <span class="mailheader">Cc:</span> header. If the first element of
+<var>pair</var> is false, then the second element is returned unmodified.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-124' xml:id='l2h-124' class="function">getaddresses</tt></b>(</nobr></td>
+ <td><var>fieldvalues</var>)</td></tr></table></dt>
+<dd>
+This method returns a list of 2-tuples of the form returned by
+<code>parseaddr()</code>. <var>fieldvalues</var> is a sequence of header field
+values as might be returned by <tt class="method">Message.get_all()</tt>. Here's a
+simple example that gets all the recipients of a message:
+
+<P>
+<div class="verbatim"><pre>
+from email.utils import getaddresses
+
+tos = msg.get_all('to', [])
+ccs = msg.get_all('cc', [])
+resent_tos = msg.get_all('resent-to', [])
+resent_ccs = msg.get_all('resent-cc', [])
+all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
+</pre></div>
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-125' xml:id='l2h-125' class="function">parsedate</tt></b>(</nobr></td>
+ <td><var>date</var>)</td></tr></table></dt>
+<dd>
+Attempts to parse a date according to the rules in <a class="rfc" id='rfcref-3259' xml:id='rfcref-3259'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>.
+however, some mailers don't follow that format as specified, so
+<tt class="function">parsedate()</tt> tries to guess correctly in such cases.
+<var>date</var> is a string containing an <a class="rfc" id='rfcref-3261' xml:id='rfcref-3261'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> date, such as
+<code>"Mon, 20 Nov 1995 19:12:08 -0500"</code>. If it succeeds in parsing
+the date, <tt class="function">parsedate()</tt> returns a 9-tuple that can be passed
+directly to <tt class="function">time.mktime()</tt>; otherwise <code>None</code> will be
+returned. Note that fields 6, 7, and 8 of the result tuple are not
+usable.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-126' xml:id='l2h-126' class="function">parsedate_tz</tt></b>(</nobr></td>
+ <td><var>date</var>)</td></tr></table></dt>
+<dd>
+Performs the same function as <tt class="function">parsedate()</tt>, but returns
+either <code>None</code> or a 10-tuple; the first 9 elements make up a tuple
+that can be passed directly to <tt class="function">time.mktime()</tt>, and the tenth
+is the offset of the date's timezone from UTC (which is the official
+term for Greenwich Mean Time)<A NAME="tex2html40"
+ HREF="#foot2357"><SUP>3</SUP></A>. If the input
+string has no timezone, the last element of the tuple returned is
+<code>None</code>. Note that fields 6, 7, and 8 of the result tuple are not
+usable.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-127' xml:id='l2h-127' class="function">mktime_tz</tt></b>(</nobr></td>
+ <td><var>tuple</var>)</td></tr></table></dt>
+<dd>
+Turn a 10-tuple as returned by <tt class="function">parsedate_tz()</tt> into a UTC
+timestamp. It the timezone item in the tuple is <code>None</code>, assume
+local time. Minor deficiency: <tt class="function">mktime_tz()</tt> interprets the
+first 8 elements of <var>tuple</var> as a local time and then compensates
+for the timezone difference. This may yield a slight error around
+changes in daylight savings time, though not worth worrying about for
+common use.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-128' xml:id='l2h-128' class="function">formatdate</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>timeval</var><big>[</big><var>, localtime</var><big>]</big><var></var><big>[</big><var>, usegmt</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Returns a date string as per <a class="rfc" id='rfcref-3263' xml:id='rfcref-3263'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>, e.g.:
+
+<P>
+<div class="verbatim"><pre>
+Fri, 09 Nov 2001 01:08:47 -0000
+</pre></div>
+
+<P>
+Optional <var>timeval</var> if given is a floating point time value as
+accepted by <tt class="function">time.gmtime()</tt> and <tt class="function">time.localtime()</tt>,
+otherwise the current time is used.
+
+<P>
+Optional <var>localtime</var> is a flag that when <code>True</code>, interprets
+<var>timeval</var>, and returns a date relative to the local timezone
+instead of UTC, properly taking daylight savings time into account.
+The default is <code>False</code> meaning UTC is used.
+
+<P>
+Optional <var>usegmt</var> is a flag that when <code>True</code>, outputs a
+date string with the timezone as an ascii string <code>GMT</code>, rather
+than a numeric <code>-0000</code>. This is needed for some protocols (such
+as HTTP). This only applies when <var>localtime</var> is <code>False</code>.
+
+<span class="versionnote">New in version 2.4.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-129' xml:id='l2h-129' class="function">make_msgid</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>idstring</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Returns a string suitable for an <a class="rfc" id='rfcref-3265' xml:id='rfcref-3265'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant
+<span class="mailheader">Message-ID:</span> header. Optional <var>idstring</var> if given, is
+a string used to strengthen the uniqueness of the message id.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-130' xml:id='l2h-130' class="function">decode_rfc2231</tt></b>(</nobr></td>
+ <td><var>s</var>)</td></tr></table></dt>
+<dd>
+Decode the string <var>s</var> according to <a class="rfc" id='rfcref-3267' xml:id='rfcref-3267'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-131' xml:id='l2h-131' class="function">encode_rfc2231</tt></b>(</nobr></td>
+ <td><var>s</var><big>[</big><var>, charset</var><big>[</big><var>, language</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Encode the string <var>s</var> according to <a class="rfc" id='rfcref-3269' xml:id='rfcref-3269'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. Optional
+<var>charset</var> and <var>language</var>, if given is the character set name
+and language name to use. If neither is given, <var>s</var> is returned
+as-is. If <var>charset</var> is given but <var>language</var> is not, the
+string is encoded using the empty string for <var>language</var>.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-132' xml:id='l2h-132' class="function">collapse_rfc2231_value</tt></b>(</nobr></td>
+ <td><var>value</var><big>[</big><var>, errors</var><big>[</big><var>,
+ fallback_charset</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+When a header parameter is encoded in <a class="rfc" id='rfcref-3271' xml:id='rfcref-3271'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a> format,
+<tt class="method">Message.get_param()</tt> may return a 3-tuple containing the character
+set, language, and value. <tt class="function">collapse_rfc2231_value()</tt> turns this into
+a unicode string. Optional <var>errors</var> is passed to the <var>errors</var>
+argument of the built-in <tt class="function">unicode()</tt> function; it defaults to
+<code>replace</code>. Optional <var>fallback_charset</var> specifies the character set
+to use if the one in the <a class="rfc" id='rfcref-3273' xml:id='rfcref-3273'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a> header is not known by Python; it defaults
+to <code>us-ascii</code>.
+
+<P>
+For convenience, if the <var>value</var> passed to
+<tt class="function">collapse_rfc2231_value()</tt> is not a tuple, it should be a string and
+it is returned unquoted.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-133' xml:id='l2h-133' class="function">decode_params</tt></b>(</nobr></td>
+ <td><var>params</var>)</td></tr></table></dt>
+<dd>
+Decode parameters list according to <a class="rfc" id='rfcref-3275' xml:id='rfcref-3275'
+href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. <var>params</var> is a
+sequence of 2-tuples containing elements of the form
+<code>(content-type, string-value)</code>.
+</dl>
+
+<P>
+
+<span class="versionnote">Changed in version 2.4:
+The <tt class="function">dump_address_pair()</tt> function has been removed;
+use <tt class="function">formataddr()</tt> instead.</span>
+
+<P>
+
+<span class="versionnote">Changed in version 2.4:
+The <tt class="function">decode()</tt> function has been removed; use the
+<tt class="method">Header.decode_header()</tt> method instead.</span>
+
+<P>
+
+<span class="versionnote">Changed in version 2.4:
+The <tt class="function">encode()</tt> function has been removed; use the
+<tt class="method">Header.encode()</tt> method instead.</span>
+
+
+<P>
+<BR><HR><H4>Footnotes</H4>
+<DL>
+<DT><A NAME="foot2357">... Time)</A><A
+ href="module-email.utils.html#tex2html40"><SUP>3</SUP></A></DT>
+<DD>Note that the sign of the timezone
+offset is the opposite of the sign of the <code>time.timezone</code>
+variable for the same timezone; the latter variable follows the
+POSIX standard while this module follows <a class="rfc" id='rfcref-3250' xml:id='rfcref-3250'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>.
+
+</DD>
+</DL>
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.8 Exception and Defect"
+ href="module-email.errors.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.10 Iterators"
+ href="module-email.iterators.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.errors.html">2.8 Exception and Defect</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.iterators.html">2.10 Iterators</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/modules.png
==============================================================================
Binary file. No diff available.
Added: sandbox/trunk/emailpkg/3.1/docs/next.png
==============================================================================
Binary file. No diff available.
Added: sandbox/trunk/emailpkg/3.1/docs/node1.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/node1.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,125 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="module-email.html" />
+<link rel="prev" href="mimelib.html" />
+<link rel="parent" href="mimelib.html" />
+<link rel="next" href="module-email.html" />
+<meta name='aesop' content='information' />
+<title>1 Introduction</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="email Package Reference"
+ href="mimelib.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="email Package Reference"
+ href="mimelib.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2 email "
+ href="module-email.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="mimelib.html">email Package Reference</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="mimelib.html">email Package Reference</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.html">2 email </A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H1><A NAME="SECTION000100000000000000000">
+1 Introduction</A>
+</H1>
+The <tt class="module">email</tt> package provides classes and utilities to create,
+parse, generate, and modify email messages, conforming to all the
+relevant email and MIME related RFCs.
+
+<P>
+This document describes version 4.0 of the <tt class="module">email</tt> package, which is
+distributed with Python 2.5 and is available as a standalone distutils-based
+package for use with earlier Python versions. <tt class="module">email</tt> 4.0 is not
+compatible with Python versions earlier than 2.3. For more information about
+the <tt class="module">email</tt> package, including download links and mailing lists, see
+<a class="ulink" href="http://www.python.org/sigs/email-sig"
+ >Python's email SIG</a>.
+
+<P>
+The documentation that follows was written for the Python project, so
+if you're reading this as part of the standalone <tt class="module">email</tt>
+package documentation, there are a few notes to be aware of:
+
+<P>
+
+<UL>
+<LI>Deprecation and ``version added'' notes are relative to the
+ Python version a feature was added or deprecated.
+
+<P>
+</LI>
+<LI>If you're reading this documentation as part of the
+ standalone <tt class="module">email</tt> package, some of the internal links to
+ other sections of the Python standard library may not resolve.
+
+<P>
+</LI>
+</UL>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="email Package Reference"
+ href="mimelib.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="email Package Reference"
+ href="mimelib.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2 email "
+ href="module-email.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="mimelib.html">email Package Reference</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="mimelib.html">email Package Reference</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.html">2 email </A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/node16.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/node16.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,270 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="node17.html" />
+<link rel="prev" href="module-email.iterators.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="node17.html" />
+<meta name='aesop' content='information' />
+<title>2.11 Package History</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.10 Iterators"
+ href="module-email.iterators.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.12 Differences from mimelib"
+ href="node17.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.iterators.html">2.10 Iterators</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node17.html">2.12 Differences from mimelib</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION0002110000000000000000">
+2.11 Package History</A>
+</H2>
+
+<P>
+Version 1 of the <tt class="module">email</tt> package was bundled with Python
+releases up to Python 2.2.1. Version 2 was developed for the Python
+2.3 release, and backported to Python 2.2.2. It was also available as
+a separate distutils-based package, and is compatible back to Python 2.1.
+
+<P>
+<tt class="module">email</tt> version 3.0 was released with Python 2.4 and as a separate
+distutils-based package. It is compatible back to Python 2.3.
+
+<P>
+<tt class="module">email</tt> version 4.0 was released with Python 2.5 and as a separate
+distutils-based package. It is also compatible back to Python 2.3.
+
+<P>
+Here are the major differences between <tt class="module">email</tt> verson 4 and version 3:
+
+<P>
+
+<UL>
+<LI>All modules have been renamed according to <a class="rfc" id='rfcref-3284' xml:id='rfcref-3284'
+href="http://www.python.org/peps/pep-0008.html">PEP 8</a> standards. For
+ example, the version 3 module <tt class="module">email.Message</tt> was renamed to
+ <tt class="module">email.message</tt> in version 4.
+
+<P>
+</LI>
+<LI>A new subpackage <tt class="module">email.mime</tt> was added and all the version 3
+ <tt class="module">email.MIME*</tt> modules were renamed and situated into the
+ <tt class="module">email.mime</tt> subpackage. For example, the version 3 module
+ <tt class="module">email.MIMEText</tt> was renamed to <tt class="module">email.mime.text</tt>.
+
+<P>
+<em>Note that the version 3 names will continue to work until Python
+ 2.6</em>.
+
+<P>
+</LI>
+<LI>Methods that were deprecated in version 3 have been removed. These
+ include <tt class="method">Generator.__call__()</tt>, <tt class="method">Message.get_type()</tt>,
+ <tt class="method">Message.get_main_type()</tt>, <tt class="method">Message.get_subtype()</tt>.
+</LI>
+</UL>
+
+<P>
+Here are the major differences between <tt class="module">email</tt> version 3 and version 2:
+
+<P>
+
+<UL>
+<LI>The <tt class="class">FeedParser</tt> class was introduced, and the <tt class="class">Parser</tt>
+ class was implemented in terms of the <tt class="class">FeedParser</tt>. All parsing
+ therefore is non-strict, and parsing will make a best effort never to
+ raise an exception. Problems found while parsing messages are stored in
+ the message's <var>defect</var> attribute.
+
+<P>
+</LI>
+<LI>All aspects of the API which raised <tt class="exception">DeprecationWarning</tt>s in
+ version 2 have been removed. These include the <var>_encoder</var> argument
+ to the <tt class="class">MIMEText</tt> constructor, the <tt class="method">Message.add_payload()</tt>
+ method, the <tt class="function">Utils.dump_address_pair()</tt> function, and the
+ functions <tt class="function">Utils.decode()</tt> and <tt class="function">Utils.encode()</tt>.
+
+<P>
+</LI>
+<LI>New <tt class="exception">DeprecationWarning</tt>s have been added to:
+ <tt class="method">Generator.__call__()</tt>, <tt class="method">Message.get_type()</tt>,
+ <tt class="method">Message.get_main_type()</tt>, <tt class="method">Message.get_subtype()</tt>, and
+ the <var>strict</var> argument to the <tt class="class">Parser</tt> class. These are
+ expected to be removed in future versions.
+
+<P>
+</LI>
+<LI>Support for Pythons earlier than 2.3 has been removed.
+</LI>
+</UL>
+
+<P>
+Here are the differences between <tt class="module">email</tt> version 2 and version 1:
+
+<P>
+
+<UL>
+<LI>The <tt class="module">email.Header</tt> and <tt class="module">email.Charset</tt> modules
+ have been added.
+
+<P>
+</LI>
+<LI>The pickle format for <tt class="class">Message</tt> instances has changed.
+ Since this was never (and still isn't) formally defined, this
+ isn't considered a backward incompatibility. However if your
+ application pickles and unpickles <tt class="class">Message</tt> instances, be
+ aware that in <tt class="module">email</tt> version 2, <tt class="class">Message</tt>
+ instances now have private variables <var>_charset</var> and
+ <var>_default_type</var>.
+
+<P>
+</LI>
+<LI>Several methods in the <tt class="class">Message</tt> class have been
+ deprecated, or their signatures changed. Also, many new methods
+ have been added. See the documentation for the <tt class="class">Message</tt>
+ class for details. The changes should be completely backward
+ compatible.
+
+<P>
+</LI>
+<LI>The object structure has changed in the face of
+ <span class="mimetype">message/rfc822</span> content types. In <tt class="module">email</tt>
+ version 1, such a type would be represented by a scalar payload,
+ i.e. the container message's <tt class="method">is_multipart()</tt> returned
+ false, <tt class="method">get_payload()</tt> was not a list object, but a single
+ <tt class="class">Message</tt> instance.
+
+<P>
+This structure was inconsistent with the rest of the package, so
+ the object representation for <span class="mimetype">message/rfc822</span> content
+ types was changed. In <tt class="module">email</tt> version 2, the container
+ <em>does</em> return <code>True</code> from <tt class="method">is_multipart()</tt>, and
+ <tt class="method">get_payload()</tt> returns a list containing a single
+ <tt class="class">Message</tt> item.
+
+<P>
+Note that this is one place that backward compatibility could
+ not be completely maintained. However, if you're already
+ testing the return type of <tt class="method">get_payload()</tt>, you should be
+ fine. You just need to make sure your code doesn't do a
+ <tt class="method">set_payload()</tt> with a <tt class="class">Message</tt> instance on a
+ container with a content type of <span class="mimetype">message/rfc822</span>.
+
+<P>
+</LI>
+<LI>The <tt class="class">Parser</tt> constructor's <var>strict</var> argument was
+ added, and its <tt class="method">parse()</tt> and <tt class="method">parsestr()</tt> methods
+ grew a <var>headersonly</var> argument. The <var>strict</var> flag was
+ also added to functions <tt class="function">email.message_from_file()</tt>
+ and <tt class="function">email.message_from_string()</tt>.
+
+<P>
+</LI>
+<LI><tt class="method">Generator.__call__()</tt> is deprecated; use
+ <tt class="method">Generator.flatten()</tt> instead. The <tt class="class">Generator</tt>
+ class has also grown the <tt class="method">clone()</tt> method.
+
+<P>
+</LI>
+<LI>The <tt class="class">DecodedGenerator</tt> class in the
+ <tt class="module">email.Generator</tt> module was added.
+
+<P>
+</LI>
+<LI>The intermediate base classes <tt class="class">MIMENonMultipart</tt> and
+ <tt class="class">MIMEMultipart</tt> have been added, and interposed in the
+ class hierarchy for most of the other MIME-related derived
+ classes.
+
+<P>
+</LI>
+<LI>The <var>_encoder</var> argument to the <tt class="class">MIMEText</tt> constructor
+ has been deprecated. Encoding now happens implicitly based
+ on the <var>_charset</var> argument.
+
+<P>
+</LI>
+<LI>The following functions in the <tt class="module">email.Utils</tt> module have
+ been deprecated: <tt class="function">dump_address_pairs()</tt>,
+ <tt class="function">decode()</tt>, and <tt class="function">encode()</tt>. The following
+ functions have been added to the module:
+ <tt class="function">make_msgid()</tt>, <tt class="function">decode_rfc2231()</tt>,
+ <tt class="function">encode_rfc2231()</tt>, and <tt class="function">decode_params()</tt>.
+
+<P>
+</LI>
+<LI>The non-public function <tt class="function">email.Iterators._structure()</tt>
+ was added.
+</LI>
+</UL>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.10 Iterators"
+ href="module-email.iterators.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.12 Differences from mimelib"
+ href="node17.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.iterators.html">2.10 Iterators</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node17.html">2.12 Differences from mimelib</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/node17.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/node17.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,300 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="node18.html" />
+<link rel="prev" href="node16.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="node18.html" />
+<meta name='aesop' content='information' />
+<title>2.12 Differences from mimelib</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.11 Package History"
+ href="node16.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.13 Examples"
+ href="node18.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node16.html">2.11 Package History</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node18.html">2.13 Examples</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION0002120000000000000000">
+2.12 Differences from <tt class="module">mimelib</tt></A>
+</H2>
+
+<P>
+The <tt class="module">email</tt> package was originally prototyped as a separate
+library called
+<a class="ulink" href="http://mimelib.sf.net/"
+ ><tt class="module">mimelib</tt></a>.
+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
+have also changed. For the most part, any functionality available in
+<tt class="module">mimelib</tt> is still available in the <tt class="module"><a href="module-email.html">email</a></tt> package,
+albeit often in a different way. Backward compatibility between
+the <tt class="module">mimelib</tt> package and the <tt class="module">email</tt> package was not a
+priority.
+
+<P>
+Here is a brief description of the differences between the
+<tt class="module">mimelib</tt> and the <tt class="module"><a href="module-email.html">email</a></tt> packages, along with hints on
+how to port your applications.
+
+<P>
+Of course, the most visible difference between the two packages is
+that the package name has been changed to <tt class="module"><a href="module-email.html">email</a></tt>. In
+addition, the top-level package has the following differences:
+
+<P>
+
+<UL>
+<LI><tt class="function">messageFromString()</tt> has been renamed to
+ <tt class="function">message_from_string()</tt>.
+
+<P>
+</LI>
+<LI><tt class="function">messageFromFile()</tt> has been renamed to
+ <tt class="function">message_from_file()</tt>.
+
+<P>
+</LI>
+</UL>
+
+<P>
+The <tt class="class">Message</tt> class has the following differences:
+
+<P>
+
+<UL>
+<LI>The method <tt class="method">asString()</tt> was renamed to <tt class="method">as_string()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">ismultipart()</tt> was renamed to
+ <tt class="method">is_multipart()</tt>.
+
+<P>
+</LI>
+<LI>The <tt class="method">get_payload()</tt> method has grown a <var>decode</var>
+ optional argument.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getall()</tt> was renamed to <tt class="method">get_all()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">addheader()</tt> was renamed to <tt class="method">add_header()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">gettype()</tt> was renamed to <tt class="method">get_type()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getmaintype()</tt> was renamed to
+ <tt class="method">get_main_type()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getsubtype()</tt> was renamed to
+ <tt class="method">get_subtype()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getparams()</tt> was renamed to
+ <tt class="method">get_params()</tt>.
+ Also, whereas <tt class="method">getparams()</tt> returned a list of strings,
+ <tt class="method">get_params()</tt> returns a list of 2-tuples, effectively
+ the key/value pairs of the parameters, split on the "<tt class="character">=</tt>"
+ sign.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getparam()</tt> was renamed to <tt class="method">get_param()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getcharsets()</tt> was renamed to
+ <tt class="method">get_charsets()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getfilename()</tt> was renamed to
+ <tt class="method">get_filename()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getboundary()</tt> was renamed to
+ <tt class="method">get_boundary()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">setboundary()</tt> was renamed to
+ <tt class="method">set_boundary()</tt>.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getdecodedpayload()</tt> was removed. To get
+ similar functionality, pass the value 1 to the <var>decode</var> flag
+ of the get_payload() method.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getpayloadastext()</tt> was removed. Similar
+ functionality
+ is supported by the <tt class="class">DecodedGenerator</tt> class in the
+ <tt class="module"><a href="module-email.generator.html">email.generator</a></tt> module.
+
+<P>
+</LI>
+<LI>The method <tt class="method">getbodyastext()</tt> was removed. You can get
+ similar functionality by creating an iterator with
+ <tt class="function">typed_subpart_iterator()</tt> in the
+ <tt class="module"><a href="module-email.iterators.html">email.iterators</a></tt> module.
+</LI>
+</UL>
+
+<P>
+The <tt class="class">Parser</tt> class has no differences in its public interface.
+It does have some additional smarts to recognize
+<span class="mimetype">message/delivery-status</span> type messages, which it represents as
+a <tt class="class">Message</tt> instance containing separate <tt class="class">Message</tt>
+subparts for each header block in the delivery status
+notification<A NAME="tex2html52"
+ HREF="#foot2667"><SUP>4</SUP></A>.
+
+<P>
+The <tt class="class">Generator</tt> class has no differences in its public
+interface. There is a new class in the <tt class="module"><a href="module-email.generator.html">email.generator</a></tt>
+module though, called <tt class="class">DecodedGenerator</tt> which provides most of
+the functionality previously available in the
+<tt class="method">Message.getpayloadastext()</tt> method.
+
+<P>
+The following modules and classes have been changed:
+
+<P>
+
+<UL>
+<LI>The <tt class="class">MIMEBase</tt> class constructor arguments <var>_major</var>
+ and <var>_minor</var> have changed to <var>_maintype</var> and
+ <var>_subtype</var> respectively.
+
+<P>
+</LI>
+<LI>The <code>Image</code> class/module has been renamed to
+ <code>MIMEImage</code>. The <var>_minor</var> argument has been renamed to
+ <var>_subtype</var>.
+
+<P>
+</LI>
+<LI>The <code>Text</code> class/module has been renamed to
+ <code>MIMEText</code>. The <var>_minor</var> argument has been renamed to
+ <var>_subtype</var>.
+
+<P>
+</LI>
+<LI>The <code>MessageRFC822</code> class/module has been renamed to
+ <code>MIMEMessage</code>. Note that an earlier version of
+ <tt class="module">mimelib</tt> called this class/module <code>RFC822</code>, but
+ that clashed with the Python standard library module
+ <tt class="module"><a href="module-rfc822.html">rfc822</a></tt> on some case-insensitive file systems.
+
+<P>
+Also, the <tt class="class">MIMEMessage</tt> class now represents any kind of
+ MIME message with main type <span class="mimetype">message</span>. It takes an
+ optional argument <var>_subtype</var> which is used to set the MIME
+ subtype. <var>_subtype</var> defaults to <span class="mimetype">rfc822</span>.
+</LI>
+</UL>
+
+<P>
+<tt class="module">mimelib</tt> provided some utility functions in its
+<tt class="module">address</tt> and <tt class="module">date</tt> modules. All of these functions
+have been moved to the <tt class="module"><a href="module-email.utils.html">email.utils</a></tt> module.
+
+<P>
+The <code>MsgReader</code> class/module has been removed. Its functionality
+is most closely supported in the <tt class="function">body_line_iterator()</tt>
+function in the <tt class="module"><a href="module-email.iterators.html">email.iterators</a></tt> module.
+
+<P>
+<BR><HR><H4>Footnotes</H4>
+<DL>
+<DT><A NAME="foot2667">...
+notification</A><A
+ HREF="node17.html#tex2html52"><SUP>4</SUP></A></DT>
+<DD>Delivery Status Notifications (DSN) are defined
+in <a class="rfc" id='rfcref-3289' xml:id='rfcref-3289'
+href="http://www.faqs.org/rfcs/rfc1894.html">RFC 1894</a>.
+
+</DD>
+</DL>
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.11 Package History"
+ href="node16.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.13 Examples"
+ href="node18.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node16.html">2.11 Package History</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node18.html">2.13 Examples</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/node18.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/node18.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,384 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="prev" href="node17.html" />
+<link rel="parent" href="module-email.html" />
+<link rel="next" href="about.html" />
+<meta name='aesop' content='information' />
+<title>2.13 Examples</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.12 Differences from mimelib"
+ href="node17.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="About this document ..."
+ href="about.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node17.html">2.12 Differences from mimelib</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="about.html">About this document ...</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION0002130000000000000000">
+2.13 Examples</A>
+</H2>
+
+<P>
+Here are a few examples of how to use the <tt class="module">email</tt> package to
+read, write, and send simple email messages, as well as more complex
+MIME messages.
+
+<P>
+First, let's see how to create and send a simple text message:
+
+<P>
+<div class="verbatim">
+<pre># Import smtplib for the actual sending function
+import smtplib
+
+# Import the email modules we'll need
+from email.mime.text import MIMEText
+
+# Open a plain text file for reading. For this example, assume that
+# the text file contains only ASCII characters.
+fp = open(textfile, 'rb')
+# Create a text/plain message
+msg = MIMEText(fp.read())
+fp.close()
+
+# me == the sender's email address
+# you == the recipient's email address
+msg['Subject'] = 'The contents of %s' % textfile
+msg['From'] = me
+msg['To'] = you
+
+# Send the message via our own SMTP server, but don't include the
+# envelope header.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, [you], msg.as_string())
+s.close()
+</pre>
+<div class="footer">
+<a href="email-simple.txt" type="text/plain">Download as text (original file name: <span class="file">email-simple.py</span>).</a>
+</div></div>
+
+<P>
+Here's an example of how to send a MIME message containing a bunch of
+family pictures that may be residing in a directory:
+
+<P>
+<div class="verbatim">
+<pre># Import smtplib for the actual sending function
+import smtplib
+
+# Here are the email package modules we'll need
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
+
+COMMASPACE = ', '
+
+# Create the container (outer) email message.
+msg = MIMEMultipart()
+msg['Subject'] = 'Our family reunion'
+# me == the sender's email address
+# family = the list of all recipients' email addresses
+msg['From'] = me
+msg['To'] = COMMASPACE.join(family)
+msg.preamble = 'Our family reunion'
+
+# Assume we know that the image files are all in PNG format
+for file in pngfiles:
+ # Open the files in binary mode. Let the MIMEImage class automatically
+ # guess the specific image type.
+ fp = open(file, 'rb')
+ img = MIMEImage(fp.read())
+ fp.close()
+ msg.attach(img)
+
+# Send the email via our own SMTP server.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, family, msg.as_string())
+s.close()
+</pre>
+<div class="footer">
+<a href="email-mime.txt" type="text/plain">Download as text (original file name: <span class="file">email-mime.py</span>).</a>
+</div></div>
+
+<P>
+Here's an example of how to send the entire contents of a directory as
+an email message:
+<A NAME="tex2html54"
+ HREF="#foot2658"><SUP>5</SUP></A>
+<P>
+<div class="verbatim">
+<pre>#!/usr/bin/env python
+
+"""Send the contents of a directory as a MIME message."""
+
+import os
+import sys
+import smtplib
+# For guessing MIME type based on file name extension
+import mimetypes
+
+from optparse import OptionParser
+
+from email import encoders
+from email.message import Message
+from email.mime.audio import MIMEAudio
+from email.mime.base import MIMEBase
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+COMMASPACE = ', '
+
+def main():
+ parser = OptionParser(usage="""\
+Send the contents of a directory as a MIME message.
+
+Usage: %prog [options]
+
+Unless the -o option is given, the email is sent by forwarding to your local
+SMTP server, which then does the normal delivery process. Your local machine
+must be running an SMTP server.
+""")
+ parser.add_option('-d', '--directory',
+ type='string', action='store',
+ help="""Mail the contents of the specified directory,
+ otherwise use the current directory. Only the regular
+ files in the directory are sent, and we don't recurse to
+ subdirectories.""")
+ parser.add_option('-o', '--output',
+ type='string', action='store', metavar='FILE',
+ help="""Print the composed message to FILE instead of
+ sending the message to the SMTP server.""")
+ parser.add_option('-s', '--sender',
+ type='string', action='store', metavar='SENDER',
+ help='The value of the From: header (required)')
+ parser.add_option('-r', '--recipient',
+ type='string', action='append', metavar='RECIPIENT',
+ default=[], dest='recipients',
+ help='A To: header value (at least one required)')
+ opts, args = parser.parse_args()
+ if not opts.sender or not opts.recipients:
+ parser.print_help()
+ sys.exit(1)
+ directory = opts.directory
+ if not directory:
+ directory = '.'
+ # Create the enclosing (outer) message
+ outer = MIMEMultipart()
+ outer['Subject'] = 'Contents of directory %s' % os.path.abspath(directory)
+ outer['To'] = COMMASPACE.join(opts.recipients)
+ outer['From'] = opts.sender
+ outer.preamble = 'You will not see this in a MIME-aware mail reader.\n'
+
+ for filename in os.listdir(directory):
+ path = os.path.join(directory, filename)
+ if not os.path.isfile(path):
+ continue
+ # Guess the content type based on the file's extension. Encoding
+ # will be ignored, although we should check for simple things like
+ # gzip'd or compressed files.
+ ctype, encoding = mimetypes.guess_type(path)
+ if ctype is None or encoding is not None:
+ # No guess could be made, or the file is encoded (compressed), so
+ # use a generic bag-of-bits type.
+ ctype = 'application/octet-stream'
+ maintype, subtype = ctype.split('/', 1)
+ if maintype == 'text':
+ fp = open(path)
+ # Note: we should handle calculating the charset
+ msg = MIMEText(fp.read(), _subtype=subtype)
+ fp.close()
+ elif maintype == 'image':
+ fp = open(path, 'rb')
+ msg = MIMEImage(fp.read(), _subtype=subtype)
+ fp.close()
+ elif maintype == 'audio':
+ fp = open(path, 'rb')
+ msg = MIMEAudio(fp.read(), _subtype=subtype)
+ fp.close()
+ else:
+ fp = open(path, 'rb')
+ msg = MIMEBase(maintype, subtype)
+ msg.set_payload(fp.read())
+ fp.close()
+ # Encode the payload using Base64
+ encoders.encode_base64(msg)
+ # Set the filename parameter
+ msg.add_header('Content-Disposition', 'attachment', filename=filename)
+ outer.attach(msg)
+ # Now send or store the message
+ composed = outer.as_string()
+ if opts.output:
+ fp = open(opts.output, 'w')
+ fp.write(composed)
+ fp.close()
+ else:
+ s = smtplib.SMTP()
+ s.connect()
+ s.sendmail(opts.sender, opts.recipients, composed)
+ s.close()
+
+if __name__ == '__main__':
+ main()
+</pre>
+<div class="footer">
+<a href="email-dir.txt" type="text/plain">Download as text (original file name: <span class="file">email-dir.py</span>).</a>
+</div></div>
+
+<P>
+And finally, here's an example of how to unpack a MIME message like
+the one above, into a directory of files:
+
+<P>
+<div class="verbatim">
+<pre>#!/usr/bin/env python
+
+"""Unpack a MIME message into a directory of files."""
+
+import os
+import sys
+import email
+import errno
+import mimetypes
+
+from optparse import OptionParser
+
+def main():
+ parser = OptionParser(usage="""\
+Unpack a MIME message into a directory of files.
+
+Usage: %prog [options] msgfile
+""")
+ parser.add_option('-d', '--directory',
+ type='string', action='store',
+ help="""Unpack the MIME message into the named
+ directory, which will be created if it doesn't already
+ exist.""")
+ opts, args = parser.parse_args()
+ if not opts.directory:
+ parser.print_help()
+ sys.exit(1)
+
+ try:
+ msgfile = args[0]
+ except IndexError:
+ parser.print_help()
+ sys.exit(1)
+
+ try:
+ os.mkdir(opts.directory)
+ except OSError, e:
+ # Ignore directory exists error
+ if e.errno <> errno.EEXIST:
+ raise
+
+ fp = open(msgfile)
+ msg = email.message_from_file(fp)
+ fp.close()
+
+ counter = 1
+ for part in msg.walk():
+ # multipart/* are just containers
+ if part.get_content_maintype() == 'multipart':
+ continue
+ # Applications should really sanitize the given filename so that an
+ # email message can't be used to overwrite important files
+ filename = part.get_filename()
+ if not filename:
+ ext = mimetypes.guess_extension(part.get_type())
+ if not ext:
+ # Use a generic bag-of-bits extension
+ ext = '.bin'
+ filename = 'part-%03d%s' % (counter, ext)
+ counter += 1
+ fp = open(os.path.join(opts.directory, filename), 'wb')
+ fp.write(part.get_payload(decode=True))
+ fp.close()
+
+if __name__ == '__main__':
+ main()
+</pre>
+<div class="footer">
+<a href="email-unpack.txt" type="text/plain">Download as text (original file name: <span class="file">email-unpack.py</span>).</a>
+</div></div>
+
+<P>
+<BR><HR><H4>Footnotes</H4>
+<DL>
+<DT><A NAME="foot2658">... message:</A><A
+ HREF="node18.html#tex2html54"><SUP>5</SUP></A></DT>
+<DD>Thanks to Matthew Dixon Cowles for the original inspiration
+ and examples.
+
+</DD>
+</DL>
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.12 Differences from mimelib"
+ href="node17.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2 email "
+ href="module-email.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="About this document ..."
+ href="about.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node17.html">2.12 Differences from mimelib</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.html">2 email </A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="about.html">About this document ...</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/node5.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/node5.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,151 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="node6.html" />
+<link rel="prev" href="module-email.parser.html" />
+<link rel="parent" href="module-email.parser.html" />
+<link rel="next" href="node6.html" />
+<meta name='aesop' content='information' />
+<title>2.2.1 FeedParser API</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2.2 Parser class API"
+ href="node6.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node6.html">2.2.2 Parser class API</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H3><A NAME="SECTION000221000000000000000">
+2.2.1 FeedParser API</A>
+</H3>
+
+<P>
+
+<span class="versionnote">New in version 2.4.</span>
+
+<P>
+The <tt class="class">FeedParser</tt>, imported from the <tt class="module">email.feedparser</tt> module,
+provides an API that is conducive to incremental parsing of email messages,
+such as would be necessary when reading the text of an email message from a
+source that can block (e.g. a socket). The
+<tt class="class">FeedParser</tt> can of course be used to parse an email message fully
+contained in a string or a file, but the classic <tt class="class">Parser</tt> API may be
+more convenient for such use cases. The semantics and results of the two
+parser APIs are identical.
+
+<P>
+The <tt class="class">FeedParser</tt>'s API is simple; you create an instance, feed it a
+bunch of text until there's no more to feed it, then close the parser to
+retrieve the root message object. The <tt class="class">FeedParser</tt> is extremely
+accurate when parsing standards-compliant messages, and it does a very good
+job of parsing non-compliant messages, providing information about how a
+message was deemed broken. It will populate a message object's <var>defects</var>
+attribute with a list of any problems it found in a message. See the
+<tt class="module"><a href="module-email.errors.html">email.errors</a></tt> module for the list of defects that it can find.
+
+<P>
+Here is the API for the <tt class="class">FeedParser</tt>:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-47' xml:id='l2h-47' class="class">FeedParser</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>_factory</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Create a <tt class="class">FeedParser</tt> instance. Optional <var>_factory</var> is a
+no-argument callable that will be called whenever a new message object is
+needed. It defaults to the <tt class="class">email.message.Message</tt> class.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-48' xml:id='l2h-48' class="method">feed</tt></b>(</nobr></td>
+ <td><var>data</var>)</td></tr></table></dt>
+<dd>
+Feed the <tt class="class">FeedParser</tt> some more data. <var>data</var> should be a
+string containing one or more lines. The lines can be partial and the
+<tt class="class">FeedParser</tt> will stitch such partial lines together properly. The
+lines in the string can have any of the common three line endings, carriage
+return, newline, or carriage return and newline (they can even be mixed).
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-49' xml:id='l2h-49' class="method">close</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Closing a <tt class="class">FeedParser</tt> completes the parsing of all previously fed data,
+and returns the root message object. It is undefined what happens if you feed
+more data to a closed <tt class="class">FeedParser</tt>.
+</dl>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2.2 Parser class API"
+ href="node6.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node6.html">2.2.2 Parser class API</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/node6.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/node6.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,235 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="node7.html" />
+<link rel="prev" href="node5.html" />
+<link rel="parent" href="module-email.parser.html" />
+<link rel="next" href="node7.html" />
+<meta name='aesop' content='information' />
+<title>2.2.2 Parser class API</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2.1 FeedParser API"
+ href="node5.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2.3 Additional notes"
+ href="node7.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node5.html">2.2.1 FeedParser API</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node7.html">2.2.3 Additional notes</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H3><A NAME="SECTION000222000000000000000">
+2.2.2 Parser class API</A>
+</H3>
+
+<P>
+The <tt class="class">Parser</tt> class, imported from the <tt class="module">email.parser</tt> module,
+provides an API that can be used to parse a message when the complete contents
+of the message are available in a string or file. The
+<tt class="module">email.parser</tt> module also provides a second class, called
+<tt class="class">HeaderParser</tt> which can be used if you're only interested in
+the headers of the message. <tt class="class">HeaderParser</tt> can be much faster in
+these situations, since it does not attempt to parse the message body,
+instead setting the payload to the raw body as a string.
+<tt class="class">HeaderParser</tt> has the same API as the <tt class="class">Parser</tt> class.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-50' xml:id='l2h-50' class="class">Parser</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>_class</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+The constructor for the <tt class="class">Parser</tt> class takes an optional
+argument <var>_class</var>. This must be a callable factory (such as a
+function or a class), and it is used whenever a sub-message object
+needs to be created. It defaults to <tt class="class">Message</tt> (see
+<tt class="module"><a href="module-email.message.html">email.message</a></tt>). The factory will be called without
+arguments.
+
+<P>
+The optional <var>strict</var> flag is ignored. <div class="versionnote"><b>Deprecated since release 2.4.</b>
+Because the
+<tt class="class">Parser</tt> class is a backward compatible API wrapper around the
+new-in-Python 2.4 <tt class="class">FeedParser</tt>, <em>all</em> parsing is effectively
+non-strict. You should simply stop passing a <var>strict</var> flag to the
+<tt class="class">Parser</tt> constructor.</div><p></p>
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+The <var>strict</var> flag was added.</span>
+
+<span class="versionnote">Changed in version 2.4:
+The <var>strict</var> flag was deprecated.</span>
+
+</dl>
+
+<P>
+The other public <tt class="class">Parser</tt> methods are:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-51' xml:id='l2h-51' class="method">parse</tt></b>(</nobr></td>
+ <td><var>fp</var><big>[</big><var>, headersonly</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Read all the data from the file-like object <var>fp</var>, parse the
+resulting text, and return the root message object. <var>fp</var> must
+support both the <tt class="method">readline()</tt> and the <tt class="method">read()</tt> methods
+on file-like objects.
+
+<P>
+The text contained in <var>fp</var> must be formatted as a block of <a class="rfc" id='rfcref-3123' xml:id='rfcref-3123'
+href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>
+style headers and header continuation lines, optionally preceded by a
+envelope header. The header block is terminated either by the
+end of the data or by a blank line. Following the header block is the
+body of the message (which may contain MIME-encoded subparts).
+
+<P>
+Optional <var>headersonly</var> is as with the <tt class="method">parse()</tt> method.
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+The <var>headersonly</var> flag was added.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-52' xml:id='l2h-52' class="method">parsestr</tt></b>(</nobr></td>
+ <td><var>text</var><big>[</big><var>, headersonly</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Similar to the <tt class="method">parse()</tt> method, except it takes a string
+object instead of a file-like object. Calling this method on a string
+is exactly equivalent to wrapping <var>text</var> in a <tt class="class">StringIO</tt>
+instance first and calling <tt class="method">parse()</tt>.
+
+<P>
+Optional <var>headersonly</var> is a flag specifying whether to stop
+parsing after reading the headers or not. The default is <code>False</code>,
+meaning it parses the entire contents of the file.
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+The <var>headersonly</var> flag was added.</span>
+
+</dl>
+
+<P>
+Since creating a message object structure from a string or a file
+object is such a common task, two functions are provided as a
+convenience. They are available in the top-level <tt class="module">email</tt>
+package namespace.
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-53' xml:id='l2h-53' class="function">message_from_string</tt></b>(</nobr></td>
+ <td><var>s</var><big>[</big><var>, _class</var><big>[</big><var>, strict</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return a message object structure from a string. This is exactly
+equivalent to <code>Parser().parsestr(s)</code>. Optional <var>_class</var> and
+<var>strict</var> are interpreted as with the <tt class="class">Parser</tt> class constructor.
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+The <var>strict</var> flag was added.</span>
+
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-54' xml:id='l2h-54' class="function">message_from_file</tt></b>(</nobr></td>
+ <td><var>fp</var><big>[</big><var>, _class</var><big>[</big><var>, strict</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+Return a message object structure tree from an open file object. This
+is exactly equivalent to <code>Parser().parse(fp)</code>. Optional
+<var>_class</var> and <var>strict</var> are interpreted as with the
+<tt class="class">Parser</tt> class constructor.
+
+<P>
+
+<span class="versionnote">Changed in version 2.2.2:
+The <var>strict</var> flag was added.</span>
+
+</dl>
+
+<P>
+Here's an example of how you might use this at an interactive Python
+prompt:
+
+<P>
+<div class="verbatim"><pre>
+>>> import email
+>>> msg = email.message_from_string(myString)
+</pre></div>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2.1 FeedParser API"
+ href="node5.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.2.3 Additional notes"
+ href="node7.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node5.html">2.2.1 FeedParser API</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="node7.html">2.2.3 Additional notes</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/node7.html
==============================================================================
--- (empty file)
+++ sandbox/trunk/emailpkg/3.1/docs/node7.html Tue Feb 21 04:03:07 2006
@@ -0,0 +1,133 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="mimelib.css" type='text/css' />
+<link rel="first" href="mimelib.html" title='email Package Reference' />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="prev" href="node6.html" />
+<link rel="parent" href="module-email.parser.html" />
+<link rel="next" href="module-email.generator.html" />
+<meta name='aesop' content='information' />
+<title>2.2.3 Additional notes</title>
+</head>
+<body>
+<DIV CLASS="navigation">
+<div id='top-navigation-panel' xml:id='top-navigation-panel'>
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2.2 Parser class API"
+ href="node6.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.3 Generating MIME documents"
+ href="module-email.generator.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node6.html">2.2.2 Parser class API</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.generator.html">2.3 Generating MIME documents</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H3><A NAME="SECTION000223000000000000000">
+2.2.3 Additional notes</A>
+</H3>
+
+<P>
+Here are some notes on the parsing semantics:
+
+<P>
+
+<UL>
+<LI>Most non-<span class="mimetype">multipart</span> type messages are parsed as a single
+ message object with a string payload. These objects will return
+ <code>False</code> for <tt class="method">is_multipart()</tt>. Their
+ <tt class="method">get_payload()</tt> method will return a string object.
+
+<P>
+</LI>
+<LI>All <span class="mimetype">multipart</span> type messages will be parsed as a
+ container message object with a list of sub-message objects for
+ their payload. The outer container message will return
+ <code>True</code> for <tt class="method">is_multipart()</tt> and their
+ <tt class="method">get_payload()</tt> method will return the list of
+ <tt class="class">Message</tt> subparts.
+
+<P>
+</LI>
+<LI>Most messages with a content type of <span class="mimetype">message/*</span>
+ (e.g. <span class="mimetype">message/delivery-status</span> and
+ <span class="mimetype">message/rfc822</span>) will also be parsed as container
+ object containing a list payload of length 1. Their
+ <tt class="method">is_multipart()</tt> method will return <code>True</code>. The
+ single element in the list payload will be a sub-message object.
+
+<P>
+</LI>
+<LI>Some non-standards compliant messages may not be internally consistent
+ about their <span class="mimetype">multipart</span>-edness. Such messages may have a
+ <span class="mailheader">Content-Type:</span> header of type <span class="mimetype">multipart</span>, but their
+ <tt class="method">is_multipart()</tt> method may return <code>False</code>. If such
+ messages were parsed with the <tt class="class">FeedParser</tt>, they will have an
+ instance of the <tt class="class">MultipartInvariantViolationDefect</tt> class in their
+ <var>defects</var> attribute list. See <tt class="module"><a href="module-email.errors.html">email.errors</a></tt> for
+ details.
+</LI>
+</UL>
+
+<P>
+
+<DIV CLASS="navigation">
+<div class='online-navigation'>
+<p></p><hr />
+<table align="center" width="100%" cellpadding="0" cellspacing="2">
+<tr>
+<td class='online-navigation'><a rel="prev" title="2.2.2 Parser class API"
+ href="node6.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="2.2 Parsing email messages"
+ href="module-email.parser.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="2.3 Generating MIME documents"
+ href="module-email.generator.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">email Package Reference</td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node6.html">2.2.2 Parser class API</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-email.parser.html">2.2 Parsing email messages</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="module-email.generator.html">2.3 Generating MIME documents</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 4.0, documentation updated on February 17, 2006.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>
Added: sandbox/trunk/emailpkg/3.1/docs/previous.png
==============================================================================
Binary file. No diff available.
Added: sandbox/trunk/emailpkg/3.1/docs/pyfav.png
==============================================================================
Binary file. No diff available.
Added: sandbox/trunk/emailpkg/3.1/docs/up.png
==============================================================================
Binary file. No diff available.
Modified: sandbox/trunk/emailpkg/3.1/email/__init__.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/__init__.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/__init__.py Tue Feb 21 04:03:07 2006
@@ -4,7 +4,7 @@
"""A package for parsing, handling, and generating email messages."""
-__version__ = '3.1'
+__version__ = '4.0'
__all__ = [
# Old names
@@ -53,7 +53,7 @@
Optional _class and strict are passed to the Parser constructor.
"""
- from email.Parser import Parser
+ from email.parser import Parser
return Parser(*args, **kws).parsestr(s)
@@ -62,13 +62,13 @@
Optional _class and strict are passed to the Parser constructor.
"""
- from email.Parser import Parser
+ from email.parser import Parser
return Parser(*args, **kws).parse(fp)
# Lazy loading to provide name mapping from new-style names (PEP 8 compatible
-# email 3.1 module names), to old-style names (email 3.0 module names).
+# email 4.0 module names), to old-style names (email 3.0 module names).
import sys
class LazyImporter(object):
Modified: sandbox/trunk/emailpkg/3.1/email/base64mime.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/base64mime.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/base64mime.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2002-2004 Python Software Foundation
+# Copyright (C) 2002-2006 Python Software Foundation
# Author: Ben Gertzfield
# Contact: email-sig at python.org
@@ -26,7 +26,7 @@
import re
from binascii import b2a_base64, a2b_base64
-from email.Utils import fix_eols
+from email.utils import fix_eols
CRLF = '\r\n'
NL = '\n'
Modified: sandbox/trunk/emailpkg/3.1/email/charset.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/charset.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/charset.py Tue Feb 21 04:03:07 2006
@@ -2,9 +2,11 @@
# Author: Ben Gertzfield, Barry Warsaw
# Contact: email-sig at python.org
-import email.base64MIME
-import email.quopriMIME
-from email.Encoders import encode_7or8bit
+import email.base64mime
+import email.quoprimime
+
+from email import errors
+from email.encoders import encode_7or8bit
@@ -186,8 +188,17 @@
"""
def __init__(self, input_charset=DEFAULT_CHARSET):
# RFC 2046, $4.1.2 says charsets are not case sensitive. We coerce to
- # unicode because its .lower() is locale insensitive.
- input_charset = unicode(input_charset, 'ascii').lower()
+ # unicode because its .lower() is locale insensitive. If the argument
+ # is already a unicode, we leave it at that, but ensure that the
+ # charset is ASCII, as the standard (RFC XXX) requires.
+ try:
+ if isinstance(input_charset, unicode):
+ input_charset.encode('ascii')
+ else:
+ input_charset = unicode(input_charset, 'ascii')
+ except UnicodeError:
+ raise errors.CharsetError(input_charset)
+ input_charset = input_charset.lower()
# Set the input charset after filtering through the aliases
self.input_charset = ALIASES.get(input_charset, input_charset)
# We can try to guess which encoding and conversion to use by the
@@ -307,12 +318,12 @@
cset = self.get_output_charset()
# The len(s) of a 7bit encoding is len(s)
if self.header_encoding == BASE64:
- return email.base64MIME.base64_len(s) + len(cset) + MISC_LEN
+ return email.base64mime.base64_len(s) + len(cset) + MISC_LEN
elif self.header_encoding == QP:
- return email.quopriMIME.header_quopri_len(s) + len(cset) + MISC_LEN
+ return email.quoprimime.header_quopri_len(s) + len(cset) + MISC_LEN
elif self.header_encoding == SHORTEST:
- lenb64 = email.base64MIME.base64_len(s)
- lenqp = email.quopriMIME.header_quopri_len(s)
+ lenb64 = email.base64mime.base64_len(s)
+ lenqp = email.quoprimime.header_quopri_len(s)
return min(lenb64, lenqp) + len(cset) + MISC_LEN
else:
return len(s)
@@ -335,16 +346,16 @@
s = self.convert(s)
# 7bit/8bit encodings return the string unchanged (modulo conversions)
if self.header_encoding == BASE64:
- return email.base64MIME.header_encode(s, cset)
+ return email.base64mime.header_encode(s, cset)
elif self.header_encoding == QP:
- return email.quopriMIME.header_encode(s, cset, maxlinelen=None)
+ return email.quoprimime.header_encode(s, cset, maxlinelen=None)
elif self.header_encoding == SHORTEST:
- lenb64 = email.base64MIME.base64_len(s)
- lenqp = email.quopriMIME.header_quopri_len(s)
+ lenb64 = email.base64mime.base64_len(s)
+ lenqp = email.quoprimime.header_quopri_len(s)
if lenb64 < lenqp:
- return email.base64MIME.header_encode(s, cset)
+ return email.base64mime.header_encode(s, cset)
else:
- return email.quopriMIME.header_encode(s, cset, maxlinelen=None)
+ return email.quoprimime.header_encode(s, cset, maxlinelen=None)
else:
return s
@@ -363,8 +374,8 @@
s = self.convert(s)
# 7bit/8bit encodings return the string unchanged (module conversions)
if self.body_encoding is BASE64:
- return email.base64MIME.body_encode(s)
+ return email.base64mime.body_encode(s)
elif self.body_encoding is QP:
- return email.quopriMIME.body_encode(s)
+ return email.quoprimime.body_encode(s)
else:
return s
Modified: sandbox/trunk/emailpkg/3.1/email/encoders.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/encoders.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/encoders.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
Modified: sandbox/trunk/emailpkg/3.1/email/errors.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/errors.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/errors.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
@@ -26,6 +26,10 @@
"""Conversion to a multipart is prohibited."""
+class CharsetError(MessageError):
+ """An illegal charset was given."""
+
+
# These are parsing defects which the parser was able to work around.
class MessageDefect:
Modified: sandbox/trunk/emailpkg/3.1/email/feedparser.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/feedparser.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/feedparser.py Tue Feb 21 04:03:07 2006
@@ -20,8 +20,8 @@
"""
import re
-from email import Errors
-from email import Message
+from email import errors
+from email import message
NLCRE = re.compile('\r\n|\r|\n')
NLCRE_bol = re.compile('(\r\n|\r|\n)')
@@ -130,7 +130,7 @@
class FeedParser:
"""A feed-style parser of email."""
- def __init__(self, _factory=Message.Message):
+ def __init__(self, _factory=message.Message):
"""_factory is called with no arguments to create a new message obj"""
self._factory = _factory
self._input = BufferedSubFile()
@@ -164,7 +164,7 @@
# Look for final set of defects
if root.get_content_maintype() == 'multipart' \
and not root.is_multipart():
- root.defects.append(Errors.MultipartInvariantViolationDefect())
+ root.defects.append(errors.MultipartInvariantViolationDefect())
return root
def _new_message(self):
@@ -277,7 +277,7 @@
# defined a boundary. That's a problem which we'll handle by
# reading everything until the EOF and marking the message as
# defective.
- self._cur.defects.append(Errors.NoBoundaryInMultipartDefect())
+ self._cur.defects.append(errors.NoBoundaryInMultipartDefect())
lines = []
for line in self._input:
if line is NeedMoreData:
@@ -381,7 +381,7 @@
# that as a defect and store the captured text as the payload.
# Everything from here to the EOF is epilogue.
if capturing_preamble:
- self._cur.defects.append(Errors.StartBoundaryNotFoundDefect())
+ self._cur.defects.append(errors.StartBoundaryNotFoundDefect())
self._cur.set_payload(EMPTYSTRING.join(preamble))
epilogue = []
for line in self._input:
@@ -432,7 +432,7 @@
# The first line of the headers was a continuation. This
# is illegal, so let's note the defect, store the illegal
# line, and ignore it for purposes of headers.
- defect = Errors.FirstHeaderLineIsContinuationDefect(line)
+ defect = errors.FirstHeaderLineIsContinuationDefect(line)
self._cur.defects.append(defect)
continue
lastvalue.append(line)
@@ -460,13 +460,13 @@
else:
# Weirdly placed unix-from line. Note this as a defect
# and ignore it.
- defect = Errors.MisplacedEnvelopeHeaderDefect(line)
+ defect = errors.MisplacedEnvelopeHeaderDefect(line)
self._cur.defects.append(defect)
continue
# Split the line on the colon separating field name from value.
i = line.find(':')
if i < 0:
- defect = Errors.MalformedHeaderDefect(line)
+ defect = errors.MalformedHeaderDefect(line)
self._cur.defects.append(defect)
continue
lastheader = line[:i]
Modified: sandbox/trunk/emailpkg/3.1/email/generator.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/generator.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/generator.py Tue Feb 21 04:03:07 2006
@@ -11,7 +11,7 @@
import warnings
from cStringIO import StringIO
-from email.Header import Header
+from email.header import Header
UNDERSCORE = '_'
NL = '\n'
@@ -81,12 +81,6 @@
print >> self._fp, ufrom
self._write(msg)
- # For backwards compatibility, but this is slower
- def __call__(self, msg, unixfrom=False):
- warnings.warn('__call__() deprecated; use flatten()',
- DeprecationWarning, 2)
- self.flatten(msg, unixfrom)
-
def clone(self, fp):
"""Clone this generator with the exact same options."""
return self.__class__(fp, self._mangle_from_, self._maxheaderlen)
Modified: sandbox/trunk/emailpkg/3.1/email/header.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/header.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/header.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2002-2004 Python Software Foundation
+# Copyright (C) 2002-2006 Python Software Foundation
# Author: Ben Gertzfield, Barry Warsaw
# Contact: email-sig at python.org
@@ -7,10 +7,11 @@
import re
import binascii
-import email.quopriMIME
-import email.base64MIME
-from email.Errors import HeaderParseError
-from email.Charset import Charset
+import email.quoprimime
+import email.base64mime
+
+from email.errors import HeaderParseError
+from email.charset import Charset
NL = '\n'
SPACE = ' '
@@ -42,7 +43,7 @@
# Helpers
-_max_append = email.quopriMIME._max_append
+_max_append = email.quoprimime._max_append
@@ -82,10 +83,10 @@
encoded = parts[2]
dec = None
if encoding == 'q':
- dec = email.quopriMIME.header_decode(encoded)
+ dec = email.quoprimime.header_decode(encoded)
elif encoding == 'b':
try:
- dec = email.base64MIME.decode(encoded)
+ dec = email.base64mime.decode(encoded)
except binascii.Error:
# Turn this into a higher level exception. BAW: Right
# now we throw the lower level exception away but
Modified: sandbox/trunk/emailpkg/3.1/email/iterators.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/iterators.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/iterators.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
@@ -25,7 +25,6 @@
# These two functions are imported into the Iterators.py interface module.
-# The Python 2.2 version uses generators for efficiency.
def body_line_iterator(msg, decode=False):
"""Iterate over the parts, returning string payloads line-by-line.
Modified: sandbox/trunk/emailpkg/3.1/email/message.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/message.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/message.py Tue Feb 21 04:03:07 2006
@@ -11,9 +11,9 @@
from cStringIO import StringIO
# Intrapackage imports
-from email import Utils
-from email import Errors
-from email import Charset
+import email.charset
+from email import utils
+from email import errors
SEMISPACE = '; '
@@ -41,11 +41,11 @@
if isinstance(value, tuple):
# Encode as per RFC 2231
param += '*'
- value = Utils.encode_rfc2231(value[2], value[0], value[1])
+ value = utils.encode_rfc2231(value[2], value[0], value[1])
# BAW: Please check this. I think that if quote is set it should
# force quoting even if not necessary.
if quote or tspecials.search(value):
- return '%s="%s"' % (param, Utils.quote(value))
+ return '%s="%s"' % (param, utils.quote(value))
else:
return '%s=%s' % (param, value)
else:
@@ -70,14 +70,14 @@
def _unquotevalue(value):
- # This is different than Utils.collapse_rfc2231_value() because it doesn't
+ # This is different than utils.collapse_rfc2231_value() because it doesn't
# try to convert the value to a unicode. Message.get_param() and
# Message.get_params() are both currently defined to return the tuple in
# the face of RFC 2231 parameters.
if isinstance(value, tuple):
- return value[0], value[1], Utils.unquote(value[2])
+ return value[0], value[1], utils.unquote(value[2])
else:
- return Utils.unquote(value)
+ return utils.unquote(value)
@@ -188,10 +188,10 @@
return None
cte = self.get('content-transfer-encoding', '').lower()
if cte == 'quoted-printable':
- return Utils._qdecode(payload)
+ return utils._qdecode(payload)
elif cte == 'base64':
try:
- return Utils._bdecode(payload)
+ return utils._bdecode(payload)
except binascii.Error:
# Incorrect padding
return payload
@@ -237,8 +237,8 @@
self._charset = None
return
if isinstance(charset, str):
- charset = Charset.Charset(charset)
- if not isinstance(charset, Charset.Charset):
+ charset = email.charset.Charset(charset)
+ if not isinstance(charset, email.charset.Charset):
raise TypeError(charset)
# BAW: should we accept strings that can serve as arguments to the
# Charset constructor?
@@ -413,49 +413,6 @@
raise KeyError(_name)
#
- # Deprecated methods. These will be removed in email 3.1.
- #
-
- def get_type(self, failobj=None):
- """Returns the message's content type.
-
- The returned string is coerced to lowercase and returned as a single
- string of the form `maintype/subtype'. If there was no Content-Type
- header in the message, failobj is returned (defaults to None).
- """
- warnings.warn('get_type() deprecated; use get_content_type()',
- DeprecationWarning, 2)
- missing = object()
- value = self.get('content-type', missing)
- if value is missing:
- return failobj
- return paramre.split(value)[0].lower().strip()
-
- def get_main_type(self, failobj=None):
- """Return the message's main content type if present."""
- warnings.warn('get_main_type() deprecated; use get_content_maintype()',
- DeprecationWarning, 2)
- missing = object()
- ctype = self.get_type(missing)
- if ctype is missing:
- return failobj
- if ctype.count('/') <> 1:
- return failobj
- return ctype.split('/')[0]
-
- def get_subtype(self, failobj=None):
- """Return the message's content subtype if present."""
- warnings.warn('get_subtype() deprecated; use get_content_subtype()',
- DeprecationWarning, 2)
- missing = object()
- ctype = self.get_type(missing)
- if ctype is missing:
- return failobj
- if ctype.count('/') <> 1:
- return failobj
- return ctype.split('/')[1]
-
- #
# Use these three methods instead of the three above.
#
@@ -537,7 +494,7 @@
name = p.strip()
val = ''
params.append((name, val))
- params = Utils.decode_params(params)
+ params = utils.decode_params(params)
return params
def get_params(self, failobj=None, header='content-type', unquote=True):
@@ -714,7 +671,7 @@
filename = self.get_param('name', missing, 'content-disposition')
if filename is missing:
return failobj
- return Utils.collapse_rfc2231_value(filename).strip()
+ return utils.collapse_rfc2231_value(filename).strip()
def get_boundary(self, failobj=None):
"""Return the boundary associated with the payload if present.
@@ -727,7 +684,7 @@
if boundary is missing:
return failobj
# RFC 2046 says that boundaries may begin but not end in w/s
- return Utils.collapse_rfc2231_value(boundary).rstrip()
+ return utils.collapse_rfc2231_value(boundary).rstrip()
def set_boundary(self, boundary):
"""Set the boundary parameter in Content-Type to 'boundary'.
@@ -744,7 +701,7 @@
if params is missing:
# There was no Content-Type header, and we don't know what type
# to set it to, so raise an exception.
- raise Errors.HeaderParseError, 'No Content-Type header found'
+ raise errors.HeaderParseError('No Content-Type header found')
newparams = []
foundp = False
for pk, pv in params:
Modified: sandbox/trunk/emailpkg/3.1/email/mime/audio.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/mime/audio.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/mime/audio.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Anthony Baxter
# Contact: email-sig at python.org
@@ -7,9 +7,8 @@
import sndhdr
from cStringIO import StringIO
-from email import Errors
-from email import Encoders
-from email.MIMENonMultipart import MIMENonMultipart
+from email import encoders
+from email.mime.nonmultipart import MIMENonMultipart
@@ -42,7 +41,7 @@
"""Class for generating audio/* MIME documents."""
def __init__(self, _audiodata, _subtype=None,
- _encoder=Encoders.encode_base64, **_params):
+ _encoder=encoders.encode_base64, **_params):
"""Create an audio/* type MIME document.
_audiodata is a string containing the raw audio data. If this data
Modified: sandbox/trunk/emailpkg/3.1/email/mime/base.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/mime/base.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/mime/base.py Tue Feb 21 04:03:07 2006
@@ -1,14 +1,14 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
"""Base class for MIME specializations."""
-from email import Message
+from email import message
-class MIMEBase(Message.Message):
+class MIMEBase(message.Message):
"""Base class for MIME specializations."""
def __init__(self, _maintype, _subtype, **_params):
@@ -18,7 +18,7 @@
arguments. Additional parameters for this header are taken from the
keyword arguments.
"""
- Message.Message.__init__(self)
+ message.Message.__init__(self)
ctype = '%s/%s' % (_maintype, _subtype)
self.add_header('Content-Type', ctype, **_params)
self['MIME-Version'] = '1.0'
Modified: sandbox/trunk/emailpkg/3.1/email/mime/image.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/mime/image.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/mime/image.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
@@ -6,9 +6,8 @@
import imghdr
-from email import Errors
-from email import Encoders
-from email.MIMENonMultipart import MIMENonMultipart
+from email import encoders
+from email.mime.nonmultipart import MIMENonMultipart
@@ -16,7 +15,7 @@
"""Class for generating image/* type MIME documents."""
def __init__(self, _imagedata, _subtype=None,
- _encoder=Encoders.encode_base64, **_params):
+ _encoder=encoders.encode_base64, **_params):
"""Create an image/* type MIME document.
_imagedata is a string containing the raw image data. If this data
Modified: sandbox/trunk/emailpkg/3.1/email/mime/message.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/mime/message.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/mime/message.py Tue Feb 21 04:03:07 2006
@@ -1,11 +1,11 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
"""Class representing message/* MIME documents."""
-from email import Message
-from email.MIMENonMultipart import MIMENonMultipart
+from email import message
+from email.mime.nonmultipart import MIMENonMultipart
@@ -23,10 +23,10 @@
the term "rfc822" is technically outdated by RFC 2822).
"""
MIMENonMultipart.__init__(self, 'message', _subtype)
- if not isinstance(_msg, Message.Message):
+ if not isinstance(_msg, message.Message):
raise TypeError('Argument is not an instance of Message')
# It's convenient to use this base class method. We need to do it
# this way or we'll get an exception
- Message.Message.attach(self, _msg)
+ message.Message.attach(self, _msg)
# And be sure our default type is set correctly
self.set_default_type('message/rfc822')
Modified: sandbox/trunk/emailpkg/3.1/email/mime/multipart.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/mime/multipart.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/mime/multipart.py Tue Feb 21 04:03:07 2006
@@ -1,14 +1,14 @@
-# Copyright (C) 2002-2004 Python Software Foundation
+# Copyright (C) 2002-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
"""Base class for MIME multipart/* type messages."""
-from email import MIMEBase
+from email.mime.base import MIMEBase
-class MIMEMultipart(MIMEBase.MIMEBase):
+class MIMEMultipart(MIMEBase):
"""Base class for MIME multipart/* type messages."""
def __init__(self, _subtype='mixed', boundary=None, _subparts=None,
@@ -31,7 +31,7 @@
Additional parameters for the Content-Type header are taken from the
keyword arguments (or passed into the _params argument).
"""
- MIMEBase.MIMEBase.__init__(self, 'multipart', _subtype, **_params)
+ MIMEBase.__init__(self, 'multipart', _subtype, **_params)
if _subparts:
for p in _subparts:
self.attach(p)
Modified: sandbox/trunk/emailpkg/3.1/email/mime/nonmultipart.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/mime/nonmultipart.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/mime/nonmultipart.py Tue Feb 21 04:03:07 2006
@@ -1,15 +1,15 @@
-# Copyright (C) 2002-2004 Python Software Foundation
+# Copyright (C) 2002-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
"""Base class for MIME type messages that are not multipart."""
-from email import Errors
-from email import MIMEBase
+from email import errors
+from email.mime.base import MIMEBase
-class MIMENonMultipart(MIMEBase.MIMEBase):
+class MIMENonMultipart(MIMEBase):
"""Base class for MIME multipart/* type messages."""
__pychecker__ = 'unusednames=payload'
@@ -18,7 +18,7 @@
# The public API prohibits attaching multiple subparts to MIMEBase
# derived subtypes since none of them are, by definition, of content
# type multipart/*
- raise Errors.MultipartConversionError(
+ raise errors.MultipartConversionError(
'Cannot attach additional subparts to non-multipart/*')
del __pychecker__
Modified: sandbox/trunk/emailpkg/3.1/email/mime/text.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/mime/text.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/mime/text.py Tue Feb 21 04:03:07 2006
@@ -1,11 +1,11 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
"""Class representing text/* type MIME documents."""
-from email.MIMENonMultipart import MIMENonMultipart
-from email.Encoders import encode_7or8bit
+from email.mime.nonmultipart import MIMENonMultipart
+from email.encoders import encode_7or8bit
Modified: sandbox/trunk/emailpkg/3.1/email/parser.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/parser.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/parser.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw, Thomas Wouters, Anthony Baxter
# Contact: email-sig at python.org
@@ -6,8 +6,9 @@
import warnings
from cStringIO import StringIO
-from email.FeedParser import FeedParser
-from email.Message import Message
+
+from email.feedparser import FeedParser
+from email.message import Message
Modified: sandbox/trunk/emailpkg/3.1/email/quoprimime.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/quoprimime.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/quoprimime.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Ben Gertzfield
# Contact: email-sig at python.org
@@ -28,7 +28,8 @@
import re
from string import hexdigits
-from email.Utils import fix_eols
+
+from email.utils import fix_eols
CRLF = '\r\n'
NL = '\n'
Modified: sandbox/trunk/emailpkg/3.1/email/test/test_email.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/test/test_email.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/test/test_email.py Tue Feb 21 04:03:07 2006
@@ -39,9 +39,6 @@
EMPTYSTRING = ''
SPACE = ' '
-# We don't care about DeprecationWarnings
-warnings.filterwarnings('ignore', '', DeprecationWarning, __name__)
-
def openfile(filename, mode='r'):
@@ -87,7 +84,7 @@
charset = Charset('iso-8859-1')
msg.set_charset(charset)
eq(msg['mime-version'], '1.0')
- eq(msg.get_type(), 'text/plain')
+ eq(msg.get_content_type(), 'text/plain')
eq(msg['content-type'], 'text/plain; charset="iso-8859-1"')
eq(msg.get_param('charset'), 'iso-8859-1')
eq(msg['content-transfer-encoding'], 'quoted-printable')
@@ -906,7 +903,7 @@
self._au = MIMEAudio(self._audiodata)
def test_guess_minor_type(self):
- self.assertEqual(self._au.get_type(), 'audio/basic')
+ self.assertEqual(self._au.get_content_type(), 'audio/basic')
def test_encoding(self):
payload = self._au.get_payload()
@@ -914,7 +911,7 @@
def test_checkSetMinor(self):
au = MIMEAudio(self._audiodata, 'fish')
- self.assertEqual(au.get_type(), 'audio/fish')
+ self.assertEqual(au.get_content_type(), 'audio/fish')
def test_add_header(self):
eq = self.assertEqual
@@ -949,7 +946,7 @@
self._im = MIMEImage(self._imgdata)
def test_guess_minor_type(self):
- self.assertEqual(self._im.get_type(), 'image/gif')
+ self.assertEqual(self._im.get_content_type(), 'image/gif')
def test_encoding(self):
payload = self._im.get_payload()
@@ -957,7 +954,7 @@
def test_checkSetMinor(self):
im = MIMEImage(self._imgdata, 'fish')
- self.assertEqual(im.get_type(), 'image/fish')
+ self.assertEqual(im.get_content_type(), 'image/fish')
def test_add_header(self):
eq = self.assertEqual
@@ -989,7 +986,7 @@
def test_types(self):
eq = self.assertEqual
unless = self.failUnless
- eq(self._msg.get_type(), 'text/plain')
+ eq(self._msg.get_content_type(), 'text/plain')
eq(self._msg.get_param('charset'), 'us-ascii')
missing = []
unless(self._msg.get_param('foobar', missing) is missing)
@@ -1058,7 +1055,7 @@
# tests
m = self._msg
unless(m.is_multipart())
- eq(m.get_type(), 'multipart/mixed')
+ eq(m.get_content_type(), 'multipart/mixed')
eq(len(m.get_payload()), 2)
raises(IndexError, m.get_payload, 2)
m0 = m.get_payload(0)
@@ -1392,7 +1389,7 @@
def test_parse_missing_minor_type(self):
eq = self.assertEqual
msg = self._msgobj('msg_14.txt')
- eq(msg.get_type(), 'text')
+ eq(msg.get_content_type(), 'text/plain')
eq(msg.get_content_maintype(), 'text')
eq(msg.get_content_subtype(), 'plain')
@@ -1544,7 +1541,7 @@
m = Message()
m['Subject'] = subject
r = MIMEMessage(m)
- eq(r.get_type(), 'message/rfc822')
+ eq(r.get_content_type(), 'message/rfc822')
payload = r.get_payload()
unless(isinstance(payload, list))
eq(len(payload), 1)
@@ -1585,7 +1582,7 @@
eq = self.assertEqual
unless = self.failUnless
msg = self._msgobj('msg_11.txt')
- eq(msg.get_type(), 'message/rfc822')
+ eq(msg.get_content_type(), 'message/rfc822')
payload = msg.get_payload()
unless(isinstance(payload, list))
eq(len(payload), 1)
@@ -1599,12 +1596,12 @@
unless = self.failUnless
# msg 16 is a Delivery Status Notification, see RFC 1894
msg = self._msgobj('msg_16.txt')
- eq(msg.get_type(), 'multipart/report')
+ eq(msg.get_content_type(), 'multipart/report')
unless(msg.is_multipart())
eq(len(msg.get_payload()), 3)
# Subpart 1 is a text/plain, human readable section
subpart = msg.get_payload(0)
- eq(subpart.get_type(), 'text/plain')
+ eq(subpart.get_content_type(), 'text/plain')
eq(subpart.get_payload(), """\
This report relates to a message you sent with the following header fields:
@@ -1624,7 +1621,7 @@
# consists of two blocks of headers, represented by two nested Message
# objects.
subpart = msg.get_payload(1)
- eq(subpart.get_type(), 'message/delivery-status')
+ eq(subpart.get_content_type(), 'message/delivery-status')
eq(len(subpart.get_payload()), 2)
# message/delivery-status should treat each block as a bunch of
# headers, i.e. a bunch of Message objects.
@@ -1642,13 +1639,13 @@
eq(dsn2.get_param('rfc822', header='final-recipient'), '')
# Subpart 3 is the original message
subpart = msg.get_payload(2)
- eq(subpart.get_type(), 'message/rfc822')
+ eq(subpart.get_content_type(), 'message/rfc822')
payload = subpart.get_payload()
unless(isinstance(payload, list))
eq(len(payload), 1)
subsubpart = payload[0]
unless(isinstance(subsubpart, Message))
- eq(subsubpart.get_type(), 'text/plain')
+ eq(subsubpart.get_content_type(), 'text/plain')
eq(subsubpart['message-id'],
'<002001c144a6$8752e060$56104586 at oxy.edu>')
@@ -1719,16 +1716,16 @@
fp.close()
container1 = msg.get_payload(0)
eq(container1.get_default_type(), 'message/rfc822')
- eq(container1.get_type(), None)
+ eq(container1.get_content_type(), 'message/rfc822')
container2 = msg.get_payload(1)
eq(container2.get_default_type(), 'message/rfc822')
- eq(container2.get_type(), None)
+ eq(container2.get_content_type(), 'message/rfc822')
container1a = container1.get_payload(0)
eq(container1a.get_default_type(), 'text/plain')
- eq(container1a.get_type(), 'text/plain')
+ eq(container1a.get_content_type(), 'text/plain')
container2a = container2.get_payload(0)
eq(container2a.get_default_type(), 'text/plain')
- eq(container2a.get_type(), 'text/plain')
+ eq(container2a.get_content_type(), 'text/plain')
def test_default_type_with_explicit_container_type(self):
eq = self.assertEqual
@@ -1739,16 +1736,16 @@
fp.close()
container1 = msg.get_payload(0)
eq(container1.get_default_type(), 'message/rfc822')
- eq(container1.get_type(), 'message/rfc822')
+ eq(container1.get_content_type(), 'message/rfc822')
container2 = msg.get_payload(1)
eq(container2.get_default_type(), 'message/rfc822')
- eq(container2.get_type(), 'message/rfc822')
+ eq(container2.get_content_type(), 'message/rfc822')
container1a = container1.get_payload(0)
eq(container1a.get_default_type(), 'text/plain')
- eq(container1a.get_type(), 'text/plain')
+ eq(container1a.get_content_type(), 'text/plain')
container2a = container2.get_payload(0)
eq(container2a.get_default_type(), 'text/plain')
- eq(container2a.get_type(), 'text/plain')
+ eq(container2a.get_content_type(), 'text/plain')
def test_default_type_non_parsed(self):
eq = self.assertEqual
@@ -1763,9 +1760,9 @@
subpart2 = MIMEMessage(subpart2a)
container.attach(subpart1)
container.attach(subpart2)
- eq(subpart1.get_type(), 'message/rfc822')
+ eq(subpart1.get_content_type(), 'message/rfc822')
eq(subpart1.get_default_type(), 'message/rfc822')
- eq(subpart2.get_type(), 'message/rfc822')
+ eq(subpart2.get_content_type(), 'message/rfc822')
eq(subpart2.get_default_type(), 'message/rfc822')
neq(container.as_string(0), '''\
Content-Type: multipart/digest; boundary="BOUNDARY"
@@ -1797,9 +1794,9 @@
del subpart1['mime-version']
del subpart2['content-type']
del subpart2['mime-version']
- eq(subpart1.get_type(), None)
+ eq(subpart1.get_content_type(), 'message/rfc822')
eq(subpart1.get_default_type(), 'message/rfc822')
- eq(subpart2.get_type(), None)
+ eq(subpart2.get_content_type(), 'message/rfc822')
eq(subpart2.get_default_type(), 'message/rfc822')
neq(container.as_string(0), '''\
Content-Type: multipart/digest; boundary="BOUNDARY"
@@ -1860,7 +1857,7 @@
def test_parse_text_message(self):
eq = self.assertEquals
msg, text = self._msgobj('msg_01.txt')
- eq(msg.get_type(), 'text/plain')
+ eq(msg.get_content_type(), 'text/plain')
eq(msg.get_content_maintype(), 'text')
eq(msg.get_content_subtype(), 'plain')
eq(msg.get_params()[1], ('charset', 'us-ascii'))
@@ -1872,7 +1869,7 @@
def test_parse_untyped_message(self):
eq = self.assertEquals
msg, text = self._msgobj('msg_03.txt')
- eq(msg.get_type(), None)
+ eq(msg.get_content_type(), 'text/plain')
eq(msg.get_params(), None)
eq(msg.get_param('charset'), None)
self._idempotent(msg, text)
@@ -1946,7 +1943,7 @@
unless = self.failUnless
# Get a message object and reset the seek pointer for other tests
msg, text = self._msgobj('msg_05.txt')
- eq(msg.get_type(), 'multipart/report')
+ eq(msg.get_content_type(), 'multipart/report')
# Test the Content-Type: parameters
params = {}
for pk, pv in msg.get_params():
@@ -1958,13 +1955,13 @@
eq(len(msg.get_payload()), 3)
# Make sure the subparts are what we expect
msg1 = msg.get_payload(0)
- eq(msg1.get_type(), 'text/plain')
+ eq(msg1.get_content_type(), 'text/plain')
eq(msg1.get_payload(), 'Yadda yadda yadda\n')
msg2 = msg.get_payload(1)
- eq(msg2.get_type(), None)
+ eq(msg2.get_content_type(), 'text/plain')
eq(msg2.get_payload(), 'Yadda yadda yadda\n')
msg3 = msg.get_payload(2)
- eq(msg3.get_type(), 'message/rfc822')
+ eq(msg3.get_content_type(), 'message/rfc822')
self.failUnless(isinstance(msg3, Message))
payload = msg3.get_payload()
unless(isinstance(payload, list))
@@ -1978,7 +1975,7 @@
unless = self.failUnless
msg, text = self._msgobj('msg_06.txt')
# Check some of the outer headers
- eq(msg.get_type(), 'message/rfc822')
+ eq(msg.get_content_type(), 'message/rfc822')
# Make sure the payload is a list of exactly one sub-Message, and that
# that submessage has a type of text/plain
payload = msg.get_payload()
@@ -1986,7 +1983,7 @@
eq(len(payload), 1)
msg1 = payload[0]
self.failUnless(isinstance(msg1, Message))
- eq(msg1.get_type(), 'text/plain')
+ eq(msg1.get_content_type(), 'text/plain')
self.failUnless(isinstance(msg1.get_payload(), str))
eq(msg1.get_payload(), '\n')
@@ -2375,7 +2372,7 @@
fp.close()
eq(msg['from'], 'ppp-request at zzz.org')
eq(msg['to'], 'ppp at zzz.org')
- eq(msg.get_type(), 'multipart/mixed')
+ eq(msg.get_content_type(), 'multipart/mixed')
self.failIf(msg.is_multipart())
self.failUnless(isinstance(msg.get_payload(), str))
@@ -2424,10 +2421,10 @@
fp.close()
eq(len(msg.get_payload()), 2)
part1 = msg.get_payload(0)
- eq(part1.get_type(), 'text/plain')
+ eq(part1.get_content_type(), 'text/plain')
eq(part1.get_payload(), 'Simple email with attachment.\r\n\r\n')
part2 = msg.get_payload(1)
- eq(part2.get_type(), 'application/riscos')
+ eq(part2.get_content_type(), 'application/riscos')
def test_multipart_digest_with_extra_mime_headers(self):
eq = self.assertEqual
@@ -2446,21 +2443,21 @@
eq(msg.is_multipart(), 1)
eq(len(msg.get_payload()), 2)
part1 = msg.get_payload(0)
- eq(part1.get_type(), 'message/rfc822')
+ eq(part1.get_content_type(), 'message/rfc822')
eq(part1.is_multipart(), 1)
eq(len(part1.get_payload()), 1)
part1a = part1.get_payload(0)
eq(part1a.is_multipart(), 0)
- eq(part1a.get_type(), 'text/plain')
+ eq(part1a.get_content_type(), 'text/plain')
neq(part1a.get_payload(), 'message 1\n')
# next message/rfc822
part2 = msg.get_payload(1)
- eq(part2.get_type(), 'message/rfc822')
+ eq(part2.get_content_type(), 'message/rfc822')
eq(part2.is_multipart(), 1)
eq(len(part2.get_payload()), 1)
part2a = part2.get_payload(0)
eq(part2a.is_multipart(), 0)
- eq(part2a.get_type(), 'text/plain')
+ eq(part2a.get_content_type(), 'text/plain')
neq(part2a.get_payload(), 'message 2\n')
def test_three_lines(self):
@@ -2742,6 +2739,11 @@
c = Charset('fake')
eq('hello w\xf6rld', c.body_encode('hello w\xf6rld'))
+ def test_unicode_charset_name(self):
+ charset = Charset(u'us-ascii')
+ self.assertEqual(str(charset), 'us-ascii')
+ self.assertRaises(Errors.CharsetError, Charset, 'asc\xffii')
+
# Test multilingual MIME headers.
Modified: sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs.py Tue Feb 21 04:03:07 2006
@@ -10,6 +10,13 @@
from email.Header import Header, decode_header
from email.Message import Message
+# We're compatible with Python 2.3, but it doesn't have the built-in Asian
+# codecs, so we have to skip all these tests.
+try:
+ unicode('foo', 'euc-jp')
+except LookupError:
+ raise TestSkipped
+
class TestEmailAsianCodecs(TestEmailBase):
Modified: sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs_renamed.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs_renamed.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/test/test_email_codecs_renamed.py Tue Feb 21 04:03:07 2006
@@ -10,6 +10,13 @@
from email.header import Header, decode_header
from email.message import Message
+# We're compatible with Python 2.3, but it doesn't have the built-in Asian
+# codecs, so we have to skip all these tests.
+try:
+ unicode('foo', 'euc-jp')
+except LookupError:
+ raise TestSkipped
+
class TestEmailAsianCodecs(TestEmailBase):
Modified: sandbox/trunk/emailpkg/3.1/email/test/test_email_renamed.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/test/test_email_renamed.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/test/test_email_renamed.py Tue Feb 21 04:03:07 2006
@@ -39,9 +39,6 @@
EMPTYSTRING = ''
SPACE = ' '
-# We don't care about DeprecationWarnings
-warnings.filterwarnings('ignore', '', DeprecationWarning, __name__)
-
def openfile(filename, mode='r'):
@@ -87,7 +84,7 @@
charset = Charset('iso-8859-1')
msg.set_charset(charset)
eq(msg['mime-version'], '1.0')
- eq(msg.get_type(), 'text/plain')
+ eq(msg.get_content_type(), 'text/plain')
eq(msg['content-type'], 'text/plain; charset="iso-8859-1"')
eq(msg.get_param('charset'), 'iso-8859-1')
eq(msg['content-transfer-encoding'], 'quoted-printable')
@@ -893,7 +890,7 @@
self._au = MIMEAudio(self._audiodata)
def test_guess_minor_type(self):
- self.assertEqual(self._au.get_type(), 'audio/basic')
+ self.assertEqual(self._au.get_content_type(), 'audio/basic')
def test_encoding(self):
payload = self._au.get_payload()
@@ -901,7 +898,7 @@
def test_checkSetMinor(self):
au = MIMEAudio(self._audiodata, 'fish')
- self.assertEqual(au.get_type(), 'audio/fish')
+ self.assertEqual(au.get_content_type(), 'audio/fish')
def test_add_header(self):
eq = self.assertEqual
@@ -936,7 +933,7 @@
self._im = MIMEImage(self._imgdata)
def test_guess_minor_type(self):
- self.assertEqual(self._im.get_type(), 'image/gif')
+ self.assertEqual(self._im.get_content_type(), 'image/gif')
def test_encoding(self):
payload = self._im.get_payload()
@@ -944,7 +941,7 @@
def test_checkSetMinor(self):
im = MIMEImage(self._imgdata, 'fish')
- self.assertEqual(im.get_type(), 'image/fish')
+ self.assertEqual(im.get_content_type(), 'image/fish')
def test_add_header(self):
eq = self.assertEqual
@@ -976,7 +973,7 @@
def test_types(self):
eq = self.assertEqual
unless = self.failUnless
- eq(self._msg.get_type(), 'text/plain')
+ eq(self._msg.get_content_type(), 'text/plain')
eq(self._msg.get_param('charset'), 'us-ascii')
missing = []
unless(self._msg.get_param('foobar', missing) is missing)
@@ -1045,7 +1042,7 @@
# tests
m = self._msg
unless(m.is_multipart())
- eq(m.get_type(), 'multipart/mixed')
+ eq(m.get_content_type(), 'multipart/mixed')
eq(len(m.get_payload()), 2)
raises(IndexError, m.get_payload, 2)
m0 = m.get_payload(0)
@@ -1379,7 +1376,7 @@
def test_parse_missing_minor_type(self):
eq = self.assertEqual
msg = self._msgobj('msg_14.txt')
- eq(msg.get_type(), 'text')
+ eq(msg.get_content_type(), 'text/plain')
eq(msg.get_content_maintype(), 'text')
eq(msg.get_content_subtype(), 'plain')
@@ -1531,7 +1528,7 @@
m = Message()
m['Subject'] = subject
r = MIMEMessage(m)
- eq(r.get_type(), 'message/rfc822')
+ eq(r.get_content_type(), 'message/rfc822')
payload = r.get_payload()
unless(isinstance(payload, list))
eq(len(payload), 1)
@@ -1572,7 +1569,7 @@
eq = self.assertEqual
unless = self.failUnless
msg = self._msgobj('msg_11.txt')
- eq(msg.get_type(), 'message/rfc822')
+ eq(msg.get_content_type(), 'message/rfc822')
payload = msg.get_payload()
unless(isinstance(payload, list))
eq(len(payload), 1)
@@ -1586,12 +1583,12 @@
unless = self.failUnless
# msg 16 is a Delivery Status Notification, see RFC 1894
msg = self._msgobj('msg_16.txt')
- eq(msg.get_type(), 'multipart/report')
+ eq(msg.get_content_type(), 'multipart/report')
unless(msg.is_multipart())
eq(len(msg.get_payload()), 3)
# Subpart 1 is a text/plain, human readable section
subpart = msg.get_payload(0)
- eq(subpart.get_type(), 'text/plain')
+ eq(subpart.get_content_type(), 'text/plain')
eq(subpart.get_payload(), """\
This report relates to a message you sent with the following header fields:
@@ -1611,7 +1608,7 @@
# consists of two blocks of headers, represented by two nested Message
# objects.
subpart = msg.get_payload(1)
- eq(subpart.get_type(), 'message/delivery-status')
+ eq(subpart.get_content_type(), 'message/delivery-status')
eq(len(subpart.get_payload()), 2)
# message/delivery-status should treat each block as a bunch of
# headers, i.e. a bunch of Message objects.
@@ -1629,13 +1626,13 @@
eq(dsn2.get_param('rfc822', header='final-recipient'), '')
# Subpart 3 is the original message
subpart = msg.get_payload(2)
- eq(subpart.get_type(), 'message/rfc822')
+ eq(subpart.get_content_type(), 'message/rfc822')
payload = subpart.get_payload()
unless(isinstance(payload, list))
eq(len(payload), 1)
subsubpart = payload[0]
unless(isinstance(subsubpart, Message))
- eq(subsubpart.get_type(), 'text/plain')
+ eq(subsubpart.get_content_type(), 'text/plain')
eq(subsubpart['message-id'],
'<002001c144a6$8752e060$56104586 at oxy.edu>')
@@ -1706,16 +1703,16 @@
fp.close()
container1 = msg.get_payload(0)
eq(container1.get_default_type(), 'message/rfc822')
- eq(container1.get_type(), None)
+ eq(container1.get_content_type(), 'message/rfc822')
container2 = msg.get_payload(1)
eq(container2.get_default_type(), 'message/rfc822')
- eq(container2.get_type(), None)
+ eq(container2.get_content_type(), 'message/rfc822')
container1a = container1.get_payload(0)
eq(container1a.get_default_type(), 'text/plain')
- eq(container1a.get_type(), 'text/plain')
+ eq(container1a.get_content_type(), 'text/plain')
container2a = container2.get_payload(0)
eq(container2a.get_default_type(), 'text/plain')
- eq(container2a.get_type(), 'text/plain')
+ eq(container2a.get_content_type(), 'text/plain')
def test_default_type_with_explicit_container_type(self):
eq = self.assertEqual
@@ -1726,16 +1723,16 @@
fp.close()
container1 = msg.get_payload(0)
eq(container1.get_default_type(), 'message/rfc822')
- eq(container1.get_type(), 'message/rfc822')
+ eq(container1.get_content_type(), 'message/rfc822')
container2 = msg.get_payload(1)
eq(container2.get_default_type(), 'message/rfc822')
- eq(container2.get_type(), 'message/rfc822')
+ eq(container2.get_content_type(), 'message/rfc822')
container1a = container1.get_payload(0)
eq(container1a.get_default_type(), 'text/plain')
- eq(container1a.get_type(), 'text/plain')
+ eq(container1a.get_content_type(), 'text/plain')
container2a = container2.get_payload(0)
eq(container2a.get_default_type(), 'text/plain')
- eq(container2a.get_type(), 'text/plain')
+ eq(container2a.get_content_type(), 'text/plain')
def test_default_type_non_parsed(self):
eq = self.assertEqual
@@ -1750,9 +1747,9 @@
subpart2 = MIMEMessage(subpart2a)
container.attach(subpart1)
container.attach(subpart2)
- eq(subpart1.get_type(), 'message/rfc822')
+ eq(subpart1.get_content_type(), 'message/rfc822')
eq(subpart1.get_default_type(), 'message/rfc822')
- eq(subpart2.get_type(), 'message/rfc822')
+ eq(subpart2.get_content_type(), 'message/rfc822')
eq(subpart2.get_default_type(), 'message/rfc822')
neq(container.as_string(0), '''\
Content-Type: multipart/digest; boundary="BOUNDARY"
@@ -1784,9 +1781,9 @@
del subpart1['mime-version']
del subpart2['content-type']
del subpart2['mime-version']
- eq(subpart1.get_type(), None)
+ eq(subpart1.get_content_type(), 'message/rfc822')
eq(subpart1.get_default_type(), 'message/rfc822')
- eq(subpart2.get_type(), None)
+ eq(subpart2.get_content_type(), 'message/rfc822')
eq(subpart2.get_default_type(), 'message/rfc822')
neq(container.as_string(0), '''\
Content-Type: multipart/digest; boundary="BOUNDARY"
@@ -1847,7 +1844,7 @@
def test_parse_text_message(self):
eq = self.assertEquals
msg, text = self._msgobj('msg_01.txt')
- eq(msg.get_type(), 'text/plain')
+ eq(msg.get_content_type(), 'text/plain')
eq(msg.get_content_maintype(), 'text')
eq(msg.get_content_subtype(), 'plain')
eq(msg.get_params()[1], ('charset', 'us-ascii'))
@@ -1859,7 +1856,7 @@
def test_parse_untyped_message(self):
eq = self.assertEquals
msg, text = self._msgobj('msg_03.txt')
- eq(msg.get_type(), None)
+ eq(msg.get_content_type(), 'text/plain')
eq(msg.get_params(), None)
eq(msg.get_param('charset'), None)
self._idempotent(msg, text)
@@ -1933,7 +1930,7 @@
unless = self.failUnless
# Get a message object and reset the seek pointer for other tests
msg, text = self._msgobj('msg_05.txt')
- eq(msg.get_type(), 'multipart/report')
+ eq(msg.get_content_type(), 'multipart/report')
# Test the Content-Type: parameters
params = {}
for pk, pv in msg.get_params():
@@ -1945,13 +1942,13 @@
eq(len(msg.get_payload()), 3)
# Make sure the subparts are what we expect
msg1 = msg.get_payload(0)
- eq(msg1.get_type(), 'text/plain')
+ eq(msg1.get_content_type(), 'text/plain')
eq(msg1.get_payload(), 'Yadda yadda yadda\n')
msg2 = msg.get_payload(1)
- eq(msg2.get_type(), None)
+ eq(msg2.get_content_type(), 'text/plain')
eq(msg2.get_payload(), 'Yadda yadda yadda\n')
msg3 = msg.get_payload(2)
- eq(msg3.get_type(), 'message/rfc822')
+ eq(msg3.get_content_type(), 'message/rfc822')
self.failUnless(isinstance(msg3, Message))
payload = msg3.get_payload()
unless(isinstance(payload, list))
@@ -1965,7 +1962,7 @@
unless = self.failUnless
msg, text = self._msgobj('msg_06.txt')
# Check some of the outer headers
- eq(msg.get_type(), 'message/rfc822')
+ eq(msg.get_content_type(), 'message/rfc822')
# Make sure the payload is a list of exactly one sub-Message, and that
# that submessage has a type of text/plain
payload = msg.get_payload()
@@ -1973,7 +1970,7 @@
eq(len(payload), 1)
msg1 = payload[0]
self.failUnless(isinstance(msg1, Message))
- eq(msg1.get_type(), 'text/plain')
+ eq(msg1.get_content_type(), 'text/plain')
self.failUnless(isinstance(msg1.get_payload(), str))
eq(msg1.get_payload(), '\n')
@@ -2056,7 +2053,10 @@
def test__all__(self):
module = __import__('email')
- self.assertEqual(sorted(module.__all__), [
+ # Can't use sorted() here due to Python 2.3 compatibility
+ all = module.__all__[:]
+ all.sort()
+ self.assertEqual(all, [
# Old names
'Charset', 'Encoders', 'Errors', 'Generator',
'Header', 'Iterators', 'MIMEAudio', 'MIMEBase',
@@ -2360,7 +2360,7 @@
fp.close()
eq(msg['from'], 'ppp-request at zzz.org')
eq(msg['to'], 'ppp at zzz.org')
- eq(msg.get_type(), 'multipart/mixed')
+ eq(msg.get_content_type(), 'multipart/mixed')
self.failIf(msg.is_multipart())
self.failUnless(isinstance(msg.get_payload(), str))
@@ -2409,10 +2409,10 @@
fp.close()
eq(len(msg.get_payload()), 2)
part1 = msg.get_payload(0)
- eq(part1.get_type(), 'text/plain')
+ eq(part1.get_content_type(), 'text/plain')
eq(part1.get_payload(), 'Simple email with attachment.\r\n\r\n')
part2 = msg.get_payload(1)
- eq(part2.get_type(), 'application/riscos')
+ eq(part2.get_content_type(), 'application/riscos')
def test_multipart_digest_with_extra_mime_headers(self):
eq = self.assertEqual
@@ -2431,21 +2431,21 @@
eq(msg.is_multipart(), 1)
eq(len(msg.get_payload()), 2)
part1 = msg.get_payload(0)
- eq(part1.get_type(), 'message/rfc822')
+ eq(part1.get_content_type(), 'message/rfc822')
eq(part1.is_multipart(), 1)
eq(len(part1.get_payload()), 1)
part1a = part1.get_payload(0)
eq(part1a.is_multipart(), 0)
- eq(part1a.get_type(), 'text/plain')
+ eq(part1a.get_content_type(), 'text/plain')
neq(part1a.get_payload(), 'message 1\n')
# next message/rfc822
part2 = msg.get_payload(1)
- eq(part2.get_type(), 'message/rfc822')
+ eq(part2.get_content_type(), 'message/rfc822')
eq(part2.is_multipart(), 1)
eq(len(part2.get_payload()), 1)
part2a = part2.get_payload(0)
eq(part2a.is_multipart(), 0)
- eq(part2a.get_type(), 'text/plain')
+ eq(part2a.get_content_type(), 'text/plain')
neq(part2a.get_payload(), 'message 2\n')
def test_three_lines(self):
@@ -2727,6 +2727,11 @@
c = Charset('fake')
eq('hello w\xf6rld', c.body_encode('hello w\xf6rld'))
+ def test_unicode_charset_name(self):
+ charset = Charset(u'us-ascii')
+ self.assertEqual(str(charset), 'us-ascii')
+ self.assertRaises(errors.CharsetError, Charset, 'asc\xffii')
+
# Test multilingual MIME headers.
Modified: sandbox/trunk/emailpkg/3.1/email/utils.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/email/utils.py (original)
+++ sandbox/trunk/emailpkg/3.1/email/utils.py Tue Feb 21 04:03:07 2006
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004 Python Software Foundation
+# Copyright (C) 2001-2006 Python Software Foundation
# Author: Barry Warsaw
# Contact: email-sig at python.org
@@ -24,7 +24,7 @@
from quopri import decodestring as _qdecode
# Intrapackage imports
-from email.Encoders import _bencode, _qencode
+from email.encoders import _bencode, _qencode
COMMASPACE = ', '
EMPTYSTRING = ''
Modified: sandbox/trunk/emailpkg/3.1/setup.py
==============================================================================
--- sandbox/trunk/emailpkg/3.1/setup.py (original)
+++ sandbox/trunk/emailpkg/3.1/setup.py Tue Feb 21 04:03:07 2006
@@ -22,5 +22,5 @@
author='Barry Warsaw',
author_email='barry at python.org',
url='http://www.python.org/sigs/email-sig',
- packages=['email'],
+ packages=['email', 'email.mime'],
)
More information about the Python-checkins
mailing list