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