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