/Doc/library/mimewriter.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 85 lines · 54 code · 31 blank · 0 comment · 0 complexity · 6e63a298ffffe100ac4582a0eca53a2b MD5 · raw file

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