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