Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{mimetools} --- |
Fred Drake | 56f8185 | 1999-02-19 22:59:56 +0000 | [diff] [blame] | 2 | Tools for parsing MIME messages} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{mimetools} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 5 | \modulesynopsis{Tools for parsing MIME-style message bodies.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 6 | |
Fred Drake | 4613876 | 2002-09-25 22:13:27 +0000 | [diff] [blame] | 7 | \deprecated{2.3}{The \refmodule{email} package should be used in |
| 8 | preference to the \module{mimetools} module. This |
| 9 | module is present only to maintain backward |
| 10 | compatibility.} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 11 | |
Fred Drake | 35784df | 2000-05-09 16:23:23 +0000 | [diff] [blame] | 12 | This module defines a subclass of the |
| 13 | \refmodule{rfc822}\refstmodindex{rfc822} module's |
| 14 | \class{Message} class and a number of utility functions that are |
| 15 | useful for the manipulation for MIME multipart or encoded message. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 16 | |
| 17 | It defines the following items: |
| 18 | |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 19 | \begin{classdesc}{Message}{fp\optional{, seekable}} |
| 20 | Return a new instance of the \class{Message} class. This is a |
| 21 | subclass of the \class{rfc822.Message} class, with some additional |
| 22 | methods (see below). The \var{seekable} argument has the same meaning |
| 23 | as for \class{rfc822.Message}. |
| 24 | \end{classdesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 25 | |
| 26 | \begin{funcdesc}{choose_boundary}{} |
| 27 | Return a unique string that has a high likelihood of being usable as a |
| 28 | part boundary. The string has the form |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 29 | \code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 30 | \end{funcdesc} |
| 31 | |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 32 | \begin{funcdesc}{decode}{input, output, encoding} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 33 | Read data encoded using the allowed MIME \var{encoding} from open file |
| 34 | object \var{input} and write the decoded data to open file object |
| 35 | \var{output}. Valid values for \var{encoding} include |
Skip Montanaro | 3b2625f | 2002-04-10 04:37:09 +0000 | [diff] [blame] | 36 | \code{'base64'}, \code{'quoted-printable'}, \code{'uuencode'}, |
| 37 | \code{'x-uuencode'}, \code{'uue'}, \code{'x-uue'}, \code{'7bit'}, and |
| 38 | \code{'8bit'}. Decoding messages encoded in \code{'7bit'} or \code{'8bit'} |
| 39 | has no effect. The input is simply copied to the output. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 40 | \end{funcdesc} |
| 41 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 42 | \begin{funcdesc}{encode}{input, output, encoding} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 43 | Read data from open file object \var{input} and write it encoded using |
| 44 | the allowed MIME \var{encoding} to open file object \var{output}. |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 45 | Valid values for \var{encoding} are the same as for \method{decode()}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 46 | \end{funcdesc} |
| 47 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 48 | \begin{funcdesc}{copyliteral}{input, output} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 49 | Read lines from open file \var{input} until \EOF{} and write them to |
Fred Drake | 01dbb88 | 1998-02-13 22:13:07 +0000 | [diff] [blame] | 50 | open file \var{output}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 51 | \end{funcdesc} |
| 52 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 53 | \begin{funcdesc}{copybinary}{input, output} |
Fred Drake | 01dbb88 | 1998-02-13 22:13:07 +0000 | [diff] [blame] | 54 | Read blocks until \EOF{} from open file \var{input} and write them to |
| 55 | open file \var{output}. The block size is currently fixed at 8192. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 56 | \end{funcdesc} |
| 57 | |
| 58 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 59 | \begin{seealso} |
Fred Drake | 2d3c03d | 2002-08-06 21:26:01 +0000 | [diff] [blame] | 60 | \seemodule{email}{Comprehensive email handling package; supercedes |
| 61 | the \module{mimetools} module.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 62 | \seemodule{rfc822}{Provides the base class for |
| 63 | \class{mimetools.Message}.} |
Fred Drake | 71b04da | 2000-04-05 22:05:15 +0000 | [diff] [blame] | 64 | \seemodule{multifile}{Support for reading files which contain |
| 65 | distinct parts, such as MIME data.} |
Fred Drake | 35784df | 2000-05-09 16:23:23 +0000 | [diff] [blame] | 66 | \seeurl{http://www.cs.uu.nl/wais/html/na-dir/mail/mime-faq/.html}{ |
| 67 | The MIME Frequently Asked Questions document. For an |
| 68 | overview of MIME, see the answer to question 1.1 in Part 1 |
| 69 | of this document.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 70 | \end{seealso} |
| 71 | |
| 72 | |
Fred Drake | 2c4f554 | 2000-10-10 22:00:03 +0000 | [diff] [blame] | 73 | \subsection{Additional Methods of Message Objects |
| 74 | \label{mimetools-message-objects}} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 75 | |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 76 | The \class{Message} class defines the following methods in |
| 77 | addition to the \class{rfc822.Message} methods: |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 78 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 79 | \begin{methoddesc}{getplist}{} |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 80 | Return the parameter list of the \mailheader{Content-Type} header. |
| 81 | This is a list of strings. For parameters of the form |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 82 | \samp{\var{key}=\var{value}}, \var{key} is converted to lower case but |
| 83 | \var{value} is not. For example, if the message contains the header |
| 84 | \samp{Content-type: text/html; spam=1; Spam=2; Spam} then |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 85 | \method{getplist()} will return the Python list \code{['spam=1', |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 86 | 'spam=2', 'Spam']}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 87 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 88 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 89 | \begin{methoddesc}{getparam}{name} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 90 | Return the \var{value} of the first parameter (as returned by |
Raymond Hettinger | bf3a752 | 2003-05-12 03:23:51 +0000 | [diff] [blame^] | 91 | \method{getplist()}) of the form \samp{\var{name}=\var{value}} for the |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 92 | given \var{name}. If \var{value} is surrounded by quotes of the form |
Fred Drake | 01dbb88 | 1998-02-13 22:13:07 +0000 | [diff] [blame] | 93 | `\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 94 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 95 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 96 | \begin{methoddesc}{getencoding}{} |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 97 | Return the encoding specified in the |
| 98 | \mailheader{Content-Transfer-Encoding} message header. If no such |
| 99 | header exists, return \code{'7bit'}. The encoding is converted to |
| 100 | lower case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 101 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 102 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 103 | \begin{methoddesc}{gettype}{} |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 104 | Return the message type (of the form \samp{\var{type}/\var{subtype}}) |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 105 | as specified in the \mailheader{Content-Type} header. If no such |
| 106 | header exists, return \code{'text/plain'}. The type is converted to |
| 107 | lower case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 108 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 109 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 110 | \begin{methoddesc}{getmaintype}{} |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 111 | Return the main type as specified in the \mailheader{Content-Type} |
| 112 | header. If no such header exists, return \code{'text'}. The main |
| 113 | type is converted to lower case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 114 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 115 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 116 | \begin{methoddesc}{getsubtype}{} |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 117 | Return the subtype as specified in the \mailheader{Content-Type} |
| 118 | header. If no such header exists, return \code{'plain'}. The subtype |
| 119 | is converted to lower case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 120 | \end{methoddesc} |