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