Fred Drake | 3a0351c | 1998-04-04 07:23:21 +0000 | [diff] [blame] | 1 | \section{Standard Module \module{mailcap}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-mailcap} |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 3 | \stmodindex{mailcap} |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 4 | |
| 5 | Mailcap files are used to configure how MIME-aware applications such |
| 6 | as mail readers and Web browsers react to files with different MIME |
| 7 | types. (The name ``mailcap'' is derived from the phrase ``mail |
| 8 | capability''.) For example, a mailcap file might contain a line like |
Fred Drake | 1656d17 | 1997-12-29 16:55:50 +0000 | [diff] [blame] | 9 | \samp{video/mpeg; xmpeg \%s}. Then, if the user encounters an email |
Fred Drake | 9e9c89e | 1998-04-02 15:53:07 +0000 | [diff] [blame] | 10 | message or Web document with the MIME type \mimetype{video/mpeg}, |
| 11 | \samp{\%s} will be replaced by a filename (usually one belonging to a |
| 12 | temporary file) and the \program{xmpeg} program can be automatically |
| 13 | started to view the file. |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 14 | |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 15 | The mailcap format is documented in \rfc{1524}, ``A User Agent |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame] | 16 | Configuration Mechanism For Multimedia Mail Format Information,'' but |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 17 | is not an Internet standard. However, mailcap files are supported on |
Fred Drake | 6862b46 | 1998-01-13 19:03:36 +0000 | [diff] [blame] | 18 | most \UNIX{} systems. |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 19 | |
Fred Drake | 9e9c89e | 1998-04-02 15:53:07 +0000 | [diff] [blame] | 20 | \begin{funcdesc}{findmatch}{caps, MIMEtype% |
| 21 | \optional{, key\optional{, |
| 22 | filename\optional{, plist}}}} |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 23 | Return a 2-tuple; the first element is a string containing the command |
| 24 | line to be executed |
| 25 | (which can be passed to \code{os.system()}), and the second element is |
| 26 | the mailcap entry for a given MIME type. If no matching MIME |
| 27 | type can be found, \code{(None, None)} is returned. |
| 28 | |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 29 | \var{key} is the name of the field desired, which represents the type |
| 30 | of activity to be performed; the default value is 'view', since in the |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 31 | most common case you simply want to view the body of the MIME-typed |
| 32 | data. Other possible values might be 'compose' and 'edit', if you |
| 33 | wanted to create a new body of the given MIME type or alter the |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 34 | existing body data. See \rfc{1524} for a complete list of these |
| 35 | fields. |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 36 | |
Fred Drake | 9e9c89e | 1998-04-02 15:53:07 +0000 | [diff] [blame] | 37 | \var{filename} is the filename to be substituted for \samp{\%s} in the |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 38 | command line; the default value is |
Fred Drake | 9e9c89e | 1998-04-02 15:53:07 +0000 | [diff] [blame] | 39 | \code{'/dev/null'} which is almost certainly not what you want, so |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 40 | usually you'll override it by specifying a filename. |
| 41 | |
| 42 | \var{plist} can be a list containing named parameters; the default |
| 43 | value is simply an empty list. Each entry in the list must be a |
Fred Drake | 1656d17 | 1997-12-29 16:55:50 +0000 | [diff] [blame] | 44 | string containing the parameter name, an equals sign (\code{=}), and the |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 45 | parameter's value. Mailcap entries can contain |
Fred Drake | 1656d17 | 1997-12-29 16:55:50 +0000 | [diff] [blame] | 46 | named parameters like \code{\%\{foo\}}, which will be replaced by the |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 47 | value of the parameter named 'foo'. For example, if the command line |
Fred Drake | 9e9c89e | 1998-04-02 15:53:07 +0000 | [diff] [blame] | 48 | \samp{showpartial \%\{id\}\ \%\{number\}\ \%\{total\}} |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 49 | was in a mailcap file, and \var{plist} was set to \code{['id=1', |
| 50 | 'number=2', 'total=3']}, the resulting command line would be |
| 51 | \code{"showpartial 1 2 3"}. |
| 52 | |
| 53 | In a mailcap file, the "test" field can optionally be specified to |
| 54 | test some external condition (e.g., the machine architecture, or the |
| 55 | window system in use) to determine whether or not the mailcap line |
| 56 | applies. \code{findmatch()} will automatically check such conditions |
| 57 | and skip the entry if the check fails. |
| 58 | \end{funcdesc} |
| 59 | |
| 60 | \begin{funcdesc}{getcaps}{} |
| 61 | Returns a dictionary mapping MIME types to a list of mailcap file |
Fred Drake | 1656d17 | 1997-12-29 16:55:50 +0000 | [diff] [blame] | 62 | entries. This dictionary must be passed to the \code{findmatch()} |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 63 | function. An entry is stored as a list of dictionaries, but it |
| 64 | shouldn't be necessary to know the details of this representation. |
| 65 | |
| 66 | The information is derived from all of the mailcap files found on the |
| 67 | system. Settings in the user's mailcap file \file{\$HOME/.mailcap} |
| 68 | will override settings in the system mailcap files |
| 69 | \file{/etc/mailcap}, \file{/usr/etc/mailcap}, and |
| 70 | \file{/usr/local/etc/mailcap}. |
| 71 | \end{funcdesc} |
| 72 | |
| 73 | An example usage: |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 74 | \begin{verbatim} |
Guido van Rossum | 20af95b | 1997-03-25 22:01:35 +0000 | [diff] [blame] | 75 | >>> import mailcap |
| 76 | >>> d=mailcap.getcaps() |
| 77 | >>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223') |
| 78 | ('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'}) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 79 | \end{verbatim} |