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