diff options
Diffstat (limited to 'Lib/MimeWriter.py')
| -rw-r--r-- | Lib/MimeWriter.py | 59 |
1 files changed, 56 insertions, 3 deletions
diff --git a/Lib/MimeWriter.py b/Lib/MimeWriter.py index bb878c1..58c0a0b 100644 --- a/Lib/MimeWriter.py +++ b/Lib/MimeWriter.py @@ -1,8 +1,11 @@ """Generic MIME writer. -Classes: - -MimeWriter - the only thing here. +This module defines the class MimeWriter. The MimeWriter class implements +a basic formatter for creating MIME multi-part files. It doesn't seek around +the output file nor does it use large amounts of buffer space. You must write +the parts out in the order that they should occur in the final file. +MimeWriter does buffer the headers you add, allowing you to rearrange their +order. """ @@ -86,6 +89,14 @@ class MimeWriter: self._headers = [] def addheader(self, key, value, prefix=0): + """Add a header line to the MIME message. + + The key is the name of the header, where the value obviously provides + the value of the header. The optional argument prefix determines + where the header is inserted; 0 means append at the end, 1 means + insert at the start. The default is to append. + + """ lines = value.split("\n") while lines and not lines[-1]: del lines[-1] while lines and not lines[0]: del lines[0] @@ -99,10 +110,26 @@ class MimeWriter: self._headers.append(line) def flushheaders(self): + """Writes out and forgets all headers accumulated so far. + + This is useful if you don't need a body part at all; for example, + for a subpart of type message/rfc822 that's (mis)used to store some + header-like information. + + """ self._fp.writelines(self._headers) self._headers = [] def startbody(self, ctype, plist=[], prefix=1): + """Returns a file-like object for writing the body of the message. + + The content-type is set to the provided ctype, and the optional + parameter, plist, provides additional parameters for the + content-type declaration. The optional argument prefix determines + where the header is inserted; 0 means append at the end, 1 means + insert at the start. The default is to insert at the start. + + """ for name, value in plist: ctype = ctype + ';\n %s=\"%s\"' % (name, value) self.addheader("Content-Type", ctype, prefix=prefix) @@ -111,16 +138,42 @@ class MimeWriter: return self._fp def startmultipartbody(self, subtype, boundary=None, plist=[], prefix=1): + """Returns a file-like object for writing the body of the message. + + Additionally, this method initializes the multi-part code, where the + subtype parameter provides the multipart subtype, the boundary + parameter may provide a user-defined boundary specification, and the + plist parameter provides optional parameters for the subtype. The + optional argument, prefix, determines where the header is inserted; + 0 means append at the end, 1 means insert at the start. The default + is to insert at the start. Subparts should be created using the + nextpart() method. + + """ self._boundary = boundary or mimetools.choose_boundary() return self.startbody("multipart/" + subtype, [("boundary", self._boundary)] + plist, prefix=prefix) def nextpart(self): + """Returns a new instance of MimeWriter which represents an + individual part in a multipart message. + + This may be used to write the part as well as used for creating + recursively complex multipart messages. The message must first be + initialized with the startmultipartbody() method before using the + nextpart() method. + + """ self._fp.write("\n--" + self._boundary + "\n") return self.__class__(self._fp) def lastpart(self): + """This is used to designate the last part of a multipart message. + + It should always be used when writing multipart messages. + + """ self._fp.write("\n--" + self._boundary + "--\n") |