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