/Doc/library/mimetools.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 132 lines · 78 code · 54 blank · 0 comment · 0 complexity · 9b889714d94c6f55c567f365b21680fe MD5 · raw file

  1. :mod:`mimetools` --- Tools for parsing MIME messages
  2. ====================================================
  3. .. module:: mimetools
  4. :synopsis: Tools for parsing MIME-style message bodies.
  5. :deprecated:
  6. .. deprecated:: 2.3
  7. The :mod:`email` package should be used in preference to the :mod:`mimetools`
  8. module. This module is present only to maintain backward compatibility, and
  9. it has been removed in 3.x.
  10. .. index:: module: rfc822
  11. This module defines a subclass of the :mod:`rfc822` module's :class:`Message`
  12. class and a number of utility functions that are useful for the manipulation for
  13. MIME multipart or encoded message.
  14. It defines the following items:
  15. .. class:: Message(fp[, seekable])
  16. Return a new instance of the :class:`Message` class. This is a subclass of the
  17. :class:`rfc822.Message` class, with some additional methods (see below). The
  18. *seekable* argument has the same meaning as for :class:`rfc822.Message`.
  19. .. function:: choose_boundary()
  20. Return a unique string that has a high likelihood of being usable as a part
  21. boundary. The string has the form ``'hostipaddr.uid.pid.timestamp.random'``.
  22. .. function:: decode(input, output, encoding)
  23. Read data encoded using the allowed MIME *encoding* from open file object
  24. *input* and write the decoded data to open file object *output*. Valid values
  25. for *encoding* include ``'base64'``, ``'quoted-printable'``, ``'uuencode'``,
  26. ``'x-uuencode'``, ``'uue'``, ``'x-uue'``, ``'7bit'``, and ``'8bit'``. Decoding
  27. messages encoded in ``'7bit'`` or ``'8bit'`` has no effect. The input is simply
  28. copied to the output.
  29. .. function:: encode(input, output, encoding)
  30. Read data from open file object *input* and write it encoded using the allowed
  31. MIME *encoding* to open file object *output*. Valid values for *encoding* are
  32. the same as for :meth:`decode`.
  33. .. function:: copyliteral(input, output)
  34. Read lines from open file *input* until EOF and write them to open file
  35. *output*.
  36. .. function:: copybinary(input, output)
  37. Read blocks until EOF from open file *input* and write them to open file
  38. *output*. The block size is currently fixed at 8192.
  39. .. seealso::
  40. Module :mod:`email`
  41. Comprehensive email handling package; supersedes the :mod:`mimetools` module.
  42. Module :mod:`rfc822`
  43. Provides the base class for :class:`mimetools.Message`.
  44. Module :mod:`multifile`
  45. Support for reading files which contain distinct parts, such as MIME data.
  46. http://faqs.cs.uu.nl/na-dir/mail/mime-faq/.html
  47. The MIME Frequently Asked Questions document. For an overview of MIME, see the
  48. answer to question 1.1 in Part 1 of this document.
  49. .. _mimetools-message-objects:
  50. Additional Methods of Message Objects
  51. -------------------------------------
  52. The :class:`Message` class defines the following methods in addition to the
  53. :class:`rfc822.Message` methods:
  54. .. method:: Message.getplist()
  55. Return the parameter list of the :mailheader:`Content-Type` header. This is a
  56. list of strings. For parameters of the form ``key=value``, *key* is converted
  57. to lower case but *value* is not. For example, if the message contains the
  58. header ``Content-type: text/html; spam=1; Spam=2; Spam`` then :meth:`getplist`
  59. will return the Python list ``['spam=1', 'spam=2', 'Spam']``.
  60. .. method:: Message.getparam(name)
  61. Return the *value* of the first parameter (as returned by :meth:`getplist`) of
  62. the form ``name=value`` for the given *name*. If *value* is surrounded by
  63. quotes of the form '``<``...\ ``>``' or '``"``...\ ``"``', these are removed.
  64. .. method:: Message.getencoding()
  65. Return the encoding specified in the :mailheader:`Content-Transfer-Encoding`
  66. message header. If no such header exists, return ``'7bit'``. The encoding is
  67. converted to lower case.
  68. .. method:: Message.gettype()
  69. Return the message type (of the form ``type/subtype``) as specified in the
  70. :mailheader:`Content-Type` header. If no such header exists, return
  71. ``'text/plain'``. The type is converted to lower case.
  72. .. method:: Message.getmaintype()
  73. Return the main type as specified in the :mailheader:`Content-Type` header. If
  74. no such header exists, return ``'text'``. The main type is converted to lower
  75. case.
  76. .. method:: Message.getsubtype()
  77. Return the subtype as specified in the :mailheader:`Content-Type` header. If no
  78. such header exists, return ``'plain'``. The subtype is converted to lower case.