|
1 :mod:`MimeWriter` --- Generic MIME file writer |
|
2 ============================================== |
|
3 |
|
4 .. module:: MimeWriter |
|
5 :synopsis: Write MIME format files. |
|
6 :deprecated: |
|
7 |
|
8 .. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org> |
|
9 |
|
10 |
|
11 .. deprecated:: 2.3 |
|
12 The :mod:`email` package should be used in preference to the :mod:`MimeWriter` |
|
13 module. This module is present only to maintain backward compatibility. |
|
14 |
|
15 This module defines the class :class:`MimeWriter`. The :class:`MimeWriter` |
|
16 class implements a basic formatter for creating MIME multi-part files. It |
|
17 doesn't seek around the output file nor does it use large amounts of buffer |
|
18 space. You must write the parts out in the order that they should occur in the |
|
19 final file. :class:`MimeWriter` does buffer the headers you add, allowing you |
|
20 to rearrange their order. |
|
21 |
|
22 |
|
23 .. class:: MimeWriter(fp) |
|
24 |
|
25 Return a new instance of the :class:`MimeWriter` class. The only argument |
|
26 passed, *fp*, is a file object to be used for writing. Note that a |
|
27 :class:`StringIO` object could also be used. |
|
28 |
|
29 |
|
30 .. _mimewriter-objects: |
|
31 |
|
32 MimeWriter Objects |
|
33 ------------------ |
|
34 |
|
35 :class:`MimeWriter` instances have the following methods: |
|
36 |
|
37 |
|
38 .. method:: MimeWriter.addheader(key, value[, prefix]) |
|
39 |
|
40 Add a header line to the MIME message. The *key* is the name of the header, |
|
41 where the *value* obviously provides the value of the header. The optional |
|
42 argument *prefix* determines where the header is inserted; ``0`` means append |
|
43 at the end, ``1`` is insert at the start. The default is to append. |
|
44 |
|
45 |
|
46 .. method:: MimeWriter.flushheaders() |
|
47 |
|
48 Causes all headers accumulated so far to be written out (and forgotten). This is |
|
49 useful if you don't need a body part at all, e.g. for a subpart of type |
|
50 :mimetype:`message/rfc822` that's (mis)used to store some header-like |
|
51 information. |
|
52 |
|
53 |
|
54 .. method:: MimeWriter.startbody(ctype[, plist[, prefix]]) |
|
55 |
|
56 Returns a file-like object which can be used to write to the body of the |
|
57 message. The content-type is set to the provided *ctype*, and the optional |
|
58 parameter *plist* provides additional parameters for the content-type |
|
59 declaration. *prefix* functions as in :meth:`addheader` except that the default |
|
60 is to insert at the start. |
|
61 |
|
62 |
|
63 .. method:: MimeWriter.startmultipartbody(subtype[, boundary[, plist[, prefix]]]) |
|
64 |
|
65 Returns a file-like object which can be used to write to the body of the |
|
66 message. Additionally, this method initializes the multi-part code, where |
|
67 *subtype* provides the multipart subtype, *boundary* may provide a user-defined |
|
68 boundary specification, and *plist* provides optional parameters for the |
|
69 subtype. *prefix* functions as in :meth:`startbody`. Subparts should be created |
|
70 using :meth:`nextpart`. |
|
71 |
|
72 |
|
73 .. method:: MimeWriter.nextpart() |
|
74 |
|
75 Returns a new instance of :class:`MimeWriter` which represents an individual |
|
76 part in a multipart message. This may be used to write the part as well as |
|
77 used for creating recursively complex multipart messages. The message must first |
|
78 be initialized with :meth:`startmultipartbody` before using :meth:`nextpart`. |
|
79 |
|
80 |
|
81 .. method:: MimeWriter.lastpart() |
|
82 |
|
83 This is used to designate the last part of a multipart message, and should |
|
84 *always* be used when writing multipart messages. |
|
85 |