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