Doc/library/mailcap.rst

   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