mirror of
https://github.com/python/cpython.git
synced 2024-11-30 18:51:15 +01:00
83 lines
3.6 KiB
TeX
83 lines
3.6 KiB
TeX
\section{\module{mailcap} ---
|
|
Mailcap file handling.}
|
|
\declaremodule{standard}{mailcap}
|
|
|
|
\modulesynopsis{Mailcap file handling.}
|
|
|
|
|
|
Mailcap files are used to configure how MIME-aware applications such
|
|
as mail readers and Web browsers react to files with different MIME
|
|
types. (The name ``mailcap'' is derived from the phrase ``mail
|
|
capability''.) For example, a mailcap file might contain a line like
|
|
\samp{video/mpeg; xmpeg \%s}. Then, if the user encounters an email
|
|
message or Web document with the MIME type \mimetype{video/mpeg},
|
|
\samp{\%s} will be replaced by a filename (usually one belonging to a
|
|
temporary file) and the \program{xmpeg} program can be automatically
|
|
started to view the file.
|
|
|
|
The mailcap format is documented in \rfc{1524}, ``A User Agent
|
|
Configuration Mechanism For Multimedia Mail Format Information,'' but
|
|
is not an Internet standard. However, mailcap files are supported on
|
|
most \UNIX{} systems.
|
|
|
|
\begin{funcdesc}{findmatch}{caps, MIMEtype%
|
|
\optional{, key\optional{,
|
|
filename\optional{, plist}}}}
|
|
Return a 2-tuple; the first element is a string containing the command
|
|
line to be executed
|
|
(which can be passed to \code{os.system()}), and the second element is
|
|
the mailcap entry for a given MIME type. If no matching MIME
|
|
type can be found, \code{(None, None)} is returned.
|
|
|
|
\var{key} is the name of the field desired, which represents the type
|
|
of activity to be performed; the default value is 'view', since in the
|
|
most common case you simply want to view the body of the MIME-typed
|
|
data. Other possible values might be 'compose' and 'edit', if you
|
|
wanted to create a new body of the given MIME type or alter the
|
|
existing body data. See \rfc{1524} for a complete list of these
|
|
fields.
|
|
|
|
\var{filename} is the filename to be substituted for \samp{\%s} in the
|
|
command line; the default value is
|
|
\code{'/dev/null'} which is almost certainly not what you want, so
|
|
usually you'll override it by specifying a filename.
|
|
|
|
\var{plist} can be a list containing named parameters; the default
|
|
value is simply an empty list. Each entry in the list must be a
|
|
string containing the parameter name, an equals sign (\code{=}), and the
|
|
parameter's value. Mailcap entries can contain
|
|
named parameters like \code{\%\{foo\}}, which will be replaced by the
|
|
value of the parameter named 'foo'. For example, if the command line
|
|
\samp{showpartial \%\{id\}\ \%\{number\}\ \%\{total\}}
|
|
was in a mailcap file, and \var{plist} was set to \code{['id=1',
|
|
'number=2', 'total=3']}, the resulting command line would be
|
|
\code{"showpartial 1 2 3"}.
|
|
|
|
In a mailcap file, the "test" field can optionally be specified to
|
|
test some external condition (e.g., the machine architecture, or the
|
|
window system in use) to determine whether or not the mailcap line
|
|
applies. \code{findmatch()} will automatically check such conditions
|
|
and skip the entry if the check fails.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getcaps}{}
|
|
Returns a dictionary mapping MIME types to a list of mailcap file
|
|
entries. This dictionary must be passed to the \code{findmatch()}
|
|
function. An entry is stored as a list of dictionaries, but it
|
|
shouldn't be necessary to know the details of this representation.
|
|
|
|
The information is derived from all of the mailcap files found on the
|
|
system. Settings in the user's mailcap file \file{\$HOME/.mailcap}
|
|
will override settings in the system mailcap files
|
|
\file{/etc/mailcap}, \file{/usr/etc/mailcap}, and
|
|
\file{/usr/local/etc/mailcap}.
|
|
\end{funcdesc}
|
|
|
|
An example usage:
|
|
\begin{verbatim}
|
|
>>> import mailcap
|
|
>>> d=mailcap.getcaps()
|
|
>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
|
|
('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
|
|
\end{verbatim}
|