Backport change to 1.8 adding docstrings

diff --git a/Lib/MimeWriter.py b/Lib/MimeWriter.py
index bb878c1c9d015193d52982b109c09728bfa82ef1..58c0a0bcf2a6854431972f0a0ed50e117f049869 100644 (file)
--- 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")