Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 1 | \section{Standard Module \module{mimetools}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-mimetools} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 3 | \stmodindex{mimetools} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 4 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 5 | |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 6 | This module defines a subclass of the \class{rfc822.Message} class and |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 7 | a number of utility functions that are useful for the manipulation for |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 8 | MIME multipart or encoded message. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 9 | |
| 10 | It defines the following items: |
| 11 | |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 12 | \begin{classdesc}{Message}{fp\optional{, seekable}} |
| 13 | Return a new instance of the \class{Message} class. This is a |
| 14 | subclass of the \class{rfc822.Message} class, with some additional |
| 15 | methods (see below). The \var{seekable} argument has the same meaning |
| 16 | as for \class{rfc822.Message}. |
| 17 | \end{classdesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 18 | |
| 19 | \begin{funcdesc}{choose_boundary}{} |
| 20 | Return a unique string that has a high likelihood of being usable as a |
| 21 | part boundary. The string has the form |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 22 | \code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 23 | \end{funcdesc} |
| 24 | |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 25 | \begin{funcdesc}{decode}{input, output, encoding} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 26 | Read data encoded using the allowed MIME \var{encoding} from open file |
| 27 | object \var{input} and write the decoded data to open file object |
| 28 | \var{output}. Valid values for \var{encoding} include |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 29 | \code{'base64'}, \code{'quoted-printable'} and \code{'uuencode'}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 30 | \end{funcdesc} |
| 31 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 32 | \begin{funcdesc}{encode}{input, output, encoding} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 33 | Read data from open file object \var{input} and write it encoded using |
| 34 | the allowed MIME \var{encoding} to open file object \var{output}. |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 35 | 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] | 36 | \end{funcdesc} |
| 37 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 38 | \begin{funcdesc}{copyliteral}{input, output} |
Fred Drake | 01dbb88 | 1998-02-13 22:13:07 +0000 | [diff] [blame] | 39 | Read lines until \EOF{} from open file \var{input} and write them to |
| 40 | open file \var{output}. |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 41 | \end{funcdesc} |
| 42 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 43 | \begin{funcdesc}{copybinary}{input, output} |
Fred Drake | 01dbb88 | 1998-02-13 22:13:07 +0000 | [diff] [blame] | 44 | Read blocks until \EOF{} from open file \var{input} and write them to |
| 45 | 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] | 46 | \end{funcdesc} |
| 47 | |
| 48 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 49 | \subsection{Additional Methods of Message objects} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 50 | \nodename{mimetools.Message Methods} |
| 51 | |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 52 | The \class{Message} class defines the following methods in |
| 53 | addition to the \class{rfc822.Message} methods: |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 54 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 55 | \begin{methoddesc}{getplist}{} |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 56 | Return the parameter list of the \code{content-type} header. This is |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 57 | a list if strings. For parameters of the form |
| 58 | \samp{\var{key}=\var{value}}, \var{key} is converted to lower case but |
| 59 | \var{value} is not. For example, if the message contains the header |
| 60 | \samp{Content-type: text/html; spam=1; Spam=2; Spam} then |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 61 | \method{getplist()} will return the Python list \code{['spam=1', |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 62 | 'spam=2', 'Spam']}. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 63 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 64 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 65 | \begin{methoddesc}{getparam}{name} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 66 | Return the \var{value} of the first parameter (as returned by |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 67 | \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] | 68 | 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] | 69 | `\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 70 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 71 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 72 | \begin{methoddesc}{getencoding}{} |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 73 | Return the encoding specified in the \code{content-transfer-encoding} |
| 74 | message header. If no such header exists, return \code{'7bit'}. The |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 75 | encoding is converted to lower case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 76 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 77 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 78 | \begin{methoddesc}{gettype}{} |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 79 | Return the message type (of the form \samp{\var{type}/\var{subtype}}) |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 80 | as specified in the \code{content-type} header. If no such header |
| 81 | exists, return \code{'text/plain'}. The type is converted to lower |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 82 | case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 83 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 84 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 85 | \begin{methoddesc}{getmaintype}{} |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 86 | Return the main type as specified in the \code{content-type} header. |
| 87 | If no such header exists, return \code{'text'}. The main type is |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 88 | converted to lower case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 89 | \end{methoddesc} |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 90 | |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 91 | \begin{methoddesc}{getsubtype}{} |
Fred Drake | 0f51fff | 1998-03-14 06:16:57 +0000 | [diff] [blame] | 92 | Return the subtype as specified in the \code{content-type} header. If |
| 93 | no such header exists, return \code{'plain'}. The subtype is |
Guido van Rossum | cca8d2b | 1995-03-22 15:48:46 +0000 | [diff] [blame] | 94 | converted to lower case. |
Fred Drake | fc57619 | 1998-04-04 07:15:02 +0000 | [diff] [blame] | 95 | \end{methoddesc} |